v51

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

Product Catalog

New draft plan

Create a new draft version from plan. It returns error if there is already a plan in draft or planId does not reference the latest published version.

post/api/v1/plans/{planIdOrKey}/next

Path parameters

planIdOrKeystring required

Response

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

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.

keystring required

A semi-unique identifier for the resource.

versioninteger required

Version of the plan. Incremented when the plan is updated.

currencystring required

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

billingCadencestring duration required

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

effectiveFromstring date-time

The date and time when the plan becomes effective. When not specified, the plan is a draft.

effectiveTostring date-time

The date and time when the plan is no longer effective. When not specified, the plan is effective indefinitely.

status'draft' | 'active' | 'archived' | 'scheduled' required

The status of a plan.

settlementMode'credit_then_invoice' | 'credit_only'

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",
  "currency": "USD",
  "billingCadence": "P1M",
  "effectiveFrom": "2023-01-01T01:01:01.001Z",
  "effectiveTo": "2023-01-01T01:01:01.001Z",
  "phases": [
    {
      "metadata": {
        "externalId": "019142cc-a016-796a-8113-1a942fecd26d"
      },
      "duration": "P1Y",
      "rateCards": [
        {
          "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
            }
          }
        }
      ]
    }
  ],
  "validationErrors": [
    {
      "field": "addons/pro/ratecards/token/featureKey",
      "code": "invalid_feature_key",
      "message": "not found feature by key",
      "attributes": {
        "externalId": "019142cc-a016-796a-8113-1a942fecd26d"
      }
    }
  ]
}