comecerodocs
Subscription plans

Create a subscription plan

POST
/subscription_plans

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

Authorization

headerAuthorizationBearer <token>

A secret, trusted or limited token. See Authentication.

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

A new subscription plan.

name*string

The plan name, for your own reference.

Length1 <= length <= 75
description?string

A description, for your own reference.

Lengthlength <= 256
billing_interval*integer

How many billing_interval_unit make one billing period. Maximum: 365 days, 24 months, 2 years, 24 hours, 60 minutes (minute plans need at least 5).

Range1 <= value
billing_interval_unit*string

The unit of the billing period. hour and minute are only allowed with a test token, and minute only outside production.

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

Stop billing after this many billings. Leave it out or send null to bill until cancelled.

Range1 <= value
trial_interval?|

The trial length in trial_interval_unit. Maximum: 365 days, 12 months, 1 year, 24 hours, 60 minutes. Leave it out or send null for no trial.

Range1 <= value
trial_interval_unit?|

The unit of the trial. Required when trial_interval is sent.

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

Any data you want to store on the plan, up to 2,048 characters.

Response Body

The new 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.

curl -X POST 'https://api.comecero.com/api/v1/subscription_plans' \  -H 'Content-Type: application/json' \  -d '{  "name": "Monthly, 14-day trial",  "billing_interval": 1,  "billing_interval_unit": "month",  "trial_interval": 14,  "trial_interval_unit": "day"}'
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}

List subscription plans GET

Lists the subscription plans in your account. Deleted plans are not listed. The list is offset-based. Secret and trusted tokens may call it; a limited token may not (`403`).

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.