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, each with its own revision and its own write route:

Identity (name, metadata, status), updated with PATCH /v1/locations/{location_id} and guarded by expected_location_revision.
Geography (address, timezone, coordinate), published with PUT /v1/locations/{location_id}/geography and guarded by expected_geography_revision.
Inventory capability, replaced with PUT /v1/locations/{location_id}/inventory and guarded by expected_inventory_revision.

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".

Send expected_inventory_revision: null to create the block, or the current revision to replace it. The block is bounded on purpose: this route cannot change Location lifecycle or geography.

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.
Writing the inventory block requires commerce.inventory_locations.write. This is deliberately narrower than merchants.locations.write, so an operations credential can fence a Location for inventory without gaining authority over Location lifecycle.

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
Location-scoped settings policies through /v1/settings/policies

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.

Endpoints

GET/v1/locations
POST/v1/locations
GET/v1/locations/{location_id}
PATCH/v1/locations/{location_id}
POST/v1/locations/{location_id}/activate
POST/v1/locations/{location_id}/archive
POST/v1/locations/{location_id}/deactivate
PUT/v1/locations/{location_id}/geography
PUT/v1/locations/{location_id}/inventory

List locations #

GET/v1/locationsRequires 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.

activeinactivearchived

inventory_allocation_statusenum

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

activeinactive

Response · 200

dataarray of objectrequired

metaobject

next_page_tokenstring

request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDED

Bash

curl https://api.withflintpay.com/v1/locations \
  -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",
      "location_revision": 4,
      "metadata": {
        "region": "northeast"
      },
      "name": "Brooklyn warehouse",
      "status": "active",
      "timezone": "America/New_York",
      "updated_at": "2026-07-14T09:12:00Z",
      "validation_status": "not_validated"
    }
  ],
  "next_page_token": "",
  "request_id": "req_01K0P7W6A4N9F3J2T8Q5R1C6XM"
}

Create location #

POST/v1/locationsIdempotentRequires scope: merchants.locations.write

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

Request body

addressobjectrequired

coordinateobject

coordinate_sourceenum

merchant_suppliedgeocoded

inventoryobject

metadatamap of string

namestringrequired

statusenumrequired

activeinactive

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

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND

Bash

curl -X POST https://api.withflintpay.com/v1/locations \
  -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"
  }'

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",
    "location_revision": 4,
    "metadata": {
      "region": "northeast"
    },
    "name": "Brooklyn warehouse",
    "status": "active",
    "timezone": "America/New_York",
    "updated_at": "2026-07-14T09:12:00Z",
    "validation_status": "not_validated"
  },
  "request_id": "req_01K0P7W6A4N9F3J2T8Q5R1C6XM"
}

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

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

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND

Bash

curl https://api.withflintpay.com/v1/locations/loc_01K1P6G4M7H2N8Q9R3S5T6V7WX \
  -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",
    "location_revision": 4,
    "metadata": {
      "region": "northeast"
    },
    "name": "Brooklyn warehouse",
    "status": "active",
    "timezone": "America/New_York",
    "updated_at": "2026-07-14T09:12:00Z",
    "validation_status": "not_validated"
  },
  "request_id": "req_01K0P7W6A4N9F3J2T8Q5R1C6XM"
}

Update location #

PATCH/v1/locations/{location_id}IdempotentRequires scope: merchants.locations.write

Update Location name or metadata. Requires expected_location_revision and cannot change geography or lifecycle.

Path parameters

location_idstringrequired

Flint Location ID.

Request body

expected_location_revisionintegerrequired

metadataarray of integer

namestring

Response · 200

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

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND

Bash

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

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",
    "location_revision": 4,
    "metadata": {
      "region": "northeast"
    },
    "name": "Brooklyn warehouse",
    "status": "active",
    "timezone": "America/New_York",
    "updated_at": "2026-07-14T09:12:00Z",
    "validation_status": "not_validated"
  },
  "request_id": "req_01K0P7W6A4N9F3J2T8Q5R1C6XM"
}

Activate location #

POST/v1/locations/{location_id}/activateIdempotentRequires scope: merchants.locations.write

Activate location.

Path parameters

location_idstringrequired

Flint Location ID.

Request body

expected_location_revisionintegerrequired

Response · 200

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

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND

Bash

curl -X POST https://api.withflintpay.com/v1/locations/loc_01K1P6G4M7H2N8Q9R3S5T6V7WX/activate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "expected_location_revision": 4
  }'

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",
    "location_revision": 4,
    "metadata": {
      "region": "northeast"
    },
    "name": "Brooklyn warehouse",
    "status": "active",
    "timezone": "America/New_York",
    "updated_at": "2026-07-14T09:12:00Z",
    "validation_status": "not_validated"
  },
  "request_id": "req_01K0P7W6A4N9F3J2T8Q5R1C6XM"
}

Archive location #

POST/v1/locations/{location_id}/archiveIdempotentRequires scope: merchants.locations.write

Archive location.

Path parameters

location_idstringrequired

Flint Location ID.

Request body

expected_location_revisionintegerrequired

Response · 200

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

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND

Bash

curl -X POST https://api.withflintpay.com/v1/locations/loc_01K1P6G4M7H2N8Q9R3S5T6V7WX/archive \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "expected_location_revision": 4
  }'

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",
    "location_revision": 4,
    "metadata": {
      "region": "northeast"
    },
    "name": "Brooklyn warehouse",
    "status": "active",
    "timezone": "America/New_York",
    "updated_at": "2026-07-14T09:12:00Z",
    "validation_status": "not_validated"
  },
  "request_id": "req_01K0P7W6A4N9F3J2T8Q5R1C6XM"
}

Deactivate location #

POST/v1/locations/{location_id}/deactivateIdempotentRequires scope: merchants.locations.write

Deactivate location.

Path parameters

location_idstringrequired

Flint Location ID.

Request body

expected_location_revisionintegerrequired

Response · 200

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

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND

Bash

curl -X POST https://api.withflintpay.com/v1/locations/loc_01K1P6G4M7H2N8Q9R3S5T6V7WX/deactivate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "expected_location_revision": 4
  }'

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",
    "location_revision": 4,
    "metadata": {
      "region": "northeast"
    },
    "name": "Brooklyn warehouse",
    "status": "active",
    "timezone": "America/New_York",
    "updated_at": "2026-07-14T09:12:00Z",
    "validation_status": "not_validated"
  },
  "request_id": "req_01K0P7W6A4N9F3J2T8Q5R1C6XM"
}

Publish location geography #

PUT/v1/locations/{location_id}/geographyIdempotentRequires scope: merchants.locations.write

Publish the Location address, timezone, and coordinate. Requires expected_geography_revision, so metadata edits and address publications cannot invalidate each other.

Path parameters

location_idstringrequired

Flint Location ID.

Request body

addressobjectrequired

coordinateobject

coordinate_sourceenum

merchant_suppliedgeocoded

expected_geography_revisionintegerrequired

timezonestringrequired

Response · 200

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

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND

Bash

curl -X PUT https://api.withflintpay.com/v1/locations/loc_01K1P6G4M7H2N8Q9R3S5T6V7WX/geography \
  -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"
  }'

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",
    "location_revision": 4,
    "metadata": {
      "region": "northeast"
    },
    "name": "Brooklyn warehouse",
    "status": "active",
    "timezone": "America/New_York",
    "updated_at": "2026-07-14T09:12:00Z",
    "validation_status": "not_validated"
  },
  "request_id": "req_01K0P7W6A4N9F3J2T8Q5R1C6XM"
}

Replace location inventory capability #

PUT/v1/locations/{location_id}/inventoryIdempotentRequires scope: commerce.inventory_locations.write

Replace the Location inventory capability. Send expected_inventory_revision: null to create the block, or the current revision to replace it.

Path parameters

location_idstringrequired

Flint Location ID.

Request body

allocation_statusenumrequired

activeinactive

expected_inventory_revisioninteger

Response · 200

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

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND

Bash

curl -X PUT https://api.withflintpay.com/v1/locations/loc_01K1P6G4M7H2N8Q9R3S5T6V7WX/inventory \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "allocation_status": "active",
    "expected_inventory_revision": null
  }'

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",
    "location_revision": 4,
    "metadata": {
      "region": "northeast"
    },
    "name": "Brooklyn warehouse",
    "status": "active",
    "timezone": "America/New_York",
    "updated_at": "2026-07-14T09:12:00Z",
    "validation_status": "not_validated"
  },
  "request_id": "req_01K0P7W6A4N9F3J2T8Q5R1C6XM"
}

Rate this doc