DEV3 Cyclestrand
Sign inGet started

DEV3 Cyclestrand REST API

Base URL /api/v1 · Authenticate with Authorization: Bearer n3k_… · OpenAPI 3.1 JSON

get/api/v1/mescope: read

The workspace this key belongs to

get/api/v1/productsscope: read

List products

Parameters: limit (query), starting_after (query)

post/api/v1/productsscope: write

Create 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
}
get/api/v1/products/{id}scope: read

Retrieve a product

Parameters: id (path)

delete/api/v1/products/{id}scope: write

Archive a product

Parameters: id (path)

get/api/v1/pricesscope: read

List prices

Parameters: limit (query), starting_after (query)

post/api/v1/pricesscope: write

Create 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
}
get/api/v1/prices/{id}scope: read

Retrieve a price

Parameters: id (path)

delete/api/v1/prices/{id}scope: write

Archive a price

Parameters: id (path)

get/api/v1/prices/{id}/quotescope: read

What would this price cost for a quantity?

Parameters: id (path), quantity (query)

get/api/v1/couponsscope: read

List coupons

Parameters: limit (query), starting_after (query)

post/api/v1/couponsscope: write

Create 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
}
get/api/v1/customersscope: read

List customers

Parameters: limit (query), starting_after (query), email (query), external_id (query)

post/api/v1/customersscope: write

Create 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
}
get/api/v1/customers/{id}scope: read

Retrieve a customer

Parameters: id (path)

patch/api/v1/customers/{id}scope: write

Update 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
}
delete/api/v1/customers/{id}scope: write

Delete a customer (refused while invoices are open)

Parameters: id (path)

post/api/v1/customers/{id}/payment-methodsscope: write

Attach 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
}
get/api/v1/customers/{id}/payment-methodsscope: read

List payment methods

Parameters: id (path)

post/api/v1/customers/{id}/default-payment-methodscope: write

Set 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
}
get/api/v1/subscriptionsscope: read

List subscriptions

Parameters: limit (query), starting_after (query), customerId (query), status (query)

post/api/v1/subscriptionsscope: write

Create 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
}
get/api/v1/subscriptions/{id}scope: read

Retrieve a subscription

Parameters: id (path)

patch/api/v1/subscriptions/{id}scope: write

Change 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
}
post/api/v1/subscriptions/{id}/previewscope: read

Proration 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
}
post/api/v1/subscriptions/{id}/cancelscope: write

Cancel 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
}
post/api/v1/subscriptions/{id}/resumescope: write

Undo a pending cancellation or resume a paused subscription

Parameters: id (path)

post/api/v1/subscriptions/{id}/pausescope: write

Pause billing

Parameters: id (path)

post/api/v1/usagescope: usage

Record 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
}
get/api/v1/invoicesscope: read

List invoices

Parameters: limit (query), starting_after (query), customerId (query), status (query)

post/api/v1/invoicesscope: write

Create 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
}
get/api/v1/invoices/{id}scope: read

Retrieve an invoice

Parameters: id (path)

post/api/v1/invoices/{id}/finalizescope: write

Finalise a draft (assigns the number; idempotent)

Parameters: id (path)

post/api/v1/invoices/{id}/payscope: write

Attempt 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
}
post/api/v1/invoices/{id}/voidscope: write

Void an open invoice

Parameters: id (path)

post/api/v1/invoices/{id}/uncollectiblescope: write

Mark an open invoice uncollectible

Parameters: id (path)

get/api/v1/invoices/{id}/pdfscope: read

Invoice as a PDF

Parameters: id (path)

get/api/v1/credit-notesscope: read

List credit notes

Parameters: limit (query), starting_after (query)

post/api/v1/credit-notesscope: write

Issue 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
}
post/api/v1/checkout-sessionsscope: sessions

Create 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
}
post/api/v1/portal-sessionsscope: sessions

Create 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
}
post/api/v1/customers/{id}/tokenscope: sessions

Mint a short-lived customer token for the browser (secret keys only)

Parameters: id (path)

get/api/v1/webhooksscope: read

List webhook endpoints

post/api/v1/webhooksscope: write

Create 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
}
delete/api/v1/webhooks/{id}scope: write

Delete a webhook endpoint

Parameters: id (path)

post/api/v1/webhooks/{id}/testscope: write

Send a test event

Parameters: id (path)

get/api/v1/webhooks/{id}/deliveriesscope: read

Recent deliveries

Parameters: id (path), limit (query), starting_after (query)

get/api/v1/eventsscope: read

List events

Parameters: limit (query), starting_after (query), type (query)