Add Line Item

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}'

const { cart } = await client.store.carts.$id.lineItems.mutate({
  $id: "cart_01JB2KB1CD",
  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

string

required

The cart’s ID.

Body parameters

string

required

ID of the offer to add.

number

required

Quantity to add; must be a positive integer.

number

Custom unit price overriding the offer’s calculated price.

number

Compare-at unit price shown as the original price.

object

Custom key-value data stored on the line item; offer_id is merged in automatically.

object

Data passed to the add-to-cart workflow’s hooks.

Response

object

Show properties

string

The cart’s ID.

string

The cart’s currency.

string

The cart’s region.

string | null

The customer’s email.

object[]

Line items, each carrying offer_id in its metadata.

object[]

Selected shipping methods.

object[]

Applied promotions.

object | null

The shipping address.

object | null

The billing address.

object | null

The cart’s payment collection with its sessions.

number

Cart total including tax and shipping.

number

Cart subtotal.

number

Total tax amount.

number

Total discount amount.

number

Total shipping amount.

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}'

const { cart } = await client.store.carts.$id.lineItems.mutate({
  $id: "cart_01JB2KB1CD",
  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
  }
}

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}'

const { cart } = await client.store.carts.$id.lineItems.mutate({
  $id: "cart_01JB2KB1CD",
  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
  }
}

Overview

Panel extensions

Admin API

Vendor API

Store API

Configuration

Path parameters

Body parameters

Response

​Path parameters

​Body parameters

​Response

Path parameters

Body parameters

Response