Last updated

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:

PropertyTypeDescription
skustringThe SKU value of the product.
on_handintegerThe quantity of this SKU currently in the associated inventory warehouse and location.
allocatedintegerThe quantity of this SKU already allocated to orders.
availableintegerThe quantity of this SKU available to ship (on_hand minus allocated).
average_costobjectThe wholesale cost you’ve indicated for a single quantity of this SKU (not your retail price). Includes both amount and currency properties.
inventory_warehouse_idstringThe ID of the inventory warehouse the SKU is located in.
inventory_location_idstringThe ID of the inventory location the SKU is located in.

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

Query ParametersTypeDescription
skustringTo return only the properties of a specific SKU.
inventory_warehouse_idstringTo return only the SKUs and related properties that exist in a specific inventory warehouse.
inventory_location_idstringTo return only the SKUs and related properties that exist in a specific inventory location.
group_byenumerated stringUse this option to group the SKUs in the response by either warehouse or location
limitintegerLimit 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:

PropertyTypeDescription
transaction_typeenumerated 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_idstringThe unique ID for the inventory location the SKU is located in.
skustringThe SKU of the product you wish to update.
quantityintegerThe 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:

PropertyTypeDescription
costobjectIf used, this object must include both the amount (number) and currency (string) properties.
conditionenumerated stringIndicate 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.
lotstringIndicate 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_datestring (date-time)This field is not currently used by ShipStation.
usable_end_datestring (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_atstring (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.
reasonstringExplain the reason for the stock level update. reason maps to the Description field in ShipStation’s stock history pop-up.
notesstringAdd 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_idstringIf 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_costobjectIf 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_conditionstring
  • 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"
}