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

Required

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.

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. Format = 0.00

frequency

String

The billing frequency.
One of `Daily`, `Weekly`, `Bi-Weekly`, `Semi-Monthly`, `Monthly`, `Quarterly`, `Semi-Annually`, `Yearly`

frequency_units

Number

Number of frequency units between installments. Ex: `frequency = Yearly` and `frequency_units = 2` means every 2 years.

customer

A reference to the customer record.

start_date

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

number_of_payments

Number

The number of installments to be made. If left blank, the subscription continues indefinitely or until manually closed.

active

Boolean

Whether the subscription is active. Setting to `false` will irreversibly close the subscription if the customer has already accepted it.
Default = `true`

webhook_url

String

The url to post to when certain actions are performed on the subscription.

attachment_refs

A list of attachments.

bill_to_customer

The customer to bill, if different than the customer.

bill_to

Optional overrides for the Bill To section of the invoice. If bill_to_customer is provided, this object will be merged with the customer's information and can be used to override specific fields. If bill_to_customer is not provided, the fields in this object will be used as the Bill To information on the invoice.

sold_to

Optional overrides for the Sold To / Customer section of the invoice.

Sample Request

			
				{
  "_id": "61f32dc2f62bdc6a48945067",
  "description": "Gold+ Plan",
  "amount": 34.99,
  "frequency": "Monthly",
  "frequency_units": 1,
  "customer": {
    "_id": "61f32dc2f62bdc6a48951255",
    "first_name": "John",
    "last_name": "Doe",
    "mobile_phone": "111-222-3333",
    "email": "johndoe@abc.com"
  },
  "webhook_url": "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"
  ]
}