Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.stigg.io/llms.txt

Use this file to discover all available pages before exploring further.

The Stigg REST API provides a RESTful interface for integrating with Stigg’s pricing and entitlement platform. This guide covers everything you need to get started.
The REST API is currently in Public Beta.

​
Base URL

All API requests should be made to: 
https://api.stigg.io/api/v1

​
Authentication

All API requests require authentication using an API key. Include your API key in the X-API-KEY header with every request.

​
Getting your API key

  1. Log in to the Stigg app
  2. Navigate to Integrations > API Keys
  3. Copy your Full Access API Key
Keep your API key secure and never expose it in client-side code. Use environment variables to store your key.

​
Authentication example

curl -X GET "https://api.stigg.io/api/v1/customers/{id}" \
  -H "X-API-KEY: your-api-key" \
  -H "Content-Type: application/json"

​
Common Patterns

​
Request format

All requests should include the Content-Type: application/json header when sending a request body. 
curl -X POST "https://api.stigg.io/api/v1/customers" \
  -H "X-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "customer-123",
    "name": "Acme Corp",
    "email": "billing@acme.com"
  }'

​
Response format

All responses are returned in JSON format with consistent structure: Successful response: 
{
  "id": "customer-123",
  "name": "Acme Corp",
  "email": "billing@acme.com",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

​
Pagination

List endpoints support cursor-based pagination using the following query parameters:
ParameterTypeDescription
limitintegerMaximum number of items to return (default: 20, max: 100)
starting_afterstringCursor for forward pagination (item ID to start after)
ending_beforestringCursor for backward pagination (item ID to end before)
Paginated response structure: 
{
  "data": [...],
  "has_more": true,
  "next_cursor": "cus_abc123"
}
Example: Fetching paginated results 
# First page
curl -X GET "https://api.stigg.io/api/v1/customers?limit=10" \
  -H "X-API-KEY: your-api-key"

# Next page
curl -X GET "https://api.stigg.io/api/v1/customers?limit=10&starting_after=cus_abc123" \
  -H "X-API-KEY: your-api-key"

​
Filtering

List endpoints support filtering using query parameters specific to each resource: 
# Filter customers by email
curl -X GET "https://api.stigg.io/api/v1/customers?email=user@example.com" \
  -H "X-API-KEY: your-api-key"

# Filter subscriptions by status
curl -X GET "https://api.stigg.io/api/v1/subscriptions?status=active" \
  -H "X-API-KEY: your-api-key"

​
Idempotency

For POST requests, you can include an Idempotency-Key header to ensure the operation is only performed once, even if the request is retried: 
curl -X POST "https://api.stigg.io/api/v1/customers" \
  -H "X-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-request-id-123" \
  -d '{
    "id": "customer-123",
    "name": "Acme Corp"
  }'
Idempotency keys are stored for 24 hours. Repeated requests with the same key will return the cached response.

​
Error Handling

The API uses standard HTTP status codes and returns detailed error information in a consistent format.
StatusMeaning
200Success — request completed, body contains the resource
201Created — resource was successfully provisioned
400Bad request — invalid parameters or request body
401Unauthenticated — missing or invalid X-API-KEY
403Forbidden — authenticated but not authorized for this resource
404Not found — the specified resource does not exist
409Conflict — e.g. a subscription already exists for this customer
429Too many requests — rate limit exceeded; see Rate Limits

​
Known Limitations

​
Subscription list endpoint does not return entitlements

GET /api/v1/subscriptions does not include subscriptionEntitlements in its response. Returning full entitlement data for every subscription in a paginated list would be prohibitively expensive at scale. To retrieve entitlements for a specific subscription, use GET /api/v1/subscriptions/{id}. To retrieve the full entitlements defined on a plan, use GET /api/v1/plans/{id}.

​
Subscription entitlements are overrides only

The subscriptionEntitlements field on GET /api/v1/subscriptions/{id} contains only subscription-level overrides (type and ID), not the full set of entitlements inherited from the plan. To retrieve all entitlements for a plan, use GET /api/v1/plans/{planId}/entitlements.