Product Catalog

Update a plan

Update plan by id.

put/api/v1/plans/{planId}

Path parameters

planIdstring required

Example:01G65Z755AFWAKHE12NY0CQ9FH

Request body

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

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.

namestring required

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

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 request

{
  "billingCadence": "P1M",
  "metadata": {
    "externalId": "019142cc-a016-796a-8113-1a942fecd26d"
  },
  "phases": [
    {
      "duration": "P1Y",
      "metadata": {
        "externalId": "019142cc-a016-796a-8113-1a942fecd26d"
      },
      "rateCards": [
        {
          "discounts": {
            "percentage": {
              "percentage": 50
            }
          },
          "entitlementTemplate": {
            "metadata": {
              "externalId": "019142cc-a016-796a-8113-1a942fecd26d"
            }
          },
          "metadata": {
            "externalId": "019142cc-a016-796a-8113-1a942fecd26d"
          },
          "taxConfig": {
            "stripe": {
              "code": "txcd_10000000"
            },
            "taxCodeId": "01G65Z755AFWAKHE12NY0CQ9FH"
          }
        }
      ]
    }
  ]
}

Response

The request has succeeded.

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

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.

deletedAtstring date-time

Timestamp of when the resource was permanently deleted.

descriptionstring

Optional description of the resource. Maximum 1024 characters.

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.

idstring required

A unique identifier for the resource.

keystring required

A semi-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'

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'draft' | 'active' | 'archived' | 'scheduled' required

The status of a plan.

updatedAtstring date-time required

Timestamp of when the resource was last updated.

versioninteger required

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

Example response

{
  "billingCadence": "P1M",
  "createdAt": "2024-01-01T01:01:01.001Z",
  "currency": "USD",
  "deletedAt": "2024-01-01T01:01:01.001Z",
  "effectiveFrom": "2023-01-01T01:01:01.001Z",
  "effectiveTo": "2023-01-01T01:01:01.001Z",
  "id": "01G65Z755AFWAKHE12NY0CQ9FH",
  "metadata": {
    "externalId": "019142cc-a016-796a-8113-1a942fecd26d"
  },
  "phases": [
    {
      "duration": "P1Y",
      "metadata": {
        "externalId": "019142cc-a016-796a-8113-1a942fecd26d"
      },
      "rateCards": [
        {
          "discounts": {
            "percentage": {
              "percentage": 50
            }
          },
          "entitlementTemplate": {
            "metadata": {
              "externalId": "019142cc-a016-796a-8113-1a942fecd26d"
            }
          },
          "metadata": {
            "externalId": "019142cc-a016-796a-8113-1a942fecd26d"
          },
          "taxConfig": {
            "stripe": {
              "code": "txcd_10000000"
            },
            "taxCodeId": "01G65Z755AFWAKHE12NY0CQ9FH"
          }
        }
      ]
    }
  ],
  "updatedAt": "2024-01-01T01:01:01.001Z",
  "validationErrors": [
    {
      "attributes": {
        "externalId": "019142cc-a016-796a-8113-1a942fecd26d"
      },
      "code": "invalid_feature_key",
      "field": "addons/pro/ratecards/token/featureKey",
      "message": "not found feature by key"
    }
  ]
}

Changes

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