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 Console
- 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
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"
}'
{
"id": "customer-123",
"name": "Acme Corp",
"email": "billing@acme.com",
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-15T10:30:00Z"
}
| 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) |
{
"data": [...],
"has_more": true,
"next_cursor": "cus_abc123"
}
# 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"
}'
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. 
