Locations

Returns the per-field maximum lengths, list limits, sort columns, and request caps that apply to location endpoints.

Returns paginated locations. The primary location is pinned first, so limit=1 returns it when the token can see it; the chosen sort orders the remaining rows. Merchant tokens can read all locations. App tokens can read merchant-managed locations and locations owned by that app. For app-managed rows, app_id identifies the owner, app_name and app_slug describe it when available, and app_installation_active reports whether that owning app is currently installed and active. Merchant-managed rows have a null app_id, omit the optional app name and slug, and report app_installation_active: false. active_merchant_total is the number of active merchant-managed locations before list filters and pagination. Archived locations are hidden unless status=archived is requested; is_archived is always false on the other views. A merchant-managed row whose app was uninstalled reports that app in previous_app_id and previous_app_name.

Returns the location when it is visible to the authenticated token. address_lines is its address laid out the way its country writes it, ending with the country name, ready to display. Merchant tokens can read any location in their store. App tokens can read merchant-managed locations and locations owned by that app; another app's managed location is reported as LOCATION_NOT_FOUND.

Creates a location. name is required; slug is generated when omitted. Ownership follows the authenticated token: app tokens create app-managed locations owned by their active installation, while merchant tokens create merchant-managed locations. App-managed rows use the installation's separate bounded allowance and do not consume the merchant location allowance.

Updates provided location fields. Omitted fields are unchanged. fulfillment_priority is not updateable through this endpoint; it is merchant-owned routing metadata changed only through reorder. Merchant-managed locations follow normal write_locations access. An app-managed location can be updated only by the active installation that owns it; merchants and other apps receive LOCATION_APP_MANAGED_NO_EDIT.

Archives a location that is empty: no non-zero stock, no pending or in-transit transfers, and no order still holding a reservation there. The primary location cannot be archived. An archived location is inactive, hidden from lists unless status=archived is requested, does not count toward the location allowance and cannot be edited until it is restored. Archiving an archived location succeeds without changes. Ownership follows update: an app-managed location can be archived only by its owning active installation. Fires locations/deactivated when the location was active, and locations/update with is_archived in changed_fields.

Restores an archived location as an active location. Restoring counts against the allowance exactly like activating: the plan limit for a merchant-managed location, the installation's allowance for an app-managed one. Restoring a location that is not archived succeeds without changes. Fires locations/activated and locations/update with is_archived in changed_fields.

Deletes a location only when it is empty and not primary or the last active online-fulfilling location. Empty means no non-zero stock, no pending or in-transit transfers and no order still holding a reservation there. Past orders, reservations, fulfillments, stock movements and transfers do not block deletion; they keep the location's name after it is gone. Empty zero-level storage rows do not block deletion and are cleaned atomically. Archived locations can be deleted. The first request returns CONFIRMATION_REQUIRED with impact warnings and a single-use confirmation token; retry with confirmed: true and that token. Remaining locations are renumbered automatically so fulfillment priority stays gapless. App-managed locations can be deleted only by their owning active installation.

Merchant API tokens only. Fulfillment priority is merchant-owned routing metadata, not app-owned location data, so merchants may include app-managed locations in the order. Send every location id exactly once, with the primary location first: array position 0 becomes priority 0, position 1 becomes priority 1, and so on. Include the primary location, inactive locations, and app-managed locations returned by GET /locations; this changes routing priority but not ownership or status. Archived locations are not listed and must not be included; they keep their relative order after every listed location. Partial lists, duplicates, malformed ids, and ids from another store are rejected atomically.