flintDocs

Locations

A Location is a place a merchant operates from: a store, a warehouse, a stockroom. Locations are operational children of a merchant, not organization hierarchy nodes.

A Location has three independently versioned parts:

  • Identity (name, metadata, status), updated with PATCH /v1/locations/{location_id} and guarded by expected_version.
  • Geography (address, timezone, coordinate), published with PATCH /v1/locations/{location_id}/geography and guarded by expected_geography_revision.
  • Inventory capability, set with the inventory block when the Location is created or updated with PATCH /v1/locations/{location_id}/inventory, and guarded by expected_inventory_revision after the capability exists.

Splitting them means a metadata edit and an address publication cannot invalidate each other. Send the revision you read; if it no longer matches, the write is rejected rather than silently overwriting a concurrent change.

Enabling a Location for inventory#

Creating a Location does not make it hold stock. Stock lives on inventory levels, which exist per inventory item per Location, and a Location only participates in allocation once it carries an inventory block with allocation_status: "active".

Set the block when creating the Location, or update allocation_status with PATCH /v1/locations/{location_id}/inventory. Omit expected_inventory_revision the first time you enable inventory. After the inventory block exists, send its current inventory_revision. Change stock through inventory adjustments and update item-level controls through their inventory routes. Location identity and geography writes do not replace the inventory block.

Scopes#

Location reads and ordinary writes use merchants.locations.read and merchants.locations.write. The inventory block is separately gated:

  • Reading the nested inventory object requires commerce.inventory.read. Without it the object is omitted from every Location response, and inventory_allocation_status is not an accepted filter on GET /v1/locations.
  • Creating or updating an inventory block requires commerce.inventory_locations.write. This is deliberately narrower than merchants.locations.write, so a credential can manage whether a Location participates in inventory allocation without broader inventory authority.

Creating a Location with an inventory block in the same request requires both applicable write scopes.

Locations elsewhere on the API#

Location concepts also appear on resources that predate this surface:

  • location_id on devices, including filters and assignments on /v1/devices
  • location_id on inherited settings responses

Effective settings resolve through organization, then merchant, then location, then device. A device with no location_id skips the location step. Updating a device's location_id changes operational assignment, not merchant identity.

The Location object#

Every field on a location, as returned by retrieve and carried by the endpoints below.

Attributes

addressobject

Published postal address.

coordinateobject

Published geographic coordinate.

coordinate_sourceenum or null

Source of the stored latitude and longitude.

  • merchant_supplied
  • geocoded
  • null
created_atstringRequired

Time the Location was created.

external_reference_idstring

Caller-owned identifier for this resource in an external system.

geography_revisionintegerRequired

Optimistic-concurrency revision for geography writes.

inventoryobject

Inventory allocation capability at this Location.

location_idstringRequired

Stable Location ID.

metadatamap of stringRequired

Caller-owned metadata.

namestringRequired

Merchant-facing Location name.

normalized_addressobject

Provider-normalized address used for geography evaluation.

statusenumRequired

Current Location lifecycle status.

  • active
  • inactive
  • archived
timezonestringRequired

IANA timezone for local schedules.

updated_atstringRequired

Time the Location last changed.

validation_statusenumRequired

Address validation status.

  • not_validated
  • validated
  • merchant_verified
versionintegerRequired

Optimistic-concurrency version for general Location writes.

JSON
{
  "address": {
    "city": "Brooklyn",
    "country": "US",
    "line1": "120 Kent Avenue",
    "postal_code": "11249",
    "state": "NY"
  },
  "coordinate": {
    "latitude": 40.7213,
    "longitude": -73.9615
  },
  "coordinate_source": "merchant_supplied",
  "created_at": "2026-05-02T11:04:00Z",
  "geography_revision": 2,
  "inventory": {
    "allocation_status": "active",
    "created_at": "2026-05-02T11:04:00Z",
    "inventory_revision": 1,
    "updated_at": "2026-05-02T11:04:00Z"
  },
  "location_id": "loc_01K0P7W6A4N9F3J2T8Q5R1C6XM",
  "metadata": {
    "region": "northeast"
  },
  "name": "Brooklyn warehouse",
  "status": "active",
  "timezone": "America/New_York",
  "updated_at": "2026-07-14T09:12:00Z",
  "validation_status": "not_validated",
  "version": 4
}

List locations#

GET/v1/locations

Requires scope merchants.locations.read or merchants.locations.write

List Locations. Filtering by inventory_allocation_status requires commerce.inventory.read; the inventory block is omitted entirely when the caller lacks inventory read authority.

Query parameters

page_sizeinteger

Number of resources to return.

page_tokenstring

Stable cursor returned by the previous page.

statusenum

Filter by Location status. Defaults to active.

  • active
  • inactive
  • archived
inventory_allocation_statusenum

Filter by inventory allocation status. Requires commerce.inventory.read.

  • active
  • inactive
external_reference_idstring

Exact-match filter on the caller-owned external reference ID.

querystring

Search Location ID, external reference ID, or name.

Response · 200

dataarray of objectRequired
metaobject
next_page_tokenstring
request_idstring
curl https://api.withflintpay.com/v1/locations \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": [
    {
      "address": {
        "city": "Brooklyn",
        "country": "US",
        "line1": "120 Kent Avenue",
        "postal_code": "11249",
        "state": "NY"
      },
      "coordinate": {
        "latitude": 40.7213,
        "longitude": -73.9615
      },
      "coordinate_source": "merchant_supplied",
      "created_at": "2026-05-02T11:04:00Z",
      "geography_revision": 2,
      "inventory": {
        "allocation_status": "active",
        "created_at": "2026-05-02T11:04:00Z",
        "inventory_revision": 1,
        "updated_at": "2026-05-02T11:04:00Z"
      },
      "location_id": "loc_01K0P7W6A4N9F3J2T8Q5R1C6XM",
      "metadata": {
        "region": "northeast"
      },
      "name": "Brooklyn warehouse",
      "status": "active",
      "timezone": "America/New_York",
      "updated_at": "2026-07-14T09:12:00Z",
      "validation_status": "not_validated",
      "version": 4
    }
  ],
  "next_page_token": "",
  "request_id": "req_01K0P7W6A4N9F3J2T8Q5R1C6XM"
}

Create location#

POST/v1/locationsIdempotent

Requires scope merchants.locations.write

Create a Location. Including the inventory block also requires commerce.inventory_locations.write.

Request body

addressobjectRequired
coordinateobject
coordinate_sourceenum or null
  • merchant_supplied
  • geocoded
  • null
external_reference_idstring

Caller-owned identifier for this resource in an external system.

inventoryobject
metadatamap of string
namestringRequired
statusenum
  • active
  • inactive
timezonestringRequired

Response · 201

dataobjectRequired

A physical or logical place a merchant operates from. Locations own geography and, when inventory is enabled, an inventory capability block.

metaobject
request_idstring
curl -X POST https://api.withflintpay.com/v1/locations \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "address": {
      "city": "Brooklyn",
      "country": "US",
      "line1": "120 Kent Avenue",
      "postal_code": "11249",
      "state": "NY"
    },
    "inventory": {
      "allocation_status": "active"
    },
    "name": "Brooklyn warehouse",
    "status": "active",
    "timezone": "America/New_York"
  }'

Get location#

GET/v1/locations/{location_id}

Requires scope merchants.locations.read or merchants.locations.write

Get location.

Path parameters

location_idstringRequired

Flint Location ID.

Response · 200

Same response as Create location.

curl https://api.withflintpay.com/v1/locations/loc_01K1P6G4M7H2N8Q9R3S5T6V7WX \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": {
    "address": {
      "city": "Brooklyn",
      "country": "US",
      "line1": "120 Kent Avenue",
      "postal_code": "11249",
      "state": "NY"
    },
    "coordinate": {
      "latitude": 40.7213,
      "longitude": -73.9615
    },
    "coordinate_source": "merchant_supplied",
    "created_at": "2026-05-02T11:04:00Z",
    "geography_revision": 2,
    "inventory": {
      "allocation_status": "active",
      "created_at": "2026-05-02T11:04:00Z",
      "inventory_revision": 1,
      "updated_at": "2026-05-02T11:04:00Z"
    },
    "location_id": "loc_01K0P7W6A4N9F3J2T8Q5R1C6XM",
    "metadata": {
      "region": "northeast"
    },
    "name": "Brooklyn warehouse",
    "status": "active",
    "timezone": "America/New_York",
    "updated_at": "2026-07-14T09:12:00Z",
    "validation_status": "not_validated",
    "version": 4
  },
  "request_id": "req_01K0P7W6A4N9F3J2T8Q5R1C6XM"
}

Update location#

PATCH/v1/locations/{location_id}Idempotent

Requires scope merchants.locations.write

Update a Location's profile or availability. Accepts status active or inactive.

Path parameters

location_idstringRequired

Flint Location ID.

Request body

expected_versioninteger
external_reference_idstring or null

Caller-owned identifier for this resource in an external system.

metadatamap of string or null

Caller-owned metadata. Omit this field to leave metadata unchanged. Send an object to merge by key, set a key to null to remove it, or set metadata to null to clear all metadata. An empty object makes no change. Empty strings are stored. Keys starting with flint_ are reserved and cannot be written through the public API.

namestring
statusenum
  • active
  • inactive

Response · 200

Same response as Create location.

curl -X PATCH https://api.withflintpay.com/v1/locations/loc_01K1P6G4M7H2N8Q9R3S5T6V7WX \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "expected_version": 4,
    "name": "Brooklyn warehouse (Kent Ave)"
  }'

Retire location#

DELETE/v1/locations/{location_id}Idempotent

Requires scope merchants.locations.write

Retire a Location. Preserves the archived resource for direct reads.

Path parameters

location_idstringRequired

Flint Location ID.

Query parameters

expected_versioninteger

Current resource version used as a concurrency fence.

Response · 200

Same response as Create location.

curl -X DELETE https://api.withflintpay.com/v1/locations/loc_01K1P6G4M7H2N8Q9R3S5T6V7WX \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

Publish location geography#

PATCH/v1/locations/{location_id}/geographyIdempotent

Requires scope merchants.locations.write

Publishes the location geography atomically. Supply the complete address and timezone; omitted coordinates are cleared. This PATCH does not merge nested address fields. Requires expected_geography_revision, independently of the location version used for metadata edits.

Path parameters

location_idstringRequired

Flint Location ID.

Request body

addressobjectRequired
coordinateobject
coordinate_sourceenum or null
  • merchant_supplied
  • geocoded
  • null
expected_geography_revisionintegerRequired
timezonestringRequired

Response · 200

Same response as Create location.

curl -X PATCH https://api.withflintpay.com/v1/locations/loc_01K1P6G4M7H2N8Q9R3S5T6V7WX/geography \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "address": {
      "city": "Brooklyn",
      "country": "US",
      "line1": "120 Kent Avenue",
      "line2": "Suite 300",
      "postal_code": "11249",
      "state": "NY"
    },
    "coordinate": {
      "latitude": 40.7213,
      "longitude": -73.9615
    },
    "coordinate_source": "merchant",
    "expected_geography_revision": 2,
    "timezone": "America/New_York"
  }'

Update location inventory#

PATCH/v1/locations/{location_id}/inventoryIdempotent

Requires scope commerce.inventory_locations.write

Enable or disable inventory allocation at a Location. Omit expected_inventory_revision when enabling inventory for the first time; otherwise send the current inventory_revision.

Path parameters

location_idstringRequired

Flint Location ID.

Request body

allocation_statusenumRequired
  • active
  • inactive
expected_inventory_revisioninteger

Response · 200

dataobjectRequired

The inventory capability on a Location. Present only when the caller holds commerce.inventory.read.

metaobject
request_idstring
curl -X PATCH https://api.withflintpay.com/v1/locations/loc_01K1P6G4M7H2N8Q9R3S5T6V7WX/inventory \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "allocation_status": "inactive",
    "expected_inventory_revision": 2
  }'

Was this helpful?