Skip to main content
PATCH
Update one retailer product listing

Authorizations

X-API-Key
string
header
required

Path Parameters

retailer_id
string<shortuuid>
required

Unique identifier of the retailer this listing belongs to.

Required string length: 22
Pattern: ^[23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{22}$
listing_id
string<shortuuid>
required

Unique identifier of the listing to update.

Required string length: 22
Pattern: ^[23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{22}$

Body

application/json

Fields a PATCH may change on an existing listing.

Every field is optional; only the ones present in the request body are written. badges and urls are deliberately absent — see this module's docstring.

sku
string
default:""

The retailer's internal SKU for this product.

Maximum string length: 100
is_active
boolean
default:false

Set false to drop the product from the catalog (the same effect as DELETE), true to re-list it.

attributes
Attributes · object

Retailer-scoped facts with no typed column yet. Replaces the stored dict rather than merging into it, so a key can be removed. Bounded: at most 200 keys and 8000 characters per value — the same bounds the import boundary applies, because the column has no database-level shape and this would otherwise be the one path that can turn a staging area into a document store.

source_reference
string
default:""

The retailer's own product identifier in the source feed.

Maximum string length: 255

Response

OK

One retailer product listing as the catalog holds it.

id
string<shortuuid>
required

URL-safe 22-character shortuuid encoding of the row's UUID primary key. Stable across the row's lifetime; suitable for sharing in URLs, log lines, and external SDK clients. Accepted on input as either the shortuuid form or the canonical UUID form (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).

Required string length: 22
Pattern: ^[23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{22}$
retailer_id
string<shortuuid>
required

URL-safe 22-character shortuuid encoding of the row's UUID primary key. Stable across the row's lifetime; suitable for sharing in URLs, log lines, and external SDK clients. Accepted on input as either the shortuuid form or the canonical UUID form (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).

Required string length: 22
Pattern: ^[23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{22}$
product_id
string<shortuuid>
required

Identifier of the shared product this listing points at.

Required string length: 22
Pattern: ^[23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{22}$
gtin
string
required

GTIN of the listed product. The key the listing upsert accepts, echoed here so a caller can reconcile this row against its own feed without a second lookup.

sku
string
required

The retailer's own SKU for this product across its whole catalog. Distinct from an offer's SKU, which is the SKU at one specific store or storefront.

is_active
boolean
required

False once the retailer drops the product from its catalog. DELETE clears this flag rather than removing the row.

created
string<date-time>
required

When this listing row was first written.

modified
string<date-time>
required

When this listing row last changed.

attributes
Attributes · object

Retailer-scoped facts that have no typed column yet — a staging area, not a permanent home. A key that proves useful is promoted to a real column.

source_reference
string
default:""

The retailer's own product identifier in the source feed (e.g. a Sephora productId).

badges
ListingBadgeOut · object[]

Designations this retailer applies to this product. Change them through POST /retailers/{retailer_id}/listings, which syncs the whole set.

urls
ListingURLOut · object[]

One product URL per retailer web property. Change them through POST /retailers/{retailer_id}/listings, which syncs the whole set.