Pause immediately or schedule a pause for the end of the current billing or trial period. Set durationDays to null for an indefinite pause.
Pause immediately or schedule a pause for the end of the current billing or trial period. Set durationDays to null for an indefinite pause.
ApiKeyAuth In: header
Unique key used to safely retry this write for 24 hours without applying it twice.
1 <= length <= 200application/json
TypeScript Definitions
Use the request body type in TypeScript.
application/json
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/string/pause" \ -H "Content-Type: application/json" \ -d '{ "mode": "immediate", "durationDays": 1 }'{ "id": "sub_1a2b3c4d", "customerId": "cus_1a2b3c4d", "plan": { "id": "plan_1a2b3c4d", "name": "Pro", "basePrice": 2000 }, "name": "Pro", "description": null, "status": "paused", "billingInterval": "monthly", "trialEndsAt": null, "currentPeriod": { "start": "2026-09-07T12:00:00.000Z", "end": "2026-10-07T12:00:00.000Z", "daysRemaining": 30 }, "cancellation": null, "cancelAtPeriodEnd": false, "scheduledPlanChange": null, "startDate": "2026-09-07T12:00:00.000Z", "endDate": null, "billingDayOfMonth": 7, "nextBillingDate": null, "checkoutUrl": null, "createdAt": "2026-09-07T12:00:00.000Z", "updatedAt": "2026-09-07T12:00:00.000Z", "offerApplications": [], "pause": { "status": "active", "mode": "immediate", "requestedAt": "2026-09-07T12:00:00.000Z", "effectiveAt": "2026-09-07T12:00:00.000Z", "resumeAt": "2026-10-07T12:00:00.000Z" }, "priceId": "price_1a2b3c4d", "object": "subscription", "livemode": false, "consumptionModel": "metered", "features": [ { "code": "api_calls", "name": "API Calls", "type": "usage", "usage": { "current": 250, "included": 1000, "overageQuantity": 0, "unlimited": false } } ], "credits": null, "balance": null}{ "error": { "type": "validation_error", "code": "validation_error", "message": "The request contains an invalid parameter.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" }}{ "error": { "type": "authentication_error", "code": "unauthorized", "message": "A valid API key is required.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/unauthorized.md" }}{ "error": { "type": "authentication_error", "code": "forbidden", "message": "You do not have permission to perform this operation.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/forbidden.md" }}{ "error": { "type": "not_found_error", "code": "not_found", "message": "The requested resource was not found.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/not_found.md" }}{ "error": { "type": "conflict_error", "code": "idempotency_in_progress", "message": "A request with this idempotency key is still being processed.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_in_progress.md" }}{ "error": { "type": "validation_error", "code": "validation_error", "message": "The requested operation is not valid for the current configuration.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/validation_error.md" }}{ "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Retry after the interval specified in the Retry-After header.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/rate_limited.md" }}{ "error": { "type": "internal_error", "code": "internal_error", "message": "An unexpected error occurred while processing the request.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/internal_error.md" }}{ "error": { "type": "internal_error", "code": "idempotency_unavailable", "message": "Idempotency storage is temporarily unavailable. Retry with the same idempotency key.", "doc_url": "https://commet.co/docs/api-reference/2026-08-27/errors/idempotency_unavailable.md" }}List subscriptions GET
List all subscriptions. Filter by customer ID or status.
Preview plan change POST
Preview proration details for an immediate plan change without applying it. Free-to-paid changes are never scheduled and the change-plan endpoint always returns hosted checkout for them. For paid plans, interval direction takes precedence: a longer interval is immediate and a shorter interval is scheduled. When the interval is unchanged, a higher-sort-order plan is immediate and a lower-sort-order plan is scheduled. A paid-to-free change is always scheduled. Returns credit, charge, and net amount. The target plan must belong to the same plan group as the current plan, otherwise a 400 with code `plans_not_in_same_group` is returned. A change between two free plans has nothing to prorate and returns a zero-amount estimate. Scheduled changes return a 400 with code `plan_change_scheduled`; apply those via the change-plan endpoint. Pass offerId to quote the destination plan with an Offer.
Value in