snapcasterDevelopers

    API reference · Listings

    Soft-delete listings

    DELETE /listings

    Soft-delete the seller's listings for the supplied SKUs. Each delete is a listing snapshot at asOf. A delete with a newer asOf returns applied, even for a SKU that is already unlisted. Repeating the same delete with the same asOf returns noop, so you can retry a lost response safely.

    Example

    These examples send requests to the sandbox.

    cURL request - Sandbox: One listing
    curl --request DELETE \
  --url 'https://api-sandbox.snapcaster.ca/api/v1/marketplace/listings' \
  --header "Authorization: Bearer $MARKETPLACE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "skuIds": [
    14602
  ],
  "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.

    Response 200: Deleted listing
    {
  "success": true,
  "data": {
    "results": [
      {
        "skuId": 14602,
        "op": "delete",
        "status": "applied"
      }
    ]
  }
}

    Endpoint

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

    skuIds array of integer required

    Constraints: minimum items: 1; maximum items: 1000

    Field example[ 14602 ]
    asOf string required

    See Send ordered listing snapshots in Core concepts.

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

    Response

    200

    Per-item multi-status results.

    Response body: ListingWriteResponse

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

    Example 14602

    data.results[].op string required

    The write operation to apply to this item.

    Constraints: allowed values: upsert, delete Example 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 Example applied

    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.