Skip to main content
PATCH
/
subscriptions
/
{id}
Cancel, pause, or resume a subscription
curl --request PATCH \
  --url https://api.billing.io/v1/subscriptions/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{}'
{
  "id": "sub_1a2b3c4d5e",
  "org_id": "<string>",
  "customer_id": "<string>",
  "plan_id": "<string>",
  "payment_method_id": "<string>",
  "current_period_start": "2023-11-07T05:31:56Z",
  "current_period_end": "2023-11-07T05:31:56Z",
  "trial_end": "2023-11-07T05:31:56Z",
  "canceled_at": "2023-11-07T05:31:56Z",
  "cancel_at_period_end": true,
  "pause_start": "2023-11-07T05:31:56Z",
  "pause_end": "2023-11-07T05:31:56Z",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "customer": {
    "id": "cus_1a2b3c4d5e",
    "org_id": "<string>",
    "email": "jsmith@example.com",
    "name": "<string>",
    "external_id": "<string>",
    "metadata": {},
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z"
  },
  "plan": {
    "id": "plan_1a2b3c4d5e",
    "org_id": "<string>",
    "name": "<string>",
    "description": "<string>",
    "amount": 123,
    "currency": "<string>",
    "interval_count": 123,
    "trial_days": 123,
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z"
  }
}
Cancel, pause, or resume a subscription. 
curl -X PATCH https://api.billing.io/v1/subscriptions/sub_a1b2c3d4e5f6 \
  -H "Authorization: Bearer $BILLING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "action": "cancel" }'

Authorizations

​
Authorization
string
header
required

Use your secret API key as a Bearer token. Keys are prefixed: sk_live_ (production) or sk_test_ (sandbox).

Path Parameters

​
id
string
required

The subscription identifier (prefixed sub_)

Body

application/json
​
action
enum<string>
required
  • cancel — Cancel at end of current billing period
  • cancel_immediately — Cancel immediately
  • pause — Pause the subscription
  • resume — Resume a paused subscription
Available options:
cancel,
cancel_immediately,
pause,
resume

Response

Subscription updated

​
id
string

Unique identifier (prefixed sub_)

Example:

"sub_1a2b3c4d5e"

​
org_id
string

Organization identifier

​
customer_id
string

Customer identifier

​
plan_id
string

Subscription plan identifier

​
payment_method_id
string | null

Payment method identifier

​
status
enum<string>
  • trialing — Subscription is in trial period
  • active — Subscription is active and billing normally
  • past_due — Payment failed, retrying
  • paused — Subscription is paused
  • canceled — Subscription was canceled
  • expired — Subscription has expired
Available options:
trialing,
active,
past_due,
paused,
canceled,
expired
​
current_period_start
string<date-time> | null
​
current_period_end
string<date-time> | null
​
trial_end
string<date-time> | null
​
canceled_at
string<date-time> | null
​
cancel_at_period_end
boolean

Whether the subscription cancels at the end of the current period

​
pause_start
string<date-time> | null
​
pause_end
string<date-time> | null
​
environment
enum<string>
Available options:
live,
sandbox
​
created_at
string<date-time>
​
updated_at
string<date-time>
​
customer
object
​
plan
object