Skip to main content
POST
/
store
/
carts
/
{id}
/
line-items
curl -X POST 'http://localhost:9000/store/carts/cart_01JB2KB1CD/line-items' \
  -H 'Content-Type: application/json' \
  -H 'x-publishable-api-key: pk_01JB2K3XYZ' \
  -d '{"offer_id": "offer_01JB2K6G5H", "quantity": 1}'

{
  "cart": {
    "id": "cart_01JB2KB1CD",
    "currency_code": "eur",
    "region_id": "reg_01JB2K4S1T",
    "email": null,
    "items": [
      {
        "id": "cali_01JB2KB3EF",
        "title": "M",
        "product_title": "Linen Shirt",
        "quantity": 1,
        "unit_price": 4500,
        "metadata": { "offer_id": "offer_01JB2K6G5H" }
      }
    ],
    "shipping_methods": [],
    "promotions": [],
    "shipping_address": null,
    "billing_address": null,
    "payment_collection": null,
    "total": 4500,
    "subtotal": 4500,
    "tax_total": 0,
    "discount_total": 0,
    "shipping_total": 0
  }
}
Adds an item to the cart by offer — Mercur resolves the offer’s variant and stamps the offer_id on the line item so the cart can later split into per-seller orders.
Unlike vanilla Medusa, this route takes an offer_id instead of a variant_id; an unknown offer returns a 404.

​
Path parameters

​
id
string
required
The cart’s ID.

​
Body parameters

​
offer_id
string
required
ID of the offer to add.
​
quantity
number
required
Quantity to add; must be a positive integer.
​
unit_price
number
Custom unit price overriding the offer’s calculated price.
​
compare_at_unit_price
number
Compare-at unit price shown as the original price.
​
metadata
object
Custom key-value data stored on the line item; offer_id is merged in automatically.
​
additional_data
object
Data passed to the add-to-cart workflow’s hooks.

​
Response

​
cart
object
curl -X POST 'http://localhost:9000/store/carts/cart_01JB2KB1CD/line-items' \
  -H 'Content-Type: application/json' \
  -H 'x-publishable-api-key: pk_01JB2K3XYZ' \
  -d '{"offer_id": "offer_01JB2K6G5H", "quantity": 1}'

{
  "cart": {
    "id": "cart_01JB2KB1CD",
    "currency_code": "eur",
    "region_id": "reg_01JB2K4S1T",
    "email": null,
    "items": [
      {
        "id": "cali_01JB2KB3EF",
        "title": "M",
        "product_title": "Linen Shirt",
        "quantity": 1,
        "unit_price": 4500,
        "metadata": { "offer_id": "offer_01JB2K6G5H" }
      }
    ],
    "shipping_methods": [],
    "promotions": [],
    "shipping_address": null,
    "billing_address": null,
    "payment_collection": null,
    "total": 4500,
    "subtotal": 4500,
    "tax_total": 0,
    "discount_total": 0,
    "shipping_total": 0
  }
}