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

# Introduction

> Merchant API V2 — authenticated REST API for stores, LLM agents, MCP tools, and ERP integrations.

The Merchant API V2 lets merchants, scripts, and integrations interact with a Take App store through a clean, predictable REST contract. It is the successor to the V1 Platform API and is recommended for all new integrations.

V1 endpoints under `/api/platform/*` continue to work and are unchanged. V2 lives under `/api/v2/*` and is designed for long-term stability.

## What changed from V1

* **Naming**: every JSON field is `snake_case`.
* **Money**: integer values in the smallest currency unit (e.g. cents). No human-formatted strings.
* **Phone**: international, digits only, no leading `+`.
* **Order number**: the raw counter integer as a string. No prefix/suffix.
* **Errors**: structured `{ error: { type, code, message, param?, request_id } }`.
* **Lists**: cursor-paginated `{ object: "list", data, has_more, next_cursor }`.

## Authentication

All requests require an authenticated Merchant API token. Pass it in the `Authorization` header using the Bearer scheme.

```http theme={null}
GET https://take.app/api/v2/me
Authorization: Bearer YOUR_API_TOKEN
```

* `401 authentication_error` — missing or invalid token.
* `403 permission_error` — reserved for future scope checks.

> The V1 query-string `?api_key=` form is **not** accepted on V2.

## Idempotency

For safe retries on `POST` requests, pass an `Idempotency-Key` header. Repeated requests with the same token, route, and key return the same response within 24 hours.

```http theme={null}
POST https://take.app/api/v2/orders
Authorization: Bearer YOUR_API_TOKEN
Idempotency-Key: 0d3c9d04-2f2b-4e7c-9c4c-b8c0f7e0a1ab
```

## Pagination

List endpoints return:

```json theme={null}
{
  "object": "list",
  "data": [ /* ... */ ],
  "has_more": true,
  "next_cursor": "eyJjcmVhdGVkQXQiOi..."
}
```

Pass the returned `next_cursor` value as the `cursor` query parameter on the next request. Default `limit` is 25; max 100.

## Errors

All errors share one envelope:

```json theme={null}
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Customer phone is required",
    "param": "customer.phone",
    "request_id": "req_xxx"
  }
}
```

| Type                    | HTTP |
| ----------------------- | ---- |
| `invalid_request_error` | 400  |
| `authentication_error`  | 401  |
| `permission_error`      | 403  |
| `not_found_error`       | 404  |
| `rate_limit_error`      | 429  |
| `api_error`             | 500  |

Every response includes an `x-request-id` header that matches `error.request_id`.

## Resources

* **Store** — `/api/v2/me`
* **Products** — `/api/v2/products`
* **Customers** — `/api/v2/customers`
* **Orders** — `/api/v2/orders`
* **Inventory items** — `/api/v2/inventory_items`