Skip to main content

Warehouses and bin locations

Use warehouse and bin-location operations when a merchant integration needs to mirror the warehouse structure or maintain storage-location codes.

Available operations​

Example: list warehouses​

query Warehouses($cursor: String) {
  warehouses(first: 50, after: $cursor) {
    edges {
      node {
        id
        code
        name
        status
        isStockAvailableForSale
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Warehouses are returned by name. code is unique across the shop, so it is the natural key when you mirror warehouses into another system. A warehouse with status: Decommissioning is being phased out: its stock can still leave it, but orders can no longer be shipped from it. Stock in a warehouse whose isStockAvailableForSale is false counts as unavailable stock, not as available stock.

Example: list the bin locations of a warehouse​

query BinLocations($warehouseId: ID!, $cursor: String) {
  binLocations(first: 200, after: $cursor, filter: { warehouseId: { equals: $warehouseId } }) {
    edges {
      node {
        id
        code
        position
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Bin locations are returned by code. Follow endCursor until hasNextPage is false; a warehouse often has thousands of bin locations.

Example: create a warehouse​

mutation CreateWarehouse($input: CreateWarehouseInput!) {
  createWarehouse(input: $input) {
    id
    code
    name
    status
    isStockAvailableForSale
  }
}
{
  "input": {
    "name": "Returns warehouse",
    "code": "RET",
    "isStockAvailableForSale": false
  }
}

code must not be used by another warehouse yet. Omitted fields get defaults: the stock of the new warehouse is available for sale, its status is Active, and it belongs to the shop's default location unless you pass a warehouseLocationId.

Example: create or update a bin location​

mutation UpsertBinLocation($input: UpsertBinLocationInput!) {
  upsertBinLocation(input: $input) {
    id
    code
    position
  }
}
{
  "input": {
    "warehouseId": "V2FyZWhvdXNlOjAx...",
    "code": "A-01-03",
    "position": 120
  }
}

upsertBinLocation matches on the warehouse and code. When the warehouse has no bin location with that code, it creates one; otherwise it only changes the existing bin location's position, so the call is safe to repeat. Omit position to leave an existing position unchanged; a position you pass must be 1 or more. The code itself cannot be changed through the API.

Deleting warehouses and bin locations​

deleteBinLocation fails while the bin location still has a stock row. That includes every bin location that is the default bin location of a product, which keeps a row with quantity 0 even when it is empty. Move the stock away with transferStock and clear the default with setProductDefaultBinLocation first.

deleteWarehouse fails while the warehouse holds stock: on a bin location, on its unknown bin location, or in a stock container in it. Two kinds of stock on its bin locations and its unknown bin location do not block the deletion, because the mutation books them out of the warehouse before deleting it: negative stock, and stock of products whose stock is not managed. Deleting a warehouse also deletes its bin locations and the product settings that belong to it, such as reorder points and default bin locations.

Read the stock of the warehouse with stocks before you clean up the warehouse structure.