API Docs 3.1API Docs 4.0 SimpleAPI Docs 4.0

Add/Update Subscription

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 based on the notification options set on the customer record. 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.

Once the customer has accepted the Subscription, the record will become unable to be modified unless it is to close the Subscription.

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

The same endpoint is used to add or update a subscription. If the {_id} is provided, the subscription will be updated otherwise it will be inserted.
Request
Field
Type
Description
_id
String
The id of the subscription. This field is auto generated by the system and is not required when creating a new subscription, but it is required when updating an existing subscription.
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.
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.
customer
A reference to the customer record.
startDate
Date
The start date of the subscription. If left blank, it will be set when the customer confirms their payment method. 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.
attachmentRefs
A list of attachments.
billToCustomer
The customer to bill, if different than the customer.
billTo
Optional overrides for the Bill To section of the invoice. If billToCustomer is provided, this object will be merged with the customer's information and can be used to override specific fields. If billToCustomer is not provided, the fields in this object will be used as the Bill To information on the invoice.
soldTo
Optional overrides for the Sold To / Customer section of the invoice.
deleted
Boolean
This flag represents whether the record is deleted and no longer available to be used.
Sample Request
			
{
  "_id": "61f32dc2f62bdc6a48945067",
  "description": "Gold+ Plan",
  "amount": 3499,
  "frequency": "Monthly",
  "frequencyUnits": 1,
  "customer": {
    "_id": "61f32dc2f62bdc6a48951255",
    "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 auto generated id assigned to the record.
errors
String [ ]
A list of errors. Will only be returned if success is false.
Sample Response (Successful)
			
{
  "success": true,
  "action": "added",
  "_id": "60f720d248f143332af022e0"
}
Sample Response (Failed)
			
{
  "success": false,
  "errors": [
    "invalid field2",
    "missing field_name"
  ]
}