Sign in

v51

latestOpenAPI 3.0.0Apache 2.0raw.githubusercontent.com2026-08-011534301009.2 KB
Subscriptions

Edit subscription

Batch processing commands for manipulating running subscriptions. The key format is /phases/{phaseKey} or /phases/{phaseKey}/items/{itemKey}.

patch/api/v1/subscriptions/{subscriptionId}

Path parameters

subscriptionIdstring required
Example:01G65Z755AFWAKHE12NY0CQ9FH

Request body

Example request

{
  "customizations": [
    {
      "rateCard": {
        "metadata": {
          "externalId": "019142cc-a016-796a-8113-1a942fecd26d"
        },
        "entitlementTemplate": {
          "metadata": {
            "externalId": "019142cc-a016-796a-8113-1a942fecd26d"
          }
        },
        "taxConfig": {
          "stripe": {
            "code": "txcd_10000000"
          },
          "taxCodeId": "01G65Z755AFWAKHE12NY0CQ9FH"
        },
        "discounts": {
          "percentage": {
            "percentage": 50
          }
        }
      }
    }
  ],
  "timing": "2023-01-01T01:01:01.001Z"
}

Response

The request has succeeded.

idstring required

A unique identifier for the resource.

namestring required

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

descriptionstring

Optional description of the resource. Maximum 1024 characters.

metadataMetadata

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

createdAtstring date-time required

Timestamp of when the resource was created.

updatedAtstring date-time required

Timestamp of when the resource was last updated.

deletedAtstring date-time

Timestamp of when the resource was permanently deleted.

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.

status'active' | 'inactive' | 'canceled' | 'scheduled' required

Subscription status.

customerIdstring required

The customer ID of the subscription.

currencystring required

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

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).

billingAnchorstring date-time required

The normalizedbilling anchor of the subscription.

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.

Example response

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