Location

A Location of the store where physical goods reside.

Scopes

Property	Explanation
read_locations	Required for all GET resources.
write_locations	Required for all POST/PUT/DELETE resources.

Properties

Property	Explanation	Required
id	The unique numeric identifier for the Location	read-only
name	Localized Location Name	Yes
address	The Address of the Location	Yes
is_default	"true" if it is the default Location, "false" otherwise	No
allows_pickup	"true" if this Location allows pickup, "false" otherwise	No
priority	Priority of the location to assign stock during checkout. The lower the value the higher the priority	No
created_at	Date when the Location was created in ISO 8601 format	read-only
updated_at	Date when the Location was last updated in ISO 8601 format	read-only

Address Properties

Property	Explanation	Required
zipcode	The address zipcode.	Yes
street	The address street.	Yes
number	The address number.	No
floor	The address floor. Brazil complement.	No
locality	The address locality. Brazil neighborhood.	No
city	The address city name.	Yes
reference	The address reference.	No
between_streets	The address bwtween streets reference.	No
province	The address Province.	Yes
region	The address Region.	Yes
country	The address Country.	Yes
verified_at	Date when the Location Address was verified in ISO 8601 format	No

Address Province Properties

Property	Explanation
name	The address province name.
code	The address province code.

Address Region Properties

Property	Explanation
name	The address region name.
code	The address region code.

Address Country Properties

Property	Explanation
name	The address country name.
code	The address country code.

Endpoints

GET /locations

Receive a list of all Locations.

GET /locations

HTTP/1.1 200 OK

[
    {
      "id": "01HTMFDH09VC6E2Q8KGTGP44D3",
      "name": {
        "es_AR": "Nombre en espanol",
        "pt_BR": "Nome em português",
        "en_US": "Name in english"
      },
      "store_id": "12345",
      "priority": 0,
      "address": {
        "zipcode": "12910802",
        "street": "St Louis",
        "number": "01",
        "floor": "Floor",
        "locality": "Locality",
        "city": "São Paulo",
        "province": {
          "code": "SP",
          "name": "São Paulo"
        },
        "region": {
          "code": "SE",
          "name": "São Paulo"
        },
        "country": {
          "code": "BR",
          "name": "São Paulo"
        },
        "reference": "tiendanube's close",
        "between_streets": "St Mark Third",
        "verified_at": "1997-07-16T19:20:30+01:00"
      },
      "is_default": true,
      "created_at": "1997-07-16T19:20:30+01:00",
      "updated_at": "1997-07-16T19:20:30+01:00"
    },
    {
      "id": "01HTMFFHWXRC8TRS40M43XGQFB",
      "name": {
        "es_AR": "Nombre en espanol",
        "pt_BR": "Nome em português",
        "en_US": "Name in english"
      },
      "store_id": "12345",
      "priority": 1,
      "address": {
        "zipcode": "12910802",
        "street": "St Louis",
        "number": "01",
        "floor": "Floor",
        "locality": "Locality",
        "city": "São Paulo",
        "province": {
          "code": "SP",
          "name": "São Paulo"
        },
        "region": {
          "code": "SE",
          "name": "São Paulo"
        },
        "country": {
          "code": "BR",
          "name": "São Paulo"
        },
        "reference": "tiendanube's close",
        "between_streets": "St Mark Third",
        "verified_at": "1997-07-17T19:20:30+01:00"
      },
      "is_default": true,
      "created_at": "1997-07-17T19:20:30+01:00",
      "updated_at": "1997-07-17T19:20:30+01:00"
    }
]

GET /locations/{id}

Receive a single Location

GET /locations/01HTMFDH09VC6E2Q8KGTGP44D3

HTTP/1.1 200 OK

{
   "id": "01HTMFDH09VC6E2Q8KGTGP44D3",
   "name": {
        "es_AR": "Nombre en espanol",
        "pt_BR": "Nome em português",
        "en_US": "Name in english"
   },
   "store_id": "12345",
   "priority": 0,
   "address": {
      "zipcode": "12910802",
      "street": "St Louis",
      "number": "01",
      "floor": "Floor",
      "locality": "Locality",
      "city": "São Paulo",
      "province": {
         "code": "SP",
         "name": "São Paulo"
      },
      "region": {
         "code": "SE",
         "name": "São Paulo"
      },
      "country": {
         "code": "BR",
         "name": "São Paulo"
      },
      "reference": "tiendanube's close",
      "between_streets": "St Mark Third",
      "verified_at": "1997-07-16T19:20:30+01:00"
   },
   "is_default": true,
   "created_at": "1997-07-16T19:20:30+01:00",
   "updated_at": "1997-07-16T19:20:30+01:00"
}

POST /locations

Create a new Location

POST /locations

{
  "name": {
    "es_AR": "Nombre en espanol",
    "pt_BR": "Nome em português",
    "en_US": "Name in english"
  },
  "address": {
    "zipcode": "12910802",
    "street": "Some place",
    "number": "12",
    "floor": "AP1",
    "locality": "Locality",
    "reference": "REF12",
    "between_streets": "Some place between",
    "city": "São Paulo",
    "province": {
      "code": "SP",
      "name": "São Paulo"
    },
    "region": {
      "code": "SE",
      "name": "Sudeste"
    },
    "country": {
      "code": "BR",
      "name": "Brazil"
    }
  }
}

HTTP/1.1 201 Created

{
   "id": "01HTMFDH09VC6E2Q8KGTGP44D3",
   "name": {
     "es_AR": "Nombre en espanol",
     "pt_BR": "Nome em português",
     "en_US": "Name in english"
   },
   "store_id": "12345",
   "priority": 0,
   "address": {
      "zipcode": "12910802",
      "street": "12910802",
      "number": "Some place",
      "floor": "AP1",
      "locality": "Locality",
      "city": "São Paulo",
      "province": {
         "code": "SP",
         "name": "São Paulo"
      },
      "region": {
         "code": "SE",
         "name": "Sudeste"
      },
      "country": {
         "code": "BR",
         "name": "Brazil"
      },
      "reference": "REF12",
      "between_streets": "Some place between",
      "verified_at": "1997-07-16T19:20:30+01:00"
   },
   "is_default": true,
   "created_at": "1997-07-16T19:20:30+01:00",
   "updated_at": "1997-07-16T19:20:30+01:00"
}

PATCH /locations/priorities

Change priorities of all existing locations from store. On change priority the Location with priority 0 will be updated as default.

PATCH /locations/priorities

[
  {
    "id": "01HSY0PDQCTWCEKH6Y23W0P2VR",
    "priority": 0
  },
  {
    "id": "01HSY0MVKDRAXEZ45B91EGVEJX",
    "priority": 2
  },
  {
    "id": "01HSY0PNSV30VZ9F35VCDE0C52",
    "priority": 1
  }
]

HTTP/1.1 200 Ok

[
  {
    "id": "01HSY0PDQCTWCEKH6Y23W0P2VR",
    "priority": 0
  },
  {
    "id": "01HSY0MVKDRAXEZ45B91EGVEJX",
    "priority": 2
  },
  {
    "id": "01HSY0PNSV30VZ9F35VCDE0C52",
    "priority": 1
  }
]

PUT /locations/{id}

Modify an existing Location

PUT /locations/01HTMFDH09VC6E2Q8KGTGP44D3

{
  "name": {
    "es_AR": "Nombre en espanol",
    "pt_BR": "Nome em português",
    "en_US": "Name in english"
  },
  "address": {
    "zipcode": "12910802",
    "street": "Some place",
    "number": "12",
    "floor": "AP1",
    "locality": "Locality",
    "reference": "REF12",
    "between_streets": "Some place between",
    "city": "São Paulo",
    "province": {
      "code": "SP",
      "name": "São Paulo"
    },
    "region": {
      "code": "SE",
      "name": "Sudeste"
    },
    "country": {
      "code": "BR",
      "name": "Brazil"
    }
  }
}

HTTP/1.1 200 Ok

{
   "id": "01HTMFDH09VC6E2Q8KGTGP44D3",
   "name": {
    "es_AR": "Nombre en espanol",
    "pt_BR": "Nome em português",
    "en_US": "Name in english"
   },
   "store_id": "12345",
   "priority": 0,
   "address": {
      "zipcode": "12910802",
      "street": "12910802",
      "number": "Some place",
      "floor": "AP1",
      "locality": "Locality",
      "city": "São Paulo",
      "province": {
         "code": "SP",
         "name": "São Paulo"
      },
      "region": {
         "code": "SE",
         "name": "Sudeste"
      },
      "country": {
         "code": "BR",
         "name": "Brazil"
      },
      "reference": "REF12",
      "between_streets": "Some place between",
      "verified_at": "1997-07-16T19:20:30+01:00"
   },
   "is_default": true,
   "created_at": "1997-07-16T19:20:30+01:00",
   "updated_at": "1997-07-16T19:20:30+01:00"
}

DELETE /locations/{id}

Delete an existing Location, and repreorize remains locations. For the deletion to be successful the Location should not have any inventory levels assigned and Locantion can`t be default.

DELETE /locations/01HTMFDH09VC6E2Q8KGTGP44D3

HTTP/1.1 204 No Content

PATCH /locations/{id}/chosen-as-default

Change an existing Location to default and priority 0, and repreorize other locations. For the change to be successfull the Location should have priority greatter than 0.

PATCH /locations/01HSY0MVKDRAXEZ45B91EGVEJX/chosen-as-default

HTTP/1.1 200 Ok

{
   "id": "01HSY0MVKDRAXEZ45B91EGVEJX",
   "name": {
    "es_AR": "Nombre en espanol",
    "pt_BR": "Nome em português",
    "en_US": "Name in english"
   },
   "store_id": "12345",
   "priority": 0,
   "address": {
      "zipcode": "12910802",
      "street": "12910802",
      "number": "Some place",
      "floor": "AP1",
      "locality": "Locality",
      "city": "São Paulo",
      "province": {
         "code": "SP",
         "name": "São Paulo"
      },
      "region": {
         "code": "SE",
         "name": "Sudeste"
      },
      "country": {
         "code": "BR",
         "name": "Brazil"
      },
      "reference": "REF12",
      "between_streets": "Some place between",
      "verified_at": "1997-07-16T19:20:30+01:00"
   },
   "is_default": true,
   "created_at": "1997-07-16T19:20:30+01:00",
   "updated_at": "1997-07-16T19:20:30+01:00"
}

GET /locations/{id}/inventory-levels

Receive the inventory levels assigned to a particular Location.

Parameter	Explanation
variant_id	Filter only the inventory level of this Product Variant
page	Page to show (optional, default: 1)
per_page	Amount of results (optional, default: 1)

GET /locations/01HTMFDH09VC6E2Q8KGTGP44D3/inventory-levels?page=1&per_page=10

HTTP/1.1 200 OK

{
  "total": 4,
  "page": 1,
  "per_page": 10,
  "results": [
    {
        "id": "1",
        "variant_id": "101",
        "location_id": "01HTMFDH09VC6E2Q8KGTGP44D3",
        "stock": 1,
        "created_at": "2022-09-19T10:46:32+0000",
        "updated_at": "2022-09-19T10:46:32+0000"
    },
    {
        "id": "2",
        "variant_id": "102",
        "location_id": "01HTMFDH09VC6E2Q8KGTGP44D3",
        "stock": 1,
        "created_at": "2022-09-19T10:46:32+0000",
        "updated_at": "2022-09-19T10:46:32+0000"
    },
    {
        "id": "3",
        "variant_id": "103",
        "location_id": "01HTMFDH09VC6E2Q8KGTGP44D3",
        "stock": 1,
        "created_at": "2022-09-19T10:46:32+0000",
        "updated_at": "2022-09-19T10:46:32+0000"
    },
    {
        "id": "4",
        "variant_id": "104",
        "location_id": "01HTMFDH09VC6E2Q8KGTGP44D3",
        "stock": 1,
        "created_at": "2022-09-19T10:46:32+0000",
        "updated_at": "2022-09-19T10:46:32+0000"
    }
  ]
}

GET /locations/01HTMFDH09VC6E2Q8KGTGP44D3/inventory-levels?page=1&per_page=10&variant_id=101

HTTP/1.1 200 OK

{
  "total": 4,
  "page": 1,
  "per_page": 10,
  "results": [
    {
        "id": "1",
        "variant_id": "101",
        "location_id": "01HTMFDH09VC6E2Q8KGTGP44D3",
        "stock": 1,
        "created_at": "2022-09-19T10:46:32+0000",
        "updated_at": "2022-09-19T10:46:32+0000"
    }
  ]
}

Scopes​

Properties​

Address Properties​

Address Province Properties​

Address Region Properties​

Address Country Properties​

Endpoints​

GET /locations​

GET /locations​

GET /locations/{id}​

GET /locations/01HTMFDH09VC6E2Q8KGTGP44D3​

POST /locations​

POST /locations​

PATCH /locations/priorities​

PATCH /locations/priorities​

PUT /locations/{id}​

PUT /locations/01HTMFDH09VC6E2Q8KGTGP44D3​

DELETE /locations/{id}​

DELETE /locations/01HTMFDH09VC6E2Q8KGTGP44D3​

PATCH /locations/{id}/chosen-as-default​

PATCH /locations/01HSY0MVKDRAXEZ45B91EGVEJX/chosen-as-default​

GET /locations/{id}/inventory-levels​

GET /locations/01HTMFDH09VC6E2Q8KGTGP44D3/inventory-levels?page=1&per_page=10​

GET /locations/01HTMFDH09VC6E2Q8KGTGP44D3/inventory-levels?page=1&per_page=10&variant_id=101​

Scopes

Properties

Address Properties

Address Province Properties

Address Region Properties

Address Country Properties

Endpoints

GET /locations

GET /locations

GET /locations/{id}

GET /locations/01HTMFDH09VC6E2Q8KGTGP44D3

POST /locations

POST /locations

PATCH /locations/priorities

PATCH /locations/priorities

PUT /locations/{id}

PUT /locations/01HTMFDH09VC6E2Q8KGTGP44D3

DELETE /locations/{id}

DELETE /locations/01HTMFDH09VC6E2Q8KGTGP44D3

PATCH /locations/{id}/chosen-as-default

PATCH /locations/01HSY0MVKDRAXEZ45B91EGVEJX/chosen-as-default

GET /locations/{id}/inventory-levels

GET /locations/01HTMFDH09VC6E2Q8KGTGP44D3/inventory-levels?page=1&per_page=10

GET /locations/01HTMFDH09VC6E2Q8KGTGP44D3/inventory-levels?page=1&per_page=10&variant_id=101