StateSet API Reference

Welcome to the StateSet API. Our comprehensive REST and GraphQL APIs enable you to build powerful autonomous business applications that scale with your needs.

REST API

RESTful endpoints for all StateSet resources

GraphQL API

Flexible queries with real-time subscriptions

SDKs

Official SDKs for popular languages

Webhooks

Real-time event notifications

Base URL: https://api.stateset.com/v1GraphQL Endpoint: https://api.stateset.com/graphqlWebSocket URL: wss://api.stateset.com/v1/wsAPI Version: 2024-01-01 (latest)

Quick Start

Get Your API Key

Sign up at stateset.com
Navigate to Settings → API Keys
Generate a new API key with appropriate scopes

Store your API key securely and never expose it in client-side code.

Make Your First Call

Test the connection with a simple API call:

curl https://api.stateset.com/v1/orders \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json"

Explore Resources

Browse our comprehensive API reference to discover all available endpoints and capabilities.

Authentication

StateSet API uses API key authentication. Include your API key in the Authorization header using the Bearer scheme.

API Key Authentication

curl https://api.stateset.com/v1/orders \
  -H "Authorization: Bearer sk_live_51HqJx2eZvKYlo2CXcQhJZPiQdoJO4v_FGtbA8QTy9E4tY"

Environment Variables

We recommend storing your API keys as environment variables:

# Development
export STATESET_API_KEY=sk_test_51HqJx2eZvKYlo2CX...

# Production  
export STATESET_API_KEY=sk_live_51HqJx2eZvKYlo2CX...

Rate Limits

Rate Limits by Plan:

Starter: 100 requests/minute, 10,000 requests/day
Growth: 1,000 requests/minute, 100,000 requests/day
Scale: 5,000 requests/minute, 500,000 requests/day
Enterprise: Custom limits up to 10,000 requests/minute

Rate limit headers included in responses:

X-RateLimit-Limit: Maximum requests allowed in current window
X-RateLimit-Remaining: Requests remaining in current window
X-RateLimit-Reset: Unix timestamp when limit resets
X-RateLimit-Retry-After: Seconds to wait before retrying (when limited)

Handling Rate Limits

When you exceed rate limits, you’ll receive a 429 Too Many Requests response:

{
  "error": {
    "code": "RATE_LIMITED", 
    "message": "Rate limit exceeded. Please retry after 60 seconds.",
    "retry_after": 60,
    "limit": 1000,
    "remaining": 0,
    "reset_at": "2024-01-15T12:00:00Z"
  }
}

Best practices for handling rate limits:

async function apiRequestWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);
      
      if (response.status === 429) {
        const retryAfter = response.headers.get('X-RateLimit-Retry-After');
        const delay = retryAfter ? parseInt(retryAfter) * 1000 : Math.pow(2, attempt) * 1000;
        
        if (attempt < maxRetries) {
          await new Promise(resolve => setTimeout(resolve, delay));
          continue;
        }
      }
      
      return response;
    } catch (error) {
      if (attempt === maxRetries) throw error;
      await new Promise(resolve => setTimeout(resolve, Math.pow(2, attempt) * 1000));
    }
  }
}

Error Handling

StateSet API uses conventional HTTP response codes and returns detailed error information in JSON format.

HTTP Status Codes

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

Error Response Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": {
      "field": "email",
      "issue": "Invalid email format"
    },
    "request_id": "req_1NXWPnCo6bFb1KQto6C8OWvE",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Common Error Codes

Authentication Errors

Validation Errors

Resource Errors

Pagination

List endpoints support both offset-based and cursor-based pagination.

Offset-Based Pagination

GET /v1/orders?limit=20&offset=40

Cursor-Based Pagination (Recommended)

More efficient for large datasets:

GET /v1/orders?limit=20&cursor=eyJpZCI6Im9yZF8xMjM0NSJ9

Response format:

{
  "data": [...],
  "pagination": {
    "has_more": true,
    "next_cursor": "eyJpZCI6Im9yZF82Nzg5MCJ9",
    "total_count": 1250
  }
}

Filtering and Sorting

Most list endpoints support powerful filtering and sorting capabilities.

Common Filter Patterns

# Exact match
GET /v1/orders?status=shipped

# Multiple values  
GET /v1/orders?status_in=pending,processing,shipped

# Range queries
GET /v1/orders?created_after=2024-01-01T00:00:00Z
GET /v1/orders?total_amount_gte=100.00&total_amount_lte=500.00

# Search
GET /v1/orders?search=john@example.com

# Complex filtering
GET /v1/orders?status=shipped&created_after=2024-01-01&customer_tier=gold

Sorting

# Sort by field (default: ascending)
GET /v1/orders?sort=created_at

# Specify direction
GET /v1/orders?sort=total_amount&order=desc

# Multiple sort fields
GET /v1/orders?sort=status,created_at&order=asc,desc

Official SDKs

Node.js

npm install stateset-node

Python

pip install stateset-python

Ruby

gem install stateset-ruby

Go

go get github.com/stateset/stateset-go

SDK Quick Example

import { StateSetClient } from 'stateset-node';

const client = new StateSetClient({
  apiKey: process.env.STATESET_API_KEY,
  environment: 'production' // or 'sandbox'
});

// Create an order
const order = await client.orders.create({
  customer_email: 'customer@example.com',
  items: [
    { sku: 'WIDGET-001', quantity: 2, price: 29.99 }
  ]
});

console.log(`Order created: ${order.id}`);

GraphQL API

StateSet offers a powerful GraphQL API for flexible data querying and real-time subscriptions.

GraphQL Endpoint

POST https://api.stateset.com/graphql

Basic Query Example

query GetOrdersWithItems {
  orders(limit: 10, where: {status: {_eq: "shipped"}}) {
    id
    order_number
    status
    total_amount
    customer {
      id
      email
      first_name
      last_name
    }
    line_items {
      id
      sku
      quantity
      price
      product {
        name
        category
      }
    }
  }
}

Real-time Subscriptions

subscription OrderUpdates {
  orders(where: {status: {_in: ["processing", "shipped"]}}) {
    id
    status
    updated_at
  }
}

Webhooks

StateSet can send webhook notifications for important events in your account.

Webhook Events

Order Events

Webhook Setup

Configure webhook endpoints in your dashboard
Verify webhook signatures for security
Handle webhook events in your application

// Webhook verification example
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
    
  return signature === `sha256=${expectedSignature}`;
}

Testing

Sandbox Environment

Use the sandbox environment for testing:

# Sandbox endpoint
https://api.sandbox.stateset.com/v1

# Test API keys start with sk_test_
Authorization: Bearer sk_test_51HqJx2eZvKYlo2CX...

Test Data

Sandbox includes pre-populated test data:

Sample orders, customers, and products
Test credit card numbers that don’t charge real money
Predictable webhook events for testing

Pro Tip: Use idempotency keys for safe testing of POST requests:

curl -X POST https://api.stateset.com/v1/orders \
  -H "Idempotency-Key: order-test-123" \
  -H "Authorization: Bearer sk_test_..." \
  -d '{"customer_email": "test@example.com"}'

Support and Community

API Support

Get help with integration issues

Discord Community

Join our developer community

Status Page

Check API status and uptime

Ready to get started? Check out our 5-minute quickstart guide or explore the API reference sections below.

StateSet One

​StateSet API Reference

REST API

GraphQL API

SDKs

Webhooks

​Quick Start

​Authentication

​API Key Authentication

​Environment Variables

​Rate Limits

​Handling Rate Limits

​Error Handling

​HTTP Status Codes

​Error Response Format

​Common Error Codes

​Pagination

​Offset-Based Pagination

​Cursor-Based Pagination (Recommended)

​Filtering and Sorting

​Common Filter Patterns

​Sorting

​Official SDKs

Node.js

Python

Ruby

Go

​SDK Quick Example

​GraphQL API

​GraphQL Endpoint

​Basic Query Example

​Real-time Subscriptions

​Webhooks

​Webhook Events

​Webhook Setup

​Testing

​Sandbox Environment

​Test Data

​Support and Community

API Support

Discord Community

Status Page

StateSet API Reference

Quick Start

Authentication

API Key Authentication

Environment Variables

Rate Limits

Handling Rate Limits

Error Handling

HTTP Status Codes

Error Response Format

Common Error Codes

Pagination

Offset-Based Pagination

Cursor-Based Pagination (Recommended)

Filtering and Sorting

Common Filter Patterns

Sorting

Official SDKs

SDK Quick Example

GraphQL API

GraphQL Endpoint

Basic Query Example

Real-time Subscriptions

Webhooks

Webhook Events

Webhook Setup

Testing

Sandbox Environment

Test Data

Support and Community