Skip to main content
POST
Declare a retailer web property

Authorizations

X-API-Key
string
header
required

Path Parameters

retailer_id
string<shortuuid>
required

Unique identifier of the retailer this property belongs to.

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

Body

application/json

One of a retailer's web properties.

url
string
required

Root URL of the storefront — its identity, and the value a listing's urls[].store_url must match. Unique per retailer, so sending the same URL again updates the property rather than adding a second one.

Must be an absolute http(s) URL. The constraint is published rather than merely enforced, because this value is matched verbatim against a listing's store_url: a storefront stored with a malformed URL is one no listing can ever reference, and nothing downstream would report that.

Maximum string length: 500
Pattern: ^https?://[^\s/?#]+[^\s]*$
name
string
default:""

Display name. Defaults to ' Online' when blank.

Maximum string length: 255
currency
string
default:USD

ISO 4217 code this storefront transacts in — three uppercase letters. Offers attached here use it for their prices.

A pattern rather than an enum of codes: OnlineStore.currency carries no choices, so an enum here would publish a constraint the model does not enforce and would drift from it silently.

Pattern: ^[A-Z]{3}$
country
string<iso3166-alpha2> | null

ISO 3166-1 alpha-2 country code (US, CA, GB). Case-insensitive on input and normalized to upper case; unassigned codes are rejected with a 422.

Required string length: 2
Pattern: ^[A-Za-z]{2}$
is_active
boolean
default:true

Disable without deleting when a property goes dark. Only active storefronts can be referenced by a listing URL.

Response

OK

The retailer web property this call created or updated.

storefront_id
string
required

Identifier of the storefront.

url
string
required

Root URL, i.e. the value listings reference as store_url.

created
boolean
required

True when this call created the property, false when it updated one.