Skip to content
Trile Docs

Create a subscription

POST
/v1/subscriptions

Subscribes a customer to a price. Unless the price has a trial, the first cycle is charged immediately against the customer’s wallet — so the wallet must hold at least the first cycle’s amount.

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Header Parameters

Section titled “Header Parameters ”
Idempotency-Key
required
string
<= 255 characters

A client-generated unique key (UUID recommended). Required on all POST/PATCH/DELETE. Retrying with the same key returns the original response for 24 hours.

Request Body required

Section titled “Request Body required ”
object
customerId
required
string
cus_01ARZ3NDEKTSV4RRFFQ69G5FAW
priceId
required
string
price_01ARZ3NDEKTSV4RRFFQ69G5FAY
metadata

Up to 50 key/value string pairs you can attach to an object. Trile ignores them; they’re returned on every read.

object
key
additional properties
string
{
  "internal_user_id": "42"
}

Responses

Section titled “ Responses ”

201

Section titled “201 ”

A subscription object.

object
id
string
sub_01ARZ3NDEKTSV4RRFFQ69G5FAZ
customerId
string
priceId
string
status
string
Allowed values: trialing active past_due canceled
currentPeriodStart
string format: date-time
currentPeriodEnd
string format: date-time
cancelAtPeriodEnd
boolean
metadata

Up to 50 key/value string pairs you can attach to an object. Trile ignores them; they’re returned on every read.

object
key
additional properties
string
{
  "internal_user_id": "42"
}

400

Section titled “400 ”

Wallet has insufficient funds, or the price is inactive.

object
success
boolean
error
object
code
string
insufficient_funds
message
string
Wallet balance is below the first cycle amount.
meta
object
requestId
string
req_aBcDeFgHiJkL

409

Section titled “409 ”

Error.

object
success
boolean
error
object
code
string
insufficient_funds
message
string
Wallet balance is below the first cycle amount.
meta
object
requestId
string
req_aBcDeFgHiJkL

422

Section titled “422 ”

Request validation failed.

object
success
boolean
error
object
code
string
insufficient_funds
message
string
Wallet balance is below the first cycle amount.
meta
object
requestId
string
req_aBcDeFgHiJkL