Skip to content

The complete open source platform to run your entire marketplace. Storefront, vendor panel, admin console, and integrations in one enterprise-grade platform you own.

5.6 KB
Raw Blame
---
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="manage_inventory" type="boolean" default="true">
  Whether stock is tracked for the offer. Set to `false` to sell without inventory checks.
</ParamField>

<ParamField body="allow_backorder" type="boolean" default="false">
  Whether the offer can be purchased when it is out of stock.
</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="manage_inventory" type="boolean">Whether stock is tracked for the offer.</ResponseField>
    <ResponseField name="allow_backorder" type="boolean">Whether the offer can be purchased when it is out of stock.</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",
    "manage_inventory": true,
    "allow_backorder": false,
    "prices": [
      { "id": "price_01HXYZ", "amount": 2500, "currency_code": "usd" }
    ],
    "inventory_items": [
      { "inventory_item_id": "iitem_01HXYZ", "required_quantity": 1 }
    ]
  }
}
```
</ResponseExample>