Manage Inventory Levels

To list and update SKU stock levels and inventory-related properties, you’ll use the /v2/inventory endpoint.

Operations with the /v2/inventory endpoint:

GET: List the inventory-related properties for all of your SKUs. Add query parameters to list specific SKUs or SKUs in a specific warehouse or location.
POST: Update stock levels and other inventory-related properties of your SKUs.

List Inventory Levels

Use this method to list the inventory-related properties for SKUs that use inventory in your ShipStation accounts. The response will include an inventory array of objects with the following properties:

Property	Type	Description
`sku`	string	The SKU value of the product.
`on_hand`	integer	The quantity of this SKU currently in the associated inventory warehouse and location.
`allocated`	integer	The quantity of this SKU already allocated to orders.
`available`	integer	The quantity of this SKU available to ship (`on_hand` minus `allocated`).
`average_cost`	object	The wholesale cost you’ve indicated for a single quantity of this SKU (not your retail price). Includes both `amount` and `currency` properties.
`inventory_warehouse_id`	string	The ID of the inventory warehouse the SKU is located in.
`inventory_location_id`	string	The ID of the inventory location the SKU is located in.

You can use the following query parameters to filter the response:

Query Parameters	Type	Description
`sku`	string	To return only the properties of a specific SKU.
`inventory_warehouse_id`	string	To return only the SKUs and related properties that exist in a specific inventory warehouse.
`inventory_location_id`	string	To return only the SKUs and related properties that exist in a specific inventory location.
`group_by`	enumerated string	Use this option to group the SKUs in the response by either `warehouse` or `location`
`limit`	integer	Limit the number of SKUs returned in the response.

Example Request & Response

GET /v2/inventory

curl -i -X GET \
  'https://api.shipstation.com/v2/inventory?group_by=warehouse&inventory_location_id=string&inventory_warehouse_id=string&limit=0&sku=string' \
  -H 'api-key: YOUR_API_KEY_HERE'

Response

application/json

{
  "inventory": [
    { … }
  ],
  "total": 0,
  "page": 0,
  "pages": 0,
  "links": {
    "first": { … },
    "last": { … },
    "prev": { … },
    "next": { … }
  }
}

Update Inventory Levels

You can use the POST method to update the inventory levels of a specific SKU, as well as several other inventory-related properties.

Request Body Properties

The following properties are required in the request body:

Property	Type	Description
`transaction_type`	enumerated string	`increment`: use this value to add the specified quantity to the on hand inventory count in the specified location `decrement`: use this value to subtract the specified quantity from the on hand inventory count in the specified location. `adjust`: use this value set the on hand inventory count in the specified location to the amount set in the `quantity` property. `modify`: use this value to update the `new_inventory_location_id` property to move inventory to a NEW location, the `new_cost` object to update the cost values of existing inventory, and `new_condition` property to change the condition of existing inventory. Other properties in the request body can be used as filter parameters. Additionally, you can update the non-”new” properties using the `increment`, `decrement`, and `adjust` values, if needed.
`inventory_location_id`	string	The unique ID for the inventory location the SKU is located in.
`sku`	string	The SKU of the product you wish to update.
`quantity`	integer	The amount by which you are updating the SKU stock level. How this affects the stock level will be determined by the `transaction_type` value (`increment`, `decrement` or `adjust`)

You can also include the following optional properties in the request body:

Property	Type	Description
`cost`	object	If used, this object must include both the `amount` (number) and `currency` (string) properties.
`condition`	enumerated string	Indicate the condition of the SKU: `sellable`, `damaged`, `expired`, `qa_hold`. This field is not currently in use by ShipStation. However, when this property is available, you can assign a value to the quantity you are updating. Any value other than `sellable` will be removed from the on hand inventory count.
`lot`	string	Indicate which lot this SKU belongs to. This field is not currently available in the ShipStation app, but is coming soon with our Lot Tracking feature.
`usable_start_date`	string (date-time)	This field is not currently used by ShipStation.
`usable_end_date`	string (date-time)	Indicate the date after which this SKU should no longer be shipped. This field is not currently available in the ShipStation app, but is coming soon with our Lot Tracking feature.
`effective_at`	string (date-time)	Indicates the date and time when the stock is ready to be shipped. When the date passes this timestamp, the stock will be included in On Hand counts and deducted when the SKU is included in shipments. This field is not currently available in the ShipStation app but is coming soon.
`reason`	string	Explain the reason for the stock level update. `reason` maps to the Description field in ShipStation’s stock history pop-up.
`notes`	string	Add any notes you want to associate with the update. `notes` maps to the Description field in ShipStation’s stock history pop-up.
`new_inventory_location_id`	string	If using the `modify` transaction type, use this property to indicate which inventory location you are moving the SKU stock to. This is equivalent to using the Move function for a SKUs inventory in the ShipStation product details inventory settings to change the inventory location of some or all of the SKUs inventory quantity.
`new_cost`	object	If using the `modify` transaction type, use this property to indicate the new cost of an existing SKU. If used, this object must include both the `amount` (number) and `currency` (string) properties.
`new_condition`	string	If using the `modify` transaction type, use this property to indicate the new condition value for an existing SKU. `sellable`: `damaged`: `expired`: `qa_hold`:

Example Request & Response

This example request adds 250 to the quantity of a single SKU and provides a reason for the update.

POST /v2/inventory

POST /v2/inventory HTTP/1.1
Host: api.shipstation.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json

{
 "transaction_type": "increment",
 "inventory_location_id": "se-12345",
 "sku": "coolbluehat",
 "quantity": 250,
 "reason": "received incoming stock from vendor"
}

Manage Inventory Levels

List Inventory Levels

Example Request & Response

Update Inventory Levels

Request Body Properties

Example Request & Response

Was this helpful?