Store API

The Store API provides endpoints for customer-facing operations including browsing products, managing shopping carts, and placing orders.

Carts

Create and manage shopping carts, add items, and complete checkout

Products

Browse the product catalog and retrieve pricing

Customers

Manage customer accounts and authentication

Orders

View order history and track shipments

Base URL

All Store API requests should be made to:

https://switchyard.run/store

Authentication

The Store API supports both guest and authenticated customer access.

Guest Access
Customer Authentication

Many endpoints work without authentication:

Browsing products
Creating carts
Viewing shipping options
Completing checkout as a guest

Include the publishable API key in all requests:

curl -X GET 'https://switchyard.run/store/products' \
  -H 'x-publishable-api-key: YOUR_PUBLISHABLE_KEY'

For customer-specific operations, use JWT authentication:

curl -X GET 'https://switchyard.run/store/customers/me' \
  -H 'x-publishable-api-key: YOUR_PUBLISHABLE_KEY' \
  -H 'Authorization: Bearer CUSTOMER_JWT_TOKEN'

Obtain a token by authenticating:

curl -X POST 'https://switchyard.run/auth/customer/emailpass' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "customer@example.com",
    "password": "securepassword"
  }'

Required Headers

x-publishable-api-key

string

required

Your publishable API key. Identifies your sales channel and enables API access.

Content-Type

string

Set to application/json for requests with a body.

Authorization

string

Bearer token for authenticated customer requests. Format: Bearer YOUR_JWT_TOKEN

Response Format

All successful responses follow this structure:

Single Resource

{
  "resource_name": {
    "id": "resource_123",
    "property": "value"
  }
}

List Response

{
  "resources": [
    { "id": "resource_1" },
    { "id": "resource_2" }
  ],
  "count": 100,
  "offset": 0,
  "limit": 20
}

Error Handling

Errors return appropriate HTTP status codes with details:

Error Response

{
  "type": "invalid_data",
  "message": "Variant with id variant_123 not found",
  "code": "variant_not_found"
}

Common Status Codes

Status	Description
`200`	Success
`201`	Created
`400`	Bad Request - Invalid data provided
`401`	Unauthorized - Authentication required
`404`	Not Found - Resource doesn’t exist
`409`	Conflict - Business rule violation (e.g., insufficient inventory)
`500`	Server Error

Pagination

List endpoints support pagination using limit and offset:

curl -X GET 'https://switchyard.run/store/products?limit=20&offset=40' \
  -H 'x-publishable-api-key: YOUR_KEY'

limit

integer

default:"20"

Maximum number of items to return. Range: 1-100.

offset

integer

default:"0"

Number of items to skip before starting to return results.

Field Selection

Use the fields parameter to select specific fields:

curl -X GET 'https://switchyard.run/store/carts/cart_123?fields=id,items,total' \
  -H 'x-publishable-api-key: YOUR_KEY'

Selecting only the fields you need improves response times and reduces bandwidth.

Expanding Relations

Use the expand parameter to include related data:

curl -X GET 'https://switchyard.run/store/carts/cart_123?expand=items.variant,shipping_methods' \
  -H 'x-publishable-api-key: YOUR_KEY'

Rate Limiting

The API is rate-limited to prevent abuse. Rate limit information is included in response headers:

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

If you exceed the rate limit, you’ll receive a 429 Too Many Requests response. Wait until the reset time before retrying.

Available Endpoints

Endpoint	Description
`/store/carts`	Shopping cart management
`/store/products`	Product catalog
`/store/collections`	Product collections
`/store/regions`	Available regions
`/store/shipping-options`	Shipping methods
`/store/payment-providers`	Payment options
`/store/customers`	Customer accounts
`/store/orders`	Order history

Overview

Scanner API

Admin API

Store API

Store API Introduction

Store API

Carts

Products

Customers

Orders

Base URL

Authentication

Required Headers

Response Format

Error Handling

Common Status Codes

Field Selection

Expanding Relations

Rate Limiting

Available Endpoints

Overview

Scanner API

Admin API

Store API

​Store API

Carts

Products

Customers

Orders

​Base URL

​Authentication

​Required Headers

​Response Format

​Error Handling

​Common Status Codes

​Pagination

​Field Selection

​Expanding Relations

​Rate Limiting

​Available Endpoints

Store API

Base URL

Authentication

Required Headers

Response Format

Error Handling

Common Status Codes

Pagination

Field Selection

Expanding Relations

Rate Limiting

Available Endpoints