API Reference

The Socolode REST API lets you manage products, orders, customers, and store settings programmatically.

Authentication

All API requests require an access token. Generate one under Settings > API.

Authorization: Bearer sk_your_access_token

Keep your token secret. Never expose it in client-side code or public repositories.

Base URL

https://api.socolode.com/v1

Rate limits

Each store is limited to 100 requests per minute per access token. Rate limit headers are included in every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1721692800

When the limit is exceeded, the API returns 429 Too Many Requests.

Products

List products

GET /v1/products?page=1&limit=50

Response:

{
  "data": [
    {
      "id": "prd_abc123",
      "title": "Classic Sneakers",
      "price": 59.99,
      "currency": "USD",
      "status": "active",
      "inventory": 120,
      "created_at": "2026-01-15T08:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 320,
    "total_pages": 7
  }
}

Create a product

POST /v1/products
Content-Type: application/json

{
  "title": "Classic Sneakers",
  "price": 59.99,
  "currency": "USD",
  "sku": "SNK-001",
  "inventory": 100,
  "category": "footwear",
  "tags": ["new", "summer"]
}

Update a product

PATCH /v1/products/prd_abc123
Content-Type: application/json

{
  "price": 49.99,
  "inventory": 80
}

Delete a product

DELETE /v1/products/prd_abc123

Orders

List orders

GET /v1/orders?status=paid&page=1&limit=50

Retrieve an order

GET /v1/orders/ord_xyz789

Fulfill an order

POST /v1/orders/ord_xyz789/fulfillments
Content-Type: application/json

{
  "tracking_number": "1Z999AA10123456784",
  "carrier": "ups",
  "notify_customer": true
}

Webhooks

Register webhooks under Settings > API > Webhooks to receive real-time event notifications.

Event	Trigger
order.created	New order placed
order.paid	Payment captured
order.fulfilled	Order shipped
product.updated	Product modified
inventory.low	Stock below threshold

Webhook payloads are sent as POST requests with a JSON body. Verify authenticity using the X-Socolode-Signature header, which contains an HMAC-SHA256 hash of the body using your webhook secret.

Error responses

All errors follow a consistent format:

{
  "error": {
    "code": "not_found",
    "message": "Product not found",
    "request_id": "req_abc123"
  }
}

HTTP Status	Code	Description
400	bad_request	Invalid parameters
401	unauthorized	Missing or invalid token
404	not_found	Resource does not exist
422	validation_error	Request failed validation
429	rate_limited	Rate limit exceeded
500	server_error	Internal server error