curl --request PATCH \
--url https://api.sandbox.cheqpay.mx/pos/v1/subscriptions/{id}/plan \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--header 'x-merchant-id: <api-key>' \
--data '
{
"newPlanId": "123e4567-e89b-12d3-a456-426614174010",
"prorationBehavior": "create_prorations"
}
'{
"subscription": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"merchantId": "merchant_123",
"customerId": "123e4567-e89b-12d3-a456-426614174001",
"planId": "123e4567-e89b-12d3-a456-426614174010",
"paymentMethodId": "123e4567-e89b-12d3-a456-426614174003",
"status": "ACTIVE",
"currentPeriodStart": "2026-01-01T00:00:00.000Z",
"currentPeriodEnd": "2026-02-01T00:00:00.000Z",
"trialStart": null,
"trialEnd": null,
"cancelAtPeriodEnd": false,
"canceledAt": null,
"endedAt": null,
"metadata": null,
"createdAt": "2026-01-01T00:00:00.000Z",
"updatedAt": "2026-01-16T00:00:00.000Z"
},
"proration": {
"behavior": "create_prorations",
"netAmount": "5162",
"appliedOn": "next_invoice",
"invoiceId": null,
"chargedAmount": null,
"chargedAt": null,
"nextInvoiceDate": "2026-02-01T00:00:00.000Z",
"nextInvoiceAmount": "25162",
"billingCycleReset": false,
"error": null
}
}Subscription
Change subscription plan
Changes the subscription to a different plan with configurable proration behavior. Supports upgrades (immediate or deferred billing) and downgrades (always deferred to next billing cycle).
PATCH
/
v1
/
subscriptions
/
{id}
/
plan
curl --request PATCH \
--url https://api.sandbox.cheqpay.mx/pos/v1/subscriptions/{id}/plan \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--header 'x-merchant-id: <api-key>' \
--data '
{
"newPlanId": "123e4567-e89b-12d3-a456-426614174010",
"prorationBehavior": "create_prorations"
}
'{
"subscription": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"merchantId": "merchant_123",
"customerId": "123e4567-e89b-12d3-a456-426614174001",
"planId": "123e4567-e89b-12d3-a456-426614174010",
"paymentMethodId": "123e4567-e89b-12d3-a456-426614174003",
"status": "ACTIVE",
"currentPeriodStart": "2026-01-01T00:00:00.000Z",
"currentPeriodEnd": "2026-02-01T00:00:00.000Z",
"trialStart": null,
"trialEnd": null,
"cancelAtPeriodEnd": false,
"canceledAt": null,
"endedAt": null,
"metadata": null,
"createdAt": "2026-01-01T00:00:00.000Z",
"updatedAt": "2026-01-16T00:00:00.000Z"
},
"proration": {
"behavior": "create_prorations",
"netAmount": "5162",
"appliedOn": "next_invoice",
"invoiceId": null,
"chargedAmount": null,
"chargedAt": null,
"nextInvoiceDate": "2026-02-01T00:00:00.000Z",
"nextInvoiceAmount": "25162",
"billingCycleReset": false,
"error": null
}
}Authorizations
API key for authentication (required)
Merchant ID for identifying the merchant (required)
Path Parameters
Subscription unique identifier
Body
application/json
New plan ID to change to
Example:
"123e4567-e89b-12d3-a456-426614174010"
How to handle proration: create_prorations (deferred to next invoice), always_invoice (immediate charge), none (no proration for downgrades)
Available options:
create_prorations, always_invoice, none Example:
"create_prorations"
Effective date for the plan change (defaults to now)
Example:
"2026-01-16T00:00:00.000Z"
Whether to reset the billing cycle anchor (start new period from change date)
Example:
false