@mercurjs/docs 2.2.0-canary.40

package/content/references/api/vendor/members/update-current-member.mdx

@@ -0,0 +1,70 @@
+---
+title: "Update Current Member"
+api: "POST /vendor/members/me"
+description: "Update the authenticated member's profile."
+---
+
+Updates the member's personal details and returns the seller member record for the active seller.
+
+## Body parameters
+
+<ParamField body="first_name" type="string">
+  The member's first name.
+</ParamField>
+
+<ParamField body="last_name" type="string">
+  The member's last name.
+</ParamField>
+
+<ParamField body="locale" type="string">
+  The member's preferred locale (e.g. `en-US`).
+</ParamField>
+
+## Query parameters
+
+<ParamField query="fields" type="string">
+  Comma-separated fields to include in the response.
+</ParamField>
+
+## Response
+
+<ResponseField name="seller_member" type="object">
+  <Expandable title="properties">
+    <ResponseField name="id" type="string">The seller member's ID.</ResponseField>
+    <ResponseField name="is_owner" type="boolean">Whether the member owns the seller account.</ResponseField>
+    <ResponseField name="member" type="object">The updated member profile.</ResponseField>
+    <ResponseField name="rbac_role" type="object">The member's role for this seller.</ResponseField>
+    <ResponseField name="seller" type="object">The active seller.</ResponseField>
+  </Expandable>
+</ResponseField>
+
+<RequestExample>
+```bash cURL
+curl -X POST 'http://localhost:9000/vendor/members/me' \
+  -H 'Authorization: Bearer <token>' \
+  -H 'x-seller-id: <seller_id>' \
+  -H 'Content-Type: application/json' \
+  -d '{"first_name": "Jane", "last_name": "Smith"}'
+```
+
+```ts JS Client
+const { seller_member } = await client.vendor.members.me.mutate({
+  first_name: "Jane",
+  last_name: "Smith",
+})
+```
+</RequestExample>
+
+<ResponseExample>
+```json 200
+{
+  "seller_member": {
+    "id": "selmem_01HXYZ",
+    "is_owner": true,
+    "member": { "id": "mem_01HXYZ", "first_name": "Jane", "last_name": "Smith" },
+    "rbac_role": { "id": "role_seller_administration", "name": "Administration" },
+    "seller": { "id": "sel_01HXYZ", "name": "Acme Store" }
+  }
+}
+```
+</ResponseExample>

package/content/references/api/vendor/offers/batch-create-offers.mdx

@@ -0,0 +1,123 @@
+---
+title: "Batch Create Offers"
+api: "POST /vendor/offers/batch"
+description: "Create up to 100 offers in a single request."
+---
+
+Creates multiple offers at once; the whole batch is validated and processed together.
+
+## Query parameters
+
+<ParamField query="fields" type="string">
+  Comma-separated fields to include in the returned offers. Prefix with `+`/`-` to add to or remove from the defaults.
+</ParamField>
+
+## Body parameters
+
+<ParamField body="offers" type="object[]" required>
+  Between 1 and 100 offers to create.
+  <Expandable title="properties">
+    <ParamField body="sku" type="string" required>The seller's SKU for the listing.</ParamField>
+    <ParamField body="variant_id" type="string" required>ID of the product variant being listed.</ParamField>
+    <ParamField body="shipping_profile_id" type="string" required>ID of the shipping profile used to fulfill the offer.</ParamField>
+    <ParamField body="prices" type="object[]" required>
+      At least one price.
+      <Expandable title="properties">
+        <ParamField body="amount" type="number" required>Price amount.</ParamField>
+        <ParamField body="currency_code" type="string" required>Currency code, e.g. `usd`.</ParamField>
+        <ParamField body="min_quantity" type="number">Minimum quantity for the price to apply; positive integer.</ParamField>
+        <ParamField body="max_quantity" type="number">Maximum quantity for the price to apply; positive integer.</ParamField>
+        <ParamField body="rules" type="object">Price rules as attribute-to-value pairs.</ParamField>
+      </Expandable>
+    </ParamField>
+    <ParamField body="inventory_items" type="object[]" required>
+      At least one inventory item.
+      <Expandable title="properties">
+        <ParamField body="title" type="string">Title for the created inventory item.</ParamField>
+        <ParamField body="sku" type="string">SKU for the created inventory item.</ParamField>
+        <ParamField body="required_quantity" type="number" default="1">Units consumed per sale; positive integer.</ParamField>
+        <ParamField body="stock_levels" type="object[]">
+          <Expandable title="properties">
+            <ParamField body="location_id" type="string" required>Stock location ID.</ParamField>
+            <ParamField body="stocked_quantity" type="number" required>Stocked quantity at the location; non-negative integer.</ParamField>
+          </Expandable>
+        </ParamField>
+      </Expandable>
+    </ParamField>
+    <ParamField body="ean" type="string">EAN barcode.</ParamField>
+    <ParamField body="upc" type="string">UPC barcode.</ParamField>
+    <ParamField body="metadata" type="object">Custom key-value pairs.</ParamField>
+  </Expandable>
+</ParamField>
+
+## Response
+
+<ResponseField name="offers" type="object[]">
+  <Expandable title="properties">
+    <ResponseField name="id" type="string">The offer's ID.</ResponseField>
+    <ResponseField name="variant_id" type="string">ID of the listed product variant.</ResponseField>
+    <ResponseField name="sku" type="string">The seller's SKU for the listing.</ResponseField>
+    <ResponseField name="prices" type="object[]">The offer's prices.</ResponseField>
+    <ResponseField name="inventory_items" type="object[]">Linked inventory items.</ResponseField>
+  </Expandable>
+</ResponseField>
+
+<RequestExample>
+```bash cURL
+curl -X POST 'http://localhost:9000/vendor/offers/batch' \
+  -H 'Authorization: Bearer <token>' \
+  -H 'x-seller-id: <seller_id>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "offers": [
+      {
+        "sku": "ACME-SHIRT-S",
+        "variant_id": "variant_01HABC",
+        "shipping_profile_id": "sp_01HXYZ",
+        "prices": [{ "amount": 2500, "currency_code": "usd" }],
+        "inventory_items": [{ "required_quantity": 1 }]
+      },
+      {
+        "sku": "ACME-SHIRT-M",
+        "variant_id": "variant_01HXYZ",
+        "shipping_profile_id": "sp_01HXYZ",
+        "prices": [{ "amount": 2500, "currency_code": "usd" }],
+        "inventory_items": [{ "required_quantity": 1 }]
+      }
+    ]
+  }'
+```
+
+```ts JS Client
+const { offers } = await client.vendor.offers.batch.mutate({
+  offers: [
+    {
+      sku: "ACME-SHIRT-M",
+      variant_id: "variant_01HXYZ",
+      shipping_profile_id: "sp_01HXYZ",
+      prices: [{ amount: 2500, currency_code: "usd" }],
+      inventory_items: [{ required_quantity: 1 }],
+    },
+  ],
+})
+```
+</RequestExample>
+
+<ResponseExample>
+```json 201
+{
+  "offers": [
+    {
+      "id": "offer_01HABC",
+      "variant_id": "variant_01HABC",
+      "sku": "ACME-SHIRT-S"
+    },
+    {
+      "id": "offer_01HXYZ",
+      "variant_id": "variant_01HXYZ",
+      "sku": "ACME-SHIRT-M"
+    }
+  ]
+}
+```
+</ResponseExample>

package/content/references/api/vendor/offers/batch-offer-inventory-items.mdx

@@ -0,0 +1,103 @@
+---
+title: "Batch Offer Inventory Items"
+api: "POST /vendor/offers/{id}/inventory-items/batch"
+description: "Link, update, or unlink inventory items on an offer."
+---
+
+Manages the inventory items backing an offer in one request and returns the refreshed offer.
+
+## Path parameters
+
+<ParamField path="id" type="string" required>
+  The offer's ID.
+</ParamField>
+
+## Body parameters
+
+<ParamField body="create" type="object[]">
+  Inventory items to link to the offer.
+  <Expandable title="properties">
+    <ParamField body="inventory_item_id" type="string" required>ID of an existing inventory item.</ParamField>
+    <ParamField body="required_quantity" type="number" default="1">Units consumed per sale; positive integer.</ParamField>
+  </Expandable>
+</ParamField>
+
+<ParamField body="update" type="object[]">
+  Existing links to update.
+  <Expandable title="properties">
+    <ParamField body="inventory_item_id" type="string" required>ID of the linked inventory item.</ParamField>
+    <ParamField body="required_quantity" type="number" required>New units consumed per sale; positive integer.</ParamField>
+  </Expandable>
+</ParamField>
+
+<ParamField body="delete" type="string[]">
+  Inventory item IDs to unlink from the offer.
+</ParamField>
+
+## Response
+
+<ResponseField name="created" type="object[]">
+  Links created by this request.
+</ResponseField>
+
+<ResponseField name="updated" type="object[]">
+  Links updated by this request.
+</ResponseField>
+
+<ResponseField name="deleted" type="string[]">
+  Inventory item IDs unlinked by this request.
+</ResponseField>
+
+<ResponseField name="offer" type="object">
+  <Expandable title="properties">
+    <ResponseField name="id" type="string">The offer's ID.</ResponseField>
+    <ResponseField name="sku" type="string">The seller's SKU for the listing.</ResponseField>
+    <ResponseField name="inventory_items" type="object[]">The offer's inventory items after the batch, with `id`, `inventory_item_id`, `required_quantity`, and `sku`.</ResponseField>
+  </Expandable>
+</ResponseField>
+
+<RequestExample>
+```bash cURL
+curl -X POST 'http://localhost:9000/vendor/offers/offer_01HXYZ/inventory-items/batch' \
+  -H 'Authorization: Bearer <token>' \
+  -H 'x-seller-id: <seller_id>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "create": [{ "inventory_item_id": "iitem_01HABC", "required_quantity": 2 }],
+    "update": [{ "inventory_item_id": "iitem_01HXYZ", "required_quantity": 1 }],
+    "delete": ["iitem_01HDEF"]
+  }'
+```
+
+```ts JS Client
+const { offer, created, updated, deleted } =
+  await client.vendor.offers.$id.inventoryItems.batch.mutate({
+    $id: "offer_01HXYZ",
+    create: [{ inventory_item_id: "iitem_01HABC", required_quantity: 2 }],
+    update: [{ inventory_item_id: "iitem_01HXYZ", required_quantity: 1 }],
+    delete: ["iitem_01HDEF"],
+  })
+```
+</RequestExample>
+
+<ResponseExample>
+```json 200
+{
+  "created": [
+    { "inventory_item_id": "iitem_01HABC", "required_quantity": 2 }
+  ],
+  "updated": [
+    { "inventory_item_id": "iitem_01HXYZ", "required_quantity": 1 }
+  ],
+  "deleted": ["iitem_01HDEF"],
+  "offer": {
+    "id": "offer_01HXYZ",
+    "sku": "ACME-SHIRT-M",
+    "inventory_items": [
+      { "inventory_item_id": "iitem_01HXYZ", "required_quantity": 1 },
+      { "inventory_item_id": "iitem_01HABC", "required_quantity": 2 }
+    ]
+  }
+}
+```
+</ResponseExample>

package/content/references/api/vendor/offers/create-offer.mdx

@@ -0,0 +1,141 @@
+---
+title: "Create Offer"
+api: "POST /vendor/offers"
+description: "Create a listing for a product variant."
+---
+
+Creates the seller's offer for a variant — the seller's SKU, shipping profile, prices, and backing inventory.
+
+<Note>
+  A product can be listed by many sellers; the offer is what carries the seller's own price and stock for a variant.
+</Note>
+
+## Query parameters
+
+<ParamField query="fields" type="string">
+  Comma-separated fields to include in the returned offer. Prefix with `+`/`-` to add to or remove from the defaults.
+</ParamField>
+
+## Body parameters
+
+<ParamField body="sku" type="string" required>
+  The seller's SKU for this listing.
+</ParamField>
+
+<ParamField body="variant_id" type="string" required>
+  ID of the product variant being listed.
+</ParamField>
+
+<ParamField body="shipping_profile_id" type="string" required>
+  ID of the seller's shipping profile used to fulfill the offer.
+</ParamField>
+
+<ParamField body="inventory_items" type="object[]" required>
+  Inventory items backing the offer; at least one is required.
+  <Expandable title="properties">
+    <ParamField body="title" type="string">Title for the created inventory item.</ParamField>
+    <ParamField body="sku" type="string">SKU for the created inventory item.</ParamField>
+    <ParamField body="required_quantity" type="number" default="1">Units of the item consumed per sale; positive integer.</ParamField>
+    <ParamField body="stock_levels" type="object[]">
+      <Expandable title="properties">
+        <ParamField body="location_id" type="string" required>Stock location ID.</ParamField>
+        <ParamField body="stocked_quantity" type="number" required>Stocked quantity at the location; non-negative integer.</ParamField>
+      </Expandable>
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+<ParamField body="prices" type="object[]" required>
+  Offer prices; at least one is required.
+  <Expandable title="properties">
+    <ParamField body="amount" type="number" required>Price amount.</ParamField>
+    <ParamField body="currency_code" type="string" required>Currency code, e.g. `usd`.</ParamField>
+    <ParamField body="min_quantity" type="number">Minimum quantity for the price to apply; positive integer.</ParamField>
+    <ParamField body="max_quantity" type="number">Maximum quantity for the price to apply; positive integer.</ParamField>
+    <ParamField body="rules" type="object">Price rules as attribute-to-value pairs, e.g. `{"region_id": "reg_01..."}`.</ParamField>
+  </Expandable>
+</ParamField>
+
+<ParamField body="ean" type="string">
+  EAN barcode.
+</ParamField>
+
+<ParamField body="upc" type="string">
+  UPC barcode.
+</ParamField>
+
+<ParamField body="metadata" type="object">
+  Custom key-value pairs.
+</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 owning seller.</ResponseField>
+    <ResponseField name="variant_id" type="string">ID of the listed product variant.</ResponseField>
+    <ResponseField name="product_id" type="string">ID of the parent product.</ResponseField>
+    <ResponseField name="shipping_profile_id" type="string">ID of the shipping profile.</ResponseField>
+    <ResponseField name="sku" type="string">The seller's SKU for this listing.</ResponseField>
+    <ResponseField name="prices" type="object[]">Offer prices with `id`, `amount`, `currency_code`, `min_quantity`, `max_quantity`, and `price_rules`.</ResponseField>
+    <ResponseField name="inventory_items" type="object[]">Linked inventory items with `id`, `inventory_item_id`, `required_quantity`, and `sku`.</ResponseField>
+  </Expandable>
+</ResponseField>
+
+<RequestExample>
+```bash cURL
+curl -X POST 'http://localhost:9000/vendor/offers' \
+  -H 'Authorization: Bearer <token>' \
+  -H 'x-seller-id: <seller_id>' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "sku": "ACME-SHIRT-M",
+    "variant_id": "variant_01HXYZ",
+    "shipping_profile_id": "sp_01HXYZ",
+    "prices": [{ "amount": 2500, "currency_code": "usd" }],
+    "inventory_items": [
+      {
+        "required_quantity": 1,
+        "stock_levels": [{ "location_id": "sloc_01HXYZ", "stocked_quantity": 100 }]
+      }
+    ]
+  }'
+```
+
+```ts JS Client
+const { offer } = await client.vendor.offers.mutate({
+  sku: "ACME-SHIRT-M",
+  variant_id: "variant_01HXYZ",
+  shipping_profile_id: "sp_01HXYZ",
+  prices: [{ amount: 2500, currency_code: "usd" }],
+  inventory_items: [
+    {
+      required_quantity: 1,
+      stock_levels: [{ location_id: "sloc_01HXYZ", stocked_quantity: 100 }],
+    },
+  ],
+})
+```
+</RequestExample>
+
+<ResponseExample>
+```json 201
+{
+  "offer": {
+    "id": "offer_01HXYZ",
+    "seller_id": "sel_01HXYZ",
+    "variant_id": "variant_01HXYZ",
+    "product_id": "prod_01HXYZ",
+    "shipping_profile_id": "sp_01HXYZ",
+    "sku": "ACME-SHIRT-M",
+    "prices": [
+      { "id": "price_01HXYZ", "amount": 2500, "currency_code": "usd" }
+    ],
+    "inventory_items": [
+      { "inventory_item_id": "iitem_01HXYZ", "required_quantity": 1 }
+    ]
+  }
+}
+```
+</ResponseExample>

package/content/references/api/vendor/offers/delete-offer.mdx

@@ -0,0 +1,51 @@
+---
+title: "Delete Offer"
+api: "DELETE /vendor/offers/{id}"
+description: "Delete one of the seller's offers."
+---
+
+Deletes the offer immediately; the underlying product and variant are unaffected.
+
+## Path parameters
+
+<ParamField path="id" type="string" required>
+  The offer's ID.
+</ParamField>
+
+## Response
+
+<ResponseField name="id" type="string">
+  The deleted offer's ID.
+</ResponseField>
+
+<ResponseField name="object" type="string">
+  Always `offer`.
+</ResponseField>
+
+<ResponseField name="deleted" type="boolean">
+  Always `true`.
+</ResponseField>
+
+<RequestExample>
+```bash cURL
+curl -X DELETE 'http://localhost:9000/vendor/offers/offer_01HXYZ' \
+  -H 'Authorization: Bearer <token>' \
+  -H 'x-seller-id: <seller_id>'
+```
+
+```ts JS Client
+const { id, deleted } = await client.vendor.offers.$id.delete({
+  $id: "offer_01HXYZ",
+})
+```
+</RequestExample>
+
+<ResponseExample>
+```json 200
+{
+  "id": "offer_01HXYZ",
+  "object": "offer",
+  "deleted": true
+}
+```
+</ResponseExample>

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

@@ -0,0 +1,125 @@
+---
+title: "List Offers"
+api: "GET /vendor/offers"
+description: "Retrieve a paginated list of the seller's offers."
+---
+
+Returns the seller's offers with variant, shipping profile, prices, and linked inventory items.
+
+## Query parameters
+
+<ParamField query="limit" type="number" default="50">
+  The maximum number of offers to return.
+</ParamField>
+
+<ParamField query="offset" type="number" default="0">
+  The number of offers to skip before returning results.
+</ParamField>
+
+<ParamField query="order" type="string">
+  The field to sort by, e.g. `created_at` or `-created_at` for descending.
+</ParamField>
+
+<ParamField query="fields" type="string">
+  Comma-separated fields to include in the response. Prefix with `+`/`-` to add to or remove from the defaults.
+</ParamField>
+
+<ParamField query="q" type="string">
+  Search term matched against offer fields.
+</ParamField>
+
+<ParamField query="id" type="string | string[]">
+  Filter by offer ID(s).
+</ParamField>
+
+<ParamField query="variant_id" type="string | string[]">
+  Filter by product variant ID(s).
+</ParamField>
+
+<ParamField query="shipping_profile_id" type="string | string[]">
+  Filter by shipping profile ID(s).
+</ParamField>
+
+<ParamField query="sku" type="string | string[]">
+  Filter by seller SKU(s).
+</ParamField>
+
+<ParamField query="ean" type="string | string[]">
+  Filter by EAN(s).
+</ParamField>
+
+<ParamField query="upc" type="string | string[]">
+  Filter by UPC(s).
+</ParamField>
+
+<ParamField query="created_at" type="object">
+  Filter by creation date using operators like `$gt`, `$lt`, `$gte`, `$lte`.
+</ParamField>
+
+<ParamField query="updated_at" type="object">
+  Filter by update date using operators like `$gt`, `$lt`, `$gte`, `$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 owning seller.</ResponseField>
+    <ResponseField name="variant_id" type="string">ID of the listed product variant.</ResponseField>
+    <ResponseField name="product_id" type="string">ID of the parent product.</ResponseField>
+    <ResponseField name="shipping_profile_id" type="string">ID of the shipping profile used to fulfill the offer.</ResponseField>
+    <ResponseField name="sku" type="string">The seller's SKU for this listing.</ResponseField>
+    <ResponseField name="ean" type="string">EAN barcode.</ResponseField>
+    <ResponseField name="upc" type="string">UPC barcode.</ResponseField>
+    <ResponseField name="seller" type="object">The seller with `id`, `name`, and `handle`.</ResponseField>
+    <ResponseField name="product_variant" type="object">The variant with `id`, `title`, and `sku`.</ResponseField>
+    <ResponseField name="shipping_profile" type="object">The shipping profile with `id` and `name`.</ResponseField>
+    <ResponseField name="prices" type="object[]">Offer prices with `id`, `amount`, `currency_code`, `min_quantity`, `max_quantity`, and `price_rules`.</ResponseField>
+    <ResponseField name="inventory_items" type="object[]">Linked inventory items with `id`, `inventory_item_id`, `required_quantity`, and `sku`.</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/vendor/offers?variant_id=variant_01HXYZ' \
+  -H 'Authorization: Bearer <token>' \
+  -H 'x-seller-id: <seller_id>'
+```
+
+```ts JS Client
+const { offers, count } = await client.vendor.offers.query({
+  variant_id: "variant_01HXYZ",
+})
+```
+</RequestExample>
+
+<ResponseExample>
+```json 200
+{
+  "offers": [
+    {
+      "id": "offer_01HXYZ",
+      "seller_id": "sel_01HXYZ",
+      "variant_id": "variant_01HXYZ",
+      "product_id": "prod_01HXYZ",
+      "shipping_profile_id": "sp_01HXYZ",
+      "sku": "ACME-SHIRT-M",
+      "prices": [
+        { "id": "price_01HXYZ", "amount": 2500, "currency_code": "usd" }
+      ],
+      "inventory_items": [
+        { "inventory_item_id": "iitem_01HXYZ", "required_quantity": 1 }
+      ]
+    }
+  ],
+  "count": 1,
+  "offset": 0,
+  "limit": 50
+}
+```
+</ResponseExample>