comecerodocs
Subscription plans

Update a subscription plan

POST
/subscription_plans/{subscription_plan_id}

Changes a subscription plan. Only new subscriptions use the new values; existing subscriptions keep what they copied when they were made. Secret and trusted tokens may call it; a limited token may not (403).

Authorization

headerAuthorizationBearer <token>

A secret, trusted or limited token. See Authentication.

Path Parameters

subscription_plan_id*string

The subscription plan id.

Query Parameters

show?string

Comma-separated fields to return; all others are left out. Use dot notation for child fields (customer.email). You cannot send show and hide together (400). See Customizing output.

hide?string

Comma-separated fields to leave out of the response. Use dot notation for child fields (customer.email). You cannot send show and hide together (400). See Customizing output.

formatted?boolean

When true, the object also has a formatted child with amounts and dates as display text in the shopper's language and currency (for example $19.99 or November 7, 2026). The default is false. See Localized formatting.

Defaultfalse

Request Body

application/json
  1. body

Changes to a subscription plan. Send only the fields to change. Existing subscriptions keep the values they copied when they were made.

name?string

The plan name.

Lengthlength <= 75
description?string

A description.

Lengthlength <= 256
billing_interval?integer

How many billing_interval_unit make one billing period. Same limits as on create.

Range1 <= value
billing_interval_unit?string

The unit of the billing period. hour and minute only with a test token.

Value in"day""month""year""hour""minute"
end_at_billing_count?|

Stop billing after this many billings. null removes the limit.

Range1 <= value
trial_interval?|

The trial length. null removes the trial (and its unit).

Range1 <= value
trial_interval_unit?|

The unit of the trial. null removes the trial.

Value in"day""month""year""hour""minute"null
meta?unknown

Any data you want to store on the plan. Replaces the old value.

Response Body

The updated plan.

application/json
  1. response

The billing rules a subscription product follows: how often it bills, any free trial, and how many billings before it stops. A subscription copies these values when it is made, so later changes to a plan only affect new subscriptions.

object*"subscription_plan"

The object type. Always subscription_plan.

Value in"subscription_plan"
url*string

The full URL of this plan.

Formaturi
subscription_plan_id*string

The plan id.

date_created*string

When the plan was created.

Formatdate-time
date_modified*string

When the plan was last changed.

Formatdate-time
test*boolean

true for a test plan, false for a live one.

account_id*string

The account the plan belongs to.

name?string

The plan name, for your own reference. Not returned to a limited token.

description?|

A description, for your own reference. Not returned to a limited token.

billing_interval*integer

How many billing_interval_unit make one billing period.

billing_interval_unit*string

The unit of the billing period. hour and minute are only allowed on test plans, and minute only outside production.

Value in"minute""hour""day""month""year"
billing_interval_description*string

The billing period as text, for example 1 month or 3 months.

end_at_billing_count*|

The number of billings after which a subscription completes. null means it bills until cancelled.

trial_interval*|

The trial length in trial_interval_unit. null when there is no trial.

trial_interval_unit*|

The unit of the trial. null when there is no trial.

Value in"minute""hour""day""month""year"null
trial_interval_description*|

The trial length as text, for example 14 days. null when there is no trial.

deleted?boolean

true once the plan is deleted. Not returned to a limited token.

date_deleted?|

When the plan was deleted. Not returned to a limited token.

Formatdate-time
meta?unknown

Any data you stored on the plan. Not returned to a limited token.

formatted?

The dates as display text. Only returned with formatted=true.

Example Request
curl -X POST 'https://api.comecero.com/api/v1/subscription_plans/string' \  -H 'Content-Type: application/json' \  -d '{  "name": "Monthly, 30-day trial",  "trial_interval": 30}'
Example Response
{  "object": "subscription_plan",  "url": "https://api.comecero.com/api/v1/subscription_plans/0093472113202Spzs4AV8C",  "subscription_plan_id": "0093472113202Spzs4AV8C",  "date_created": "2026-09-18T20:28:33Z",  "date_modified": "2026-09-18T20:28:33Z",  "test": true,  "account_id": "AB1234",  "name": "Monthly, 14-day trial",  "description": null,  "billing_interval": 1,  "billing_interval_unit": "month",  "billing_interval_description": "1 month",  "end_at_billing_count": null,  "trial_interval": 14,  "trial_interval_unit": "day",  "trial_interval_description": "14 days",  "deleted": false,  "date_deleted": null,  "meta": null}

Get a subscription plan GET

Returns one subscription plan. Secret, trusted and limited tokens may call it. A limited token gets the billing fields only: `name`, `description`, `deleted`, `date_deleted` and `meta` are left out.

Delete a subscription plan DELETE

Retires a subscription plan: it is marked `deleted` and leaves the plan list, but you can still get it by id. Subscriptions already on the plan keep billing as before. Core does not check whether products still use the plan, so move those products first. Secret and trusted tokens may call it; a limited token may not (`403`).