Purge all listings

POST/listings/purge

Soft-delete all of the Seller’s listings (e.g. a store closing). Returns the number removed.

When to use

Use this operation to purge all listings.

Endpoint

POST /listings/purge

Environment	Base URL
Sandbox	https://api-sandbox.snapcaster.ca/api/v1/marketplace
Production	https://api.snapcaster.ca/api/v1/marketplace

Authentication

• marketplaceApiKey - http bearer. Seller-scoped Marketplace API key, presented as `Authorization: Bearer mp_{sellerCode}_{hex}`. The `mp_{sellerCode}_` prefix identifies the Seller; the trailing hex is the secret. Generated by the Seller and pasted into its Platform.

Request

No parameters.

No request body.

Example

Sandbox is the default. These requests use the contract's canonical field examples.

Generated cURL request - Sandbox

curl --request POST \
  --url 'https://api-sandbox.snapcaster.ca/api/v1/marketplace/listings/purge' \
  --header "Authorization: Bearer $MARKETPLACE_API_KEY"

Response

200

The count of listings removed.

Generated Response 200: Generated response 200

{
  "success": true,
  "data": {
    "purged": 0
  }
}

Field	Type	Constraints	Meaning	Example
successrequired	boolean	allowed values: true	Whether the operation completed as requested.	true (generated)
datarequired	object	None	The operation or event payload.	{ "purged": 0 } (generated)
data.purgedrequired	integer	None	The number of Listings removed by the purge.	0 (generated)

Errors

Status	Code	Meaning	Do this
401	UNAUTHORIZED	Missing or invalid Marketplace API key (`UNAUTHORIZED`).	Send the Marketplace API key for this Seller as a Bearer token, then retry.
409	SELLER_SOURCE_EXCLUSIVE	The authenticated Seller’s declared inventory source is not `platform` (`SELLER_SOURCE_EXCLUSIVE`). Listing writes through the integration API are reserved for platform-source Sellers; sources are exclusive and never mixed.	Use the Seller’s declared inventory source, or ask Snapcaster to move the Seller to the platform source.

Related

Operations

• Export listings
• Upsert listings
• Soft-delete listings
• Bulk upsert/delete listings

Concepts

• Core concepts
• Path A
• API versioning
• Webhook signing

Changelog

• The baseline dated version: the full partner surface exactly as documented on this page. Introducing versioning changed no wire bytes on the endpoints; the only wire change was additive.

Schema

Full schema details (13 fields)

Parameters

None.

Request

None.

Response 200 (application/json)

Field	Type	Constraints	Meaning	Example
successrequired	boolean	allowed values: true	Whether the operation completed as requested.	true (generated)
datarequired	object	None	The operation or event payload.	{ "purged": 0 } (generated)
data.purgedrequired	integer	None	The number of Listings removed by the purge.	0 (generated)

Error 401 (application/json)

Field	Type	Constraints	Meaning	Example
successrequired	boolean	allowed values: false	Whether the operation completed as requested.	false (generated)
errorrequired	object	None	Structured error information returned when the request cannot be completed.	{ "code": "UNAUTHORIZED", "message": "string" } (generated)
error.coderequired	string	allowed values: UNAUTHORIZED, INVALID_REQUEST, UNSUPPORTED_API_VERSION, SELLER_SOURCE_EXCLUSIVE, BATCH_TOO_LARGE, RATE_LIMITED, ORDER_NOT_FOUND, SELLER_NOT_FOUND, INVALID_TRANSITION, CHECKOUT_IDEMPOTENCY_KEY_REUSED, CHECKOUT_MANUAL_SELLER_UNSUPPORTED, CHECKOUT_SELF_PURCHASE_NOT_ALLOWED, CHECKOUT_SELLER_UNAVAILABLE, CHECKOUT_NOT_FOUND, FEATURE_DISABLED	Stable public error code the Platform can branch on.	UNAUTHORIZED (generated)
error.messagerequired	string	None	A human-readable explanation of the result.	string (generated)
error.details	unknown	None	Additional structured context for diagnosing the result.	{} (generated)

Error 409 (application/json)

Field	Type	Constraints	Meaning	Example
successrequired	boolean	allowed values: false	Whether the operation completed as requested.	false (generated)
errorrequired	object	None	Structured error information returned when the request cannot be completed.	{ "code": "UNAUTHORIZED", "message": "string" } (generated)
error.coderequired	string	allowed values: UNAUTHORIZED, INVALID_REQUEST, UNSUPPORTED_API_VERSION, SELLER_SOURCE_EXCLUSIVE, BATCH_TOO_LARGE, RATE_LIMITED, ORDER_NOT_FOUND, SELLER_NOT_FOUND, INVALID_TRANSITION, CHECKOUT_IDEMPOTENCY_KEY_REUSED, CHECKOUT_MANUAL_SELLER_UNSUPPORTED, CHECKOUT_SELF_PURCHASE_NOT_ALLOWED, CHECKOUT_SELLER_UNAVAILABLE, CHECKOUT_NOT_FOUND, FEATURE_DISABLED	Stable public error code the Platform can branch on.	UNAUTHORIZED (generated)
error.messagerequired	string	None	A human-readable explanation of the result.	string (generated)
error.details	unknown	None	Additional structured context for diagnosing the result.	{} (generated)