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.

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
The id of the recipient of the subscription. This can either be a Client or a Company.

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",
    "collectionMethod": "sendInvoice",
    "status": "active",
    "recipientId": "d0000000-d7a5-473d-a75b-9821a8f4e180",
    "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
        }
    ]
}