API Introduction

Base URLs

Sticker provides separate environments for development and production:

https://api.usesticker.com/v1/

Authentication

All API requests require authentication using your Partner API Key:

Authorization: Bearer sk_live_your_api_key_here

Keep your API keys secure. Never expose them in client-side code or commit them to version control.

Request Format

All requests must:

Use HTTPS
Include Content-Type: application/json header
Send JSON-formatted request bodies
Include proper authentication headers

Example Request

curl -X POST https://api.staging.usesticker.com/v1/partner/organization-setup \
  -H "Authorization: Bearer sk_test_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "organization": {
      "name": "Acme Medical",
      "email": "admin@acme.com"
    }
  }'

Response Format

All responses are JSON-formatted and include:

Success Response

{
  "success": true,
  "data": { /* response data */ }
}

Error Response

{
  "error": "Error message",
  "code": "ERROR_CODE",
  "details": "Additional context"
}

HTTP Status Codes

Code	Meaning	Description
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 not found
409	Conflict	Resource already exists
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error
503	Service Unavailable	Temporary outage

Rate Limiting

API requests are rate limited to ensure system stability:

Endpoint	Rate Limit	Burst Limit
Organization Setup	100/hour	10 concurrent
Handshake	1,000/hour	100 concurrent

Rate Limit Headers

Responses include rate limit information:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1639584000

Handling Rate Limits

When rate limited, you’ll receive a 429 response:

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "retry_after": 60
}

Implement exponential backoff for retries.

Error Codes

Authentication Errors

INVALID_API_KEY - API key is invalid or expired
UNAUTHORIZED - Missing authentication header

Request Errors

INVALID_REQUEST - Malformed request body
MISSING_FIELD - Required field is missing
INVALID_FORMAT - Field format is incorrect

Resource Errors

ORGANIZATION_NOT_FOUND - Organization doesn’t exist
USER_NOT_FOUND - User not in organization
DUPLICATE_ORGANIZATION - Organization already exists

System Errors

RATE_LIMIT_EXCEEDED - Too many requests
INTERNAL_ERROR - Server error
SERVICE_UNAVAILABLE - Temporary outage

Pagination

List endpoints support pagination:

GET /api/partner/orders?page=2&limit=50

Pagination Parameters

page

number

default:"1"

Page number (1-indexed)

limit

number

default:"25"

Number of items per page (max: 100)

Pagination Response

{
  "data": [ /* items */ ],
  "pagination": {
    "page": 2,
    "limit": 25,
    "total": 127,
    "pages": 6
  }
}

Versioning

The API is versioned through the URL path:

https://api.sticker.com/v1/partner/...

Current version: v1

When we introduce breaking changes, we’ll release a new API version and provide migration guides.

Idempotency

POST requests support idempotency keys to prevent duplicate operations:

curl -X POST https://api.staging.usesticker.com/v1/partner/organization-setup \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: unique-key-123" \
  -H "Content-Type: application/json" \
  -d '{ /* request body */ }'

If you retry a request with the same idempotency key within 24 hours, you’ll receive the cached response.

Webhooks

Sticker can send real-time notifications to your server:

Order placed
Order shipped
Order delivered
Order cancelled

See the Webhooks Guide for setup instructions.

SDKs & Libraries

Official SDKs coming soon. For now, use standard HTTP libraries:

// Using fetch
const response = await fetch('https://api.staging.usesticker.com/v1/partner/handshake', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.STICKER_SANDBOX_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(data)
});

Testing

Use the sandbox environment for testing:

# Sandbox base URL
https://api.staging.usesticker.com/v1/

# Sandbox API key
sk_test_...

Sandbox features:

Separate database from production
Test credit cards accepted
No real orders fulfilled
Unlimited API calls
Data reset every 30 days

API Reference

Base URLs

Authentication

Request Format

Example Request

Response Format

Success Response

Error Response

HTTP Status Codes

Rate Limiting

Rate Limit Headers

Handling Rate Limits

Error Codes

Versioning

Idempotency

Webhooks

SDKs & Libraries

Testing

Support

API Status

Partner Support

Next Steps

Organization Setup API

Handshake API

API Reference

​Base URLs

​Authentication

​Request Format

​Example Request

​Response Format

​Success Response

​Error Response

​HTTP Status Codes

​Rate Limiting

​Rate Limit Headers

​Handling Rate Limits

​Error Codes

​Pagination

​Pagination Parameters

​Pagination Response

​Versioning

​Idempotency

​Webhooks

​SDKs & Libraries

​Testing

​Support

API Status

Partner Support

​Next Steps

Organization Setup API

Handshake API

Base URLs

Authentication

Request Format

Example Request

Response Format

Success Response

Error Response

HTTP Status Codes

Rate Limiting

Rate Limit Headers

Handling Rate Limits

Error Codes

Pagination

Pagination Parameters

Pagination Response

Versioning

Idempotency

Webhooks

SDKs & Libraries

Testing

Support

Next Steps