Overview

Turnstile's API enables you to integrate billing and usage data with your existing systems to automate your Quote to Cash workflow. Use the API to ingest usage events for consumption-based pricing and receive webhooks for key lifecycle events like quote acceptance and invoice generation. This guide covers authentication, available endpoints, and payload formats.

Production vs Test Endpoints

All production API endpoints live at https://api.tryturnstile.com/endpoint
We also have test endpoints at https://api.tryturnstile.com/test/endpoint that merely validate request shape (fields and types).
- Test endpoints accept any random value as the bearer token.

Authentication

All production API endpoints are authenticated using Bearer tokens. Please contact support for your API token.

"security": [
  {
    "bearerAuth": []
  }
]

Usage Ingestion

Endpoint: /usage/ingest
Accepts: POST requests with application/json encoding

Payload Body

All of the following fields are required.

customer_alias
- stripe_customer_id (string): The Stripe customer ID associated with the customer. Either this or turnstile_customer_id must be provided. If both are provided, stripe_customer_id will be used.
- turnstile_customer_id (string): The Turnstile customer ID associated with the customer.
timestamp (string): The timestamp when the event happened. This must be in RFC3339 format (UTC), such as '2024-05-29T01:23:45Z'.
quantity (integer): Number of events. Negatives supported.
event_type (string): The kind of event, used to associate the event with a Billable Metric in your Turnstile Catalog. Examples: "test_run", "page_processed".

Provisioning (Beta)

Turnstile can send you webhooks when certain events occur within the system. Please contact support for further details on getting access to this feature.

We support several quote and invoice lifecycle events. The most popular are shown below.

v1.quote.finalized

Occurs when a quote is accepted or signed and becomes a subscription.

Payload:

{
  "changeCause": "PHASE_ACTIVE",
  "crmCustomerId": "18688415805",
  "effectiveEnd": "2025-02-20T22:07:07.427Z",
  "effectiveStart": "2025-02-20T22:07:07.427Z",
  "newEntitlements": [
    {
      "productName": "API Calls Processed",
      "productUnitName": "api_calls",
      "quantity": 100
    }
  ],
  "orderFlowType": "TURNSTILE_SIGN",
  "publicAccountViewUrl": "https://app.tryturnstile.com/p/abc/def",
  "quoteId": "b24fd8f6-4b90-48c1-b5b8-507dce6c3d6d",
  "subscriptionUrl": "uri",
  "tcv": "$3.14",
  "turnstileCustomerId": "ef0a2a9e-1b30-4fe7-b985-5389721580dd",
  "turnstileCustomerName": "Pepsi Co",
  "turnstileSubscriptionId": "bb03c399-b627-47cb-83ff-3681bea36819",
  "type": "QUOTE"
}

Quoting FAQs

Guide to Recording Usage Pricing

Recording Usage in Turnstile

Quoting Overview

Turnstile Concepts & Relationships