API Overview

The Storelayer API is a RESTful API that uses JSON for request and response bodies. All endpoints are served from https://api.storelayer.io.

Base URL

https://api.storelayer.io/v1

Authentication

All API requests require authentication. See Authentication for details.

Request Format

Use Content-Type: application/json for all requests with a body
All request bodies must be valid JSON
Dates use ISO 8601 format (2025-01-15T10:30:00Z)
Monetary values are in cents (e.g., 4999 = $49.99)

Response Format

All responses follow a consistent envelope:

// Success
{
  "success": true,
  "data": { ... }
}

// Success with pagination
{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 142
  }
}

// Error
{
  "success": false,
  "error": {
    "code": 400,
    "message": "Validation error: email is required"
  }
}

HTTP Status Codes

Code	Meaning
`200`	Success
`201`	Created
`400`	Bad request / validation error
`401`	Unauthorized — invalid or missing credentials
`403`	Forbidden — insufficient permissions
`404`	Resource not found
`409`	Conflict — resource already exists
`429`	Rate limit exceeded
`500`	Internal server error

Pagination

List endpoints support pagination with query parameters:

GET /v1/customers?page=2&limit=50

Parameter	Default	Max	Description
`page`	1	—	Page number
`limit`	20	100	Items per page

Idempotency

For POST requests, include an Idempotency-Key header to safely retry requests:

curl -X POST https://api.storelayer.io/v1/wallets/{id}/credit \
  -H "Idempotency-Key: unique-request-id" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"amount": 100}'

API Endpoints

Resource	Endpoint	Description
Customers	`/v1/customers`	Manage customers
Wallets	`/v1/wallets`	Points & ledger
Promotions	`/v1/promotions`	Offers & coupons
Events	`/ingest/events`	Event tracking
Referrals	`/v1/referrals`	Referral programs
Catalog	`/v1/catalog`	Products
Stores	`/v1/stores`	Locations