Add items to your cart

​

Adds one or more listings to your cart. Each item names a listing (from GET /v1/products/{productId}/listings or an optimizer run's lines) and how many units to buy.

Items are processed in order, and each succeeds or fails on its own: the response carries your updated cart plus an errors array naming the rejected items and why. Adding a listing already in your cart adds to its quantity, subject to any per-listing limit the seller sets — going past it rejects the item with QUANTITY_LIMIT_EXCEEDED.

deliveryCountry sets where your order will ship, on every call. When it differs from your cart's current delivery country, the cart switches to it — items already in your cart from sellers who don't ship to the new country are removed. A cart holds items from one marketplace region (eu or na) at a time — listings from the other region are rejected with REGION_MISMATCH.

To buy an optimizer result, pass each line's listingId and quantity from the option you chose.

Send an Idempotency-Key header to make retries safe: the same key returns the same response for 24 hours.

Requires the cart:write scope.

Body
required
application/json
  • deliveryCountry
    Type: string
    min length:  
    2
    max length:  
    2
    required

    Where your order will ship, as a two-letter ISO 3166-1 alpha-2 code, e.g. FR. Must be a country CardNexus delivers to. When it differs from your cart's current delivery country, the cart switches to it, and items from sellers who don't ship there are removed.

  • items
    Type: array object[] 1…1000
    required

    The items to add — between 1 and 1000 per call.

Responses
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for post/cart/items
curl https://public-api.cardnexus.com/v1/cart/items \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "deliveryCountry": "",
  "items": [
    {
      "listingId": "",
      "quantity": 1
    }
  ]
}'

{
  "cart": {
    "deliveryCountry": "FR",
    "itemCount": 2,
    "sellers": [
      {
        "seller": {
          "id": "665f3a2b1c8d4e9f7a6b5c4d",
          "username": "north_arena_tcg",
          "country": "DE",
          "type": "pro",
          "rating": {
            "average": 4.9,
            "count": 214
          },
          "shipping": {
            "amount": 3.5,
            "currency": "EUR"
          }
        },
        "itemsSubtotal": {
          "amount": 9,
          "currency": "EUR"
        },
        "items": [
          {
            "listingId": "665f3a2b1c8d4e9f7a6b5c52",
            "productId": 50212,
            "productName": "Dark Magician (SDMY-EN001)",
            "imageUrl": "https://images.cardnexus.com/yugioh/SDMY-EN001.png",
            "condition": "NM",
            "language": "en",
            "finish": "Standard",
            "graded": null,
            "quantity": 2,
            "unitPrice": {
              "amount": 4.5,
              "currency": "EUR"
            },
            "lineTotal": {
              "amount": 9,
              "currency": "EUR"
            },
            "addedAt": "2026-07-12T15:02:00.000Z"
          }
        ]
      }
    ]
  },
  "errors": [
    {
      "index": 1,
      "listingId": "665f3a2b1c8d4e9f7a6b5c61",
      "code": "INSUFFICIENT_QUANTITY",
      "data": {
        "requested": 4,
        "available": 2
      }
    }
  ]
}

Items added.