API reference

GET /products

List products with their variants

Parameters

limit, starting_after

query

Cursor paging, newest first.

Response · Product

object	"product"
id	string
name	string
slug	string
status	string
delivery_type	string | null
variants	array of Variant

GET /products/{id}

Retrieve a product

Parameters

id

path, required

Response · Product

object	"product"
id	string
name	string
slug	string
status	string
delivery_type	string | null
variants	array of Variant

POST /checkouts

Create a checkout

Returns a hosted payment page url that lasts 24 hours. No amount is ever accepted; unknown fields are rejected. An unusable coupon returns 422 with code `coupon_<reason>`.

Request body (JSON)

variant_id	string, required
customer_email	string
coupon_code	string	A coupon of your store; validated on the server.
success_url	string	Where the buyer returns after paying. Must be https on your storefront address, a live custom domain, or a return domain you allowed in the dashboard.
cancel_url	string	Where the buyer returns if they cancel. Same rules as `success_url`.
metadata	object	Keys match `[A-Za-z0-9_.-]{1,40}`.

Response · Checkout

object	"checkout"
id	string
url	string
status	open | complete | expired
livemode	boolean
variant_id	string
metadata	object
created	integer	Unix seconds.
expires_at	integer | null	Unix seconds.

GET /checkouts/{id}

Retrieve a checkout

Parameters

id

path, required

Response · Checkout

object	"checkout"
id	string
url	string
status	open | complete | expired
livemode	boolean
variant_id	string
metadata	object
created	integer	Unix seconds.
expires_at	integer | null	Unix seconds.

GET /orders

List orders

Parameters

status	query	Order status.
customer_email	query	Exact customer email.
created[gte]	query	Created at or after (unix seconds).
created[lte]	query	Created at or before (unix seconds).
limit, starting_after	query	Cursor paging, newest first.

Response · Order

object	"order"
id	string
status	string
currency	"usd"
subtotal	integer
discount	integer
tax	integer
total	integer
platform_fee	integer
seller_net	integer
product_id	string
variant_id	string
customer	object
customer.id	string
customer.email	string
customer.country	string | null
livemode	boolean
paid_at	integer	Unix seconds.

GET /orders/{id}

Retrieve an order

Parameters

id

path, required

Response · Order

object	"order"
id	string
status	string
currency	"usd"
subtotal	integer
discount	integer
tax	integer
total	integer
platform_fee	integer
seller_net	integer
product_id	string
variant_id	string
customer	object
customer.id	string
customer.email	string
customer.country	string | null
livemode	boolean
paid_at	integer	Unix seconds.

POST /orders/{id}/refund

Refund an order

The refund is requested from Stripe; the order status and your balance change when Stripe confirms (an `order.refunded` webhook follows).

Parameters

id

path, required

Request body (JSON)

amount

integer

Cents to refund. Omit to refund everything that is left.

Response · Refund

object	"refund"
id	string
order_id	string
amount	integer
currency	"usd"
status	string
created	integer	Unix seconds.

GET /customers

List customers

Parameters

email	query	Exact email.
limit, starting_after	query	Cursor paging, newest first.

Response · Customer

object	"customer"
id	string
email	string
name	string | null
country	string | null
created	integer	Unix seconds.

GET /customers/{id}

Retrieve a customer

Parameters

id

path, required

Response · Customer

object	"customer"
id	string
email	string
name	string | null
country	string | null
created	integer	Unix seconds.

GET /subscriptions

List subscriptions

Parameters

status	query	Subscription status.
customer_email	query	Exact customer email.
limit, starting_after	query	Cursor paging, newest first.

Response · Subscription

object	"subscription"
id	string
status	active | past_due | canceled | unpaid | incomplete
product_id	string
variant_id	string
customer	object
customer.id	string
customer.email	string
customer.country	string | null
current_period_start	integer | null	Unix seconds.
current_period_end	integer | null	Unix seconds.
cancel_at_period_end	boolean
canceled_at	integer | null	Unix seconds.
order_id	string | null
livemode	boolean

GET /subscriptions/{id}

Retrieve a subscription

Parameters

id

path, required

Response · Subscription

object	"subscription"
id	string
status	active | past_due | canceled | unpaid | incomplete
product_id	string
variant_id	string
customer	object
customer.id	string
customer.email	string
customer.country	string | null
current_period_start	integer | null	Unix seconds.
current_period_end	integer | null	Unix seconds.
cancel_at_period_end	boolean
canceled_at	integer | null	Unix seconds.
order_id	string | null
livemode	boolean

POST /subscriptions/{id}/cancel

Cancel a subscription

Parameters

id

path, required

Request body (JSON)

at_period_end

boolean

true: end at the close of the paid period. false: end now and revoke any license.

Response · Subscription

object	"subscription"
id	string
status	active | past_due | canceled | unpaid | incomplete
product_id	string
variant_id	string
customer	object
customer.id	string
customer.email	string
customer.country	string | null
current_period_start	integer | null	Unix seconds.
current_period_end	integer | null	Unix seconds.
cancel_at_period_end	boolean
canceled_at	integer | null	Unix seconds.
order_id	string | null
livemode	boolean

GET /license-keys

List the license keys of an order

For a subscription renewal order the keys of the subscription are returned.

Parameters

order_id

query, required

Order id (`ord_…`).

Response · LicenseKey

object	"license_key"
id	string
order_id	string
subscription_id	string | null
key	string
status	active | revoked

GET /coupons

List coupons

Parameters

limit, starting_after

query

Cursor paging, newest first.

Response · Coupon

object	"coupon"
id	string
code	string
name	string | null
type	percent | amount
percent_off	integer | null
amount_off	integer | null
currency	string | null
starts_at	integer | null	Unix seconds.
expires_at	integer | null	Unix seconds.
max_redemptions	integer | null
redemptions_count	integer
product_ids	array
active	boolean
created	integer	Unix seconds.

POST /coupons

Create a coupon

Type and value cannot be changed later. A subscription coupon discounts the first payment only.

Request body (JSON)

code	string, required
name	string
type	percent | amount, required
percent_off	integer
amount_off	integer	Cents.
starts_at	integer	Unix seconds.
expires_at	integer	Unix seconds.
max_redemptions	integer
product_ids	array	Restrict to these products. Omit for all.

Response · Coupon

object	"coupon"
id	string
code	string
name	string | null
type	percent | amount
percent_off	integer | null
amount_off	integer | null
currency	string | null
starts_at	integer | null	Unix seconds.
expires_at	integer | null	Unix seconds.
max_redemptions	integer | null
redemptions_count	integer
product_ids	array
active	boolean
created	integer	Unix seconds.

GET /coupons/{id}

Retrieve a coupon

Parameters

id

path, required

Response · Coupon

object	"coupon"
id	string
code	string
name	string | null
type	percent | amount
percent_off	integer | null
amount_off	integer | null
currency	string | null
starts_at	integer | null	Unix seconds.
expires_at	integer | null	Unix seconds.
max_redemptions	integer | null
redemptions_count	integer
product_ids	array
active	boolean
created	integer	Unix seconds.

DELETE /coupons/{id}

Delete a coupon

Parameters

id

path, required

Response · Deleted

object	string
id	string
deleted	"true"

GET /webhook-endpoints

List webhook endpoints of the key's mode

Parameters

limit, starting_after

query

Cursor paging, newest first.

Response · WebhookEndpoint

object	"webhook_endpoint"
id	string
url	string
events	array
mode	live | test
status	active | disabled
created	integer	Unix seconds.

POST /webhook-endpoints

Create a webhook endpoint

The mode of the endpoint is the mode of the key. The signing `secret` is returned only here.

Request body (JSON)

url	string, required	https, port 443, public host.
events	array

Response · WebhookEndpointWithSecret

object	"webhook_endpoint"
id	string
url	string
events	array
mode	live | test
status	active | disabled
created	integer	Unix seconds.
secret	string	Signing secret (`whsec_…`), shown only once.

GET /webhook-endpoints/{id}

Retrieve a webhook endpoint

Parameters

id

path, required

Response · WebhookEndpoint

object	"webhook_endpoint"
id	string
url	string
events	array
mode	live | test
status	active | disabled
created	integer	Unix seconds.

PATCH /webhook-endpoints/{id}

Update a webhook endpoint

Parameters

id

path, required

Request body (JSON)

url	string
events	array
status	active | disabled

Response · WebhookEndpoint

object	"webhook_endpoint"
id	string
url	string
events	array
mode	live | test
status	active | disabled
created	integer	Unix seconds.

DELETE /webhook-endpoints/{id}

Delete a webhook endpoint

Parameters

id

path, required

Response · Deleted

object	string
id	string
deleted	"true"

POST /webhook-endpoints/{id}/test

Send a test event

Parameters

id

path, required