Upsert listings

POST/listings

Push a single Listing or an array of them (desired-state upsert). Each item is reported independently in the multi-status response; one malformed item does not fail the batch.

When to use

Use this operation to upsert listings.

Endpoint

POST /listings

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.

Request body (application/json)

Field	Type	Constraints	Meaning	Example
skuIdconditional	integer	exclusive minimum: 0	Sku Id supplied to or returned by this operation.	427286
productIdconditional	integer	exclusive minimum: 0	Product Id supplied to or returned by this operation.	24692
priceconditional	integer	minimum: 0	The unit price in minor currency units.	2499
quantityconditional	integer	None	The number of inventory units represented by this record.	3
externalRef	string	maximum length: 255	External Ref supplied to or returned by this operation.	platform-listing-1042
asOf	string	format: date-time	As Of supplied to or returned by this operation.	2026-09-04T18:30:00.000Z
[].skuIdrequired	integer	exclusive minimum: 0	Sku Id for the surrounding item record.	1 (generated)
[].productIdrequired	integer	exclusive minimum: 0	Product Id for the surrounding item record.	1 (generated)
[].pricerequired	integer	minimum: 0	The unit price in minor currency units.	0 (generated)
[].quantityrequired	integer	None	The number of inventory units represented by this record.	0 (generated)
[].externalRef	string	maximum length: 255	External Ref for the surrounding item record.	string (generated)
[].asOf	string	format: date-time	As Of for the surrounding item record.	2026-01-01T00:00:00.000Z (generated)

Example

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

cURL request - Sandbox: One Listing

curl --request POST \
  --url 'https://api-sandbox.snapcaster.ca/api/v1/marketplace/listings' \
  --header "Authorization: Bearer $MARKETPLACE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "skuId": 427286,
  "productId": 24692,
  "price": 2499,
  "quantity": 3,
  "externalRef": "platform-listing-1042",
  "asOf": "2026-09-04T18:30:00.000Z"
}'

cURL request - Sandbox: Multiple Listings

curl --request POST \
  --url 'https://api-sandbox.snapcaster.ca/api/v1/marketplace/listings' \
  --header "Authorization: Bearer $MARKETPLACE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '[
  {
    "skuId": 427286,
    "productId": 24692,
    "price": 2499,
    "quantity": 3,
    "externalRef": "platform-listing-1042",
    "asOf": "2026-09-04T18:30:00.000Z"
  },
  {
    "skuId": 427287,
    "productId": 24692,
    "price": 2699,
    "quantity": 1,
    "externalRef": "platform-listing-1043",
    "asOf": "2026-09-04T18:30:00.000Z"
  }
]'

Response

200

Per-item multi-status results.

Response 200: Applied Listing

{
  "success": true,
  "data": {
    "results": [
      {
        "skuId": 427286,
        "op": "upsert",
        "status": "applied",
        "externalRef": "platform-listing-1042"
      }
    ]
  }
}

Field	Type	Constraints	Meaning	Example
successrequired	boolean	allowed values: true	Whether the operation completed as requested.	true
datarequired	object	None	The operation or event payload.	{ "results": [ { "skuId": 427286, "op": "upsert", "status": "applied", "externalRef": "platform-listing-1042" } ] }
data.resultsrequired	array of object	None	The outcome recorded for each submitted item.	[ { "skuId": 427286, "op": "upsert", "status": "applied", "externalRef": "platform-listing-1042" } ]
data.results[].skuIdrequired	integer	None	Sku Id for the surrounding results item record.	427286
data.results[].oprequired	string	allowed values: upsert, delete	The write operation to apply to this item.	upsert
data.results[].statusrequired	string	allowed values: applied, unmatched, rejected	Per-item outcome. `unmatched` corresponds to the public per-item code `UNMATCHED` (persisted but not in the Canonical Catalog); `rejected` corresponds to `REJECTED` (failed validation, not persisted; see `reason`).	applied
data.results[].reason	string	None	Why the item was rejected; present only when status is "rejected".	string (generated)
data.results[].externalRef	string	None	Echo of the pushed external_ref, when one was supplied.	platform-listing-1042

Errors

Status	Code	Meaning	Do this
400	INVALID_REQUEST	The request failed validation (`INVALID_REQUEST`).	Correct the fields named in the error details, then retry the request.
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.
413	BATCH_TOO_LARGE	The request carried more than the 1,000-item per-request cap (`BATCH_TOO_LARGE`).	Split the write into batches of at most 1,000 items and retry each batch.

Related

Operations

• Export listings
• Soft-delete listings
• Purge all 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 (40 fields)

Parameters

None.

Request

Field	Type	Constraints	Meaning	Example
skuIdconditional	integer	exclusive minimum: 0	Sku Id supplied to or returned by this operation.	427286
productIdconditional	integer	exclusive minimum: 0	Product Id supplied to or returned by this operation.	24692
priceconditional	integer	minimum: 0	The unit price in minor currency units.	2499
quantityconditional	integer	None	The number of inventory units represented by this record.	3
externalRef	string	maximum length: 255	External Ref supplied to or returned by this operation.	platform-listing-1042
asOf	string	format: date-time	As Of supplied to or returned by this operation.	2026-09-04T18:30:00.000Z
[].skuIdrequired	integer	exclusive minimum: 0	Sku Id for the surrounding item record.	1 (generated)
[].productIdrequired	integer	exclusive minimum: 0	Product Id for the surrounding item record.	1 (generated)
[].pricerequired	integer	minimum: 0	The unit price in minor currency units.	0 (generated)
[].quantityrequired	integer	None	The number of inventory units represented by this record.	0 (generated)
[].externalRef	string	maximum length: 255	External Ref for the surrounding item record.	string (generated)
[].asOf	string	format: date-time	As Of for the surrounding item record.	2026-01-01T00:00:00.000Z (generated)

Response 200 (application/json)

Field	Type	Constraints	Meaning	Example
successrequired	boolean	allowed values: true	Whether the operation completed as requested.	true
datarequired	object	None	The operation or event payload.	{ "results": [ { "skuId": 427286, "op": "upsert", "status": "applied", "externalRef": "platform-listing-1042" } ] }
data.resultsrequired	array of object	None	The outcome recorded for each submitted item.	[ { "skuId": 427286, "op": "upsert", "status": "applied", "externalRef": "platform-listing-1042" } ]
data.results[].skuIdrequired	integer	None	Sku Id for the surrounding results item record.	427286
data.results[].oprequired	string	allowed values: upsert, delete	The write operation to apply to this item.	upsert
data.results[].statusrequired	string	allowed values: applied, unmatched, rejected	Per-item outcome. `unmatched` corresponds to the public per-item code `UNMATCHED` (persisted but not in the Canonical Catalog); `rejected` corresponds to `REJECTED` (failed validation, not persisted; see `reason`).	applied
data.results[].reason	string	None	Why the item was rejected; present only when status is "rejected".	string (generated)
data.results[].externalRef	string	None	Echo of the pushed external_ref, when one was supplied.	platform-listing-1042

Error 400 (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 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)

Error 413 (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)