Overview

The CartOS REST API allows third-party applications to integrate with CartOS stores. You can read product catalogs, manage orders, access customer data, handle subscriptions, and subscribe to real-time webhook events.

All requests use standard HTTP methods and return JSON responses. The API follows RESTful conventions with predictable resource URLs.

Authentication

All API requests require authentication via an API key passed in the X-API-Key header. Keys are scoped to specific permissions — a key with products:read can list products but cannot create orders.

Request Header
X-API-Key: ak_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
⚠️
Security: Never expose your API key in client-side code or public repositories. Always make API requests from your server, and always use HTTPS.

Base URL

All API endpoints are relative to the store's domain:

Base URL
https://{store-domain}/api

For example, if a store is at myshop.com, the products endpoint would be https://myshop.com/api/products.

Response Format

All responses return JSON with a consistent structure. Successful responses return the requested resource(s) directly. List endpoints include pagination metadata.

Successful Response
{
  "products": [ ... ],
  "pagination": {
    "total": 142,
    "page": 1,
    "per_page": 25,
    "total_pages": 6
  }
}

Error Handling

Errors return an appropriate HTTP status code with a JSON body containing an error object:

Error Response
{
  "error": {
    "code": "invalid_scope",
    "message": "Your API key does not have the 'orders:write' scope."
  }
}
StatusMeaning
200Success
201Resource created
400Bad request — check your parameters
401Unauthorized — missing or invalid API key
403Forbidden — API key lacks the required scope
404Resource not found
429Rate limit exceeded
500Internal server error

Pagination

List endpoints support limit/offset pagination with the following query parameters:

ParameterDefaultDescription
page1Page number
per_page25Results per page (max 100)

Rate Limits

API requests are rate limited per API key. Current limits are returned in response headers:

HeaderDescription
X-RateLimit-LimitMaximum requests per window
X-RateLimit-RemainingRequests remaining in current window
X-RateLimit-ResetUnix timestamp when the window resets

Products

Retrieve product data including titles, prices, images, variants, and inventory levels.

GET /api/products List products

Returns a paginated list of products. Supports filtering by category, price range, and availability.

Query Parameters

ParameterTypeDescription
collection_idintegerFilter by collection
availablebooleanFilter by availability
price_mindecimalMinimum price filter
price_maxdecimalMaximum price filter
created_afterdatetimeProducts created after this date (ISO 8601)
sortstringtitle, price, created_at, updated_at
orderstringasc or desc

Example Request

cURL
curl -H "X-API-Key: ak_live_xxxxxxxx" \
     "https://myshop.com/api/products?available=true&sort=price&order=asc"

Example Response

{
  "products": [
    {
      "id": 1042,
      "title": "Classic Tee",
      "handle": "classic-tee",
      "description": "A timeless cotton tee...",
      "price": 29.99,
      "compare_at_price": 39.99,
      "available": true,
      "images": ["https://cdn.myshop.com/products/tee-front.jpg"],
      "variants": [
        { "id": 2001, "title": "Small / Black", "price": 29.99, "inventory_quantity": 42 }
      ],
      "created_at": "2026-01-15T10:30:00Z"
    }
  ],
  "pagination": { "total": 86, "page": 1, "per_page": 25, "total_pages": 4 }
}

products:read

GET /api/products/{id} Get product details

Returns full details for a single product including all variants, images, and metadata.

Path Parameters

ParameterTypeDescription
id requiredintegerProduct ID

products:read

GET /api/products/{id}/inventory Check stock levels

Returns inventory quantities for all variants of a product.

products:read

Orders

Create, retrieve, and manage orders. Ideal for fulfillment partners, ERP integrations, and order management systems.

GET /api/orders List orders

Returns a paginated list of orders with filtering by status and date range.

Query Parameters

ParameterTypeDescription
statusstringpending, processing, shipped, delivered, cancelled
created_afterdatetimeFilter by creation date (ISO 8601)
created_beforedatetimeFilter by creation date (ISO 8601)
customer_idintegerFilter by customer

orders:read

GET /api/orders/{id} Get order details

Returns full order details including line items, shipping address, payment info, and status history.

Example Response

{
  "order": {
    "id": 50821,
    "order_number": "#1042",
    "status": "processing",
    "total": 79.97,
    "subtotal": 89.97,
    "discount": 10.00,
    "shipping": 0.00,
    "tax": 6.40,
    "line_items": [
      {
        "product_id": 1042,
        "variant_id": 2001,
        "title": "Classic Tee – Small / Black",
        "quantity": 3,
        "price": 29.99
      }
    ],
    "customer": { "id": 8842, "email": "jane@example.com" },
    "created_at": "2026-01-28T14:22:00Z"
  }
}

orders:read

POST /api/orders Create order

Creates a new order programmatically. Requires line items and customer information.

Request Body

{
  "customer_id": 8842,
  "line_items": [
    { "variant_id": 2001, "quantity": 2 }
  ],
  "shipping_address": {
    "first_name": "Jane",
    "last_name": "Smith",
    "address1": "123 Main St",
    "city": "Austin",
    "state": "TX",
    "zip": "78701",
    "country": "US"
  }
}

orders:write

PATCH /api/orders/{id}/status Update order status

Updates the fulfillment status of an order. Commonly used by shipping and fulfillment integrations.

Request Body

{
  "status": "shipped",
  "tracking_number": "1Z999AA10123456784",
  "tracking_url": "https://tracking.example.com/1Z999AA10123456784"
}

orders:write

Customers

Access customer profiles, order history, and loyalty program data.

GET /api/customers/{id} Get customer details

Returns customer profile including contact info, address book, and account status.

customers:read

POST /api/customers Create customer

Creates a new customer account. Email must be unique per store.

customers:write

PATCH /api/customers/{id} Update customer

Updates customer information. Only include the fields you want to change.

customers:write

GET /api/customers/{id}/orders Customer order history

Returns all orders placed by this customer, newest first.

customers:read

GET /api/customers/{id}/loyalty Loyalty points balance

Returns the customer's current loyalty points balance and transaction history.

customers:read

Subscriptions

Manage recurring subscriptions created through CartOS's Subscribe & Save system.

GET /api/subscriptions/{id} Get subscription details

Returns subscription details including products, frequency, status, and next renewal date.

Example Response

{
  "subscription": {
    "id": 3201,
    "customer_id": 8842,
    "status": "active",
    "frequency": "every_30_days",
    "next_order_date": "2026-02-15",
    "items": [
      { "product_id": 1042, "variant_id": 2001, "quantity": 1, "price": 26.99 }
    ],
    "created_at": "2025-11-15T09:00:00Z"
  }
}

subscriptions:read

POST /api/subscriptions Create subscription

Creates a new recurring subscription for a customer.

subscriptions:write

PATCH /api/subscriptions/{id} Modify subscription

Update frequency, products, or quantities on an existing subscription.

subscriptions:write

POST /api/subscriptions/{id}/cancel Cancel subscription

Cancels an active subscription. The subscription status changes to cancelled and no further orders are generated.

subscriptions:write

GET /api/subscriptions/{id}/upcoming Next scheduled order

Returns a preview of the next scheduled order for this subscription, including items and estimated total.

subscriptions:read

Webhooks

Subscribe to real-time events from CartOS stores. Webhooks send HTTP POST requests to your endpoint when events occur.

Available Events

EventTrigger
order.createdA new order is placed
order.updatedOrder details are modified
order.shippedOrder status changes to shipped
order.cancelledAn order is cancelled
product.createdA new product is published
product.updatedProduct details are modified
customer.createdA new customer registers
subscription.renewedA subscription generates a new order
subscription.cancelledA subscription is cancelled
payment.failedA payment attempt fails

Webhook Payload

All webhook payloads include the event type, a timestamp, and the relevant resource data:

{
  "event": "order.created",
  "timestamp": "2026-01-28T14:22:01Z",
  "data": {
    "order": {
      "id": 50821,
      "order_number": "#1042",
      "total": 79.97,
      // ... full order object
    }
  }
}
🛈
Verification: All webhook requests include an X-CartOS-Signature header containing an HMAC-SHA256 signature of the payload. Always verify this signature before processing webhook data.

Permission Scopes

Each API key is issued with specific scopes that control access. Request only the scopes your integration needs.

ScopeAllows
products:readList products, get product details, check inventory
products:writeCreate and update products
orders:readList orders, get order details
orders:writeCreate orders, update order status
customers:readGet customer info, order history, loyalty balance
customers:writeCreate and update customers
subscriptions:readView subscription details, upcoming orders
subscriptions:writeCreate, modify, and cancel subscriptions
*Admin access — all endpoints (use sparingly)