experimental

Start a cart-wizard run

​

Optimizes a basket of cards into the cheapest / fewest-seller / balanced ways to buy them, accounting for each seller's shipping, fees and VAT.

The run executes in the background: this call returns right away with a run id and status: "queued". Poll GET /v1/optimizer/runs/{id} — the options' totals fill in as it solves, and the full per-seller breakdown is ready once status is done. Subscribe to the optimizer.run.completed webhook to avoid polling. When two modes yield the same solution, the result contains a single option whose modes lists both.

Each target is either a specific printing (productId) or any printing of a card (card by slug). A basket holds up to 400 targets, in any mix of the two forms. Set per-target condition / finish / language, or defaults for the whole basket. Narrow the sellers by country, rating or an explicit include/exclude list.

Rate limited to 10 runs per hour. Send an Idempotency-Key header to make retries safe.

Body
required
application/json
  • destination
    Type: object
    required
  • targets
    Type: array object[] 1…400
    required

    The cards to optimize.

  • defaults
    Type: object

    Defaults applied to every target that doesn't set its own value.

  • options
    Type: object
  • sellers
    Type: object
Responses
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for post/optimizer/runs
curl https://public-api.cardnexus.com/v1/optimizer/runs \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "targets": [
    {
      "productId": 1,
      "card": {
        "gameSlug": "",
        "nameSlug": ""
      },
      "quantity": -9007199254740991,
      "minCondition": "NM",
      "finish": "standard",
      "languages": [
        "en"
      ],
      "maxUnitPrice": {
        "amount": 14.99,
        "currency": "USD"
      }
    }
  ],
  "destination": {
    "country": "",
    "currency": "USD"
  },
  "defaults": {
    "minCondition": "NM",
    "finish": "standard",
    "languages": [
      "en"
    ]
  },
  "sellers": {
    "countries": [
      ""
    ],
    "include": [
      ""
    ],
    "exclude": [
      ""
    ],
    "proOnly": true,
    "minRating": 0
  },
  "options": {
    "modes": [
      "lowest_price"
    ],
    "strictFullCoverage": true
  }
}'

{
  "id": "opt_9f2c1a7b3d4e5f60",
  "status": "queued"
}

Run accepted and queued.