@mercurjs/docs 2.2.0-canary.40

package/content/references/api/store/carts/complete-cart.mdx

@@ -0,0 +1,98 @@
+---
+title: "Complete Cart"
+api: "POST /store/carts/{id}/complete"
+description: "Complete the cart and split it into per-seller orders under an order group."
+---
+
+Completes the cart with Mercur's split-order workflow: items are grouped by seller, one order is created per seller, and all orders are attached to a single order group returned to the shopper.
+
+<Note>
+  On payment errors that need customer action (authorization failed or requires more), the route still returns `200` with `type: "cart"`, the refreshed cart, and an `error` object; any other failure is thrown as an error response.
+</Note>
+
+## Path parameters
+
+<ParamField path="id" type="string" required>
+  The cart's ID.
+</ParamField>
+
+## Query parameters
+
+<ParamField query="fields" type="string">
+  Comma-separated fields to include on the returned order group; prefix with `+`/`-` to add to or remove from the defaults.
+</ParamField>
+
+## Response
+
+<ResponseField name="type" type="string">
+  `order_group` on success, `cart` when payment requires further action.
+</ResponseField>
+
+<ResponseField name="order_group" type="object">
+  Present when `type` is `order_group`.
+  <Expandable title="properties">
+    <ResponseField name="id" type="string">The order group's ID.</ResponseField>
+    <ResponseField name="customer_id" type="string">ID of the purchasing customer.</ResponseField>
+    <ResponseField name="cart_id" type="string">ID of the completed cart.</ResponseField>
+    <ResponseField name="seller_count" type="number">Number of per-seller orders created.</ResponseField>
+    <ResponseField name="total" type="number">Combined total across all child orders.</ResponseField>
+    <ResponseField name="created_at" type="string">Creation timestamp.</ResponseField>
+    <ResponseField name="updated_at" type="string">Last update timestamp.</ResponseField>
+  </Expandable>
+</ResponseField>
+
+<ResponseField name="cart" type="object">
+  Present when `type` is `cart`; the refreshed cart with items, totals, and payment collection.
+</ResponseField>
+
+<ResponseField name="error" type="object">
+  Present when `type` is `cart`.
+  <Expandable title="properties">
+    <ResponseField name="message" type="string">The payment error message.</ResponseField>
+    <ResponseField name="name" type="string">The error name.</ResponseField>
+    <ResponseField name="type" type="string">One of `payment_authorization_error` or `payment_requires_more_error`.</ResponseField>
+  </Expandable>
+</ResponseField>
+
+<RequestExample>
+```bash cURL
+curl -X POST 'http://localhost:9000/store/carts/cart_01JB2KB1CD/complete' \
+  -H 'x-publishable-api-key: pk_01JB2K3XYZ'
+```
+
+```ts JS Client
+const result = await client.store.carts.$id.complete.mutate({ $id: "cart_01JB2KB1CD" })
+if (result.type === "order_group") {
+  console.log(result.order_group.id)
+}
+```
+</RequestExample>
+
+<ResponseExample>
+```json 200 (success)
+{
+  "type": "order_group",
+  "order_group": {
+    "id": "og_01JB2KE7NP",
+    "customer_id": "cus_01JB2KE8QR",
+    "cart_id": "cart_01JB2KB1CD",
+    "seller_count": 2,
+    "total": 9900,
+    "created_at": "2026-05-01T10:05:00.000Z",
+    "updated_at": "2026-05-01T10:05:00.000Z"
+  }
+}
+```
+
+```json 200 (payment error)
+{
+  "type": "cart",
+  "cart": { "id": "cart_01JB2KB1CD", "total": 9900 },
+  "error": {
+    "message": "Payment authorization failed",
+    "name": "Error",
+    "type": "payment_authorization_error"
+  }
+}
+```
+</ResponseExample>

package/content/references/api/store/offers/list-offers.mdx

@@ -0,0 +1,161 @@
+---
+title: "List Offers"
+api: "GET /store/offers"
+description: "Retrieve seller offers with per-offer calculated prices."
+---
+
+Returns a paginated list of offers from visible sellers whose products are published.
+
+<Note>
+  Customer authentication is optional. When a customer token is provided, the customer's group memberships enter the pricing context used for `calculated_price`. Prices are computed per offer (each offer scopes the variant's price set by an `offer_id` rule) only when `calculated_price` is in `fields` and a pricing context (`region_id`, `country_code`, or `cart_id`) resolves. Requesting `inventory_quantity` or `in_stock` requires a single sales channel — either configured on the publishable key or passed as `sales_channel_id`.
+</Note>
+
+## Query parameters
+
+<ParamField query="limit" type="number" default="50">
+  Maximum number of offers to return.
+</ParamField>
+
+<ParamField query="offset" type="number" default="0">
+  Number of offers to skip before collecting results.
+</ParamField>
+
+<ParamField query="order" type="string">
+  Field to sort by, prefixed with `-` for descending order.
+</ParamField>
+
+<ParamField query="fields" type="string">
+  Comma-separated fields and relations to include; add `calculated_price`, `inventory_quantity`, or `in_stock` to receive the computed fields.
+</ParamField>
+
+<ParamField query="region_id" type="string">
+  Region used to build the pricing context for `calculated_price`.
+</ParamField>
+
+<ParamField query="country_code" type="string">
+  Country used for the tax portion of the pricing context.
+</ParamField>
+
+<ParamField query="province" type="string">
+  Province used for the tax portion of the pricing context.
+</ParamField>
+
+<ParamField query="cart_id" type="string">
+  Cart whose region and customer resolve the pricing context.
+</ParamField>
+
+<ParamField query="q" type="string">
+  Free-text search term applied to offer fields.
+</ParamField>
+
+<ParamField query="id" type="string | string[]">
+  Filter by one or more offer IDs.
+</ParamField>
+
+<ParamField query="product_id" type="string | string[]">
+  Filter by one or more product IDs.
+</ParamField>
+
+<ParamField query="variant_id" type="string | string[]">
+  Filter by one or more variant IDs.
+</ParamField>
+
+<ParamField query="seller_id" type="string | string[]">
+  Filter by one or more seller IDs.
+</ParamField>
+
+<ParamField query="sku" type="string | string[]">
+  Filter by one or more offer SKUs.
+</ParamField>
+
+<ParamField query="created_at" type="object">
+  Filter by creation date using operators like `$gt`, `$gte`, `$lt`, `$lte`.
+</ParamField>
+
+<ParamField query="updated_at" type="object">
+  Filter by update date using operators like `$gt`, `$gte`, `$lt`, `$lte`.
+</ParamField>
+
+## Response
+
+<ResponseField name="offers" type="object[]">
+  <Expandable title="properties">
+    <ResponseField name="id" type="string">The offer's ID.</ResponseField>
+    <ResponseField name="seller_id" type="string">ID of the selling seller.</ResponseField>
+    <ResponseField name="variant_id" type="string">ID of the offered product variant.</ResponseField>
+    <ResponseField name="product_id" type="string">ID of the offered product.</ResponseField>
+    <ResponseField name="shipping_profile_id" type="string | null">ID of the offer's shipping profile.</ResponseField>
+    <ResponseField name="sku" type="string | null">The offer's SKU.</ResponseField>
+    <ResponseField name="ean" type="string | null">The offer's EAN.</ResponseField>
+    <ResponseField name="upc" type="string | null">The offer's UPC.</ResponseField>
+    <ResponseField name="seller" type="object">The seller's `id`, `name`, and `handle`.</ResponseField>
+    <ResponseField name="product_variant" type="object">The variant's `id`, `title`, `sku`, and `price_set`.</ResponseField>
+    <ResponseField name="shipping_profile" type="object | null">The shipping profile's `id` and `name`.</ResponseField>
+    <ResponseField name="prices" type="object[]">Raw offer prices with `amount`, `currency_code`, `min_quantity`, and `max_quantity`.</ResponseField>
+    <ResponseField name="inventory_item_link" type="object[]">Inventory items backing the offer, with location stock levels.</ResponseField>
+    <ResponseField name="calculated_price" type="object | null">
+      Per-offer calculated price; includes `calculated_amount_with_tax` / `calculated_amount_without_tax` (and original-amount variants) when a tax context resolves. Only present when requested.
+    </ResponseField>
+    <ResponseField name="inventory_quantity" type="number">Available quantity in the sales channel's stock locations; only present when requested.</ResponseField>
+    <ResponseField name="in_stock" type="boolean">Whether the offer has available inventory; only present when requested.</ResponseField>
+    <ResponseField name="metadata" type="object | null">Custom key-value data.</ResponseField>
+    <ResponseField name="created_at" type="string">Creation timestamp.</ResponseField>
+    <ResponseField name="updated_at" type="string">Last update timestamp.</ResponseField>
+  </Expandable>
+</ResponseField>
+
+<ResponseField name="count" type="number">Total number of matching offers.</ResponseField>
+<ResponseField name="offset" type="number">Number of skipped offers.</ResponseField>
+<ResponseField name="limit" type="number">Maximum number of returned offers.</ResponseField>
+
+<RequestExample>
+```bash cURL
+curl 'http://localhost:9000/store/offers?product_id=prod_01JB2K5M8N&region_id=reg_01JB2K4S1T&fields=%2Bcalculated_price' \
+  -H 'x-publishable-api-key: pk_01JB2K3XYZ'
+```
+
+```ts JS Client
+const { offers, count } = await client.store.offers.query({
+  product_id: "prod_01JB2K5M8N",
+  region_id: "reg_01JB2K4S1T",
+  fields: "+calculated_price",
+})
+```
+</RequestExample>
+
+<ResponseExample>
+```json 200
+{
+  "offers": [
+    {
+      "id": "offer_01JB2K6G5H",
+      "seller_id": "sel_01JB2K8A1B",
+      "variant_id": "variant_01JB2K6E4F",
+      "product_id": "prod_01JB2K5M8N",
+      "shipping_profile_id": "sp_01JB2K9C2D",
+      "sku": "NT-LINEN-M",
+      "ean": null,
+      "upc": null,
+      "seller": { "id": "sel_01JB2K8A1B", "name": "Nordic Textiles", "handle": "nordic-textiles" },
+      "product_variant": { "id": "variant_01JB2K6E4F", "title": "M", "sku": null, "price_set": { "id": "pset_01JB2K9E3F" } },
+      "shipping_profile": { "id": "sp_01JB2K9C2D", "name": "Default" },
+      "prices": [
+        { "id": "price_01JB2K9G4H", "amount": 4500, "currency_code": "eur", "min_quantity": null, "max_quantity": null }
+      ],
+      "inventory_item_link": [],
+      "calculated_price": {
+        "calculated_amount": 4500,
+        "original_amount": 4500,
+        "currency_code": "eur"
+      },
+      "metadata": null,
+      "created_at": "2026-05-01T10:00:00.000Z",
+      "updated_at": "2026-05-01T10:00:00.000Z"
+    }
+  ],
+  "count": 3,
+  "offset": 0,
+  "limit": 50
+}
+```
+</ResponseExample>

package/content/references/api/store/offers/retrieve-offer.mdx

@@ -0,0 +1,112 @@
+---
+title: "Retrieve Offer"
+api: "GET /store/offers/{id}"
+description: "Retrieve a seller offer by ID with its per-offer calculated price."
+---
+
+Returns a single offer; offers from hidden sellers or on unpublished products return a `404`.
+
+<Note>
+  Customer authentication is optional. `calculated_price` is computed per offer only when requested in `fields` and a pricing context (`region_id`, `country_code`, or `cart_id`) resolves; requesting `inventory_quantity` or `in_stock` requires a single sales channel on the publishable key or via `sales_channel_id`.
+</Note>
+
+## Path parameters
+
+<ParamField path="id" type="string" required>
+  The offer's ID.
+</ParamField>
+
+## Query parameters
+
+<ParamField query="fields" type="string">
+  Comma-separated fields and relations to include; add `calculated_price`, `inventory_quantity`, or `in_stock` to receive the computed fields.
+</ParamField>
+
+<ParamField query="region_id" type="string">
+  Region used to build the pricing context for `calculated_price`.
+</ParamField>
+
+<ParamField query="country_code" type="string">
+  Country used for the tax portion of the pricing context.
+</ParamField>
+
+<ParamField query="province" type="string">
+  Province used for the tax portion of the pricing context.
+</ParamField>
+
+<ParamField query="cart_id" type="string">
+  Cart whose region and customer resolve the pricing context.
+</ParamField>
+
+## Response
+
+<ResponseField name="offer" type="object">
+  <Expandable title="properties">
+    <ResponseField name="id" type="string">The offer's ID.</ResponseField>
+    <ResponseField name="seller_id" type="string">ID of the selling seller.</ResponseField>
+    <ResponseField name="variant_id" type="string">ID of the offered product variant.</ResponseField>
+    <ResponseField name="product_id" type="string">ID of the offered product.</ResponseField>
+    <ResponseField name="shipping_profile_id" type="string | null">ID of the offer's shipping profile.</ResponseField>
+    <ResponseField name="sku" type="string | null">The offer's SKU.</ResponseField>
+    <ResponseField name="ean" type="string | null">The offer's EAN.</ResponseField>
+    <ResponseField name="upc" type="string | null">The offer's UPC.</ResponseField>
+    <ResponseField name="seller" type="object">The seller's `id`, `name`, and `handle`.</ResponseField>
+    <ResponseField name="product_variant" type="object">The variant's `id`, `title`, `sku`, and `price_set`.</ResponseField>
+    <ResponseField name="shipping_profile" type="object | null">The shipping profile's `id` and `name`.</ResponseField>
+    <ResponseField name="prices" type="object[]">Raw offer prices with `amount`, `currency_code`, `min_quantity`, and `max_quantity`.</ResponseField>
+    <ResponseField name="inventory_item_link" type="object[]">Inventory items backing the offer, with location stock levels.</ResponseField>
+    <ResponseField name="calculated_price" type="object | null">Per-offer calculated price with tax-adjusted amounts when a tax context resolves; only present when requested.</ResponseField>
+    <ResponseField name="inventory_quantity" type="number">Available quantity in the sales channel's stock locations; only present when requested.</ResponseField>
+    <ResponseField name="in_stock" type="boolean">Whether the offer has available inventory; only present when requested.</ResponseField>
+    <ResponseField name="metadata" type="object | null">Custom key-value data.</ResponseField>
+    <ResponseField name="created_at" type="string">Creation timestamp.</ResponseField>
+    <ResponseField name="updated_at" type="string">Last update timestamp.</ResponseField>
+  </Expandable>
+</ResponseField>
+
+<RequestExample>
+```bash cURL
+curl 'http://localhost:9000/store/offers/offer_01JB2K6G5H?region_id=reg_01JB2K4S1T&fields=%2Bcalculated_price' \
+  -H 'x-publishable-api-key: pk_01JB2K3XYZ'
+```
+
+```ts JS Client
+const { offer } = await client.store.offers.$id.query({
+  $id: "offer_01JB2K6G5H",
+  region_id: "reg_01JB2K4S1T",
+  fields: "+calculated_price",
+})
+```
+</RequestExample>
+
+<ResponseExample>
+```json 200
+{
+  "offer": {
+    "id": "offer_01JB2K6G5H",
+    "seller_id": "sel_01JB2K8A1B",
+    "variant_id": "variant_01JB2K6E4F",
+    "product_id": "prod_01JB2K5M8N",
+    "shipping_profile_id": "sp_01JB2K9C2D",
+    "sku": "NT-LINEN-M",
+    "ean": null,
+    "upc": null,
+    "seller": { "id": "sel_01JB2K8A1B", "name": "Nordic Textiles", "handle": "nordic-textiles" },
+    "product_variant": { "id": "variant_01JB2K6E4F", "title": "M", "sku": null, "price_set": { "id": "pset_01JB2K9E3F" } },
+    "shipping_profile": { "id": "sp_01JB2K9C2D", "name": "Default" },
+    "prices": [
+      { "id": "price_01JB2K9G4H", "amount": 4500, "currency_code": "eur", "min_quantity": null, "max_quantity": null }
+    ],
+    "inventory_item_link": [],
+    "calculated_price": {
+      "calculated_amount": 4500,
+      "original_amount": 4500,
+      "currency_code": "eur"
+    },
+    "metadata": null,
+    "created_at": "2026-05-01T10:00:00.000Z",
+    "updated_at": "2026-05-01T10:00:00.000Z"
+  }
+}
+```
+</ResponseExample>

package/content/references/api/store/order-groups/list-order-groups.mdx

@@ -0,0 +1,105 @@
+---
+title: "List Order Groups"
+api: "GET /store/order-groups"
+description: "Retrieve the authenticated customer's order groups."
+---
+
+Returns a paginated list of the logged-in customer's order groups — the multi-seller wrappers created when a cart is completed.
+
+<Note>
+  Customer authentication is required (`Authorization: Bearer <customer_token>` or a session cookie); results are always scoped to the authenticated customer.
+</Note>
+
+## Query parameters
+
+<ParamField query="limit" type="number" default="50">
+  Maximum number of order groups to return.
+</ParamField>
+
+<ParamField query="offset" type="number" default="0">
+  Number of order groups to skip before collecting results.
+</ParamField>
+
+<ParamField query="order" type="string">
+  Field to sort by, prefixed with `-` for descending order.
+</ParamField>
+
+<ParamField query="fields" type="string">
+  Comma-separated fields to include; only fields from the route's allowed list are accepted.
+</ParamField>
+
+<ParamField query="id" type="string | string[]">
+  Filter by one or more order group IDs.
+</ParamField>
+
+<ParamField query="created_at" type="object">
+  Filter by creation date using operators like `$gt`, `$gte`, `$lt`, `$lte`.
+</ParamField>
+
+<ParamField query="updated_at" type="object">
+  Filter by update date using operators like `$gt`, `$gte`, `$lt`, `$lte`.
+</ParamField>
+
+## Response
+
+<ResponseField name="order_groups" type="object[]">
+  <Expandable title="properties">
+    <ResponseField name="id" type="string">The order group's ID.</ResponseField>
+    <ResponseField name="customer_id" type="string">ID of the purchasing customer.</ResponseField>
+    <ResponseField name="seller_count" type="number">Number of per-seller orders in the group.</ResponseField>
+    <ResponseField name="total" type="number">Combined total across all child orders.</ResponseField>
+    <ResponseField name="orders" type="object[]">
+      Child orders, each with `seller_id` and its `items` (including each item's variant, product, and seller).
+    </ResponseField>
+    <ResponseField name="created_at" type="string">Creation timestamp.</ResponseField>
+    <ResponseField name="updated_at" type="string">Last update timestamp.</ResponseField>
+  </Expandable>
+</ResponseField>
+
+<ResponseField name="count" type="number">Total number of matching order groups.</ResponseField>
+<ResponseField name="offset" type="number">Number of skipped order groups.</ResponseField>
+<ResponseField name="limit" type="number">Maximum number of returned order groups.</ResponseField>
+
+<RequestExample>
+```bash cURL
+curl 'http://localhost:9000/store/order-groups?limit=10' \
+  -H 'x-publishable-api-key: pk_01JB2K3XYZ' \
+  -H 'Authorization: Bearer <customer_token>'
+```
+
+```ts JS Client
+const { order_groups, count } = await client.store.orderGroups.query({ limit: 10 })
+```
+</RequestExample>
+
+<ResponseExample>
+```json 200
+{
+  "order_groups": [
+    {
+      "id": "og_01JB2KE7NP",
+      "customer_id": "cus_01JB2KE8QR",
+      "seller_count": 2,
+      "total": 9900,
+      "orders": [
+        {
+          "id": "order_01JB2KH1WX",
+          "seller_id": "sel_01JB2K8A1B",
+          "items": [{ "id": "ordli_01JB2KH2YZ", "title": "M", "quantity": 1 }]
+        },
+        {
+          "id": "order_01JB2KH3AB",
+          "seller_id": "sel_01JB2KF9ST",
+          "items": [{ "id": "ordli_01JB2KH4CD", "title": "One Size", "quantity": 1 }]
+        }
+      ],
+      "created_at": "2026-05-01T10:05:00.000Z",
+      "updated_at": "2026-05-01T10:05:00.000Z"
+    }
+  ],
+  "count": 4,
+  "offset": 0,
+  "limit": 10
+}
+```
+</ResponseExample>

package/content/references/api/store/order-groups/retrieve-order-group.mdx

@@ -0,0 +1,78 @@
+---
+title: "Retrieve Order Group"
+api: "GET /store/order-groups/{id}"
+description: "Retrieve one of the authenticated customer's order groups by ID."
+---
+
+Returns a single order group with its per-seller child orders; order groups belonging to another customer return a `404`.
+
+<Note>
+  Customer authentication is required (`Authorization: Bearer <customer_token>` or a session cookie).
+</Note>
+
+## Path parameters
+
+<ParamField path="id" type="string" required>
+  The order group's ID.
+</ParamField>
+
+## Query parameters
+
+<ParamField query="fields" type="string">
+  Comma-separated fields to include; only fields from the route's allowed list are accepted.
+</ParamField>
+
+## Response
+
+<ResponseField name="order_group" type="object">
+  <Expandable title="properties">
+    <ResponseField name="id" type="string">The order group's ID.</ResponseField>
+    <ResponseField name="customer_id" type="string">ID of the purchasing customer.</ResponseField>
+    <ResponseField name="seller_count" type="number">Number of per-seller orders in the group.</ResponseField>
+    <ResponseField name="total" type="number">Combined total across all child orders.</ResponseField>
+    <ResponseField name="orders" type="object[]">
+      Child orders, each with `seller_id` and its `items` (including each item's variant, product, and seller).
+    </ResponseField>
+    <ResponseField name="created_at" type="string">Creation timestamp.</ResponseField>
+    <ResponseField name="updated_at" type="string">Last update timestamp.</ResponseField>
+  </Expandable>
+</ResponseField>
+
+<RequestExample>
+```bash cURL
+curl 'http://localhost:9000/store/order-groups/og_01JB2KE7NP' \
+  -H 'x-publishable-api-key: pk_01JB2K3XYZ' \
+  -H 'Authorization: Bearer <customer_token>'
+```
+
+```ts JS Client
+const { order_group } = await client.store.orderGroups.$id.query({ $id: "og_01JB2KE7NP" })
+```
+</RequestExample>
+
+<ResponseExample>
+```json 200
+{
+  "order_group": {
+    "id": "og_01JB2KE7NP",
+    "customer_id": "cus_01JB2KE8QR",
+    "seller_count": 2,
+    "total": 9900,
+    "orders": [
+      {
+        "id": "order_01JB2KH1WX",
+        "seller_id": "sel_01JB2K8A1B",
+        "items": [{ "id": "ordli_01JB2KH2YZ", "title": "M", "quantity": 1 }]
+      },
+      {
+        "id": "order_01JB2KH3AB",
+        "seller_id": "sel_01JB2KF9ST",
+        "items": [{ "id": "ordli_01JB2KH4CD", "title": "One Size", "quantity": 1 }]
+      }
+    ],
+    "created_at": "2026-05-01T10:05:00.000Z",
+    "updated_at": "2026-05-01T10:05:00.000Z"
+  }
+}
+```
+</ResponseExample>