Update Subscription

Updates an existing subscription's plan or item price. Use this to upgrade or downgrade a customer to a different plan.

PUT /subscriptions/{subscription_id}/update

Path Parameters

Parameter	Type	Required	Description
`subscription_id`	string	Yes	The unique identifier for the subscription.

Headers

Header	Type	Required	Description
`api-key`	string	Yes	Your secret API key.
`X-Profile-Id`	string	Yes	Profile ID for authentication.

Body Parameters

Parameter	Type	Required	Description
`plan_id`	string	Yes	The new plan ID to switch the subscription to.
`item_price_id`	string	Yes	The new item price ID associated with the plan (e.g. `cbdemo_enterprise-suite-monthly`).

Request Example

curl -X PUT 'https://api.sandbox.paychtec.com/subscriptions/sub_abc123/update' \
  -H "Content-Type: application/json" \
  -H "api-key: snd_YOUR_API_KEY" \
  -H "X-Profile-Id: prof_12345" \
  -d '{
  "plan_id": "cbdemo_enterprise-suite",
  "item_price_id": "cbdemo_enterprise-suite-monthly"
}'

curl -X PUT 'https://api.sandbox.paychtec.com/subscriptions/sub_abc123/update' \  -H "Content-Type: application/json" \  -H "api-key: snd_YOUR_API_KEY" \  -H "X-Profile-Id: prof_12345" \  -d '{  "plan_id": "cbdemo_enterprise-suite",  "item_price_id": "cbdemo_enterprise-suite-monthly"}'

Response

{
  "id": "sub_abc123",
  "status": "active",
  "profile_id": "prof_12345",
  "merchant_id": "mer_abc123",
  "customer_id": "cust_123456789",
  "plan_id": "cbdemo_enterprise-suite",
  "item_price_id": "cbdemo_enterprise-suite-monthly",
  "merchant_reference_id": "mer_ref_123456789",
  "payment": {
    "payment_id": "pay_xyz789",
    "status": "succeeded",
    "amount": 9900,
    "currency": "USD",
    "payment_method_type": "credit"
  },
  "invoice": {
    "id": "inv_abc123",
    "subscription_id": "sub_abc123",
    "amount": 9900,
    "currency": "USD",
    "status": "invoice_paid"
  }
}

Response Fields

Field	Type	Description
`id`	string	Unique identifier for the subscription.
`status`	string	Current subscription status.
`profile_id`	string	The profile this subscription belongs to.
`merchant_id`	string	The merchant account identifier.
`customer_id`	string	The customer this subscription belongs to.
`plan_id`	string	The updated plan ID.
`item_price_id`	string	The updated item price ID.
`merchant_reference_id`	string	Your own reference ID for this subscription, if set.
`coupon_code`	string	Coupon code applied to this subscription, if any.
`client_secret`	string	Short-lived token (15 min) for SDK authentication, if a new payment confirmation is required.
`payment`	object	Details of the most recent payment.
`invoice`	object	Details of the most recent invoice.

Subscription Statuses

Status	Description
`active`	Subscription is live on the new plan.
`pending`	Plan change is pending activation.
`unpaid`	Payment for the plan change failed.
`cancelled`	Subscription was cancelled.
`failed`	Plan update failed.

Error Responses

Status Code	Description
`400`	Invalid update data — check that both `plan_id` and `item_price_id` are provided and valid.
`404`	Subscription not found — verify the `subscription_id`.

On this page