experimental

Apply a run's option to your cart

​

Replaces your cart with one of the run's options. Every line of the option goes into your cart exactly as proposed — listing and quantity — and anything already in your cart is removed. Cart prices are shown in each seller's listing currency, which can differ from the currency the run reports totals in. Unlike POST /v1/cart/items, which adds to what is already there, this replaces the whole cart in one step.

The run must be done — a run that is still queued or solving, or that failed, returns 409 RUN_NOT_READY. Pick the option by mode — lowest_price, fewest_sellers, or balanced — matching the modes of the run's result.options; a mode no option satisfies returns 404 OPTION_NOT_FOUND.

Your cart's delivery country becomes the run's destination country.

Returns your updated cart, in the same shape as GET /v1/cart.

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

Requires the cart:write scope.

Path Parameters
  • id
    Type: string
    min length:  
    1
    required

    The run id returned by POST /v1/optimizer/runs. Path parameter.

Body
required
application/json
  • mode
    Type: string enum
    required

    The run option to put in your cart: lowest_price, fewest_sellers, or balanced. Must appear in the modes of one of the run's result.options.

    values
    • lowest_price
    • fewest_sellers
    • balanced
Responses
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for post/optimizer/runs/{id}/apply
curl 'https://public-api.cardnexus.com/v1/optimizer/runs/{id}/apply' \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "mode": "lowest_price"
}'

{
  "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"
        }
      ]
    }
  ]
}

Cart replaced with the option.