Skip to main content
POST
Create Product Subscription

Authorizations

x-api-key
string
header
required

Body

application/json

What to subscribe to: a canonical product's offer events, optionally narrowed by merchant domains and, when the product has variant options, pinned to one variant.

product_id
string
required

Canonical product ID, as returned by /v1/products or /v1/lookup. Lookup IDs are canonicalized automatically. When selection picks another product (e.g. another color), the subscription is created on that product

events
enum<string>[]
required

Offer event types to receive.

Minimum array length: 1
Available options:
offer.price.changed,
offer.availability.changed,
offer.created,
offer.deleted
domains
string[] | null

Restrict events to offers on these merchant domains (e.g. nike.com, max 25). Omitted = every offer.

selection
SelectedOption · object[] | null

The variant to watch: one {name, label} per option in variants.options on the product detail or lookup response; variants.selected can be passed as is. Required when the product has variant options, omitted when it has none. A value that is its own product (e.g. another color) subscribes you to that product, and the response's product_id is that product.

Minimum array length: 1

Response

Successful Response

A product subscription's scope and lifecycle state.

subscription_id
string
required
product_id
string
required

The product subscribed to. Differs from the requested product_id when the selection picked another product.

events
enum<string>[]
required
Available options:
offer.price.changed,
offer.availability.changed,
offer.created,
offer.deleted
locale
WebhookLocale · object
required

The locale the subscription reads the product in.

status
enum<string>
required

Lifecycle status: "active" or "cancelled"

Available options:
active,
cancelled
created_at
string<date-time>
required
domains
string[] | null
selection
StoredSelection · object[] | null

The variant the subscription watches, including the values that identify the product itself (e.g. its color); null when nothing is pinned.