API Reference – CartOS Developers

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."
  }
}

Status	Meaning
`200`	Success
`201`	Resource created
`400`	Bad request — check your parameters
`401`	Unauthorized — missing or invalid API key
`403`	Forbidden — API key lacks the required scope
`404`	Resource not found
`429`	Rate limit exceeded
`500`	Internal server error

Pagination

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

Parameter	Default	Description
`page`	`1`	Page number
`per_page`	`25`	Results per page (max 100)

Rate Limits

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

Header	Description
`X-RateLimit-Limit`	Maximum requests per window
`X-RateLimit-Remaining`	Requests remaining in current window
`X-RateLimit-Reset`	Unix 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

Parameter	Type	Description
collection_id	integer	Filter by collection
available	boolean	Filter by availability
price_min	decimal	Minimum price filter
price_max	decimal	Maximum price filter
created_after	datetime	Products created after this date (ISO 8601)
sort	string	`title`, `price`, `created_at`, `updated_at`
order	string	`asc` 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

Parameter	Type	Description
id required	integer	Product 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

Parameter	Type	Description
status	string	`pending`, `processing`, `shipped`, `delivered`, `cancelled`
created_after	datetime	Filter by creation date (ISO 8601)
created_before	datetime	Filter by creation date (ISO 8601)
customer_id	integer	Filter 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

Event	Trigger
`order.created`	A new order is placed
`order.updated`	Order details are modified
`order.shipped`	Order status changes to shipped
`order.cancelled`	An order is cancelled
`product.created`	A new product is published
`product.updated`	Product details are modified
`customer.created`	A new customer registers
`subscription.renewed`	A subscription generates a new order
`subscription.cancelled`	A subscription is cancelled
`payment.failed`	A 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.

Scope	Allows
`products:read`	List products, get product details, check inventory
`products:write`	Create and update products
`orders:read`	List orders, get order details
`orders:write`	Create orders, update order status
`customers:read`	Get customer info, order history, loyalty balance
`customers:write`	Create and update customers
`subscriptions:read`	View subscription details, upcoming orders
`subscriptions:write`	Create, modify, and cancel subscriptions
`*`	Admin access — all endpoints (use sparingly)