Stores¶

PUT /stores

Creates or updates store master data (upsert by store_id). Send it before go-live and whenever a store changes.

Authentication: API key (x-functions-key)

Request¶

Request body¶

Field	Type	Required	Description
batch_id	UUID	Yes	Idempotency key
stores	array of Store	Yes	1–500 stores. Every `store_id` must be registered for your account.

Store object¶

Field	Type	Required	Description
store_id	string	Yes	Store code, unique within your account
store_name	string	Yes	Store name
country_code	string	Yes	ISO 3166-1 alpha-2
currency	string	Yes	ISO 4217. All amounts for this store use this currency.
time_zone	string	Yes	IANA time zone
locale	string	Yes	BCP 47
workday_start	string	Yes	Store-local time (`HH:mm`) when a new business date begins. With `04:00`, transactions before 4 a.m. belong to the previous business date.
prices_include_tax	boolean	Yes	Whether product prices include tax
status	enum	Yes	`ACTIVE` / `INACTIVE`
last_modified_at	timestamp	Yes	Last change time

Example¶

{
  "batch_id": "3a9e7d10-5f2b-4c8e-8d11-0a1b2c3d4e5f",
  "stores": [
    {
      "store_id": "US001",
      "store_name": "Main St",
      "country_code": "US",
      "currency": "USD",
      "time_zone": "America/Los_Angeles",
      "locale": "en-US",
      "workday_start": "04:00",
      "prices_include_tax": false,
      "status": "ACTIVE",
      "last_modified_at": "2026-10-14T10:00:00-07:00"
    }
  ]
}

Response¶

202 Accepted

{ "batch_id": "3a9e7d10-5f2b-4c8e-8d11-0a1b2c3d4e5f", "status": "ACCEPTED", "record_count": 1, "warnings": [] }

Resending the same batch_id returns 200 with "status": "ALREADY_RECEIVED".

Errors¶

HTTP	code	When
400	INVALID_PAYLOAD	Invalid type, missing field, invalid enum or format
400	BATCH_TOO_LARGE	More stores than your batch limit
403	STORE_NOT_ALLOWED	A `store_id` is not registered for your account
413	PAYLOAD_TOO_LARGE	Body larger than 5 MB

See Error Codes for the full list.

Notes¶

Note

New stores must first be registered for your account by HQ. Contact HQ integration support before sending a new store_id.