# OneCart API v2

OneCart is a global multichannel commerce platform — it supports sellers
worldwide, not any single region. The OneCart API lets you manage products,
orders, listings, and sales analytics across global marketplaces and
storefronts from one place, including Amazon (US, UK, EU and other regions),
Shopify, eBay, Walmart, TikTok Shop, WooCommerce, Magento, and Southeast Asian
marketplaces such as Shopee and Lazada.

> **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