Field
Type
Description
_id
The id we assign to this subscription. Leave it out when creating a subscription, and send it when updating one.
externalId
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.
frequency
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 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.
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
The number of installments to be made. If left blank, the subscription continues indefinitely or until manually closed.
status
The current status of the subscription.
One of pending, active, paused, failed, closed
webhookUrl
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.
customer
The _id of the customer
code
The unique code used in the customer-facing link to the subscription.
lines
The line items on each invoice the subscription creates. A request that only sends amount and description gets a single recurring line built from them.
totalsRecurring
The totals of each recurring invoice. total is the amount charged each billing period.
totalsFirstInvoice
The totals of the first invoice, which also includes any one-time lines.
billToCustomer
The _id of the customer who receives and pays the invoice.
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
This flag represents whether the record is deleted and no longer available to be used.