• Pricing
  • Blog
Log inBook a demo
Adjust balance POSTApply an Offer to a subscription PUTCancel subscription POSTChange plan POSTCreate a recovery payment link for a past due subscription POSTCreate subscription POSTGet active subscription GETGet subscription by ID GETList subscriptions GETPreview plan change POSTReactivate a past due or canceled subscription POSTRemove an Offer from a pending checkout DELETETop up balance POSTRevert scheduled cancellation POSTUpdate payment method POST
System status
DocumentationKnowledge BaseBuild with AIAPI ReferenceWebhooks

Create subscription

Create a subscription for a customer. Commet selects the default price when priceId is omitted and resolves its market from the customer's billing country. Without an offer override, Commet applies the price's automatic introductory Offer. Pass offerId to apply an active compatible Offer directly, or cardPromotionId to preselect a card-eligible Promotional Offer for the initial checkout when card promotions are enabled for the organization. For the initial checkout, provider accepts either a processor name or an exact payment connection ID.

POST
/subscriptions

Create a subscription for a customer. Commet selects the default price when priceId is omitted and resolves its market from the customer's billing country. Without an offer override, Commet applies the price's automatic introductory Offer. Pass offerId to apply an active compatible Offer directly, or cardPromotionId to preselect a card-eligible Promotional Offer for the initial checkout when card promotions are enabled for the organization. For the initial checkout, provider accepts either a processor name or an exact payment connection ID.

Authorization

ApiKeyAuth
x-api-key<token>

In: header

Header Parameters

Idempotency-Key?string

Unique key used to safely retry this write for 24 hours without applying it twice.

Length1 <= length <= 200

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/subscriptions" \  -H "Content-Type: application/json" \  -d '{    "customerId": "string",    "planId": "string"  }'
{  "id": "string",  "customerId": "string",  "plan": {    "id": "string",    "name": "string"  },  "name": "string",  "description": "string",  "status": "draft",  "billingInterval": "weekly",  "trialEndsAt": "2019-08-24T14:15:22Z",  "currentPeriod": {    "start": "2019-08-24T14:15:22Z",    "end": "2019-08-24T14:15:22Z",    "daysRemaining": 0  },  "cancellation": {    "scheduledAt": "2019-08-24T14:15:22Z",    "reason": "string",    "effectiveAt": "2019-08-24T14:15:22Z"  },  "cancelAtPeriodEnd": true,  "scheduledPlanChange": {    "changeType": "plan_downgrade",    "newPlanId": "string",    "newPlanName": "string",    "newBillingInterval": "string",    "scheduledFor": "2019-08-24T14:15:22Z"  },  "startDate": "2019-08-24T14:15:22Z",  "endDate": "2019-08-24T14:15:22Z",  "billingDayOfMonth": -9007199254740991,  "nextBillingDate": "2019-08-24T14:15:22Z",  "checkoutUrl": "string",  "createdAt": "2019-08-24T14:15:22Z",  "updatedAt": "2019-08-24T14:15:22Z",  "offerApplications": [    {      "id": "string",      "name": "string",      "appliesTo": {        "type": "plan_price",        "id": "string"      },      "offerId": "string",      "source": "direct",      "status": "quoted",      "currency": "string",      "subtotal": -9007199254740991,      "discountAmount": -9007199254740991,      "total": -9007199254740991,      "phases": [        {          "type": "free_trial",          "durationDays": 1,          "durationInterval": "weekly",          "startsAt": "2019-08-24T14:15:22Z",          "endsAt": "2019-08-24T14:15:22Z"        }      ],      "quotedAt": "2019-08-24T14:15:22Z",      "expiresAt": "2019-08-24T14:15:22Z",      "appliedAt": "2019-08-24T14:15:22Z"    }  ],  "checkoutProvider": "stripe",  "priceId": "string",  "object": "subscription",  "livemode": true}
{  "error": {    "type": "string",    "code": "string",    "message": "string",    "param": "string",    "details": null,    "doc_url": "string"  }}
{  "error": {    "type": "string",    "code": "string",    "message": "string",    "param": "string",    "details": null,    "doc_url": "string"  }}
{  "error": {    "type": "string",    "code": "string",    "message": "string",    "param": "string",    "details": null,    "doc_url": "string"  }}
{  "error": {    "type": "string",    "code": "string",    "message": "string",    "param": "string",    "details": null,    "doc_url": "string"  }}
{  "error": {    "type": "string",    "code": "string",    "message": "string",    "param": "string",    "details": null,    "doc_url": "string"  }}
{  "error": {    "type": "string",    "code": "string",    "message": "string",    "param": "string",    "details": null,    "doc_url": "string"  }}
{  "error": {    "type": "string",    "code": "string",    "message": "string",    "param": "string",    "details": null,    "doc_url": "string"  }}
{  "error": {    "type": "string",    "code": "string",    "message": "string",    "param": "string",    "details": null,    "doc_url": "string"  }}

Create a recovery payment link for a past due subscription POST

Generates a hosted, signed recovery link that lets the customer pay the outstanding renewal charge for a past_due subscription. Unlike reactivate, which charges server-to-server, this returns a link the merchant can deliver through their own email, SMS, or dashboard. The link carries a self-contained signed token and stays valid until the charge is paid or the subscription is no longer past due.

Get active subscription GET

Get the active subscription for a customer. Returns null if none.

customerId*string
Length1 <= length <= 200
billingInterval?|null
priceId?string

Public price ID. When omitted, Commet selects the default price for the billing interval and still applies its market pricing.

Length1 <= length
initialSeats?
provider?|

Payment provider name or exact public payment connection ID for the initial checkout. Overrides country routing when present.

name?string
startDate?string
Formatdate-time
successUrl?string
Formaturi
offerId?not (unknown)
promoCode?string
Length1 <= length
customTrialDays?integer
Range0 <= value <= 9007199254740991
skipTrial?boolean
Defaultfalse
planId*string
Length1 <= length