Add/Update Subscription

Use this when a customer should be billed the same amount on a schedule, such as monthly service.


The following endpoint can be used to add or update a Subscription within the Hyfin application. When a Subscription 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 Subscription on their device and it gets updated, a message will display letting the customer know the Subscription has been updated and the new version of the Subscription will automatically be displayed on the customers device.

Who gets notified

Each customer is under exactly one notification control, worked out from the site and the customer. It is never stored and cannot be set directly.

  • Contact control : each email address and phone number on the customer's contacts carries its own doNotContact flag, and that flag is the only thing that stops automatic messages to it. This is the control for customers created in the app, for every customer on a QuickBooks site that does not map payment methods to notifications, and for integrations on API v4.
  • Customer control : the customer's notificationOptions (one choice each for email, text message and WhatsApp) decide for every address of every contact. A missing choice means notify. This is the control for every customer on a QuickBooks site that maps payment methods to notifications, and for customers whose integration set those options on a version before 4.0.

On API v4:

  • A customer or subscription write that carries notificationOptions is refused with a 400 and the message "notification_options is not accepted on API v4. Set do_not_contact on the contact emails and phone_numbers instead."
  • On an invoice write, notificationOptions is deprecated and will be refused in a future release. It is still applied, exactly as on 3.1: it becomes the invoice's send.to recipients, and the response succeeds with a warnings entry. Sent together with send.to it is refused with a 400. Move to send.to now.
  • A customer write on a site that is not connected to QuickBooks moves that customer to contact control. Its notification options are copied onto doNotContact on every address once, then removed, and the doNotContact values in the request are applied after that.
  • On a QuickBooks site with mapPaymentMethodsToNotifications on, QuickBooks payment methods decide notifications for every customer, so a customer write that carries doNotContact is refused with a 400 that names that setting. Leave the flag out, or have the merchant turn the setting off.
  • onHold: false on an invoice write does not release an invoice that is held because it reaches nobody. Give it a recipient to let it send.
  • The customer read never returns notificationOptions .

Endpoint

The following endpoint can be used to add or update a Subscription. 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

Request
Field
Type
Description
externalId
String
Your own id for this subscription, from your software. Send the same externalId again to update this subscription instead of adding a new one. We match on this value but do not stop duplicates, so keep it unique within the site.
description
String
A short description of the products/services on the subscription used in the payment request displayed to the customer.
amount
Number
The amount to charge for each billing period. This is an integer number of cents, so 1035 means $10.35.
frequency
String
The billing frequency. Bi-Weekly bills every 14 days and Quarterly every 3 months. Semi-Monthly bills twice a month, on the start day and on the day of the month 14 away from it: a start on the 1st bills the 1st and 15th, and a start on the 20th bills the 20th and the 6th. Semi-Annually bills every 6 months on the start day. A Monthly subscription started on the 29th to 31st bills on the last day of a shorter month and stays on that day afterwards.
One of Daily, Weekly, Bi-Weekly, Semi-Monthly, Monthly, Quarterly, Semi-Annually, Yearly
frequencyUnits
Number
Number of frequency units between installments. Ex: frequency = Yearly and frequencyUnits = 2 means every 2 years. Only applies to Daily, Weekly, Monthly and Yearly, and is ignored for the other frequencies.
customer
A reference to the customer record.
startDate
The start date of the subscription. If left blank, it will be set when the customer confirms their payment method. A date without a time. A time or time zone sent with it is dropped, not converted, so the date stays as written. Format = YYYY-MM-DD
numberOfPayments
Number
The number of installments to be made. If left blank, the subscription continues indefinitely or until manually closed.
webhookUrl
String
The url to post to when certain actions are performed on the subscription. A webhook is sent when a payment reaches a new status, and when a text message, email or WhatsApp message is sent, delivered, read, delayed or fails, or the customer clicks the payment link.
attachmentRefs
A list of attachments.
send
Who the subscription is sent to, per channel. A channel you list is used as given, and an empty list ([]) turns that channel off. A channel you omit keeps the recipients the subscription already has, or is filled from the customer's contacts, following the customer's notification control, when it has none yet. On a create, leave send out to let the customer's contacts decide every channel when the subscription is sent. On an update, leaving it out keeps the recipients already chosen. A read returns send.to as null until recipients have been chosen. billTo.emails and billTo.sms stay the override for who receives those channels, but never turn back on a channel send turned off. Every invoice the subscription generates is sent to these recipients, as they stand when that invoice is generated, so a change applies to invoices generated afterwards.
deleted
Boolean
This flag represents whether the record is deleted and no longer available to be used.
			
{
  "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"
}


		
Response
Field
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. A moment in time in ISO 8601, with a time zone. Format = YYYY-MM-DDTHH:mm:ss.SSSZ
errors
String [ ]
A list of errors. Will only be returned if success is false.
link
String
The link the customer uses to confirm their payment method for the subscription.
			
{
  "success": true,
  "action": "added",
  "_id": "60f720d248f143332af022e0",
  "updatedAt": "2025-05-30T19:19:44.143Z",
  "link": "https://site.url/KA39T1A45JL"
}


		

Related