Sign in
Subscriptions

Create subscription

post/api/v1/subscriptions

Request body

OR

Example request

{
  "billingAnchor": "2023-01-01T01:01:01.001Z",
  "customerId": "01G65Z755AFWAKHE12NY0CQ9FH",
  "metadata": {
    "externalId": "019142cc-a016-796a-8113-1a942fecd26d"
  },
  "timing": "2023-01-01T01:01:01.001Z"
}

Response

The request has succeeded and a new resource has been created as a result.

activeFromstring date-time required

The cadence start of the resource.

activeTostring date-time

The cadence end of the resource.

annotationsAnnotations

Set of key-value pairs managed by the system. Cannot be modified by user.

billingAnchorstring date-time required

The normalizedbilling anchor of the subscription.

billingCadencestring duration required

The billing cadence for the subscriptions. Defines how often customers are billed using ISO8601 duration format. Examples: "P1M" (monthly), "P3M" (quarterly), "P1Y" (annually).

costBasisMode'dynamic' | 'pinned' required

Controls how custom-currency cost bases are selected for the subscription.

createdAtstring date-time required

Timestamp of when the resource was created.

currencystring required

Three-letter ISO4217 currency code. Custom three-letter currency codes are also supported for convenience.

customerIdstring required

The customer ID of the subscription.

deletedAtstring date-time

Timestamp of when the resource was permanently deleted.

descriptionstring

Optional description of the resource. Maximum 1024 characters.

idstring required

A unique identifier for the resource.

metadataMetadata

Set of key-value pairs. Metadata can be used to store additional information about a resource.

namestring required

Human-readable name for the resource. Between 1 and 256 characters.

settlementMode'credit_then_invoice' | 'credit_only' required

The settlement mode of a plan. It determines how the billing system generates invoices and credits for the subscriptions using this plan.

  • credit_then_invoice: credits from the previous billing period are applied first, then the remaining balance is invoiced. This is the default and most common settlement mode.
  • credit_only: only credits from the previous billing period are generated and applied. No invoices are generated for the subscription.
status'active' | 'inactive' | 'canceled' | 'scheduled' required

Subscription status.

updatedAtstring date-time required

Timestamp of when the resource was last updated.

Example response

{
  "activeFrom": "2023-01-01T01:01:01.001Z",
  "activeTo": "2023-01-01T01:01:01.001Z",
  "annotations": {
    "externalId": "019142cc-a016-796a-8113-1a942fecd26d"
  },
  "billingAnchor": "2023-01-01T01:01:01.001Z",
  "billingCadence": "P1M",
  "costBasisPins": [
    {
      "costBasisId": "01G65Z755AFWAKHE12NY0CQ9FH",
      "customCurrencyId": "01G65Z755AFWAKHE12NY0CQ9FH",
      "invoiceCurrency": "USD"
    }
  ],
  "createdAt": "2024-01-01T01:01:01.001Z",
  "currency": "USD",
  "customerId": "01G65Z755AFWAKHE12NY0CQ9FH",
  "deletedAt": "2024-01-01T01:01:01.001Z",
  "id": "01G65Z755AFWAKHE12NY0CQ9FH",
  "metadata": {
    "externalId": "019142cc-a016-796a-8113-1a942fecd26d"
  },
  "plan": {
    "id": "01G65Z755AFWAKHE12NY0CQ9FH"
  },
  "updatedAt": "2024-01-01T01:01:01.001Z"
}

Changes

No recorded changes to this endpoint across all 1 revision of this API.