snapcasterDevelopers

    API reference · Listings

    Purge all listings

    POST /listings/purge

    Remove listings at or before asOf and retain newer snapshots. The purge fences delayed pushes, including SKUs never stored here. Repeating the same purge is a no-op. A stale purge returns 409 STALE_SNAPSHOT.

    Example

    These examples send requests to the sandbox.

    Generated cURL request - Sandbox: Generated request
    curl --request POST \
  --url 'https://api-sandbox.snapcaster.ca/api/v1/marketplace/listings/purge' \
  --header "Authorization: Bearer $MARKETPLACE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "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": {
    "purged": 0
  }
}

    Endpoint

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

    asOf string required

    See Send ordered listing snapshots in Core concepts.

    Constraints: format: date-time

    Response

    200

    The count of listings removed.

    Response body: PurgeListingsResponse

    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.purged integer required

    The number of listings removed by the purge.

    Errors

    Errors return a MarketplaceError body, except HTTP 413, 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 STALE_SNAPSHOT

      The seller uses another inventory source, or asOf precedes an existing purge.

      Do this: Use the declared inventory source. For STALE_SNAPSHOT, discard the delayed purge; use a newly measured snapshot for a new purge.

    • 413 PAYLOAD_TOO_LARGE

      The body is larger than this route accepts (PAYLOAD_TOO_LARGE).

      Do this: Send a smaller body and retry.

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