Complete reference for the StateSet API - Build powerful autonomous business applications
https://api.stateset.com/v1
https://api.stateset.com/graphql
wss://api.stateset.com/v1/ws
https://api.sandbox.stateset.com/v1
https://api.sandbox.stateset.com/graphql
wss://api.sandbox.stateset.com/v1/ws
Get Your API Key
Make Your First Call
Explore Resources
Key Type | Prefix | Environment | Usage |
---|---|---|---|
Live Key | sk_live_ | Production | Real transactions and data |
Test Key | sk_test_ | Sandbox | Development and testing |
Restricted Key | rk_live_ | Production | Limited scope access |
Publishable Key | pk_live_ | Client-side | Public operations only |
X-RateLimit-Limit
: Maximum requests allowed in current windowX-RateLimit-Remaining
: Requests remaining in current windowX-RateLimit-Reset
: Unix timestamp when limit resetsX-RateLimit-Retry-After
: Seconds to wait before retrying (when limited)429 Too Many Requests
response:
Code | Meaning |
---|---|
200 | OK - Request succeeded |
201 | Created - Resource created successfully |
400 | Bad Request - Invalid request parameters |
401 | Unauthorized - Invalid or missing API key |
403 | Forbidden - Insufficient permissions |
404 | Not Found - Resource doesn’t exist |
409 | Conflict - Resource already exists or constraint violation |
422 | Unprocessable Entity - Validation errors |
429 | Too Many Requests - Rate limit exceeded |
500 | Internal Server Error - Something went wrong on our end |
Authentication Errors
INVALID_API_KEY
: API key is invalid or expiredMISSING_API_KEY
: No API key providedINSUFFICIENT_PERMISSIONS
: API key doesn’t have required permissionsValidation Errors
VALIDATION_ERROR
: Request data failed validationMISSING_REQUIRED_FIELD
: Required field not providedINVALID_FIELD_FORMAT
: Field format is incorrectResource Errors
RESOURCE_NOT_FOUND
: Requested resource doesn’t existRESOURCE_ALREADY_EXISTS
: Resource with same identifier existsRESOURCE_CONFLICT
: Operation conflicts with current resource stateParameter | Type | Default | Max | Description |
---|---|---|---|---|
limit | integer | 10 | 100 | Number of items per page |
cursor | string | null | - | Cursor for next page (recommended) |
offset | integer | 0 | 10000 | Number of items to skip |
page | integer | 1 | - | Page number (deprecated) |
Operator | Description | Example |
---|---|---|
_eq | Equals | ?status_eq=shipped |
_ne | Not equals | ?status_ne=cancelled |
_gt | Greater than | ?amount_gt=100 |
_gte | Greater than or equal | ?amount_gte=100 |
_lt | Less than | ?amount_lt=500 |
_lte | Less than or equal | ?amount_lte=500 |
_in | In array | ?status_in=pending,processing |
_like | Pattern match | ?email_like=%@example.com |
_between | Range | ?created_between=2024-01-01,2024-01-31 |
Order Events
order.created
- New order placedorder.updated
- Order details modifiedorder.paid
- Payment confirmedorder.processing
- Order processing startedorder.shipped
- Shipment createdorder.delivered
- Delivery confirmedorder.cancelled
- Order cancelledorder.refunded
- Refund processedReturn Events
return.created
- Return initiatedreturn.approved
- Return approvedreturn.received
- Items receivedreturn.processed
- Return completedreturn.rejected
- Return rejectedInventory Events
inventory.low_stock
- Stock below thresholdinventory.out_of_stock
- Item out of stockinventory.updated
- Stock levels changedinventory.transfer
- Stock transferredCustomer Events
customer.created
- New customer registeredcustomer.updated
- Customer profile updatedcustomer.deleted
- Customer deletedcustomer.subscription.created
- Subscription startedcustomer.subscription.cancelled
- Subscription cancelledCard Number | Scenario | Result |
---|---|---|
4242 4242 4242 4242 | Successful payment | Always succeeds |
4000 0000 0000 0002 | Card declined | Always fails |
4000 0000 0000 9995 | Insufficient funds | Fails with insufficient_funds |
4000 0000 0000 0127 | Incorrect CVC | Fails CVC check |
{resource}-{uuid}
(e.g., order-550e8400-e29b-41d4-a716
)Plan | Requests/Min | Requests/Day | Burst Limit | Concurrent Connections |
---|---|---|---|---|
Free | 60 | 1,000 | 100/sec | 10 |
Starter | 100 | 10,000 | 200/sec | 25 |
Growth | 1,000 | 100,000 | 1,000/sec | 100 |
Scale | 5,000 | 500,000 | 5,000/sec | 500 |
Enterprise | Custom | Unlimited | Custom | Unlimited |
Resource | Limit | Notes |
---|---|---|
Max request size | 10 MB | Increase available for Enterprise |
Max response size | 50 MB | Paginate for larger datasets |
Webhook timeout | 30 seconds | Retry up to 3 times |
File upload size | 100 MB | Direct upload to S3 for larger files |
Batch operations | 1,000 items | Use async jobs for larger batches |