DEV3 Cyclestrand REST API
Base URL /api/v1 · Authenticate with Authorization: Bearer n3k_… · OpenAPI 3.1 JSON
/api/v1/mescope: readThe workspace this key belongs to
/api/v1/productsscope: readList products
Parameters: limit (query), starting_after (query)
/api/v1/productsscope: writeCreate a product
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"description": {
"type": "string",
"maxLength": 2000
},
"tax_code": {
"type": "string",
"maxLength": 40
},
"metadata": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"required": [
"name"
],
"additionalProperties": false
}/api/v1/products/{id}scope: readRetrieve a product
Parameters: id (path)
/api/v1/products/{id}scope: writeArchive a product
Parameters: id (path)
/api/v1/pricesscope: readList prices
Parameters: limit (query), starting_after (query)
/api/v1/pricesscope: writeCreate a price (flat, per unit, tiered, volume, package or metered)
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"productId": {
"type": "string",
"pattern": "^[0-9a-f]{24}$"
},
"currency": {
"type": "string",
"minLength": 3,
"maxLength": 3
},
"interval": {
"type": "object",
"properties": {
"unit": {
"type": "string",
"enum": [
"day",
"week",
"month",
"year"
]
},
"count": {
"default": 1,
"type": "integer",
"minimum": 1,
"maximum": 36
}
},
"required": [
"unit",
"count"
],
"additionalProperties": false
},
"model": {
"type": "string",
"enum": [
"flat",
"per_unit",
"tiered_graduated",
"tiered_volume",
"package",
"metered_sum",
"metered_max",
"metered_last"
]
},
"unit_amount": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"unit_size": {
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"tiers": {
"maxItems": 50,
"type": "array",
"items": {
"type": "object",
"properties": {
"up_to": {
"anyOf": [
{
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
{
"type": "null"
}
]
},
"unit_amount": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"flat_amount": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"up_to",
"unit_amount"
],
"additionalProperties": false
}
},
"package_size": {
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"metered_pricing": {
"type": "string",
"enum": [
"per_unit",
"graduated",
"volume",
"package"
]
},
"free_units": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"trial_days": {
"type": "integer",
"minimum": 0,
"maximum": 730
},
"tax_behavior": {
"type": "string",
"enum": [
"inclusive",
"exclusive"
]
},
"meterId": {
"type": "string",
"pattern": "^[0-9a-f]{24}$"
},
"nickname": {
"type": "string",
"maxLength": 120
}
},
"required": [
"productId",
"currency",
"interval",
"model"
],
"additionalProperties": false
}/api/v1/prices/{id}scope: readRetrieve a price
Parameters: id (path)
/api/v1/prices/{id}scope: writeArchive a price
Parameters: id (path)
/api/v1/prices/{id}/quotescope: readWhat would this price cost for a quantity?
Parameters: id (path), quantity (query)
/api/v1/couponsscope: readList coupons
Parameters: limit (query), starting_after (query)
/api/v1/couponsscope: writeCreate a coupon
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"code": {
"type": "string",
"minLength": 2,
"maxLength": 40
},
"percent_bp": {
"type": "integer",
"minimum": 1,
"maximum": 10000
},
"amount_off": {
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"currency": {
"type": "string",
"minLength": 3,
"maxLength": 3
},
"duration": {
"type": "string",
"enum": [
"once",
"repeating",
"forever"
]
},
"duration_months": {
"type": "integer",
"minimum": 1,
"maximum": 60
},
"max_redemptions": {
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"expires_at": {},
"priceIds": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[0-9a-f]{24}$"
}
}
},
"required": [
"code"
],
"additionalProperties": false
}/api/v1/customersscope: readList customers
Parameters: limit (query), starting_after (query), email (query), external_id (query)
/api/v1/customersscope: writeCreate a customer
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"email": {
"type": "string",
"maxLength": 200,
"format": "email",
"pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
},
"name": {
"type": "string",
"maxLength": 160
},
"external_id": {
"type": "string",
"maxLength": 100
},
"address": {
"type": "object",
"properties": {
"line1": {
"type": "string",
"maxLength": 200
},
"city": {
"type": "string",
"maxLength": 100
},
"region": {
"type": "string",
"maxLength": 100
},
"postal_code": {
"type": "string",
"maxLength": 20
},
"country": {
"type": "string",
"minLength": 2,
"maxLength": 2
}
},
"additionalProperties": false
},
"tax_id": {
"type": "string",
"maxLength": 30
},
"tax_exempt": {
"type": "boolean"
},
"metadata": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"required": [
"email"
],
"additionalProperties": false
}/api/v1/customers/{id}scope: readRetrieve a customer
Parameters: id (path)
/api/v1/customers/{id}scope: writeUpdate a customer
Parameters: id (path)
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"email": {
"type": "string",
"maxLength": 200,
"format": "email",
"pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
},
"name": {
"type": "string",
"maxLength": 160
},
"external_id": {
"type": "string",
"maxLength": 100
},
"address": {
"type": "object",
"properties": {
"line1": {
"type": "string",
"maxLength": 200
},
"city": {
"type": "string",
"maxLength": 100
},
"region": {
"type": "string",
"maxLength": 100
},
"postal_code": {
"type": "string",
"maxLength": 20
},
"country": {
"type": "string",
"minLength": 2,
"maxLength": 2
}
},
"additionalProperties": false
},
"tax_id": {
"type": "string",
"maxLength": 30
},
"tax_exempt": {
"type": "boolean"
},
"metadata": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"additionalProperties": false
}/api/v1/customers/{id}scope: writeDelete a customer (refused while invoices are open)
Parameters: id (path)
/api/v1/customers/{id}/payment-methodsscope: writeAttach a gateway payment-method token
Parameters: id (path)
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"token": {
"type": "string",
"minLength": 4,
"maxLength": 100
},
"brand": {
"type": "string",
"maxLength": 20
},
"last4": {
"type": "string",
"minLength": 4,
"maxLength": 4
},
"exp_month": {
"type": "integer",
"minimum": 1,
"maximum": 12
},
"exp_year": {
"type": "integer",
"minimum": 2000,
"maximum": 2200
},
"default": {
"type": "boolean"
}
},
"required": [
"token"
],
"additionalProperties": false
}/api/v1/customers/{id}/payment-methodsscope: readList payment methods
Parameters: id (path)
/api/v1/customers/{id}/default-payment-methodscope: writeSet the default payment method
Parameters: id (path)
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"payment_method": {
"type": "string",
"pattern": "^[0-9a-f]{24}$"
}
},
"required": [
"payment_method"
],
"additionalProperties": false
}/api/v1/subscriptionsscope: readList subscriptions
Parameters: limit (query), starting_after (query), customerId (query), status (query)
/api/v1/subscriptionsscope: writeCreate a subscription (bills the first period unless trialing)
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"customerId": {
"type": "string",
"pattern": "^[0-9a-f]{24}$"
},
"items": {
"minItems": 1,
"maxItems": 20,
"type": "array",
"items": {
"type": "object",
"properties": {
"priceId": {
"type": "string",
"pattern": "^[0-9a-f]{24}$"
},
"quantity": {
"type": "integer",
"minimum": 0,
"maximum": 1000000
},
"addon": {
"type": "boolean"
}
},
"required": [
"priceId"
],
"additionalProperties": false
}
},
"trial_days": {
"type": "integer",
"minimum": 0,
"maximum": 730
},
"coupon": {
"type": "string",
"maxLength": 40
},
"collection_method": {
"type": "string",
"enum": [
"charge_automatically",
"send_invoice"
]
},
"proration_behavior": {
"type": "string",
"enum": [
"create_prorations",
"always_invoice",
"none"
]
},
"allow_multiple": {
"type": "boolean"
}
},
"required": [
"customerId",
"items"
],
"additionalProperties": false
}/api/v1/subscriptions/{id}scope: readRetrieve a subscription
Parameters: id (path)
/api/v1/subscriptions/{id}scope: writeChange items or quantities with a proration behaviour, or schedule the change for period end
Parameters: id (path)
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"items": {
"minItems": 1,
"maxItems": 20,
"type": "array",
"items": {
"type": "object",
"properties": {
"priceId": {
"type": "string",
"pattern": "^[0-9a-f]{24}$"
},
"quantity": {
"type": "integer",
"minimum": 0,
"maximum": 1000000
},
"addon": {
"type": "boolean"
}
},
"required": [
"priceId"
],
"additionalProperties": false
}
},
"proration_behavior": {
"type": "string",
"enum": [
"create_prorations",
"always_invoice",
"none"
]
},
"schedule_at_period_end": {
"type": "boolean"
}
},
"required": [
"items"
],
"additionalProperties": false
}/api/v1/subscriptions/{id}/previewscope: readProration preview (nothing is changed or billed)
Parameters: id (path)
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"items": {
"minItems": 1,
"maxItems": 20,
"type": "array",
"items": {
"type": "object",
"properties": {
"priceId": {
"type": "string",
"pattern": "^[0-9a-f]{24}$"
},
"quantity": {
"type": "integer",
"minimum": 0,
"maximum": 1000000
},
"addon": {
"type": "boolean"
}
},
"required": [
"priceId"
],
"additionalProperties": false
}
},
"at": {}
},
"required": [
"items"
],
"additionalProperties": false
}/api/v1/subscriptions/{id}/cancelscope: writeCancel at period end (default) or immediately
Parameters: id (path)
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"at_period_end": {
"type": "boolean"
},
"prorate": {
"type": "boolean"
},
"reason": {
"type": "string",
"maxLength": 300
}
},
"additionalProperties": false
}/api/v1/subscriptions/{id}/resumescope: writeUndo a pending cancellation or resume a paused subscription
Parameters: id (path)
/api/v1/subscriptions/{id}/pausescope: writePause billing
Parameters: id (path)
/api/v1/usagescope: usageRecord up to 1,000 usage events (idempotent per idempotency_key)
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"events": {
"minItems": 1,
"maxItems": 1000,
"type": "array",
"items": {
"type": "object",
"properties": {
"event_name": {
"type": "string",
"maxLength": 64
},
"customer": {
"type": "string",
"minLength": 1,
"maxLength": 100
},
"value": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"timestamp": {},
"idempotency_key": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"properties": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"required": [
"event_name",
"customer",
"idempotency_key"
],
"additionalProperties": false
}
},
"strict": {
"type": "boolean"
}
},
"required": [
"events"
],
"additionalProperties": false
}/api/v1/invoicesscope: readList invoices
Parameters: limit (query), starting_after (query), customerId (query), status (query)
/api/v1/invoicesscope: writeCreate a one-off draft invoice
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"customerId": {
"type": "string",
"pattern": "^[0-9a-f]{24}$"
},
"currency": {
"type": "string",
"minLength": 3,
"maxLength": 3
},
"lines": {
"minItems": 1,
"maxItems": 100,
"type": "array",
"items": {
"type": "object",
"properties": {
"description": {
"type": "string",
"minLength": 1,
"maxLength": 300
},
"amount": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"quantity": {
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
}
},
"required": [
"description",
"amount"
],
"additionalProperties": false
}
},
"collection_method": {
"type": "string",
"enum": [
"charge_automatically",
"send_invoice"
]
}
},
"required": [
"customerId",
"currency",
"lines"
],
"additionalProperties": false
}/api/v1/invoices/{id}scope: readRetrieve an invoice
Parameters: id (path)
/api/v1/invoices/{id}/finalizescope: writeFinalise a draft (assigns the number; idempotent)
Parameters: id (path)
/api/v1/invoices/{id}/payscope: writeAttempt payment now
Parameters: id (path)
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"payment_token": {
"type": "string",
"maxLength": 100
}
},
"additionalProperties": false
}/api/v1/invoices/{id}/voidscope: writeVoid an open invoice
Parameters: id (path)
/api/v1/invoices/{id}/uncollectiblescope: writeMark an open invoice uncollectible
Parameters: id (path)
/api/v1/invoices/{id}/pdfscope: readInvoice as a PDF
Parameters: id (path)
/api/v1/credit-notesscope: readList credit notes
Parameters: limit (query), starting_after (query)
/api/v1/credit-notesscope: writeIssue a credit note against a paid invoice (refund or credit balance)
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"invoiceId": {
"type": "string",
"pattern": "^[0-9a-f]{24}$"
},
"amount": {
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"lines": {
"maxItems": 50,
"type": "array",
"items": {
"type": "object",
"properties": {
"description": {
"type": "string",
"minLength": 1,
"maxLength": 300
},
"amount": {
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
}
},
"required": [
"description",
"amount"
],
"additionalProperties": false
}
},
"reason": {
"type": "string",
"maxLength": 300
},
"outcome": {
"type": "string",
"enum": [
"refund",
"credit_balance"
]
}
},
"required": [
"invoiceId",
"outcome"
],
"additionalProperties": false
}/api/v1/checkout-sessionsscope: sessionsCreate a hosted checkout session
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"items": {
"minItems": 1,
"maxItems": 20,
"type": "array",
"items": {
"type": "object",
"properties": {
"priceId": {
"type": "string",
"pattern": "^[0-9a-f]{24}$"
},
"quantity": {
"type": "integer",
"minimum": 0,
"maximum": 1000000
},
"addon": {
"type": "boolean"
}
},
"required": [
"priceId"
],
"additionalProperties": false
}
},
"customerId": {
"type": "string",
"pattern": "^[0-9a-f]{24}$"
},
"customer_email": {
"type": "string",
"format": "email",
"pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
},
"customer_token": {
"type": "string",
"maxLength": 300
},
"success_url": {
"type": "string",
"maxLength": 2000,
"format": "uri"
},
"cancel_url": {
"type": "string",
"maxLength": 2000,
"format": "uri"
},
"coupon": {
"type": "string",
"maxLength": 40
}
},
"required": [
"items",
"success_url",
"cancel_url"
],
"additionalProperties": false
}/api/v1/portal-sessionsscope: sessionsCreate a customer portal session (publishable keys must send a customer_token minted by your server)
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"customerId": {
"type": "string",
"pattern": "^[0-9a-f]{24}$"
},
"customer_token": {
"type": "string",
"maxLength": 300
},
"return_url": {
"type": "string",
"maxLength": 2000,
"format": "uri"
}
},
"required": [
"customerId",
"return_url"
],
"additionalProperties": false
}/api/v1/customers/{id}/tokenscope: sessionsMint a short-lived customer token for the browser (secret keys only)
Parameters: id (path)
/api/v1/webhooksscope: readList webhook endpoints
/api/v1/webhooksscope: writeCreate a webhook endpoint (the signing secret is shown once)
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"url": {
"type": "string",
"maxLength": 2000,
"format": "uri"
},
"events": {
"maxItems": 30,
"type": "array",
"items": {
"type": "string",
"maxLength": 60
}
},
"description": {
"type": "string",
"maxLength": 200
}
},
"required": [
"url"
],
"additionalProperties": false
}/api/v1/webhooks/{id}scope: writeDelete a webhook endpoint
Parameters: id (path)
/api/v1/webhooks/{id}/testscope: writeSend a test event
Parameters: id (path)
/api/v1/webhooks/{id}/deliveriesscope: readRecent deliveries
Parameters: id (path), limit (query), starting_after (query)
/api/v1/eventsscope: readList events
Parameters: limit (query), starting_after (query), type (query)