Subscriptions

The subscriptions endpoints of the Kashu API, with their parameters, objects, errors and examples. The guide explains how they fit together.

Endpoint	What it does
POST `/v1/subscriptions`	Bill a customer's saved card on a schedule. The first charge is made at once; it and every renewal arrive as payments that name the subscription.
GET `/v1/subscriptions`	List subscriptions, newest first.
GET `/v1/subscriptions/{id}`	Retrieve a subscription.
POST `/v1/subscriptions/{id}/cancel`	Cancel a subscription at the end of its period, or now with at_period_end false. Either way nothing more is billed after it ends.
POST `/v1/subscriptions/{id}/resume`	Undo a cancel scheduled for the end of the period. A canceled subscription cannot be resumed.
POST `/v1/subscriptions/{id}/charge_now`	Bill the subscription now if its next charge is due within 12 hours. Otherwise nothing is charged and it is returned unchanged.

The subscription object

Field	Type	About
`id`	string	An id that starts `sb_`.
`object`	string	Always `"subscription"`.
`status`	enum	One of `pending`, `active`, `canceled`, `failed`, `processing`.
`customer`	string	An id that starts `cu_`.
`payment_method`	string	An id that starts `pm_`.
`store`	string	An id that starts `st_`.
`amount`	integer	In the currency's minor unit, such as cents for USD. More than 0.
`currency`	string	Three capital letters, such as `USD`.
`interval`	enum	One of `day`, `week`, `month`, `year`.
`interval_count`	integer	More than 0.
`description`	string or null
`cancel_at_period_end`	boolean
`current_period_start`	integer or null	Unix seconds.
`current_period_end`	integer or null	Unix seconds.
`next_billing_at`	integer or null	Unix seconds.
`canceled_at`	integer or null	Unix seconds.
`metadata`	map of strings
`livemode`	boolean
`created`	integer	Unix seconds.

{
  "id": "sb_1a2B3c4D5e6F7g8H9i0J1k2L",
  "object": "subscription",
  "status": "active",
  "customer": "cu_1a2B3c4D5e6F7g8H9i0J1k2L",
  "payment_method": "pm_1a2B3c4D5e6F7g8H9i0J1k2L",
  "store": "st_1a2B3c4D5e6F7g8H9i0J1k2L",
  "amount": 4999,
  "currency": "USD",
  "interval": "month",
  "interval_count": 1,
  "description": "Order 1001",
  "cancel_at_period_end": false,
  "current_period_start": 1762473600,
  "current_period_end": 1762473600,
  "next_billing_at": 1762473600,
  "canceled_at": null,
  "metadata": {
    "order": "1001"
  },
  "livemode": false,
  "created": 1762473600
}

POST `/v1/subscriptions`

Bill a customer's saved card on a schedule. The first charge is made at once; it and every renewal arrive as payments that name the subscription.

Scope: subscriptions:write
Keys: Secret, or restricted with the scope below.
Idempotency-Key: Required. This endpoint moves money. See Idempotency.
Answers: 201 with the Subscription.

Parameters

Name	In	Type	Required	About
`Idempotency-Key`	header	string	Required	Required. Retry with the same key and get the same result. Up to 255 characters.
`Kashu-Version`	header	string	Optional	The API version to answer in. Defaults to the key's pinned version.

Request body

Field	Type	Required	About
`customer`	string	Required	An id that starts `cu_`.
`payment_method`	string	Required	A saved card of the customer's. Every charge goes to it. An id that starts `pm_`.
`amount`	integer	Required	In the currency's minor unit, such as cents for USD. More than 0. Up to 99999999.
`currency`	string	Required	Three capital letters, such as `USD`.
`interval`	enum	Required	One of `day`, `week`, `month`, `year`.
`interval_count`	integer	Optional	How many intervals each period spans, 1 by default. A period is at most a year. At least 1. Up to 365.
`store`	string	Optional	An id that starts `st_`.
`description`	string	Optional	What the plan is called. The buyer may see it. Up to 200 characters.
`metadata`	map of strings	Optional	Keys up to 40 characters, values up to 500.

Errors

Status	Codes
400	`invalid_json`, `parameter_missing`, `parameter_invalid`, `parameter_unknown`, `api_version_invalid`, `idempotency_key_missing`, `idempotency_key_invalid`, `idempotency_key_reused`
401	`api_key_missing`, `api_key_invalid`, `api_key_expired`
403	`livemode_unavailable`, `insufficient_scope`, `publishable_key_not_allowed`, `payments_not_enabled`
404	`resource_missing`
409	`idempotency_key_in_use`
429	`rate_limited`
500	`api_error`

Examples

curl https://api.kashupay.com/v1/subscriptions \
  -H "Authorization: Bearer $KASHU_SECRET_KEY" \
  -H "Idempotency-Key: subscriptions-create-1001" \
  -H "Content-Type: application/json" \
  -d '{"customer":"cu_1a2B3c4D5e6F7g8H9i0J1k2L","payment_method":"pm_1a2B3c4D5e6F7g8H9i0J1k2L","amount":4999,"currency":"USD","interval":"month"}'

const subscription = await kashu("POST", "/v1/subscriptions", {
  "customer": "cu_1a2B3c4D5e6F7g8H9i0J1k2L",
  "payment_method": "pm_1a2B3c4D5e6F7g8H9i0J1k2L",
  "amount": 4999,
  "currency": "USD",
  "interval": "month"
}, { idempotencyKey: "subscriptions-create-1001" });
console.log(subscription.status);

GET `/v1/subscriptions`

List subscriptions, newest first.

Scope: subscriptions:read
Keys: Secret, or restricted with the scope below.
Idempotency-Key: Not used. A read changes nothing.
Answers: 200 with a list of Subscription, newest first.

Parameters

Name	In	Type	Required	About
`customer`	query	string	Optional	An id that starts `cu_`.
`status`	query	enum	Optional	One of `pending`, `active`, `canceled`, `failed`.
`limit`	query	integer	Optional	At least 1. Up to 100. Defaults to `10`.
`cursor`	query	string	Optional
`Kashu-Version`	header	string	Optional	The API version to answer in. Defaults to the key's pinned version.

Errors

Status	Codes
400	`parameter_missing`, `parameter_invalid`, `parameter_unknown`, `cursor_invalid`, `cursor_expired`, `api_version_invalid`
401	`api_key_missing`, `api_key_invalid`, `api_key_expired`
403	`livemode_unavailable`, `insufficient_scope`, `publishable_key_not_allowed`
500	`api_error`

Examples

curl "https://api.kashupay.com/v1/subscriptions?limit=3" \
  -H "Authorization: Bearer $KASHU_SECRET_KEY"

const list = await kashu("GET", "/v1/subscriptions?limit=3");
console.log(list.has_more);

GET `/v1/subscriptions/{id}`

Retrieve a subscription.

Scope: subscriptions:read
Keys: Secret, or restricted with the scope below.
Idempotency-Key: Not used. A read changes nothing.
Answers: 200 with the Subscription.

Parameters

Name	In	Type	Required	About
`id`	path	string	Required	An id that starts `sb_`.
`Kashu-Version`	header	string	Optional	The API version to answer in. Defaults to the key's pinned version.

Errors

Status	Codes
400	`parameter_unknown`, `api_version_invalid`
401	`api_key_missing`, `api_key_invalid`, `api_key_expired`
403	`livemode_unavailable`, `insufficient_scope`, `publishable_key_not_allowed`
404	`resource_missing`
500	`api_error`

Examples

curl https://api.kashupay.com/v1/subscriptions/sb_1a2B3c4D5e6F7g8H9i0J1k2L \
  -H "Authorization: Bearer $KASHU_SECRET_KEY"

const subscription = await kashu("GET", "/v1/subscriptions/sb_1a2B3c4D5e6F7g8H9i0J1k2L");
console.log(subscription.status);

POST `/v1/subscriptions/{id}/cancel`

Cancel a subscription at the end of its period, or now with at_period_end false. Either way nothing more is billed after it ends.

Scope: subscriptions:write
Keys: Secret, or restricted with the scope below.
Idempotency-Key: Required. This endpoint moves money. See Idempotency.
Answers: 200 with the Subscription.

Parameters

Name	In	Type	Required	About
`id`	path	string	Required	An id that starts `sb_`.
`Idempotency-Key`	header	string	Required	Required. Retry with the same key and get the same result. Up to 255 characters.
`Kashu-Version`	header	string	Optional	The API version to answer in. Defaults to the key's pinned version.

Request body

Field	Type	Required	About
`at_period_end`	boolean	Optional	true by default: the subscription runs to the end of the period it is in.

Errors

Status	Codes
400	`invalid_json`, `parameter_missing`, `parameter_invalid`, `parameter_unknown`, `api_version_invalid`, `idempotency_key_missing`, `idempotency_key_invalid`, `idempotency_key_reused`, `subscription_unexpected_state`
401	`api_key_missing`, `api_key_invalid`, `api_key_expired`
403	`livemode_unavailable`, `insufficient_scope`, `publishable_key_not_allowed`, `payments_not_enabled`
404	`resource_missing`
409	`idempotency_key_in_use`, `operation_in_progress`
429	`rate_limited`
500	`api_error`

Examples

curl https://api.kashupay.com/v1/subscriptions/sb_1a2B3c4D5e6F7g8H9i0J1k2L/cancel \
  -H "Authorization: Bearer $KASHU_SECRET_KEY" \
  -H "Idempotency-Key: subscriptions-cancel-1001" \
  -H "Content-Type: application/json" \
  -d '{"at_period_end":false}'

const subscription = await kashu("POST", "/v1/subscriptions/sb_1a2B3c4D5e6F7g8H9i0J1k2L/cancel", {
  "at_period_end": false
}, { idempotencyKey: "subscriptions-cancel-1001" });
console.log(subscription.status);

POST `/v1/subscriptions/{id}/resume`

Undo a cancel scheduled for the end of the period. A canceled subscription cannot be resumed.

Scope: subscriptions:write
Keys: Secret, or restricted with the scope below.
Idempotency-Key: Required. This endpoint moves money. See Idempotency.
Answers: 200 with the Subscription.

Parameters

Name	In	Type	Required	About
`id`	path	string	Required	An id that starts `sb_`.
`Idempotency-Key`	header	string	Required	Required. Retry with the same key and get the same result. Up to 255 characters.
`Kashu-Version`	header	string	Optional	The API version to answer in. Defaults to the key's pinned version.

Request body

Send no body, or an empty JSON object.

Errors

Status	Codes
400	`invalid_json`, `parameter_unknown`, `api_version_invalid`, `idempotency_key_missing`, `idempotency_key_invalid`, `idempotency_key_reused`, `subscription_unexpected_state`
401	`api_key_missing`, `api_key_invalid`, `api_key_expired`
403	`livemode_unavailable`, `insufficient_scope`, `publishable_key_not_allowed`, `payments_not_enabled`
404	`resource_missing`
409	`idempotency_key_in_use`, `operation_in_progress`
429	`rate_limited`
500	`api_error`

Examples

curl https://api.kashupay.com/v1/subscriptions/sb_1a2B3c4D5e6F7g8H9i0J1k2L/resume \
  -X POST \
  -H "Authorization: Bearer $KASHU_SECRET_KEY" \
  -H "Idempotency-Key: subscriptions-resume-1001"

const subscription = await kashu("POST", "/v1/subscriptions/sb_1a2B3c4D5e6F7g8H9i0J1k2L/resume", undefined, { idempotencyKey: "subscriptions-resume-1001" });
console.log(subscription.status);

POST `/v1/subscriptions/{id}/charge_now`

Bill the subscription now if its next charge is due within 12 hours. Otherwise nothing is charged and it is returned unchanged.

Scope: subscriptions:write
Keys: Secret, or restricted with the scope below.
Idempotency-Key: Required. This endpoint moves money. See Idempotency.
Answers: 200 with the Subscription.

Parameters

Name	In	Type	Required	About
`id`	path	string	Required	An id that starts `sb_`.
`Idempotency-Key`	header	string	Required	Required. Retry with the same key and get the same result. Up to 255 characters.
`Kashu-Version`	header	string	Optional	The API version to answer in. Defaults to the key's pinned version.

Request body

Send no body, or an empty JSON object.

Errors

Status	Codes
400	`invalid_json`, `parameter_unknown`, `api_version_invalid`, `idempotency_key_missing`, `idempotency_key_invalid`, `idempotency_key_reused`, `subscription_unexpected_state`
401	`api_key_missing`, `api_key_invalid`, `api_key_expired`
403	`livemode_unavailable`, `insufficient_scope`, `publishable_key_not_allowed`, `payments_not_enabled`
404	`resource_missing`
409	`idempotency_key_in_use`, `operation_in_progress`
429	`rate_limited`
500	`api_error`

Examples

curl https://api.kashupay.com/v1/subscriptions/sb_1a2B3c4D5e6F7g8H9i0J1k2L/charge_now \
  -X POST \
  -H "Authorization: Bearer $KASHU_SECRET_KEY" \
  -H "Idempotency-Key: subscriptions-charge-now-1001"

const subscription = await kashu("POST", "/v1/subscriptions/sb_1a2B3c4D5e6F7g8H9i0J1k2L/charge_now", undefined, { idempotencyKey: "subscriptions-charge-now-1001" });
console.log(subscription.status);

Subscriptions

The subscription object

POST /v1/subscriptions

Parameters

Request body

Errors

Examples

GET /v1/subscriptions

Parameters

Errors

Examples

GET /v1/subscriptions/{id}

Parameters

Errors

Examples

POST /v1/subscriptions/{id}/cancel

Parameters

Request body

Errors

Examples

POST /v1/subscriptions/{id}/resume

Parameters

Request body

Errors

Examples

POST /v1/subscriptions/{id}/charge_now

Parameters

Request body

Errors

Examples

POST `/v1/subscriptions`

GET `/v1/subscriptions`

GET `/v1/subscriptions/{id}`

POST `/v1/subscriptions/{id}/cancel`

POST `/v1/subscriptions/{id}/resume`

POST `/v1/subscriptions/{id}/charge_now`