snapcasterDevelopers

    API reference · Listings

    Bulk upsert/delete listings

    POST /listings/bulk

    Send a mix of upsert and delete operations in one request. The response reports each item's result. An invalid item does not fail the rest of the batch.

    Example

    These examples send requests to the sandbox.

    cURL request - Sandbox: Upsert one listing and delete another
    curl --request POST \
  --url 'https://api-sandbox.snapcaster.ca/api/v1/marketplace/listings/bulk' \
  --header "Authorization: Bearer $MARKETPLACE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "items": [
    {
      "op": "upsert",
      "skuId": 14602,
      "productId": 86,
      "price": 2499,
      "quantity": 3,
      "externalRef": "platform-listing-1042",
      "asOf": "$(node -p 'new Date().toISOString()')"
    },
    {
      "op": "delete",
      "skuId": 316074,
      "asOf": "$(node -p 'new Date().toISOString()')"
    }
  ]
}
EOF

    $(node -p 'new Date().toISOString()') sets asOf to the current UTC time in milliseconds, so two writes in the same second never share an asOf.

    Generated Response 200: Generated response 200
    {
  "success": true,
  "data": {
    "results": [
      {
        "skuId": 0,
        "op": "upsert",
        "status": "applied"
      }
    ]
  }
}

    Endpoint

    EnvironmentURL
    Sandboxhttps://api-sandbox.snapcaster.ca/api/v1/marketplace/listings/bulk
    Productionhttps://api.snapcaster.ca/api/v1/marketplace/listings/bulk
    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

    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

    This operation takes no Idempotency-Key. Retries says how to resend it safely.

    Request body

    items array of object required

    The records included in this page or batch.

    Constraints: maximum items: 1000

    Show child fieldsHide child fields
    items[].skuId integer required

    See Canonical catalog in Core concepts.

    Constraints: exclusive minimum: 0 Example 14602

    items[].productId integer

    The TCGplayer product of skuId. Required only while skuId is absent from the canonical catalog; otherwise Snapcaster takes the product from the catalog and rejects a different value with PRODUCT_MISMATCH.

    Constraints: exclusive minimum: 0 Example 86

    items[].price integer conditional

    Required when op is upsert. The unit price in minor currency units.

    Constraints: minimum: 0 Example 2499

    items[].quantity integer conditional

    Required when op is upsert. The number of units.

    Example 3

    items[].externalRef string

    See Listing in Core concepts.

    Constraints: maximum length: 255 Example platform-listing-1042

    items[].asOf string required

    See Send ordered listing snapshots in Core concepts.

    Constraints: format: date-time Example 2026-09-04T18:30:00.000Z

    items[].op string required

    The write operation to apply to this item.

    Constraints: allowed values: upsert, delete Example upsert

    Response

    200

    Per-item multi-status results.

    Response body: ListingWriteResponse

    success boolean required

    Whether the operation completed as requested.

    Constraints: allowed values: true

    data object required

    The operation or event payload.

    Show child fieldsHide child fields
    data.results ListingItemResult[] required

    The outcome recorded for each submitted item.

    Show child fieldsHide child fields
    data.results[].skuId integer required

    See Canonical catalog in Core concepts.

    data.results[].op string required

    The write operation to apply to this item.

    Constraints: allowed values: upsert, delete

    data.results[].status string required

    The result for this item. unmatched corresponds to UNMATCHED: Snapcaster stored the item, but its SKU is absent from the canonical catalog. rejected corresponds to REJECTED: validation failed and Snapcaster did not store the item. Check reason for details.

    Constraints: allowed values: applied, unmatched, rejected, noop

    data.results[].code string

    The stable machine-readable code for this result.

    Constraints: allowed values: INVALID_REQUEST, STALE_SNAPSHOT, SNAPSHOT_CONFLICT, PRODUCT_MISMATCH

    data.results[].reason string

    Why the item was rejected; present only when status is "rejected".

    data.results[].externalRef string

    The submitted listing reference, if supplied.

    Errors

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

    • 400 INVALID_REQUEST UNSUPPORTED_API_VERSION

      The request failed validation (INVALID_REQUEST). Unknown or retired API-version override (UNSUPPORTED_API_VERSION).

      Do this: Correct the fields named in the error details, then retry the request. 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.

    • 409 SELLER_SOURCE_EXCLUSIVE

      The seller's inventory source is not platform (SELLER_SOURCE_EXCLUSIVE). Only platform-source sellers can write listings through the integration API. A seller uses one inventory source at a time.

      Do this: Use the seller’s declared inventory source, or ask Snapcaster to move the seller to the platform source.

    • 413 BATCH_TOO_LARGE PAYLOAD_TOO_LARGE

      The request exceeds the 1,000-item limit (BATCH_TOO_LARGE). The body is larger than this route accepts (PAYLOAD_TOO_LARGE).

      Do this: Split the write into batches of at most 1,000 items and retry each batch. Send a smaller body and retry.

    • 429 RATE_LIMITED

      The per-seller item rate ceiling was exceeded (RATE_LIMITED).

      Do this: Wait the Retry-After duration in seconds, then retry with bounded retries and jitter.

    • 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.

    Per-item errors

    A successful HTTP response can still reject items. Each rejected item carries one of these codes.

    • INVALID_REQUEST

      The item failed validation.

      Do this: Correct the fields named in reason before submitting this item again.

    • STALE_SNAPSHOT

      The snapshot is older than the retained listing or purge watermark.

      Do this: Discard the delayed snapshot. Measure current stock before sending a new snapshot; do not relabel stale stock with a newer timestamp.

    • SNAPSHOT_CONFLICT

      The same snapshot instant was used with different contents.

      Do this: Retry the original contents, or measure current stock and send it with its actual capture time.

    • PRODUCT_MISMATCH

      The productId names a different product than the canonical catalog holds for the skuId. Snapcaster stored nothing for the item and left any existing listing for the SKU unchanged.

      Do this: Send the productId that reason names, or omit productId so Snapcaster takes it from the catalog.