REST API Overview

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

Log in to the Stigg app
Navigate to Integrations > API Keys
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:

Parameter	Type	Description
`limit`	integer	Maximum number of items to return (default: 20, max: 100)
`starting_after`	string	Cursor for forward pagination (item ID to start after)
`ending_before`	string	Cursor 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.

Status	Meaning
`200`	Success — request completed, body contains the resource
`201`	Created — resource was successfully provisioned
`400`	Bad request — invalid parameters or request body
`401`	Unauthenticated — missing or invalid `X-API-KEY`
`403`	Forbidden — authenticated but not authorized for this resource
`404`	Not found — the specified resource does not exist
`409`	Conflict — e.g. a subscription already exists for this customer
`429`	Too 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.

API Keys

⌘I

​Base URL

​Authentication

​Getting your API key

​Authentication example

​Common Patterns

​Request format

​Response format

​Pagination

​Filtering

​Idempotency

​Error Handling

​Known Limitations

​Subscription list endpoint does not return entitlements

​Subscription entitlements are overrides only

Base URL

Authentication

Getting your API key

Authentication example

Common Patterns

Request format

Response format

Pagination

Filtering

Idempotency

Error Handling

Known Limitations

Subscription list endpoint does not return entitlements

Subscription entitlements are overrides only