Skip to main content
POST
/
subscriptions
Create a subscription
curl --request POST \
  --url https://api.billing.io/v1/subscriptions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customer_id": "<string>",
  "plan_id": "<string>",
  "payment_method_id": "<string>"
}
'
{
  "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"
  }
}
Subscribe a customer to a plan. Creates the first renewal automatically. 
curl -X POST https://api.billing.io/v1/subscriptions \
  -H "Authorization: Bearer $BILLING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_a1b2c3d4e5f6",
    "plan_id": "plan_a1b2c3d4e5f6",
    "payment_method_id": "pm_a1b2c3d4e5f6"
  }'
Response
{
  "id": "sub_a1b2c3d4e5f6a7b8c9d0e1f2",
  "customer_id": "cus_a1b2c3d4e5f6",
  "plan_id": "plan_a1b2c3d4e5f6",
  "status": "trialing",
  "trial_end": "2025-01-29T12:00:00Z",
  "current_period_start": "2025-01-15T12:00:00Z",
  "current_period_end": "2025-02-15T12:00:00Z",
  "created_at": "2025-01-15T12:00:00Z"
}

Authorizations

​
Authorization
string
header
required

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

Body

application/json
​
customer_id
string
required

The customer identifier

​
plan_id
string
required

The subscription plan identifier

​
payment_method_id
string

The payment method identifier (optional, uses default if omitted)

Response

Subscription created

​
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