> ## Documentation Index
> Fetch the complete documentation index at: https://docs.launchmystore.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API Overview

> REST API reference for LaunchMyStore

# API Reference

The LaunchMyStore API is a REST API that allows you to manage store data including products, orders, customers, and more.

## Base URL

```
https://api.launchmystore.io
```

## Authentication

All API requests require authentication via OAuth 2.0 access tokens:

```bash theme={null}
curl -X GET "https://api.launchmystore.io/api/v1/products.json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"
```

See [Authentication](/getting-started/authentication) for details on obtaining tokens.

## Request Format

* All requests should include `Content-Type: application/json`
* Request bodies should be valid JSON
* Date fields use ISO 8601 format (`2024-01-15T10:30:00Z`)
* Monetary values on standard commerce resources (products, orders, customers) are **decimal strings** (e.g., `"10.00"`). The only cents values are fields whose name explicitly says so (e.g., app-billing `capAmountCents`).

## Response Format

Most endpoints return a standard JSON envelope. Some resources (for example orders and products) instead return a bare response body — the resource(s) under a top-level key (`order` / `orders`, `product` / `products`) with pagination carried in a `Link` response header. Each response also advertises the contract version via the `X-LMS-Api-Version` header. Check the page for the resource you're calling to see which shape it uses.

### Success Response (standard envelope)

```json theme={null}
{
  "status": 200,
  "state": "success",
  "message": null,
  "data": {
    // Resource data
  },
  "count": null,
  "pagination": null
}
```

The `state` field is `success`, `error`, `info`, or `warning`. Single-resource responses leave `count` and `pagination` as `null`.

### List Response (standard envelope)

```json theme={null}
{
  "status": 200,
  "state": "success",
  "message": null,
  "data": [...],
  "count": 150,
  "pagination": {
    "page": 1,
    "limit": 50,
    "totalPages": 3,
    "resultCount": 50,
    "totalResult": 150
  }
}
```

### Bare Response

```
Link: <https://api.launchmystore.io/api/v1/orders.json?limit=50&page=2>; rel="next"
X-LMS-Api-Version: 2026-06
```

```json theme={null}
{
  "orders": [...]
}
```

### Error Response

Errors return a standard `{ errors }` body, where each key maps to an array of messages (`base` is used for general errors):

```json theme={null}
{
  "errors": {
    "base": ["Order not found"]
  }
}
```

Validation failures group messages per field:

```json theme={null}
{
  "errors": {
    "base": ["status must be one of the following values: pending, confirmed, processing, shipped, delivered, cancelled"]
  }
}
```

## Pagination

List endpoints that return the standard envelope accept these parameters and report totals under `pagination`:

| Parameter | Default | Description                                                           |
| --------- | ------- | --------------------------------------------------------------------- |
| `page`    | 1       | Page number                                                           |
| `limit`   | 50      | Items per page. Maximum **250** — larger values are silently clamped. |

```bash theme={null}
GET /api/v1/products.json?page=2&limit=100
```

Endpoints that return the bare response body convey paging through the RFC-5988 `Link` header (`rel="next"` / `rel="previous"`) instead of a body field.

## Filtering

Many endpoints support filtering. Supported filters vary per resource — see the individual endpoint pages for the exact query parameters each accepts (unrecognized parameters are ignored):

```bash theme={null}
GET /api/v1/products.json?status=active
GET /api/v1/orders.json?status=confirmed&since_id=1001
```

## Rate Limits

Rate limits are based on your app's billing tier:

| Tier       | Requests/second |
| ---------- | --------------- |
| Free       | 20              |
| Basic      | 40              |
| Pro        | 100             |
| Enterprise | 500             |

Rate limit headers are included in every response:

```
X-RateLimit-Limit: 40
X-RateLimit-Remaining: 38
X-RateLimit-Reset: 1705312800
```

When rate limited, you'll receive a `429 Too Many Requests` response.

## Error Codes

Errors are signalled by the HTTP status code; the response body is the `{ errors }` object described above (there is no separate machine-readable error-code string).

| HTTP Status | Description                                         |
| ----------- | --------------------------------------------------- |
| 401         | Invalid or expired token                            |
| 403         | Insufficient permissions (missing scope)            |
| 404         | Resource doesn't exist                              |
| 422         | Invalid request data (validation failure)           |
| 429         | Too many requests (rate limited; see `Retry-After`) |
| 500         | Server error                                        |

## Versioning

The API version is included in the URL path. The current version is `v1`.

Breaking changes will be released in new versions (e.g., `v2`). We'll provide at least 12 months notice before deprecating old versions.

## Resources

<CardGroup cols={2}>
  <Card title="Products" icon="box" href="/api-reference/products/list">
    Manage products and variants
  </Card>

  <Card title="Orders" icon="receipt" href="/api-reference/orders/list">
    Process and fulfill orders
  </Card>

  <Card title="Customers" icon="users" href="/api-reference/customers/list">
    Manage customer data
  </Card>

  <Card title="Inventory" icon="warehouse" href="/api-reference/inventory/list">
    Track inventory levels
  </Card>

  <Card title="Collections" icon="folder" href="/api-reference/collections/list">
    Organize products
  </Card>

  <Card title="Discounts" icon="tag" href="/api-reference/discounts/list">
    Create discount codes
  </Card>
</CardGroup>