Skip to main content
PATCH
Update one physical store

Authorizations

X-API-Key
string
header
required

Path Parameters

retailer_id
string<shortuuid>
required

Unique identifier of the retailer this store belongs to.

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

Unique identifier of the store to update.

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

Body

application/json

Fields a PATCH may change on an existing store.

Every field is optional and only the ones present in the request body are written, so a caller correcting one column cannot blank the rest by omission.

The address is not here. Street, city, coordinates and country live on the store's place and carry per-source provenance — which source wrote each column, whether it was first-party, and the previous value it superseded. Only the reconciling upsert maintains that, so address corrections go through POST /retailers/{retailer_id}/stores, which also re-runs the duplicate matcher. Repointing the store at a different place is likewise refused: a place belongs to whichever organization created it, and accepting an id here would let a store be attached to another organization's location record.

name
string
default:""

Store or branch display name.

Maximum string length: 255
store_number
string
default:""

The retailer's own key for this store. Unique per retailer when non-empty — a value another store of this retailer already holds is refused with 409, because re-keying one store onto another's number is how two stores become indistinguishable to the upsert matcher.

Maximum string length: 50
gln
string | null

GS1 Global Location Number for this store. Must already be registered — this does not mint one, because a GLN is issued by GS1 and a row invented here would be a fabricated identifier in the registry. Send "" to detach the current GLN.

Maximum string length: 13
currency
string
default:""

ISO 4217 code offers at this store are priced in.

Maximum string length: 3
is_active
boolean
default:false

Set false to retire the store (the same effect as DELETE), true to reinstate one. Retailer.is_physical is derived from the presence of active stores, so this is what flips that flag.

Response

OK

One physical store as the catalog holds it.

The retailer-owned columns plus a flattened copy of the store's locations.Place address, because a caller reconciling its own dataset against ours needs the address to compare against and should not have to follow a second identifier into another app's API to get 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}$
name
string
required

Store or branch display name.

store_number
string
required

The retailer's own key for this store, or the synthesized key the import recorded. Unique within a retailer when non-empty, and the highest-confidence tier the store upsert matches on.

is_active
boolean
required

False for a retired store. DELETE clears this flag rather than removing the row, so a deleted store still appears in this list unless you filter it out with is_active=true.

place_id
string<shortuuid>
required

Identifier of the locations.Place this store occupies — the geographic record.

Required string length: 22
Pattern: ^[23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{22}$
created
string<date-time>
required

When this store row was first written.

modified
string<date-time>
required

When this store row last changed.

gln
string | null

GS1 Global Location Number identifying this store, when issued.

currency
string
default:""

ISO 4217 code offers at this store are priced in. Empty when unset.

address_line_1
string
default:""

Street address, number and street name.

address_line_2
string
default:""

Apartment, suite, unit or floor.

city
string
default:""

City, town or locality.

region
string
default:""

State, province or region.

postal_code
string
default:""

ZIP, postal code or postcode.

country
string
default:""

ISO 3166-1 alpha-2 country code of the store.

latitude
number | null

WGS84 latitude in decimal degrees. Null when uncoordinated.

longitude
number | null

WGS84 longitude in decimal degrees. Null when uncoordinated.