> For the complete documentation index, see [llms.txt](https://orbit-b2b.gitbook.io/orbit-b2b-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://orbit-b2b.gitbook.io/orbit-b2b-docs/partner-api/endpoints.md).

# Endpoints

Every path below is shown in full — `/api/partner/v1/...` — prepend the one fixed base URL given on the [Authentication](https://orbit-b2b.gitbook.io/orbit-b2b-docs/partner-api/authentication.md) page; it isn't repeated on every endpoint here. All endpoints (except `/api/partner/v1/oauth/token`) require `Authorization: Bearer <access_token>`.

The reference below is generated from this app's own [OpenAPI spec](https://gitlab.com/thoaingo.vnkingnet/wholesale/-/tree/main/docs/gitbook/partner-api/openapi.yaml) — every request/response shape, parameter, and example is pulled straight from it, not retyped by hand.

## Auth

{% openapi src="/files/PJWD1U3aYW16eUrjpzA3" path="/api/partner/v1/oauth/token" method="post" %}
[openapi.yaml](https://1915291744-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMiJSUsT8qpgeFd9r4nHD%2Fuploads%2Fgit-blob-e34ce5b79478f571f2aacaaae04d0dc799952425%2Fopenapi.yaml?alt=media)
{% endopenapi %}

{% openapi src="/files/PJWD1U3aYW16eUrjpzA3" path="/api/partner/v1/capabilities" method="get" %}
[openapi.yaml](https://1915291744-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMiJSUsT8qpgeFd9r4nHD%2Fuploads%2Fgit-blob-e34ce5b79478f571f2aacaaae04d0dc799952425%2Fopenapi.yaml?alt=media)
{% endopenapi %}

## Pricing

{% openapi src="/files/PJWD1U3aYW16eUrjpzA3" path="/api/partner/v1/pricing-rules" method="get" %}
[openapi.yaml](https://1915291744-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMiJSUsT8qpgeFd9r4nHD%2Fuploads%2Fgit-blob-e34ce5b79478f571f2aacaaae04d0dc799952425%2Fopenapi.yaml?alt=media)
{% endopenapi %}

{% openapi src="/files/PJWD1U3aYW16eUrjpzA3" path="/api/partner/v1/pricing/calculate" method="post" %}
[openapi.yaml](https://1915291744-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMiJSUsT8qpgeFd9r4nHD%2Fuploads%2Fgit-blob-e34ce5b79478f571f2aacaaae04d0dc799952425%2Fopenapi.yaml?alt=media)
{% endopenapi %}

{% openapi src="/files/PJWD1U3aYW16eUrjpzA3" path="/api/partner/v1/pricing/validate" method="post" %}
[openapi.yaml](https://1915291744-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMiJSUsT8qpgeFd9r4nHD%2Fuploads%2Fgit-blob-e34ce5b79478f571f2aacaaae04d0dc799952425%2Fopenapi.yaml?alt=media)
{% endopenapi %}

## Draft orders

{% openapi src="/files/PJWD1U3aYW16eUrjpzA3" path="/api/partner/v1/draft-orders/{draftOrderId}/apply-pricing" method="post" %}
[openapi.yaml](https://1915291744-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMiJSUsT8qpgeFd9r4nHD%2Fuploads%2Fgit-blob-e34ce5b79478f571f2aacaaae04d0dc799952425%2Fopenapi.yaml?alt=media)
{% endopenapi %}

{% openapi src="/files/PJWD1U3aYW16eUrjpzA3" path="/api/partner/v1/draft-orders/{draftOrderId}/pricing-status" method="get" %}
[openapi.yaml](https://1915291744-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMiJSUsT8qpgeFd9r4nHD%2Fuploads%2Fgit-blob-e34ce5b79478f571f2aacaaae04d0dc799952425%2Fopenapi.yaml?alt=media)
{% endopenapi %}

## `marketId`

If this store has an active pricing rule scoped to a specific market (`marketEligibility: specific`) that is currently within its active-date window (or has no start/end dates set at all), you must send `marketId` on `/pricing/calculate`, `/pricing/validate`, `/draft-orders/:id/apply-pricing`, and `/draft-orders/:id/pricing-status` — a market-restricted rule is never applied without it. Call `GET /capabilities` first and check its `marketIdRequired` field to know ahead of time whether your store needs this, instead of discovering it from an error.

Omitting `marketId` on a store that needs it returns `400 MARKET_ID_REQUIRED` on `/pricing/calculate`, `/draft-orders/:id/apply-pricing`, and `/draft-orders/:id/pricing-status`. `/pricing/validate` is a deliberate exception: by design that route never fails the HTTP request over a pricing problem — every finding, including a missing-when-needed `marketId`, comes back inside a normal `200` response, as `MARKET_ID_REQUIRED` listed in the response body's `errors` array, not as an HTTP error status. That's consistent with the rest of `/pricing/validate`'s purpose: reporting problems in the body rather than failing the request.

`GET /pricing-rules` doesn't require `marketId` under any circumstances: it always lists every applicable rule, including market-restricted ones, and reports each one's `marketIds` so you can filter which to actually offer.

## `GET /draft-orders/:draftOrderId/pricing-status` response fields

* `applied` — true only if at least one line on the draft right now actually carries our discount. A draft that was tagged "priced" by a past Apply call that matched nothing reports `applied: false`; see `taggedPriced` below for that raw signal.
* `taggedPriced` — whether Apply was ever invoked on this draft at all, regardless of whether it discounted anything.
* `stale` / `staleLineIds` — `false` when the draft was never applied (`applied: false`); otherwise `true` when re-running today's pricing rules against this draft's current lines would produce a different title OR a different per-unit discount amount than what's actually on it (a rule's name, its %, a tier boundary, or the draft's own lines having changed since Apply last ran). A line carrying a discount that isn't ours (a manual staff discount, your own promo) is never counted as stale — don't call Apply again just because `stale` is true for lines you didn't expect it to touch; it is never true for those.

## Error codes

Errors normally look like `{ "error": { "code": "...", "message": "..." } }`.

| Code                  | HTTP status                                                                                              | Meaning                                                                                                                                                                                                                                         |
| --------------------- | -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `INVALID_REQUEST`     | 400                                                                                                      | The request body or query string failed validation (a required field is missing or malformed, or an unknown field was sent). The error's `details` lists each specific problem.                                                                 |
| `INVALID_CLIENT`      | 401                                                                                                      | `/oauth/token` was called with an unknown `client_id` or the wrong `client_secret`.                                                                                                                                                             |
| `invalid_token`       | 401                                                                                                      | The `Authorization: Bearer` access token is missing, unrecognized, or expired. (This code is lowercase — every other code in this table is `UPPER_SNAKE_CASE`. That's a real inconsistency in the API's wire contract, not a typo in this doc.) |
| `SHOP_BLOCKED`        | 403                                                                                                      | This shop is blocked from using the Partner API.                                                                                                                                                                                                |
| `PLAN_FEATURE_LOCKED` | 403                                                                                                      | This shop's current plan doesn't include the Partner API (it requires Platinum).                                                                                                                                                                |
| `MARKET_ID_REQUIRED`  | 400 (`/pricing/validate` reports it inside a `200` response instead — see [`marketId`](#marketid) above) | `marketId` is required for this request and wasn't sent.                                                                                                                                                                                        |
| `CUSTOMER_NOT_FOUND`  | 404                                                                                                      | No customer with the given `customerId` exists on this shop.                                                                                                                                                                                    |
| `VARIANT_NOT_FOUND`   | 404                                                                                                      | No product variant with the given `variantId` exists on this shop.                                                                                                                                                                              |
| `PRODUCT_NOT_FOUND`   | 404                                                                                                      | No product with the given `productId` exists on this shop.                                                                                                                                                                                      |
| `DRAFT_NOT_FOUND`     | 404                                                                                                      | No draft order with the given id exists on this shop.                                                                                                                                                                                           |
| `NO_CUSTOMER`         | 422                                                                                                      | The draft order has no customer attached, so B2B pricing can't be resolved for it.                                                                                                                                                              |
| `DRAFT_UPDATE_FAILED` | 409                                                                                                      | Shopify rejected the pricing update to this draft order (for example, it's already completed or invoiced).                                                                                                                                      |
| `INTERNAL_ERROR`      | 500                                                                                                      | An unexpected internal error. The message is always generic — retry, and report it if it persists.                                                                                                                                              |

**`429` doesn't use the envelope above.** Every route is rate-limited (10 requests/second, burst 30; `/oauth/token` separately at 5 requests/minute per IP), and a `429` response looks like `{ "error": "rate_limited", "retryAfter": <seconds> }` instead — `error` is a bare string here, not an object with `code`/`message`. Check for a `429` status directly rather than reading `error.code`, and back off for `retryAfter` seconds before retrying.

**Three more codes exist, but only inside `/pricing/validate`'s `200` response body** (its own `errors` array — see [`marketId`](#marketid) above for why that route never fails the HTTP request itself): `CUSTOMER_CHECK_FAILED`, `LINES_CHECK_FAILED`, and `MARKET_CHECK_FAILED`, each meaning that specific internal lookup failed unexpectedly while validating (not that the input was invalid — a genuinely bad `customerId`/`variantId` on this route instead shows up as `CUSTOMER_NOT_FOUND`/`VARIANT_NOT_FOUND` *inside that same body*, the same codes the table above documents as 404s elsewhere — `/pricing/validate` is the one place they can also appear with no error HTTP status at all).

## Lines

`/pricing/calculate` and `/pricing/validate` take a `lines` array, each entry shaped `{ "variantId": "...", "quantity": 1 }` (`variantId` is a numeric id or a `gid://shopify/ProductVariant/<id>`; a line may also carry `productId`, but it never substitutes for `variantId` — every line still needs its own `variantId`). `lines` must contain between 1 and 100 entries, and each `quantity` must be a positive whole number no greater than 1,000,000.
