snapcasterDevelopers

    API reference · Orders

    List substitutes for an order line

    GET /orders/{orderId}/substitute-candidates

    Read the SKUs a fulfillment report can substitute for one order line: the seller's live listings of other SKUs of the line's catalog product, with stock for the whole remaining line, that are not already on the order. Send one as substituteSkuId to POST /orders/{orderId}/change-requests. available is provisional: nothing is held for a substitute until the buyer accepts the report, and the accept checks stock again.

    Example

    These examples send requests to the sandbox.

    Replace the example orderId in the URL with your own.

    Generated cURL request - Sandbox
    curl --request GET \
  --url 'https://api-sandbox.snapcaster.ca/api/v1/marketplace/orders/ord_sandbox_01K4A8Y6D4QJH2N3P5R7S9T0VW/substitute-candidates?lineRef=oln_1f0c8a4d7e2b45c9a1d6f3b8e07c9241' \
  --header "Authorization: Bearer $MARKETPLACE_API_KEY"
    Response 200: One foil printing
    {
  "success": true,
  "data": {
    "items": [
      {
        "sku_id": 363348,
        "product_id": 86,
        "external_ref": "platform-listing-1043",
        "available": 1,
        "unit_price": 2699,
        "name": "Abyssal Nightstalker",
        "set": "Portal Second Age",
        "condition": "LP",
        "language": "EN",
        "finish": "Normal"
      }
    ]
  }
}

    Endpoint

    EnvironmentURL
    Sandboxhttps://api-sandbox.snapcaster.ca/api/v1/marketplace/orders/{orderId}/substitute-candidates
    Productionhttps://api.snapcaster.ca/api/v1/marketplace/orders/{orderId}/substitute-candidates
    Authentication
    • marketplaceApiKey - http bearer. Send the seller's marketplace API key as Authorization: Bearer mp_{sellerCode}_{hex}. The mp_{sellerCode}_ prefix identifies the seller; the trailing hex is the secret. The seller generates the key and supplies it to your platform.

    Request

    Path parameters

    orderId string required

    The opaque public order id (the webhook/poll order_id).

    Constraints: minimum length: 1 Example ord_sandbox_01K4A8Y6D4QJH2N3P5R7S9T0VW

    Query parameters

    lineRef string

    The line_ref of the order line to substitute.

    Constraints: pattern: ^oln_[0-9a-f]{32}$ Example oln_1f0c8a4d7e2b45c9a1d6f3b8e07c9241

    skuId integer

    The SKU of the order line to substitute, when that SKU is on one line only. Otherwise the read answers ORDER_LINE_AMBIGUOUS with the candidate lineRefs in details. Send exactly one of lineRef and skuId.

    Constraints: exclusive minimum: 0

    Headers

    X-Snapcaster-Api-Version string

    Override the platform pin for this request only. Webhook versions and the platform pin do not change.

    Constraints: allowed values: 2026-10 Example 2026-10

    Response

    200

    The substitutes, cheapest first.

    Response body: ChangeRequestSubstituteCandidateListResponse

    success boolean required

    Whether the operation completed as requested.

    Constraints: allowed values: true Example true

    data object required

    The operation or event payload.

    Show child fieldsHide child fields
    data.items ChangeRequestSubstituteCandidate[] required

    The SKUs the line can be substituted with, cheapest first; empty when none qualify.

    Show child fieldsHide child fields
    data.items[].sku_id integer required

    The SKU to send as substituteSkuId (STABLE).

    Example 363348

    data.items[].product_id integer required

    The catalog product of that SKU, the same one the line's SKU belongs to (STABLE).

    Example 86

    data.items[].external_ref string or null required

    Your platform's reference on the seller's listing for that SKU; null when none was sent (STABLE).

    Example platform-listing-1043

    data.items[].available integer required

    Units of that SKU available now: the listing's quantity less the units other orders hold. Provisional: nothing is held for the substitute until the buyer accepts, and the accept checks stock again (STABLE).

    Example 1

    data.items[].unit_price integer required

    The listing's price per unit in cents. For reference only: the buyer still pays the line's own unit_price, less your creditCents (STABLE).

    Example 2699

    data.items[].name string or null required

    The card title; null when the catalog has none (STABLE).

    Example Abyssal Nightstalker

    data.items[].set string or null required

    The set the printing belongs to; null when the catalog has none (STABLE).

    Example Portal Second Age

    data.items[].condition string or null required

    The condition grade; null when the catalog has none (STABLE).

    Example LP

    data.items[].language string or null required

    The printing language; null when the catalog has none (STABLE).

    Example EN

    data.items[].finish string or null required

    The printing or finish, such as Foil; null when the catalog has none (STABLE).

    Example Normal

    Errors

    Errors return a MarketplaceError body, except HTTP 500 (ApiError). Error codes explains both error bodies and lists every code.

    • 400 INVALID_REQUEST ORDER_LINE_AMBIGUOUS UNSUPPORTED_API_VERSION

      Invalid query, a line the order does not have, or a skuId on more than one line (ORDER_LINE_AMBIGUOUS, with the candidate lineRefs in details). Unknown or retired API-version override (UNSUPPORTED_API_VERSION).

      Do this: Name exactly one line. For ORDER_LINE_AMBIGUOUS, name it by one of the lineRef values in details. For UNSUPPORTED_API_VERSION, choose a supported version from the API versioning guide.

    • 401 UNAUTHORIZED

      Missing or invalid marketplace API key (UNAUTHORIZED).

      Do this: Send the marketplace API key for this seller as a Bearer token, then retry.

    • 403 SUBSCRIPTION_EXCLUDES_ORDERS

      The platform's subscription is inventory, which does not include orders (SUBSCRIPTION_EXCLUDES_ORDERS). Only orders and both subscriptions read and act on orders.

      Do this: Do not retry. Ask Snapcaster to change the platform subscription to orders or both if the platform should handle orders.

    • 404 ORDER_NOT_FOUND

      No order matches this id for the authenticated seller (ORDER_NOT_FOUND). Another seller's order also returns 404, so the response does not reveal whether it exists.

      Do this: Check the order_id against GET /orders for the authenticated seller, then retry with that id.

    • 500 INTERNAL_ERROR

      An unexpected failure (INTERNAL_ERROR).

      Do this: Retry with bounded retries and jitter. If the failure persists, contact Snapcaster with the X-Correlation-ID response header.