DIdistru
Location

Get locations

Changed on

Returns the paginated list of locations belonging to your company, oldest first (ascending creation date). A location is a physical or logical place that holds inventory and appears throughout the rest of the API: it is where a purchase receives inventory, where an order ships from, and where stock and packages are held. Each location optionally links to a compliance license; that link (license / license_id) is null for locations with no compliance license. When the linked license is a Metrc license, metrc_id is the identifier of the corresponding Metrc room; it is null for locations not synced to Metrc, and it is a raw Metrc integer id, not a Distru id.

By default only non-deleted locations are returned; use deleted to include or isolate soft-deleted locations. Filter the result set by name (case-insensitive substring), license_number (exact match on the linked license), creation window (inserted_datetime), and last-modified window (updated_datetime); when several are supplied a location must satisfy all of them to be returned (AND). Results are scoped to your own company; you never see another tenant's locations.

Results are paginated: read the top-level next_page URL to fetch the following page, and stop when it is null. Page size is fixed by the server and is not client-controllable.

This endpoint returns eventually consistent data, with changes taking up to 1 second to propagate in responses.

Required permission: companies_permissions_view.

get/public/v1/locations

Request

  • Base URL
    https://app.distru.com
  • Auth
    HTTP bearer

Query parameters

idsstring[]

Restrict the result to specific locations by ID (the same ID returned as each location's id). Repeat the bracketed key once per ID. Unknown IDs simply match nothing; an empty list is treated as no filter. At most 200 IDs may be given.

inserted_datetimestring

Filter by creation datetime. Accepts a comma-separated from,to range in ISO-8601 UTC; both bounds are inclusive and either side may be omitted. 2022-07-10T00:00:00Z, returns locations created on or after that time; ,2022-07-10T00:00:00Z returns those created on or before it; 2022-07-01T00:00:00Z,2022-07-31T00:00:00Z returns those in the window. Omit the param to apply no creation-date filter. Combines with updated_datetime via AND — a location must fall in both windows to be returned.

deleted'no' | 'include' | 'only'

Controls whether soft-deleted locations are returned. no (the default when omitted) returns only non-deleted locations, only returns only soft-deleted ones, include returns both. A soft-deleted location has a non-null deleted_at in the response.

license_numberstring

Filter by the exact license_number of the location's linked compliance license (as returned under license.license_number). Case-sensitive exact match; locations with no linked license never match. Send a single value, not a list.

namestring

Case-insensitive substring match on the location name (partial matches count; e.g. main matches Main Warehouse). Send a single value, not a list.

pagestring

Page selector. Page size is fixed by the server; paginate by following the next_page URL in each response rather than building page selectors yourself — it is null on the last page. next_page uses page[after]=<cursor>, an opaque token marking where the next page resumes; pass it back exactly as given, and only to the endpoint that issued it. This is seek-based, so every page stays fast no matter how deep you page.

updated_datetimestring

Filter by last-modified datetime. Accepts a comma-separated from,to range in ISO-8601 UTC; both bounds are inclusive and either side may be omitted. ,2022-07-10T00:00:00Z returns locations last modified on or before that time; 2022-07-10T00:00:00Z, returns those modified on or after it. Omit the param to apply no last-modified filter.

Response

A list of locations

next_pagestring

URL for the next page of results; null when there is no next page

Example response

{
  "data": [
    {
      "address": "1234 Warehouse Street, Oakland, CA",
      "company_id": "02c88a3f-d759-4973-88f9-60049d682524",
      "id": "02c88a3f-d759-4973-88f9-60049d682524",
      "license": {
        "id": "02c88a3f-d759-4973-88f9-60049d682524",
        "license_number": "C11-1234567890"
      },
      "license_id": "02c88a3f-d759-4973-88f9-60049d682524",
      "name": "Warehouse 1"
    }
  ]
}

Changes