Items:

Items

List Items

Example

GET

`/v1/items`

When you want to retrieve multiple items, your data property on the result will always be an array even if you don't have any items.

        const response = await fetch("https://api.packagex.io/v1/items", {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
}).then((res) => res.json());

const items = response.data; //the array of items
const pagination = response.pagination; //the pagination object

Pagination

If the has_more property on the pagination object is set to true, you know there are more items in the database that have not been returned to you. The pagination object also has a page property indicating your current offset and a limit property. The total_count property in pagination returns the the total number of items in the database.

By default the page is set to 1 and the limit is 25.

If we want to query for items 26 - 50, we would request page 2 with a query parameter.

        const response = await fetch("https://api.packagex.io/v1/items?page=2&limit=25", {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
}).then((res) => res.json());

const items = response.data; //the array of items 25 - 50
const pagination = response.pagination; //the pagination object

Filter

You can filter items by location_id, layout_id, layout_path, sku, upc, harmonized_code, and external_id. The API also supports listing only the items that are marked as an asset, using the is_asset parameter. In addition, you can specify whether to include items that do not have inventory at the given location by passing include_zero_inventory=true

location_id - Add the ID of one of your locations to get all of the items currently mapped to that location. For example: location_id=loc_czhgjrk5JaVvyATPDbyURp

        const response = await fetch("https://api.packagex.io/v1/items?location_id=loc_hj7gjrk5JaVvyATPDbyURp&page=3", {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
}).then((res) => res.json());

const items = response.data;
const pagination = response.pagination;

layout_id - Add the ID of one of your layouts to get all of the items currently mapped to that location. For example:

        const response = await fetch("https://api.packagex.io/v1/items?layout_id=lay_hj7gjrk5JaVvyATPDbyURp", {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
}).then((res) => res.json());

const items = response.data;
const pagination = response.pagination;

layout_path - Add the path of one of your layouts to get all of the items currently mapped to that location. For example:

        const response = await fetch("https://api.packagex.io/v1/items?layout_path=default", {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
}).then((res) => res.json());

const items = response.data;
const pagination = response.pagination;

sku - Filter items by one or more comma separated SKU(s). For example:

        const response = await fetch("https://api.packagex.io/v1/items?sku=abc123,def456", {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
}).then((res) => res.json());

const items = response.data;
const pagination = response.pagination;

upc - Filter items by one or more comma separated UPC(s). For example:

        const response = await fetch("https://api.packagex.io/v1/items?upc=abc123,def456", {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
}).then((res) => res.json());

const items = response.data;
const pagination = response.pagination;

harmonized_code - Filter items by one or more comma separated harmonized code(s). For example:

        const response = await fetch("https://api.packagex.io/v1/items?harmonized_code=0101.21,0101.29", {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
}).then((res) => res.json());

const items = response.data;
const pagination = response.pagination;

external_id - Filter items by one or more comma separated external ids. For example:

        const response = await fetch("https://api.packagex.io/v1/items?external_id=item_123,item_abc", {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
}).then((res) => res.json());

const items = response.data;
const pagination = response.pagination;

is_asset - Filter items that have been marked as an asset

        const response = await fetch("https://api.packagex.io/v1/items?is_asset=true", {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
}).then((res) => res.json());

const items = response.data;
const pagination = response.pagination;

include_zero_inventory - Include items that have no inventory at the given location now, provided they previously had some inventory on the said location. Defaults to false.

        const response = await fetch("https://api.packagex.io/v1/items?location_id=loc_czhgjrk5JaVvyATPDbyURp&include_zero_inventory=true", {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
}).then((res) => res.json());

const items = response.data;
const pagination = response.pagination;

Sorting

Sorting describes in what order you want your responses to come in. You can select an available property by which to sort, as well as the direction.

order_by - The property by which to sort. Available properties are: created_at, name
direction - The direction to sort. Available directions are: asc and desc

By default, items will be sorted by in ascending order by name, meaning they are returned alphabetically.

        const response = await fetch("https://api.packagex.io/v1/items?order_by=name&direction=asc", {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
}).then((res) => res.json());

const items = response.data;
const pagination = response.pagination;

Search

There are times when filtering is not enough and you want to find a specific item by some other attribute, typically by name, SKU, or GTIN. In this case, you can do a fuzzy, typo-tolerant search of every item in the database. Below are the item properties that are supported by our full text search. The properties follow the same schema as the actual item model, just with a subset of properties.

Searchable Properties

name
sku
gtin
metadata._search

To search, simply provide a string to search by using the search query param. If you want to highlight matching search results for a frontend, we provide a special property for search-returned shipment objects called _search which will have the matched text surrounded with <mark> handles.

Ordering Search Results

By default, search results are ordered by relevance. However, if you include an order_by parameter along with your search query, the results will be ordered by the specified property instead of by relevance.

Relevance Score

Relevance scores are included in the search results by default. Note that this could add up to 10ms of extra time to the request.

        const response = await fetch("https://api.packagex.io/v1/items?search=coffee", {
  method: "GET",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
}).then((res) => res.json());

const item = response.data[0];

# List Items

# Example

# Pagination

# Filter

# Sorting