Subscriptions

Create a subscription

Creates a subscription. The worker creates the first invoice within about a minute and then one every week or month. Each invoice stays payable for 24 hours. When email is configured, the customer receives each invoice by email, up to 10 payment-link emails per address in 24 hours. A business can create at most 500 subscriptions in 24 hours (10 until it receives its first payment) and keep at most 2,000 active ones; past either limit the response is 409 invalid_state. Rate limit: 60 per minute per API key, shared with the other endpoints that have this limit.

POST
/api/v1/subscriptions

Authorization

bearerAuth
headerAuthorizationBearer <token>

A live API key, sk_live_ followed by 32 base58 characters.

Header Parameters

Idempotency-Key?string

A unique string of 1 to 255 characters for this operation. A key belongs to the business across every endpoint for 24 hours, so give each operation its own key, for example invoice-order-1042 and refund-order-1042, not the order id alone. A retry with the same key on the same endpoint and with the same body returns the stored response with the header Idempotent-Replayed: true. The same key with a different body or on another endpoint returns 409 idempotency_conflict. Errors are not stored, so a request that failed can be retried with the same key, even with a corrected body. While the first request with a key is still running, a retry gets 409 idempotency_conflict with Retry-After: 1.

Length1 <= length <= 255

Request Body

application/json
  1. body
customer_email*string
Formatemail
amount*Amount

Decimal string with up to 2 decimals, greater than 0.

Match^\d{1,12}(\.\d{1,2})?$
currency*Currency
Value in"USD""EUR""INR"
interval*string
Value in"week""month"
description?string
Lengthlength <= 200

Response Body

The subscription was created.

application/json
  1. response
id*string
object*string
status*string
Value in"active""canceled"
customer_email*string
amount*string
currency*Currency
Value in"USD""EUR""INR"
interval*string
Value in"week""month"
description*string|null
next_invoice_at*string
Formatdate-time
created_at*string
Formatdate-time
Example Request
curl -X POST 'https://example.com/api/v1/subscriptions' \  -H 'Content-Type: application/json' \  -d '{  "customer_email": "ada@example.com",  "amount": "9.00",  "currency": "USD",  "interval": "month",  "description": "Pro plan"}'
Example Response
{  "id": "sub_2mQ8vT4kW9xL3pN7rB5s",  "object": "subscription",  "status": "active",  "customer_email": "string",  "amount": "string",  "currency": "USD",  "interval": "week",  "description": "string",  "next_invoice_at": "2019-08-24T14:15:22Z",  "created_at": "2019-08-24T14:15:22Z"}