Add/Update Abonnement

Utilisez ceci lorsqu'un client doit être facturé du même montant selon un calendrier, comme un service mensuel.


The following endpoint can be used to add or update a Abonnement within the Hyfin application. When a Abonnement is added to Hyfin, a request will be automatically generated and the customer will be notified via text message, email or both, as described under Who gets notified below. After submitting their payment method, the customer will automatically be charged based on the frequency of the recurring payment.

If the customer is viewing the Abonnement on their device and it gets updated, a message will display letting the customer know the Abonnement has been updated and the new version of the Abonnement will automatically be displayed on the customers device.

Qui est notifié

Chaque client est sous un seul contrôle des notifications, déterminé à partir du site et du client. Il n'est jamais enregistré et ne peut pas être défini directement.

  • Contrôle par contact : chaque adresse courriel et chaque numéro de téléphone des contacts du client porte son propre doNotContact indicateur, et cet indicateur est la seule chose qui arrête les messages automatiques envoyés à cette adresse ou à ce numéro. C'est le mode de contrôle des clients créés dans l'application, de tous les clients d'un site QuickBooks qui n'associe pas les modes de paiement aux notifications, et des intégrations sur l'API v4.
  • Contrôle par client : les notificationOptions du client (un choix pour chacun : courriel, message texte et WhatsApp) s'appliquent à chaque adresse de chaque contact. Un choix manquant signifie que le client est avisé. C'est le mode de contrôle de tous les clients d'un site QuickBooks qui associe les modes de paiement aux notifications, et des clients dont l'intégration a défini ces options dans une version antérieure à 4.0.

Sur l'API v4 :

  • Une écriture de client ou d'abonnement qui contient notificationOptions est refusée avec une erreur 400 et le message « notification_options is not accepted on API v4. Set do_not_contact on the contact emails and phone_numbers instead. »
  • Lors de l'écriture d'une facture, notificationOptions est obsolète et sera refusé dans une prochaine version. Il est toujours appliqué, exactement comme sur la version 3.1 : il devient les destinataires de la facture, send.to et la réponse réussit avec une entrée warnings . S'il est envoyé avec send.to il est refusé avec une erreur 400. Passez dès maintenant à send.to .
  • Une écriture de client sur un site non connecté à QuickBooks fait passer ce client au contrôle par contact. Ses options de notification sont copiées une seule fois sur doNotContact pour chaque adresse, puis supprimées, et les doNotContact valeurs de la requête sont appliquées ensuite.
  • Sur un site QuickBooks avec mapPaymentMethodsToNotifications activé, les modes de paiement QuickBooks déterminent les notifications de chaque client; une écriture de client qui contient doNotContact est donc refusée avec une erreur 400 qui nomme ce paramètre. Omettez l'indicateur, ou demandez au marchand de désactiver le paramètre.
  • onHold: false lors de l'écriture d'une facture ne libère pas une facture retenue parce qu'elle ne joint personne. Ajoutez-lui un destinataire pour permettre l'envoi.
  • La lecture d'un client ne renvoie jamais notificationOptions .

Point de terminaison

The following endpoint can be used to add or update a Abonnement. You must replace the {base_url} and {site_id} variable with the site id that was provided when the site was created.

POST
{base_url}/api/v4/site/{site_id}/subscription/addUpdate

Demande
Champ
Type
Description
externalId
String
Votre propre identifiant pour cet abonnement, provenant de votre logiciel. Envoyez à nouveau le même externalId pour mettre à jour cet abonnement au lieu d'en ajouter un nouveau. Nous faisons la correspondance sur cette valeur, mais nous n'empêchons pas les doublons; gardez-la donc unique au sein du site.
description
String
Une brève description des produits/services sur l'abonnement utilisé dans la demande de paiement affichée au client.
amount
Number
Le montant à facturer pour chaque période de facturation. Il s'agit d'un nombre entier de cents, donc 1035 signifie $10.35.
frequency
String
La fréquence de facturation. Bi-Weekly facture tous les 14 jours et Quarterly tous les 3 mois. Semi-Monthly facture deux fois par mois, le jour de début et le jour du mois situé à 14 jours d'écart : un début le 1er facture le 1er et le 15, et un début le 20 facture le 20 et le 6. Semi-Annually facture tous les 6 mois le jour de début. Un abonnement Monthly commencé du 29 au 31 est facturé le dernier jour d'un mois plus court et reste ensuite à ce jour.
One of Daily, Weekly, Bi-Weekly, Semi-Monthly, Monthly, Quarterly, Semi-Annually, Yearly
frequencyUnits
Number
Nombre d'unités de fréquence entre les versements. Ex. : frequency = Yearly et frequencyUnits = 2 signifie tous les 2 ans. S'applique uniquement à Daily, Weekly, Monthly et Yearly, et est ignoré pour les autres fréquences.
customer
Une référence au dossier du client.
startDate
La date de début de l'abonnement. Si laissée vide, elle sera définie lorsque le client confirme son mode de paiement. Une date sans heure. Une heure ou un fuseau horaire envoyé avec elle est ignoré, et non converti, de sorte que la date reste telle qu'écrite. Format = YYYY-MM-DD
numberOfPayments
Number
Le nombre de versements à effectuer. Si laissé vide, l'abonnement se poursuit indéfiniment ou jusqu'à ce qu'il soit fermé manuellement.
webhookUrl
String
L'URL à laquelle envoyer une requête POST lorsque certaines actions sont effectuées sur l'abonnement. Un webhook est envoyé lorsqu'un paiement atteint un nouvel état, et lorsqu'un message texte, un courriel ou un message WhatsApp est envoyé, livré, lu, retardé ou échoue, ou lorsque le client clique sur le lien de paiement.
attachmentRefs
Une liste de pièces jointes.
send
À qui Abonnement est envoyé, par canal. Un canal que vous indiquez est utilisé tel quel, et une liste vide ([]) désactive ce canal. Un canal que vous omettez conserve les destinataires que Abonnement a déjà, ou est rempli à partir des contacts du client, selon le contrôle des notifications du client, lorsqu'il n'en a pas encore. Lors d'une création, omettez send pour laisser les contacts du client décider de chaque canal lors de l'envoi de Abonnement. Lors d'une mise à jour, l'omettre conserve les destinataires déjà choisis. Une lecture renvoie send.to à null tant que les destinataires n'ont pas été choisis. billTo.emails et billTo.sms demeurent le remplacement pour déterminer qui reçoit ces canaux, mais ne réactivent jamais un canal que send a désactivé. Chaque Facture générée par l'abonnement est envoyée à ces destinataires, tels qu'ils sont au moment où cette Facture est générée; un changement s'applique donc aux Factures générées par la suite.
deleted
Boolean
Ce drapeau représente si l'enregistrement est supprimé et n'est plus disponible pour être utilisé.
			
{
  "externalId": "439772921",
  "description": "Gold+ Plan",
  "amount": 3499,
  "frequency": "Monthly",
  "frequencyUnits": 1,
  "customer": {
    "externalId": "39772634",
    "firstName": "John",
    "lastName": "Doe",
    "mobilePhone": "111-222-3333",
    "email": "johndoe@abc.com"
  },
  "webhookUrl": "https://yourcompany.com/webhook"
}


		
Réponse
Champ
Type
Description
success
Boolean
Whether the record was added or updated successfully.
action
String
Informs whether the record was added or updated. Will only be returned if success is true.
One of added, updated
_id
String
The id we assign to the record.
updatedAt
The date the record was last updated. Un moment précis en format ISO 8601, avec un fuseau horaire. Format = YYYY-MM-DDTHH:mm:ss.SSSZ
errors
String [ ]
A list of errors. Will only be returned if success is false.
link
String
Le lien que le client utilise pour confirmer son mode de paiement pour l'abonnement.
			
{
  "success": true,
  "action": "added",
  "_id": "60f720d248f143332af022e0",
  "updatedAt": "2025-05-30T19:19:44.143Z",
  "link": "https://site.url/KA39T1A45JL"
}


		

Voir aussi