Subscriptions

This resource represents a subscription. A subscription can be created using a template or by specifying individual line items. Subscriptions can be configured to automatically charge or send invoices based on the specified billing interval. All amounts are in the minor unit of the currency. For example, 1000 represents $10.00 for USD, £10.00 for GBP, or ¥1000 for JPY.

Properties

id string The unique identifier for this subscription.

createdAt string The date this subscription was created in RFC3339 format.

updatedAt string The date this subscription was updated in RFC3339 format.

object string The object type of this resource.

collectionMethod string How the payment for this subscription is collected. One of:

• chargeAutomatically - Charges are automatically processed
• sendInvoice - Invoices are sent to the recipient for payment

status string The status of the invoice. One of active, canceled, notStarted

recipientId string Deprecated in favor of clientId and companyId.

clientId string The ID of the client this subscription is assigned to.

companyId string The ID of the company this subscription is assigned to. When the subscription is assigned to an individual this represents which of the client’s companies this item is associated with.

memo string An arbitrary string attached to the subscription, often useful for displaying to users.

taxPercentage number The percentage of tax applied to the subscription amount.

currency string The 3 letter currency code representing the settlement currency for this subscription.

interval string The billing frequency of the subscription. One of:

• day - Daily billing
• week - Weekly billing
• month - Monthly billing
• yearly - Yearly billing

intervalCount integer The number of intervals between subscription billings. For example, interval=month and intervalCount=3 bills every 3 months.

daysUntilDue integer Number of days after invoice creation until the invoice is due.

canceledAt string | null The date when this subscription was canceled in RFC3339 format.

paymentMethodPreferences Array(object) Array of payment method configurations that specify which payment methods are allowed and how transaction fees are handled for each method.

Each object in the array contains:

• type string - Payment method type. Values are creditCard or bankAccount
• feePaidByClient boolean - When true, the transaction fee is paid by the client. When false, the fee is absorbed by the business.

lineItems array(lineItems)

• amount string  The amount for a single unit of this line item. The total amount due for this line item is the product of this amount and quantity
• description string The description given to this line item
• quantity string How many units of this item are being invoiced
• priceId string The ID of the price that this line item is based off. The amount property is set based on the amount of specified on the Price. This is not relevant for one-off line items.
• productId string The ID of the product that this line item is based off. The description property is set based on the description of set on the product. This is not relevant for one-off line items.

{
    "id": "sub_01HN4V8K5P7RNQJ6MGXKDZ8T2W",
    "object": "subscription",
    "createdAt": "2024-02-21T15:31:16.789Z",
    "status": "active",
    "clientId": "d0000000-d7a5-473d-a75b-9821a8f4e180",
    "companyId": "04a818c2-d035-495c-9cc2-06a11a8b91f6",
    "collectionMethod": "sendInvoice",
    "memo": "Monthly service subscription",
    "taxPercentage": 8.5,
    "currency": "USD",
    "interval": "month",
    "intervalCount": 1,
    "daysUntilDue": 30,
    "canceledAt": "2024-02-21T15:31:16.789Z",
    "paymentMethodPreferences": [
        {
            "type": "creditCard",
            "feePaidByClient": false
        },
        {
            "type": "bankAccount",
            "feePaidByClient": true
        }
    ],
    "lineItems": [
        {
            "priceId": "K5P7RNQJ6",
            "productId": "d0000000-d7a5-473d-a75b-9821a8f4e191",
            "description": "Professional Plan",
            "quantity": 1
        },
        {
            "amount": 5000,
            "description": "Additional Storage",
            "quantity": 2
        }
    ],
    "updatedAt": "2024-02-21T15:31:16.789Z"
}