comecerodocs
Subscription plans

Get a subscription plan

GET
/subscription_plans/{subscription_plan_id}

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.

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

Response Body

The 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 GET 'https://api.comecero.com/api/v1/subscription_plans/string'
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}

Create a subscription plan POST

Creates a subscription plan. Link it to a product (the product's `subscription_plan_id`) to sell that product as a subscription. Secret and trusted tokens may call it; a limited token may not (`403`).

Update a subscription plan POST

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