Skip to main content
Programmatic equivalent of the organization’s Locations page in the dashboard (the list, and its add, edit and delete forms, including the phone number, website and email address rows). The page and the API write through the same service and the same form validation, so a place saved on one reads back on the other, and a value one refuses the other refuses too. A place is a physical location the organization itself runs: a store, a warehouse, a farm, a plant. Local search ranks places by distance, so a place without latitude and longitude is stored but cannot be found by a shopper nearby.

​
When to use

  • The organization has no places recorded yet, or is missing some.
  • An address, phone number, website or email address has changed.
  • A place has closed (mark it inactive).

​
Auth

X-API-Key header or OAuth token. Reading needs any member of the organization (or any API key of it). Writing needs an OWNER, MANAGER or EDITOR (or an API key with the EDITOR role or above): a read-only key gets 403. An organization the caller does not belong to, or a place another organization owns, is 404.

​
Flow

  • GET .../places — every place by name, inactive ones included, paginated: id, name, the address (address_line_1, address_line_2, city, region, county, postal_code, country), latitude, longitude, gln, supply_chain_type, google_place_id, is_active, the lists urls, phones and emails, created, modified.
  • POST .../places — add a place. address_line_1, city, region, postal_code and country (ISO alpha-2, such as US) are required. Optional: name, address_line_2, latitude with longitude, gln, supply_chain_type, google_place_id, is_active (default true), and the contact lists:
    • phones: label (required), number, optional extension;
    • urls: url (http or https), optional label (default Website);
    • emails: email, optional label (default Inquiries);
    • each row takes an optional sort_order. Returns 201 with the place.
  • PATCH .../places/{place_id} — send only the fields you are changing. A contact list you send replaces the place’s whole list (an empty list clears it); a list you leave out is untouched. null clears gln and supply_chain_type and is 422 anywhere else.
  • DELETE .../places/{place_id} — delete the place and its contact rows (204). A place that traceability records (harvest areas, critical tracking events) still name is 409; send {"is_active": false} instead.
A value the dashboard form would refuse — a postal code over 20 characters, an invalid phone number or email address, a non-web URL, a GLN that is not 13 digits, a supply_chain_type without a gln, latitude without longitude — is 422, with one details row per field. A contact row’s error is located by its position in the list you sent, such as ["body", "data", "phones", 1, "number"].

​
Verify

  1. GET .../places again and confirm each place you added or changed reads back with the address, coordinates and contact details you intended.
  2. Confirm no place you did not mean to touch changed or disappeared.