1. Inventory
  2. Items

Inventory

Items

Before you create items, you'll want to set up locations and layouts in your dashboard so that you'll be able to add inventory levels for the item.

Your inventory for items is tracked in a property called levels, which will give you information about the location and optionally the layout the item is in.

Create Item

POST
`/v1/items`

The only property you need to create an item is name, by which this item will be searchable. However, we recommend adding a few more properties:

name string (required)
The name of the item
sku or gtin string
One of these is most likely on the barcode of your items so it's best to include this so that barcode scanners play nicely.
packaged_length float
If you're planning to do fulfillments, this property will be required, so it is easier to add it on the item
packaged_width float
If you're planning to do fulfillments, this property will be required, so it is easier to add it on the item
packaged_height float
If you're planning to do fulfillments, this property will be required, so it is easier to add it on the item
packaged_weight float
If you're planning to do fulfillments, this property will be required, so it is easier to add it on the item

Example

js
        const item = {
  name: "My item name",
  sku: "123345",
  gtin: "987654", //can have both, why not?
  packaged_length: 5, //inches
  packaged_width: 6,
  packaged_height: 7,
  packaged_weight: 8, //lbs
};

fetch("https://api.packagex.io/v1/items", {
  method: "POST",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(data),
});

      

Update Item

POST
`/v1/items/:item`

You can update an item by using its ID.

When updating inventory, you increment and decrement quantities by passing in positive and negative integers.

You can reset a value by passing the integer inside of an array as shown in the example below. It's not recommended to reset values, since incrementing and decrementing will get you the same result, but this is an escape hatch if you need it and thus the ergonomics of an array prevent accidental usage of an otherwise potentially dangerous feature.

Lastly, you can optionally provide a layout value to be more specific about the item's exact whereabouts in that location. If the item already has a layout associated with it, it will keep adding to that layout unless you explicitly tell it not to. The best rule of thumb is either use layouts for everything, or don't use them at all.

Example

js
        const update = {
  name: "Updated Name",
  levels: [
    {
      location_id: "loc_8GiCVuqZqBJi43v2WebaME",
      verified_qty: 30,
    },
    {
      location_id: "loc_dKa43ncARLdGENQPUq2CoX",
      verified_qty: -50,
    },
    {
      location_id: "loc_v4BPffa3m2zJdhCLE8SL4C",
      layout_id: "lay_27ee779f2c9747228e1b62929522bb83",
      verified_qty: [100], //Value is being reset to 100
    },
  ],
};

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

const item = response.data;

      

Retrieve Item

GET
`/v1/items/:item`

Get a single item using its id.

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

const item = response.data;

      

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.

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

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.

js
        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

  • location_id - Add the ID of one of your locations to get all of the deliveries currently mapped to that location. For example: location_id=loc_czhgjrk5JaVvyATPDbyURp
js
        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;

      

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.

js
        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;

      

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.

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.

js
        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];

      

Delete Item

DELETE
`/v1/items/:item`

You can delete an item by using its ID. All information about the item will be lost. Any shipments, manifests, or fulfillments that are completed will not be impacted, but the reference to that item ID will be broken.

Example

js
        const response = await fetch(`https://api.packagex.io/v1/items/${item.id}`, {
  method: "DELETE",
  headers: {
    "PX-API-KEY": process.env.PX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(body),
}).then((res) => res.json());

const item = response.data; //will be empty object {}