# OneCart API v2

The OneCart API lets you manage your products, orders, listings, and
sales analytics across every channel you sell on — Shopee, Lazada,
Shopify, TikTok, and more — from one place.

> **Using API v1?** Version 1 is deprecated and at end of life. It will
> keep running **without support until 31 January 2027**, after which it
> will be shut down. Please migrate to v2 (documented here) in good time
> — see [Versioning](#versioning).

- **Base URL:** `https://app.getonecart.com/api/v2`
- All responses are JSON. Request parameters can be sent as query
  strings, form fields, or a JSON body.

## Authentication

Every request must include your API key in the `Authorization` header:

```
Authorization: YOUR_API_KEY
```

Create and manage keys in **Settings → API Keys** in your OneCart
dashboard. Each key belongs to one company and only ever sees that
company's data.

Keys come in two access levels:

- **Full access** — read and write.
- **Read-only** — `GET` requests only. Any write returns `403 FORBIDDEN`.

A missing or invalid key returns `401 UNAUTHORIZED`.

## Rate limits

Requests are limited to **300 per 60 seconds, per API key**. Every
response to a rate-limited endpoint carries:

| Header | Meaning |
| --- | --- |
| `X-RateLimit-Limit` | Requests allowed in the window |
| `X-RateLimit-Remaining` | Requests left in the current window |
| `X-RateLimit-Reset` | Unix time when the window resets |

Over the limit returns `429 RATE_LIMITED` with a `Retry-After` header
(seconds to wait). Back off and retry after that interval.

## Response format

Every successful response is wrapped in a consistent envelope:

```json
{
  "data": { },
  "meta": { },
  "links": { },
  "errors": [],
  "warnings": []
}
```

- `data` — the resource or list of resources you requested.
- `meta` — pagination and context (see below).
- `links` — pagination links; present on list endpoints only.
- `errors` — always empty (`[]`) on a successful response. When a request
  fails you get a different shape instead — see [Errors](#errors).
- `warnings` — non-fatal notices, such as deprecations. Usually empty.

## Pagination

List endpoints accept `page` (default `1`) and `per_page`
(default `25`, max `100`). `meta` reports where you are:

```json
"meta": {
  "current_page": 2,
  "per_page": 25,
  "total_items": 342,
  "total_pages": 14,
  "has_next_page": true,
  "has_previous_page": true
}
```

`links` gives ready-made URLs for `self`, `first`, `prev`, `next`,
and `last` — follow `next` until it is `null`.

## Choosing fields

Most endpoints support a `_fields` query parameter so you only fetch
what you need:

- Omit it for the resource's default fields.
- Pass a bare list — `?_fields=id,order_no,status` — to get exactly
  those fields (`id` is always included).
- Adjust the defaults with `+`/`-` — `?_fields=+order_items,-tracking_no`.

Unknown field names are ignored. Mixing a bare list with `+`/`-`
adjustments in the same request returns a `400`.

## Errors

When a request fails, the body is a single `error` object — not the empty
`errors` array from the success envelope:

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [{ "field": "quantity", "message": "must be an integer" }],
    "request_id": "b1f2…"
  }
}
```

`request_id` matches the `X-Request-Id` response header — include it when
contacting support.

| Code | Status | Meaning |
| --- | --- | --- |
| `UNAUTHORIZED` | 401 | Missing or invalid API key |
| `FORBIDDEN` | 403 | Key lacks access (e.g. read-only key on a write) |
| `NOT_FOUND` | 404 | Resource does not exist or isn't yours |
| `VALIDATION_ERROR` | 400 / 422 | Request parameters were invalid |
| `RATE_LIMITED` | 429 | Too many requests — see Rate limits |

## Versioning

This is version 2 of the OneCart API — the current, actively supported
version. We add fields without notice, so build clients that ignore
unrecognized fields; breaking changes ship as a new version.

**Version 1 is deprecated and at end of life.** It remains available but
**unsupported until 31 January 2027**, after which it will be shut down
permanently. All v1 users are strongly encouraged to migrate to v2 well
before that date.


- Base URL: https://app.getonecart.com/api/v2
- Auth: send your OneCart API key in the Authorization header. Read-only keys may call GET only.
- OpenAPI spec: https://developers.getonecart.com/openapi/v2.json

## Endpoints
- GET /api/v2/brands — List brands
- GET /api/v2/brands/{id}/skus — List a brand's SKUs
- POST /api/v2/bundle_uploads — Create a bundle upload
- GET /api/v2/bundle_uploads/{id} — Get a bundle upload
- GET /api/v2/buyer_categories — List buyer categories
- GET /api/v2/buyer_categories/{id}/skus — List SKUs in a category
- GET /api/v2/coverage — Find SKU coverage gaps
- POST /api/v2/coverage — Find SKU coverage gaps for a large SKU list
- GET /api/v2/delivery_orders — List delivery orders
- GET /api/v2/insights/brand_sales — Sales summary for a brand
- GET /api/v2/insights/bundles — Bundle analysis
- GET /api/v2/insights/cancellations — Cancellation metrics
- GET /api/v2/insights/category_sales — Sales summary for a category
- GET /api/v2/insights/channels — Channel performance
- GET /api/v2/insights/fees_by_brand — Fees by brand
- GET /api/v2/insights/fees_by_category — Fees by category
- GET /api/v2/insights/fees_by_shop — Fees by shop
- GET /api/v2/insights/fees_by_sku — Fees by SKU
- GET /api/v2/insights/fees_summary — Fee summary
- GET /api/v2/insights/hidden_winners — Hidden winners
- GET /api/v2/insights/out_of_stock_sellers — Out-of-stock sellers
- GET /api/v2/insights/peak_hours — Peak shopping hours
- GET /api/v2/insights/sku_sales — Sales summary for a SKU
- GET /api/v2/insights/sla_risks — Orders at risk of missing their ship-by deadline
- GET /api/v2/insights/slow_movers — Slow-moving inventory
- GET /api/v2/insights/stockout_risks — Products at risk of stocking out
- GET /api/v2/listings — List listings
- GET /api/v2/listings/count — Count listings
- GET /api/v2/listings/{id} — Get a listing
- PUT /api/v2/listings/{id} — Update a listing
- GET /api/v2/listings/{id}/skus — List a listing's SKUs
- GET /api/v2/orders — List orders
- PUT /api/v2/orders/bulk_cancel — Cancel orders in bulk
- GET /api/v2/orders/cancelled — List cancelled orders
- POST /api/v2/orders/print_awbs — Print shipping labels
- GET /api/v2/orders/{id} — Get an order
- PUT /api/v2/orders/{id} — Mark an order shipped
- PUT /api/v2/orders/{id}/cancel — Cancel an order
- GET /api/v2/shopify_locations — List Shopify locations
- PUT /api/v2/shopify_locations/{id} — Update location stock
- GET /api/v2/shops — List shops
- GET /api/v2/sku_channels — Look up channels for SKUs
- GET /api/v2/variants — List products
- POST /api/v2/variants — Create products
- PUT /api/v2/variants/bulk_update — Update stock in bulk
- GET /api/v2/variants/count — Count products
- POST /api/v2/variants/force_push — Resync stock to channels
- PUT /api/v2/variants/{id} — Update stock
- GET /api/v2/zapier — Test the connection