The Stock Management API allows sellers to query and review their Fulfillment stocks stored in Octopia’s warehouses. It provides visibility into quantity breakdowns (available, allocated, blocked, return, etc.) and localized stock per storage country. This is vital for sellers to understand their inventory state, trigger inbound or outbound orders, and monitor stock health.
Key Principles & Business Behavior
Before retrieving stock, products must be declared and supplied to the warehouse (See Inbound documentation). Stock is only available after the warehouse received and at least started processing the supply order.
Localization per storage country: enables seller to see how much stock is in each warehouse location, changes, and update reasons.
The API supports:
Retrieving a single stock record by its uuId
Listing stocks with filters and cursor‐based pagination
Querying “stock seller references” (i.e. reference entries that link seller product reference + warehouse stock)
Some filters are mutually exclusive: for instance, deliveryCountry cannot be combined with updatedAtMin/Max, storageCountry, sort, or order.
Sorting is allowed by quantity fields (e.g. Available, Blocked, etc.) via a sort parameter, and ordering Asc/Desc.
The stock-seller-references endpoints let sellers review their own product references tied to underlying stocks and octopia productIds (without retrieving full inventory details)etrieving full inventory details).
The stock API is a core foundation of the Fulfillment flow: after any inbound shipment reception, stock becomes visible, and sellers can plan outbound shipments, returns, or inventory operations based on live data.
Key Attributes
Field
Level
Description
id
Global
Unique identifier of the stock entry
productId
Global
Octopia product identifier
productState
Global
Main state of the product. Possible values: New, Used, Refurbished
A limit parameter is required; maximum is 1000 per page.
This endpoint retrieves a paginated list of all fulfillment stocks.
It supports filters such as productId, sellerProductReference, productCondition, productState, storageCountry, deliveryCountry, and update dates.
This is the primary method to view inventory.
Endpoint to use
A route used to get list stocks fulfillment by sellerId & limit as
required and any of those parameter sellerProductReference,
productId, productCondition, productState, storageCountry,
cursor.
Using a cursor pagination. A cursor parameter is used to navigate to the previous
or the next page. This parameter is encoded and acts as a pointer to the first
or the last item in the page. When the parameter is not provided, the first
products are returned until the expected limit.
Functional Rules:
The parameter deliveryCountry cannot be combined with updatedAtMin, updatedAtMax, storageCountry, sort or order parameters.
Exemples:
Retrieves list of stock fulfillment for a specified seller
/stocks?limit=100
Retrieve seller stock fulfillment with a cursor linked to the next or previous page.
Retrieves list of stocks fulfillment for a specified seller with a sellerproductReference value that's not empty or null.
/stocks?hasSellerProductReference=true&limit=100
Parameters - Headers
Name
In
Type
Description
SellerId*
header
string
Octopia Seller Identifier.
Example : 98979
Parameters - Query
Name
In
Type
Description
limit
query
integer
number of items in response
Example : 10
sellerProductReference
query
string
seller Product Reference
Example : product01X98979
productId
query
string
Product Id
Example : product01
productCondition
query
string|enum
Product Condition
Example : New
Available values : ["New", "LikeNew", "VeryGoodState", "AverageState", "RefurbishedLikeNew", "RefurbishedVeryGoodState", "RefurbishedCorrectState"]
productState
query
string|enum
Product state
Example : New
Available values : ["New", "Used", "Refurbished"]
hasSellerProductReference
query
boolean
SellerProductReference is filled
Example : 1
storageCountry
query
string
Country of stock's storage - ISO 3166-1 alpha-2. This parameter cannot be combined with the deliveryCountry parameter.
Example : FR
deliveryCountry
query
string
Filters the stock that can be delivered to the specified country - ISO 3166-1 alpha-2. This parameter cannot be combined with updatedAtMin, updatedAtMax, storageCountry, sort, order parameters.
Example : FR
updatedAtMin
query
string
Date of stock's minumum update (UTC). This parameter cannot be combined with the deliveryCountry parameter. This parameters must be smaller than the updatedAtMax parameter.
Example : 2020-04-20 10:10:00
updatedAtMax
query
string
Date of stock's maximum update (UTC). This parameter cannot be combined with the deliveryCountry parameter. This parameters must be greater than the updatedAtMin parameter.
Example : 2020-04-21 10:10:00
cursor
query
string|null
Pagination cursor.
Example : QXNjXzE2OTA0NjI3NzYyNzI=
sort
query
string|enum
Field to order by the stock's sort field. This parameter cannot be combined with the deliveryCountry parameter.
Example : Available
Available values : ["Available", "Blocked", "Allocated", "Removal", "Litigation", "Return", "LogisticOperations"]
order
query
string|enum
Field to order by the stock's sort field. This parameter cannot be combined with the deliveryCountry parameter.
Product state. Only three values are possible:
- `New`: The product is new.
- `Used`: The product is used.
- `Refurbished`: The product is refurbished.Enum[3]: [New, Used, Refurbished]
productCondition: string|enum
Product condition enum.
* `New` - New
* `LikeNew` - Like new.
* `VeryGoodState` - Very good state.
* `AverageState` - Average state.
* `RefurbishedLikeNew` - Refurbished like new
* `RefurbishedVeryGoodState` - Refurbished very good state
* `RefurbishedCorrectState` - Refurbished correct stateEnum[7]: [New, LikeNew, VeryGoodState, AverageState, RefurbishedLikeNew, RefurbishedVeryGoodState, RefurbishedCorrectState]
sellerId: string
The seller identifier.
supplyMode: string|enum
The stock types:
- `Fulfillment`: Stock stored in Fulfillment.
- `Seller`: Stock stored by the seller.Enum[2]: [Fulfillment, Seller]
quantities: {
The quantities of different types of stocks.
Available: integer|null
Available quantity, total stock available for shipment.
Allocated: integer|null
Allocated quantity, stock reserved for specific orders.
Blocked: integer|null
Blocked quantity, stock blocked for various reasons (counterfeit, customs, etc.).
Litigation: integer|null
Stock in dispute due to a reception anomaly.
Removal: integer|null
Removal quantity, Stock ready for pickup at the warehouse by the seller.
Return: integer|null
Returned stock that cannot be shipped again.
LogisticOperations: integer|null
Stock in the process of logistics handling, blocked between 24 and 72 hours.
}
localizedStocks: {
The stock localizations.
TwoLettersCountryCode: {
The stock localizations.
localizedQuantities: {
The quantities of different types of stocks.
Available: integer|null
Available quantity, total stock available for shipment.
Allocated: integer|null
Allocated quantity, stock reserved for specific orders.
Blocked: integer|null
Blocked quantity, stock blocked for various reasons (counterfeit, customs, etc.).
Litigation: integer|null
Stock in dispute due to a reception anomaly.
Removal: integer|null
Removal quantity, Stock ready for pickup at the warehouse by the seller.
Return: integer|null
Returned stock that cannot be shipped again.
LogisticOperations: integer|null
Stock in the process of logistics handling, blocked between 24 and 72 hours.
}
availabilityChange: boolean|null
Is any data changed.
updateReason: string|null
stock update reason
updateDetails: string|null
stock update details
volume: number|null
stock volume in m3
createdAt: string (date-time)
localised stock created date.
updatedAt: string (date-time)|null
localised stock updated date.
}
}
sellerProductReference: string|null
seller Product Reference
createdAt: string (date-time)
stock created date
updatedAt: string (date-time)
stock updated date
}
]
}
Headers:
Name
Type
Description
Link
string
Linked pagination request
Example : </stocks?limit=20&cursor=Rm9yd2FyZF9iNWE3YjVjYi0yYzBlLTQzNjItODQzMC1kMmEzN2UxOWMyZTNfMA==>;rel=next, </stocks?limit=20&cursor=QmFja3dhcmRfOWU5Nzc4ZTAtMzczMS0wOGRjLTAwMDAtMDAwMDAwMDAwMDAwXzA=>;rel="prev"
400 - Bad Request
application/problem+json
{
"type": "https://tools.ietf.org/html/rfc7231",
"status": 400,
"title": "One or more validation errors occurred.",
"errors": {
"Order": [
"Missing order parameter for sorting."
]
}
}
A human-readable explanation specific to this occurence of the problem
instance: string|null
A URI reference that identifies the specific occurence of the problem.
traceId: string|null
The response identifier.
status: integer (int32)|null
The HTTP status code generated by the origin server for this occurence of the problem.
title: string|null
A short human-readable summary of the problem type.
type: string (uri)|null
A URI reference that identifies the problem type and provides a human-readable documentation for the problem.
}
Important notes
deliveryCountry filtering is exclusive: it cannot be combined with storageCountry, sort,order, or date filters.
Sorting is possible on stock types such as Available, Blocked, etc., using sort and order.
Each stock line includes warehouse-specific metrics, making this endpoint useful for monitoring volume and allocation.
Retrieve a Single Stock
Prerequisites
You must have the unique stockId of the record to retrieve.
The stock must exist in the system and be linked to the seller’s account.
This endpoint retrieves all information related to a specific stock item, including product identity, available quantities by type (e.g., Available, Blocked, Litigation), and localization per storage country.
It is useful for back-office views, issue investigation (e.g., blocked or litigated stock), or customer service reconciliation.
Endpoint to use
Aucun endpoint trouvé avec l'operationId « get-stocks-stockId ».
Important notes
Quantities are broken down by operational states (e.g., Blocked, Allocated, LogisticOperations).
Localization provides warehouse-specific view, including update reason and volume.
Product condition and state are distinct: both are included in the response.
Retrieve Stock Seller References
Prerequisites
The seller must have already declared products into the system.
Pagination is required via limit and cursor.
This endpoint lists the current stock-level references linking products (via productId and productCondition) to a seller-defined identifier (sellerProductReference).
It is typically used to align external systems (e.g., marketplaces or ERPs) with Octopia’s internal product tracking.
Endpoint to use
A route used to get stock seller reference fulfillment by sellerId & limit as required and any of those parameters sellerProductReference, productId, productCondition, cursor. Results are ordered by creation date descendant by default.
Exemples:
Retrieves list of stock seller reference fulfillment for a specified seller.
/stock-seller-references?limit=100
Retrieve seller reference fulfillment with a cursor linked to the next page.
/stock-seller-references?limit=100&cursor=91425db0-d61a-410a-9e69-cfa02a103216
Retrieves list of stock seller reference fulfillment for a specified seller and
sellerProductReference.
/stock-seller-references?sellerProductReference=SELLERX1204&limit=100
Retrieves list of stock seller reference fulfillment for a specified seller and productId.
/stock-seller-references?productId=product01&limit=100
Retrieves list of stock seller reference fulfillment for a specified seller and productCondition.
/stock-seller-references?productCondition=New&limit=100
Retrieves list of stock seller reference fulfillment for a specified seller and order the response by creation date ascendant.
/stock-seller-references?limit=100&orderBy=Asc
Parameters - Headers
Name
In
Type
Description
SellerId*
header
string
Octopia Seller Identifier.
Example : 98979
Parameters - Query
Name
In
Type
Description
limit
query
integer
limit items by request
Example : 10
sellerProductReference
query
string|null
seller Product Reference
Example : product01X98979
productId
query
string|null
product Id
Example : product01
productCondition
query
string|enum
product Condition
Example : New
Available values : ["New", "LikeNew", "VeryGoodState", "AverageState", "RefurbishedLikeNew", "RefurbishedVeryGoodState", "RefurbishedCorrectState"]
orderBy
query
string|enum
Field to order by the outbound-shipment created date.
Product state. Only three values are possible:
- `New`: The product is new.
- `Used`: The product is used.
- `Refurbished`: The product is refurbished.Enum[3]: [New, Used, Refurbished]
productCondition: string|enum
Product condition enum.
* `New` - New
* `LikeNew` - Like new.
* `VeryGoodState` - Very good state.
* `AverageState` - Average state.
* `RefurbishedLikeNew` - Refurbished like new
* `RefurbishedVeryGoodState` - Refurbished very good state
* `RefurbishedCorrectState` - Refurbished correct stateEnum[7]: [New, LikeNew, VeryGoodState, AverageState, RefurbishedLikeNew, RefurbishedVeryGoodState, RefurbishedCorrectState]
sellerProductReference: string|null
SellerproductReference code.
createdAt: string (date-time)
The creation date.
updatedAt: string (date-time)|null
The update date.
}
]
}
Headers:
Name
Type
Description
Link
string
Links to get next page
Example : </stock-seller-references?limit=10&cursor=f8cf2180-885a-4eb4-8e12-1763071198fe>;rel=next
400 - Bad Request
application/problem+json
{
"detail": "Information about the errors",
"type": "https://tools.ietf.org/html/rfc7231",
"status": 400,
"title": "Bad Request",
"traceId": "00-9055d0e39a4a5554866eee202737812f-8e3fb58dea31a710-00",
"errors": {
"Field": [
"Any error on specified field"
],
"OtherField": [
"Any other error on specified field"
]
}
}
{
Problem details with errors description model.
detail: string|null
A human-readable explanation specific to this occurence of the problem
instance: string|null
A URI reference that identifies the specific occurence of the problem.
traceId: string|null
The response identifier.
status: integer (int32)|null
The HTTP status code generated by the origin server for this occurence of the problem.
title: string|null
A short human-readable summary of the problem type.
type: string (uri)|null
A URI reference that identifies the problem type and provides a human-readable documentation for the problem.
A human-readable explanation specific to this occurence of the problem
instance: string|null
A URI reference that identifies the specific occurence of the problem.
traceId: string|null
The response identifier.
status: integer (int32)|null
The HTTP status code generated by the origin server for this occurence of the problem.
title: string|null
A short human-readable summary of the problem type.
type: string (uri)|null
A URI reference that identifies the problem type and provides a human-readable documentation for the problem.
}
Important notes
Each reference includes creation and update timestamps, which can be used for sync verification.
Filtering is possible by productId, condition, sellerProductReference, or datetime updates.
FAQ
What does this API allow me to do?
It allows you to retrieve real-time stock levels and inventory details for your products stores in Octopia Fulfillment’s network of warehouses.
What are the different stock quantities I can retrieve?
Each stock entry contains the following information:
Available: ready to ship
Allocated: reserved for orders
Blocked: locked due to issues (customs, QC, fraud…)
Litigation: under investigation (damaged or dispute)
Removal: pending pickup/removal by seller
Return: returned but not sellable
LogisticOperations: in transit inside warehouse or between warehouses
You also get this data per storage country via localizedStocks.
What is the difference between the stock and seller stock reference endpoints ?
The stocks endpoint refers to a product’s inventory in warehouses.
The stock seller reference endpoint only returns seller provided product references.
How often are stock values updated?
Stock data is near real-time (updates occur after inbound, outbound, returns, etc.).
You can filter by:
updatedAtMin / updatedAtMax (timestamps)
storageCountry, deliveryCountry, or sort by specific quantity types
What’s the difference between storageCountry and deliveryCountry filters?
storageCountry: shows stock physically located in a given country (e.g. FR, ES)
deliveryCountry: shows stock eligiblefor deliveryto that country (cross-dock logic)
Note: deliveryCountry cannot be combined with updatedAt, sort, or storageCountry.
Why is my stock Available = 0 but I see Litigation = 3?
This means the product was received but flagged during warehouse inspection. It’s quarantined and not shippable.
This requires manual seller action.
Can I match stock with product condition?
Yes — each stock entry has a productCondition and productState, which allow you to distinguish:
New vs Used
Refurbished (LikeNew, Good, Correct, etc.)
Can I use this API in sandbox?
There is no sandbox available.
Due to the nature of some of the manual operations involved in processing product data, receiving physical goods, and packaging shipments, along with synchronizing multiple warehouses and databases, conducting complete tests is relatively complicated and thus not provided as a common possibility.
