> For the complete documentation index, see [llms.txt](https://api-portal.novapost.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-portal.novapost.com/methods/methods/fullfillment.md).
# Fullfillment
## Create Goods
> This endpoint is used to create one or more goods records that can be added to an Inbound Plan or an Order.
```json
{"openapi":"3.0.0","info":{"title":"API Nova Post","version":"1.0.0"},"tags":[{"name":"Fulfillment"}],"servers":[{"description":"sandbox","url":"https://api-stage.novapost.com/v.1.0/"},{"description":"production","url":"https://api.novapost.com/v.1.0/"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"Authorization","description":"Authorization JWT-token with a lifetime of 1 hour in header"}}},"paths":{"/fulfillment/{countrycode}/v1/goods/multiple":{"post":{"summary":"Create Goods","description":"This endpoint is used to create one or more goods records that can be added to an Inbound Plan or an Order.\n","operationId":"createGoodsMultiple","tags":["Fulfillment"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","maxItems":5000,"description":"Array of goods objects.","items":{"type":"object","additionalProperties":false,"properties":{"sku":{"type":"string","description":"Unique product SKU in the client's information system.\n\nCase-insensitive.\n","minLength":2,"maxLength":72},"goodsUnitName":{"type":"string","description":"Short product name.","minLength":2,"maxLength":255},"goodsUnitFullName":{"type":"string","nullable":true,"description":"Full product name.","minLength":2,"maxLength":255},"price":{"type":"number","format":"float","description":"Price per product unit.","minimum":0.01,"maximum":100000000},"inventExpireDays":{"type":"integer","nullable":true,"description":"Shelf life in days. Enables expiration date control.","minimum":1,"maximum":15000}},"required":["sku","goodsUnitName","price"]}}}}},"responses":{"207":{"description":"Multi-Status. One or more goods were processed.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","description":"Array of successfully created goods.","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier of the product."},"sku":{"type":"string","description":"Product SKU in the client's information system."},"goodsUnitName":{"type":"string","description":"Short product name."},"goodsUnitFullName":{"type":"string","nullable":true,"description":"Full product name."},"price":{"type":"number","format":"float","description":"Price per product unit."},"inventExpireDays":{"type":"integer","nullable":true,"description":"Shelf life in days."},"createdAt":{"type":"string","format":"date-time","description":"Product creation date and time."},"updatedAt":{"type":"string","format":"date-time","description":"Date and time of the last product update."}},"required":["id","sku","goodsUnitName","price","createdAt","updatedAt"]}},"errors":{"type":"object","description":"Validation errors for goods that could not be created."}},"required":["data","errors"]}}}}}}}}}
```
## Update goods' details
> This endpoint allows modifying details of an existing goods.\
> Only the fields that need to be changed should be included in the request body (partial update), for example updating the name, price, or shelf life of a product.\
> \
> 🔸All fields are optional, but at least one field must be provided to perform an update. On success, the API returns the updated goods fields.
```json
{"openapi":"3.0.0","info":{"title":"API Nova Post","version":"1.0.0"},"tags":[{"name":"Fulfillment"}],"servers":[{"description":"sandbox","url":"https://api-stage.novapost.com/v.1.0/"},{"description":"production","url":"https://api.novapost.com/v.1.0/"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"Authorization","description":"Authorization JWT-token with a lifetime of 1 hour in header"}}},"paths":{"/fulfillment/{countrycode}/v1/goods/{id}":{"patch":{"summary":"Update goods' details","description":"This endpoint allows modifying details of an existing goods.\nOnly the fields that need to be changed should be included in the request body (partial update), for example updating the name, price, or shelf life of a product.\n\n🔸All fields are optional, but at least one field must be provided to perform an update. On success, the API returns the updated goods fields.\n","operationId":"updateGoods","tags":["Fulfillment"],"parameters":[{"name":"id","in":"path","required":true,"description":"Unique identifier of the goods to be updated.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"description":"Request body for updating goods.\nOnly the fields that need to be changed should be provided.\nAt least one field must be present.\n","properties":{"goodsUnitName":{"type":"string","description":"Short product name.","minLength":2,"maxLength":255},"goodsUnitFullName":{"type":"string","description":"Full product name.","minLength":2,"maxLength":255},"price":{"type":"number","format":"float","description":"Price per product unit.","minimum":0.01,"maximum":100000000},"inventExpireDays":{"type":"integer","nullable":true,"description":"Shelf life in days. Pass `null` to disable expiration date control.","minimum":1,"maximum":15000}},"minProperties":1}}}},"responses":{"200":{"description":"Request successful. Goods details were updated.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","description":"Updated goods details.","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier of the goods."},"sku":{"type":"string","description":"Unique product SKU in the client's information system."},"goodsUnitName":{"type":"string","description":"Short product name."},"goodsUnitFullName":{"type":"string","nullable":true,"description":"Full product name."},"price":{"type":"number","format":"float","description":"Price per product unit."},"inventExpireDays":{"type":"integer","nullable":true,"description":"Shelf life in days."},"createdAt":{"type":"string","format":"date-time","description":"Goods creation date and time."},"updatedAt":{"type":"string","format":"date-time","description":"Date and time of the last goods update."}},"required":["id","sku","goodsUnitName","price","createdAt","updatedAt"]}},"required":["data"]}}}}}}}}}
```
## Create Barcode
> This endpoint is used to create one or more barcodes associated with a specific good.\
> The barcode data is provided as an array, allowing multiple barcodes to be created in a single request.\
> \
> On success, the API returns all created barcodes with their unique identifiers and the parameters specified in the request.
```json
{"openapi":"3.0.0","info":{"title":"API Nova Post","version":"1.0.0"},"tags":[{"name":"Fulfillment"}],"servers":[{"description":"sandbox","url":"https://api-stage.novapost.com/v.1.0/"},{"description":"production","url":"https://api.novapost.com/v.1.0/"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"Authorization","description":"Authorization JWT-token with a lifetime of 1 hour in header"}}},"paths":{"/fulfillment/{countrycode}/v1/goods/{objectId}/barcodes/multiple":{"post":{"summary":"Create Barcode","description":"This endpoint is used to create one or more barcodes associated with a specific good.\nThe barcode data is provided as an array, allowing multiple barcodes to be created in a single request.\n\nOn success, the API returns all created barcodes with their unique identifiers and the parameters specified in the request.\n","operationId":"createBarcodes","tags":["Fulfillment"],"parameters":[{"name":"objectId","in":"path","required":true,"description":"Unique identifier of the goods for which barcodes are created.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","maxItems":5000,"items":{"type":"object","additionalProperties":false,"properties":{"barCode":{"type":"string","description":"Barcode value.","minLength":2,"maxLength":72},"weight":{"type":"number","format":"float","description":"Weight in kilograms.","minimum":0.01,"maximum":1000000},"length":{"type":"number","format":"float","description":"Length in centimeters.","minimum":0.01,"maximum":1000000},"height":{"type":"number","format":"float","description":"Height in centimeters.","minimum":0.01,"maximum":1000000},"width":{"type":"number","format":"float","description":"Width in centimeters.","minimum":0.01,"maximum":1000000}},"required":["barCode"]}}}}},"responses":{"207":{"description":"Multi-Status. Barcodes were processed.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","description":"Array of successfully created barcode objects.","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier of the barcode."},"barcode":{"type":"string","description":"Barcode value."},"measureUnitName":{"type":"string","description":"Unit of measurement."},"includes":{"type":"integer","description":"Number of units in the package."},"weight":{"type":"number","format":"float","description":"Weight in kilograms."},"length":{"type":"number","format":"float","description":"Length in centimeters."},"height":{"type":"number","format":"float","description":"Height in centimeters."},"width":{"type":"number","format":"float","description":"Width in centimeters."},"createdAt":{"type":"string","format":"date-time","description":"Barcode creation date and time."},"updatedAt":{"type":"string","format":"date-time","description":"Date and time of the last barcode update."}},"required":["id","barcode","measureUnitName","includes","createdAt","updatedAt"]}},"errors":{"type":"object","description":"Validation errors for barcodes that could not be created."}},"required":["data","errors"]}}}}}}}}}
```
## Update Barcode Details
> This endpoint is used to update the parameters of an existing barcode in the system by its unique identifier.\
> \
> Only the fields that need to be updated should be included in the request body.\
> \
> 🔸All fields are optional, but at least one field must be provided to perform the update. On success, the API returns the updated barcode object.
```json
{"openapi":"3.0.0","info":{"title":"API Nova Post","version":"1.0.0"},"tags":[{"name":"Fulfillment"}],"servers":[{"description":"sandbox","url":"https://api-stage.novapost.com/v.1.0/"},{"description":"production","url":"https://api.novapost.com/v.1.0/"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"Authorization","description":"Authorization JWT-token with a lifetime of 1 hour in header"}}},"paths":{"/fulfillment/{countrycode}/v1/barcodes/{id}":{"patch":{"summary":"Update Barcode Details","description":"This endpoint is used to update the parameters of an existing barcode in the system by its unique identifier.\n\nOnly the fields that need to be updated should be included in the request body.\n\n🔸All fields are optional, but at least one field must be provided to perform the update. On success, the API returns the updated barcode object.\n","operationId":"updateBarcode","tags":["Fulfillment"],"parameters":[{"name":"id","in":"path","required":true,"description":"Unique identifier of the barcode to be updated.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"description":"Request body for updating barcode details.\nOnly the fields that need to be changed should be provided.\nAt least one field must be present.\n","properties":{"weight":{"type":"number","format":"float","description":"Weight in kilograms.","minimum":0.01,"maximum":1000000},"length":{"type":"number","format":"float","description":"Length in centimeters.","minimum":0.01,"maximum":1000000},"height":{"type":"number","format":"float","description":"Height in centimeters.","minimum":0.01,"maximum":1000000},"width":{"type":"number","format":"float","description":"Width in centimeters.","minimum":0.01,"maximum":1000000}},"minProperties":1}}}},"responses":{"200":{"description":"Barcode successfully updated.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","description":"Updated barcode details.","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier of the barcode."},"barcode":{"type":"string","description":"Barcode value."},"measureUnitName":{"type":"string","description":"Unit of measurement."},"includes":{"type":"integer","description":"Number of units in the package."},"weight":{"type":"number","format":"float","description":"Weight in kilograms."},"length":{"type":"number","format":"float","description":"Length in centimeters."},"height":{"type":"number","format":"float","description":"Height in centimeters."},"width":{"type":"number","format":"float","description":"Width in centimeters."},"createdAt":{"type":"string","format":"date-time","description":"Barcode creation date and time."},"updatedAt":{"type":"string","format":"date-time","description":"Date and time of the last barcode update."}},"required":["id","barcode","measureUnitName","includes","createdAt","updatedAt"]}},"required":["data"]}}}}}}}}}
```
## Create Inbound Plan
> This endpoint allows creating a new inbound plan to receive goods at the specified warehouse.\
> \
> Only one inbound plan can be created per request.\
> A plan may contain one or more goods positions.\
> \
> On success, the API returns the created inbound plan with its unique identifier.
```json
{"openapi":"3.0.0","info":{"title":"API Nova Post","version":"1.0.0"},"tags":[{"name":"Fulfillment"}],"servers":[{"description":"sandbox","url":"https://api-stage.novapost.com/v.1.0/"},{"description":"production","url":"https://api.novapost.com/v.1.0/"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"Authorization","description":"Authorization JWT-token with a lifetime of 1 hour in header"}}},"paths":{"/fulfillment/{countrycode}/v1/inbound-plans":{"post":{"summary":"Create Inbound Plan","description":"This endpoint allows creating a new inbound plan to receive goods at the specified warehouse.\n\nOnly one inbound plan can be created per request.\nA plan may contain one or more goods positions.\n\nOn success, the API returns the created inbound plan with its unique identifier.\n","operationId":"createInboundPlan","tags":["Fulfillment"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"description":"Request body for creating an inbound plan.\nAll required fields must be provided.\n","properties":{"externalNumber":{"type":"string","description":"Unique document number in the client's information system.","minLength":2,"maxLength":72},"guid":{"type":"string","description":"Unique document GUID in the client's information system.","minLength":2,"maxLength":72},"destWarehouse":{"type":"string","description":"Destination warehouse code.","minLength":2,"maxLength":255},"deliveryType":{"type":"integer","description":"Delivery type (1 — Supplier delivery, 3 — Nova Post return, 7 — Nova Post delivery).","enum":[1,3,7]},"additionalInfo":{"type":"string","description":"Additional comment.","maxLength":255},"details":{"type":"array","description":"Array of goods items.","minItems":1,"maxItems":1000,"items":{"type":"object","additionalProperties":false,"properties":{"objectId":{"type":"string","format":"uuid","description":"Goods identifier in WMS (Warehouse Management System)."},"quantity":{"type":"integer","description":"Quantity of goods units.","minimum":1,"maximum":1000000}},"required":["objectId","quantity"]}}},"required":["externalNumber","destWarehouse","deliveryType","details"]}}}},"responses":{"201":{"description":"Request successful. Inbound plan was created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","description":"Created inbound plan.","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier of the inbound plan."},"externalNumber":{"type":"string","description":"Document number in the client's information system."},"guid":{"type":"string","description":"Unique document GUID in the client's information system."},"destWarehouse":{"type":"string","description":"Destination warehouse code."},"deliveryType":{"type":"integer","description":"Delivery type."},"additionalInfo":{"type":"string","description":"Additional comment."},"createdAt":{"type":"string","format":"date-time","description":"Inbound plan creation date and time."},"updatedAt":{"type":"string","format":"date-time","description":"Date and time of the last inbound plan update."},"details":{"type":"array","description":"Array of goods items included in the inbound plan.","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier of the inbound plan item."},"objectId":{"type":"string","format":"uuid","description":"Goods identifier in WMS (Warehouse Management System)."},"quantity":{"type":"integer","description":"Quantity of goods units."}},"required":["id","objectId","quantity"]}}},"required":["id","externalNumber","destWarehouse","deliveryType","createdAt","updatedAt","details"]}},"required":["data"]}}}}}}}}}
```
## Add Goods to Inbound Plan
> This endpoint is used to add new goods items to an existing inbound plan that is in status \`1\` (\*\*New\*\*).
```json
{"openapi":"3.0.0","info":{"title":"API Nova Post","version":"1.0.0"},"tags":[{"name":"Fulfillment"}],"servers":[{"description":"sandbox","url":"https://api-stage.novapost.com/v.1.0/"},{"description":"production","url":"https://api.novapost.com/v.1.0/"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"Authorization","description":"Authorization JWT-token with a lifetime of 1 hour in header"}}},"paths":{"/fulfillment/{countrycode}/v1/inbound-plans/{id}/details":{"post":{"summary":"Add Goods to Inbound Plan","description":"This endpoint is used to add new goods items to an existing inbound plan that is in status `1` (**New**).\n","operationId":"addGoodsToInboundPlan","tags":["Fulfillment"],"parameters":[{"name":"id","in":"path","required":true,"description":"Unique identifier of the inbound plan.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","minItems":1,"maxItems":1000,"items":{"type":"object","additionalProperties":false,"properties":{"objectId":{"type":"string","format":"uuid","description":"Goods UUID in WMS (Warehouse Management System)."},"quantity":{"type":"integer","description":"Quantity of goods units.","minimum":1,"maximum":1000000}},"required":["objectId","quantity"]}}}}},"responses":{"201":{"description":"Request successful. Goods were added to the inbound plan.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier of the inbound plan item."},"objectId":{"type":"string","format":"uuid","description":"Goods UUID in WMS (Warehouse Management System)."},"quantity":{"type":"integer","description":"Quantity of goods units."}},"required":["id","objectId","quantity"]}}}}}}}}}}
```
## Update Inbound Plan
> This endpoint is used to update the parameters of an inbound plan that is in status \`1\` (\*\*New\*\*).\
> \
> The endpoint allows updating the destination warehouse, delivery type, additional information, and quantities of existing goods items.\
> \
> 🔸Adding or removing goods items through this endpoint is not supported.
```json
{"openapi":"3.0.0","info":{"title":"API Nova Post","version":"1.0.0"},"tags":[{"name":"Fulfillment"}],"servers":[{"description":"sandbox","url":"https://api-stage.novapost.com/v.1.0/"},{"description":"production","url":"https://api.novapost.com/v.1.0/"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"Authorization","description":"Authorization JWT-token with a lifetime of 1 hour in header"}}},"paths":{"/fulfillment/{countrycode}/v1/inbound-plans/{id}":{"patch":{"summary":"Update Inbound Plan","description":"This endpoint is used to update the parameters of an inbound plan that is in status `1` (**New**).\n\nThe endpoint allows updating the destination warehouse, delivery type, additional information, and quantities of existing goods items.\n\n🔸Adding or removing goods items through this endpoint is not supported.\n","operationId":"updateInboundPlan","tags":["Fulfillment"],"parameters":[{"name":"id","in":"path","required":true,"description":"Unique identifier of the inbound plan.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"description":"Request body for updating an inbound plan.\nOnly the fields that need to be changed should be provided.\nAt least one field must be present.\n","properties":{"destWarehouse":{"type":"string","description":"Destination warehouse code.","minLength":2,"maxLength":255},"deliveryType":{"type":"integer","description":"Delivery type (1 — Supplier delivery, 3 — Nova Post return, 7 — Nova Post delivery).","enum":[1,3,7]},"additionalInfo":{"type":"string","description":"Comment.","maxLength":255},"details":{"type":"array","description":"Array of existing goods items for quantity update.","minItems":1,"maxItems":1000,"items":{"type":"object","additionalProperties":false,"properties":{"objectId":{"type":"string","format":"uuid","description":"Goods UUID in WMS (Warehouse Management System).\n\n🔹Required if `quantity` is specified.\n"},"quantity":{"type":"integer","description":"Quantity of goods units.\n\n🔹Required if `objectId` is specified.\n","minimum":1,"maximum":1000000}},"required":["objectId","quantity"]}}},"minProperties":1}}}},"responses":{"200":{"description":"Request successful. Inbound plan was updated.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","description":"Updated inbound plan.","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier of the inbound plan."},"externalNumber":{"type":"string","description":"Document number in the client's information system."},"guid":{"type":"string","description":"Document GUID in the client's information system."},"destWarehouse":{"type":"string","description":"Destination warehouse code."},"deliveryType":{"type":"integer","description":"Delivery type."},"additionalInfo":{"type":"string","description":"Comment."},"createdAt":{"type":"string","format":"date-time","description":"Inbound plan creation date and time."},"updatedAt":{"type":"string","format":"date-time","description":"Date and time of the last inbound plan update."},"details":{"type":"array","description":"Array of inbound plan items.","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the inbound plan item."},"objectId":{"type":"string","description":"Goods UUID in WMS (Warehouse Management System)."},"quantity":{"type":"integer","description":"Quantity of goods units."}},"required":["id","objectId","quantity"]}}},"required":["id","externalNumber","destWarehouse","deliveryType","createdAt","updatedAt","details"]}},"required":["data"]}}}}}}}}}
```
## Delete Goods from Inbound Plan
> This endpoint is used to remove goods items from an inbound plan that is in status \`1\` (\*\*New\*\*).\
> \
> On success, the API returns only the goods items that remain in the inbound plan.
```json
{"openapi":"3.0.0","info":{"title":"API Nova Post","version":"1.0.0"},"tags":[{"name":"Fulfillment"}],"servers":[{"description":"sandbox","url":"https://api-stage.novapost.com/v.1.0/"},{"description":"production","url":"https://api.novapost.com/v.1.0/"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"Authorization","description":"Authorization JWT-token with a lifetime of 1 hour in header"}}},"paths":{"/fulfillment/{countrycode}/v1/inbound-plans/{id}/details/multiple-delete":{"post":{"summary":"Delete Goods from Inbound Plan","description":"This endpoint is used to remove goods items from an inbound plan that is in status `1` (**New**).\n\nOn success, the API returns only the goods items that remain in the inbound plan.\n","operationId":"deleteGoodsFromInboundPlan","tags":["Fulfillment"],"parameters":[{"name":"id","in":"path","required":true,"description":"Unique identifier of the inbound plan.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","minItems":1,"maxItems":1000,"items":{"type":"object","additionalProperties":false,"properties":{"objectId":{"type":"string","format":"uuid","description":"Goods UUID in WMS (Warehouse Management System)."}},"required":["objectId"]}}}}},"responses":{"200":{"description":"Request successful. Goods items were removed from the inbound plan.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier of the inbound plan item."},"objectId":{"type":"string","format":"uuid","description":"Goods UUID in WMS (Warehouse Management System)."},"quantity":{"type":"integer","description":"Quantity of goods units."}},"required":["id","objectId","quantity"]}}}}}}}}}}
```
## Cancel Inbound Plan
> This endpoint is used to cancel an inbound plan that is in status \`1\` (\*\*New\*\*).\
> \
> On success, the inbound plan is moved to status \`10\` (\*\*Canceled\*\*) and the updated inbound plan is returned.
```json
{"openapi":"3.0.0","info":{"title":"API Nova Post","version":"1.0.0"},"tags":[{"name":"Fulfillment"}],"servers":[{"description":"sandbox","url":"https://api-stage.novapost.com/v.1.0/"},{"description":"production","url":"https://api.novapost.com/v.1.0/"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"Authorization","description":"Authorization JWT-token with a lifetime of 1 hour in header"}}},"paths":{"/fulfillment/{countrycode}/v1/inbound-plans/{id}/cancel":{"patch":{"summary":"Cancel Inbound Plan","description":"This endpoint is used to cancel an inbound plan that is in status `1` (**New**).\n\nOn success, the inbound plan is moved to status `10` (**Canceled**) and the updated inbound plan is returned.\n","operationId":"cancelInboundPlan","tags":["Fulfillment"],"parameters":[{"name":"id","in":"path","required":true,"description":"Unique identifier of the inbound plan.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Request successful. The inbound plan was canceled.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","description":"Canceled inbound plan.","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier of the inbound plan."},"externalNumber":{"type":"string","description":"Document number in the client's information system."},"guid":{"type":"string","description":"Document GUID in the client's information system."},"destWarehouse":{"type":"string","description":"Destination warehouse code."},"deliveryType":{"type":"integer","description":"Delivery type."},"additionalInfo":{"type":"string","description":"Comment."},"createdAt":{"type":"string","format":"date-time","description":"Inbound plan creation date and time."},"updatedAt":{"type":"string","format":"date-time","description":"Date and time of the last inbound plan update."},"details":{"type":"array","description":"Array of inbound plan items.","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the inbound plan item."},"objectId":{"type":"string","description":"Goods UUID in WMS."},"quantity":{"type":"integer","description":"Quantity of goods units."}},"required":["id","objectId","quantity"]}}},"required":["id","externalNumber","destWarehouse","deliveryType","createdAt","updatedAt","details"]}},"required":["data"]}}}}}}}}}
```
## Create Orders
> This endpoint is used to create one or more customer orders for shipping goods from the warehouse in a single request.\
> \
> Two delivery scenarios are supported:\
> \- \*\*Nova Post delivery\*\* — an international express waybill number must be specified. The waybill is validated in AWIS / Oper Module.\
> \- \*\*Customer pickup\*\* — the order is created without specifying an international express waybill.\
> \
> If the request is valid and all requirements are met, each order is created with one of the following statuses:\
> \- \`1\` \*\*(New)\*\* — when all products are available in stock.\
> \- \`13\` \*\*(Incomplete)\*\* — when some products are fully or partially unavailable.
```json
{"openapi":"3.0.0","info":{"title":"API Nova Post","version":"1.0.0"},"tags":[{"name":"Fulfillment"}],"servers":[{"description":"sandbox","url":"https://api-stage.novapost.com/v.1.0/"},{"description":"production","url":"https://api.novapost.com/v.1.0/"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"Authorization","description":"Authorization JWT-token with a lifetime of 1 hour in header"}}},"paths":{"/fulfillment/{countrycode}/v1/orders/multiple":{"post":{"summary":"Create Orders","description":"This endpoint is used to create one or more customer orders for shipping goods from the warehouse in a single request.\n\nTwo delivery scenarios are supported:\n- **Nova Post delivery** — an international express waybill number must be specified. The waybill is validated in AWIS / Oper Module.\n- **Customer pickup** — the order is created without specifying an international express waybill.\n\nIf the request is valid and all requirements are met, each order is created with one of the following statuses:\n- `1` **(New)** — when all products are available in stock.\n- `13` **(Incomplete)** — when some products are fully or partially unavailable.\n","operationId":"createOrdersMultiple","tags":["Fulfillment"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"object","additionalProperties":false,"properties":{"externalNumber":{"type":"string","description":"Customer's internal order number.","minLength":2,"maxLength":72},"destWarehouse":{"type":"string","description":"Warehouse code.","minLength":2,"maxLength":255},"deliveryType":{"type":"integer","description":"Delivery type (`1` — Nova Post shipment, `2` — Customer pickup).","enum":[1,2]},"waybillNumber":{"type":"string","description":"Nova Post waybill number. Required when `deliveryType = 1`."},"additionalInfo":{"type":"string","description":"Additional information or comment.","maxLength":255},"details":{"type":"array","description":"List of product items included in the order.","minItems":1,"maxItems":1000,"items":{"type":"object","additionalProperties":false,"properties":{"objectId":{"type":"string","format":"uuid","description":"Product UUID in WMS."},"quantity":{"type":"integer","description":"Number of product units.","minimum":1,"maximum":1000},"price":{"type":"number","format":"float","description":"Unit price.","minimum":0.01,"maximum":100000000},"sum":{"type":"number","format":"float","description":"Total item amount.","minimum":0.01,"maximum":100000000}},"required":["objectId","quantity"]}}},"required":["externalNumber","destWarehouse","deliveryType","details"]}}}}},"responses":{"207":{"description":"Request processed. Returns the creation result for each order.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","description":"Successfully created orders.","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique order identifier."},"externalNumber":{"type":"string","description":"Customer's internal order number."},"destWarehouse":{"type":"string","description":"Warehouse code."},"deliveryType":{"type":"integer","description":"Delivery type."},"waybillNumber":{"type":"string","nullable":true,"description":"Nova Post waybill number."},"additionalInfo":{"type":"string","description":"Additional information or comment."},"createdAt":{"type":"string","format":"date-time","description":"Order creation date and time."},"updatedAt":{"type":"string","format":"date-time","description":"Order last update date and time."},"details":{"type":"array","description":"Product items included in the order.","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique order item identifier."},"objectId":{"type":"string","format":"uuid","description":"Product UUID in WMS."},"quantity":{"type":"integer","description":"Quantity of the goods."},"price":{"type":"number","format":"float","description":"Unit price."},"sum":{"type":"number","format":"float","description":"Total item amount."}},"required":["id","objectId","quantity"]}}}},"required":["id","externalNumber","destWarehouse","deliveryType","details"]},"errors":{"type":"object","description":"Errors for orders that could not be created."}},"required":["data","errors"]}}}}}}}}}
```
## Add Goods to Order
> This endpoint is used to add new product items to an existing order that is currently in status \`13\` \*\*(Incomplete)\*\*.\
> \
> The response (\`201 Created\`) returns the complete list of product items currently included in the order.
```json
{"openapi":"3.0.0","info":{"title":"API Nova Post","version":"1.0.0"},"tags":[{"name":"Fulfillment"}],"servers":[{"description":"sandbox","url":"https://api-stage.novapost.com/v.1.0/"},{"description":"production","url":"https://api.novapost.com/v.1.0/"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"Authorization","description":"Authorization JWT-token with a lifetime of 1 hour in header"}}},"paths":{"/fulfillment/{countrycode}/v1/orders/{id}/details":{"post":{"summary":"Add Goods to Order","description":"This endpoint is used to add new product items to an existing order that is currently in status `13` **(Incomplete)**.\n\nThe response (`201 Created`) returns the complete list of product items currently included in the order.\n","operationId":"addGoodsToClientOrder","tags":["Fulfillment"],"parameters":[{"name":"id","in":"path","required":true,"description":"Unique identifier of the order.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","description":"Root-level array of product items to be added to the order.\nAt least one product item must be provided.\n","minItems":1,"items":{"type":"object","additionalProperties":false,"properties":{"objectId":{"type":"string","description":"Product identifier."},"quantity":{"type":"integer","description":"Quantity of product.","minimum":1,"maximum":1000},"price":{"type":"number","format":"float","description":"Unit price."},"sum":{"type":"number","format":"float","description":"Total amount for the line item."}},"required":["objectId","quantity"]}}}}},"responses":{"201":{"description":"Complete order item list returned successfully.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier of the order item."},"objectId":{"type":"string","description":"Product identifier."},"quantity":{"type":"integer","description":"Quantity of product."},"price":{"type":"number","format":"float","description":"Unit price."},"sum":{"type":"number","format":"float","description":"Total amount for the line item."}},"required":["id","objectId","quantity"]}}}}}}}}}}
```
## Check Order Status
> This endpoint is used to retrieve the current status of one or more orders, with optional filtering parameters.\
> \
> Filter values within the same parameter are combined using \*\*OR\*\*, while different filter parameters are combined using \*\*AND\*\*.\
> \
> 🔹\*\*If no filter parameters are provided, the response returns the most recent orders.\*\*\
> \
> 🔸This \`GET\` request does not return an error when incorrect, non-existent, or partially invalid filter values are used.\
> In such cases, invalid or empty filters are ignored, and if no orders match the criteria, an empty array is returned.
```json
{"openapi":"3.0.0","info":{"title":"API Nova Post","version":"1.0.0"},"tags":[{"name":"Fulfillment"}],"servers":[{"description":"sandbox","url":"https://api-stage.novapost.com/v.1.0/"},{"description":"production","url":"https://api.novapost.com/v.1.0/"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"Authorization","description":"Authorization JWT-token with a lifetime of 1 hour in header"}}},"paths":{"/fulfillment/{countrycode}/v1/orders/status":{"get":{"summary":"Check Order Status","description":"This endpoint is used to retrieve the current status of one or more orders, with optional filtering parameters.\n\nFilter values within the same parameter are combined using **OR**, while different filter parameters are combined using **AND**.\n\n🔹**If no filter parameters are provided, the response returns the most recent orders.**\n\n🔸This `GET` request does not return an error when incorrect, non-existent, or partially invalid filter values are used.\nIn such cases, invalid or empty filters are ignored, and if no orders match the criteria, an empty array is returned.\n","operationId":"checkOrderStatus","tags":["Fulfillment"],"parameters":[{"name":"ids[]","in":"query","required":false,"description":"Array of system order identifiers.","schema":{"type":"array","items":{"type":"string","format":"uuid"}}},{"name":"externalNumbers[]","in":"query","required":false,"description":"Array of external order numbers.","schema":{"type":"array","items":{"type":"string"}}},{"name":"destWarehouses[]","in":"query","required":false,"description":"Array of destination warehouse codes.","schema":{"type":"array","items":{"type":"string"}}},{"name":"startDate","in":"query","required":false,"description":"Start creation date in ISO 8601 format.","schema":{"type":"string","format":"date-time"}},{"name":"endDate","in":"query","required":false,"description":"End creation date in ISO 8601 format.","schema":{"type":"string","format":"date-time"}},{"name":"page","in":"query","required":false,"description":"Pagination page number (up to 25 objects per page).","schema":{"type":"integer"}}],"responses":{"200":{"description":"Request successful.\nReturns a list of orders matching the filtering criteria.\n","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","description":"List of orders.","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the order."},"externalNumber":{"type":"string","description":"External order number."},"destWarehouse":{"type":"string","description":"Destination warehouse code."},"status":{"type":"integer","description":"Current order status."},"statusTime":{"type":"string","format":"date-time","nullable":true,"description":"Timestamp of the latest status update."},"waybillNumber":{"type":"string","nullable":true,"description":"Waybill number."}},"required":["id","externalNumber","destWarehouse","status"]}},"links":{"type":"object","description":"Pagination links."},"meta":{"type":"object","description":"Pagination metadata."}},"required":["data","links","meta"]}}}}}}}}}
```
## Cancel Order
> This endpoint is used to cancel a order that is currently in status \`13\` \*\*(Incomplete)\*\*.\
> \
> Once canceled, the order transitions to status \`10\` \*\*(Canceled)\*\*.\
> \
> If a related Nova Post waybill number exists, it is automatically deleted.
```json
{"openapi":"3.0.0","info":{"title":"API Nova Post","version":"1.0.0"},"tags":[{"name":"Fulfillment"}],"servers":[{"description":"sandbox","url":"https://api-stage.novapost.com/v.1.0/"},{"description":"production","url":"https://api.novapost.com/v.1.0/"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"Authorization","description":"Authorization JWT-token with a lifetime of 1 hour in header"}}},"paths":{"/fulfillment/{countrycode}/v1/orders/{id}/cancel":{"patch":{"summary":"Cancel Order","description":"This endpoint is used to cancel a order that is currently in status `13` **(Incomplete)**.\n\nOnce canceled, the order transitions to status `10` **(Canceled)**.\n\nIf a related Nova Post waybill number exists, it is automatically deleted.\n","operationId":"cancelClientOrder","tags":["Fulfillment"],"parameters":[{"name":"id","in":"path","required":true,"description":"Unique identifier of the order.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The order was successfully canceled.\nReturns the updated order.\n","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier of the order."},"externalNumber":{"type":"string","description":"External order number."},"destWarehouse":{"type":"string","description":"Shipping warehouse code."},"deliveryType":{"type":"integer","description":"Delivery type."},"waybillNumber":{"type":"string","nullable":true,"description":"Waybill number. Returns `null` after cancellation."},"additionalInfo":{"type":"string","description":"Additional information or comment."},"status":{"type":"string","description":"Order status (`10` = Canceled).","enum":["10"]},"createdAt":{"type":"string","format":"date-time","description":"Order creation date and time."},"updatedAt":{"type":"string","format":"date-time","description":"Order last update date and time."},"details":{"type":"array","description":"Order item list.","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier of the order item."},"objectId":{"type":"string","description":"Product identifier."},"quantity":{"type":"integer","description":"Product quantity."},"price":{"type":"number","format":"float","description":"Unit price."},"sum":{"type":"number","format":"float","description":"Total amount for the line item."}},"required":["id","objectId","quantity"]}}},"required":["id","externalNumber","status","details"]}},"required":["data"]}}}}}}}}}
```
## Get Order Details
> This endpoint is used to retrieve the complete details of a specific order by its \*\*id\*\*.\
> \
> The response returns the complete list of order items, including planned and actual quantities, product condition, and serial numbers (if applicable).
```json
{"openapi":"3.0.0","info":{"title":"API Nova Post","version":"1.0.0"},"tags":[{"name":"Fulfillment"}],"servers":[{"description":"sandbox","url":"https://api-stage.novapost.com/v.1.0/"},{"description":"production","url":"https://api.novapost.com/v.1.0/"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"Authorization","description":"Authorization JWT-token with a lifetime of 1 hour in header"}}},"paths":{"/fulfillment/{countrycode}/v1/orders/{id}/details":{"get":{"summary":"Get Order Details","description":"This endpoint is used to retrieve the complete details of a specific order by its **id**.\n\nThe response returns the complete list of order items, including planned and actual quantities, product condition, and serial numbers (if applicable).\n","operationId":"getOrderDetails","tags":["Fulfillment"],"parameters":[{"name":"id","in":"path","required":true,"description":"Unique identifier of the order.","schema":{"type":"string"}}],"responses":{"200":{"description":"Data successfully retrieved.\nReturns the complete details of the order.\n","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of the order."},"externalNumber":{"type":"string","description":"External order number."},"details":{"type":"array","description":"List of order items.","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier of the order item."},"objectId":{"type":"string","description":"Product identifier."},"sku":{"type":"string","description":"Product SKU."},"measureUnitName":{"type":"string","description":"Unit of measurement."},"plannedQuantity":{"type":"integer","description":"Planned quantity."},"actualQuantity":{"type":"integer","description":"Actual quantity."},"condition":{"type":"integer","description":"Product condition.","enum":[0,1]},"series":{"type":"array","description":"List of serial numbers.","items":{"type":"string"}}},"required":["id","objectId","sku","plannedQuantity","actualQuantity","condition","series"]}}},"required":["id","externalNumber","details"]}}}}}}}}}
```
## Update Order
> This endpoint updates an existing customer order that is currently in status \`13\` \*\*(Incomplete)\*\*.\
> \
> The request allows updating general order parameters, delivery settings, and existing order items. If \*\*Nova Post delivery\*\* is selected, a waybill number must be provided. If the delivery type is changed to \*\*Customer pickup\*\*, the existing waybill is removed from the system.\
> \
> 🔸All fields are optional, but at least one field must be provided to perform the update.
```json
{"openapi":"3.0.0","info":{"title":"API Nova Post","version":"1.0.0"},"tags":[{"name":"Fulfillment"}],"servers":[{"description":"sandbox","url":"https://api-stage.novapost.com/v.1.0/"},{"description":"production","url":"https://api.novapost.com/v.1.0/"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"Authorization","description":"Authorization JWT-token with a lifetime of 1 hour in header"}}},"paths":{"/fulfillment/{countrycode}/v1/orders/{id}":{"patch":{"summary":"Update Order","description":"This endpoint updates an existing customer order that is currently in status `13` **(Incomplete)**.\n\nThe request allows updating general order parameters, delivery settings, and existing order items. If **Nova Post delivery** is selected, a waybill number must be provided. If the delivery type is changed to **Customer pickup**, the existing waybill is removed from the system.\n\n🔸All fields are optional, but at least one field must be provided to perform the update.\n","operationId":"updateOrder","tags":["Fulfillment"],"parameters":[{"name":"id","in":"path","required":true,"description":"Unique identifier of the customer order.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"description":"Request body for updating a customer order.\nOnly the fields that need to be changed should be provided.\nAt least one field must be present.\n","properties":{"destWarehouse":{"type":"string","description":"Warehouse code."},"deliveryType":{"type":"integer","description":"Delivery type (`1` — Nova Post shipment, `2` — Customer pickup).","enum":[1,2]},"waybillNumber":{"type":"string","nullable":true,"description":"Nova Post waybill number. Required when `deliveryType = 1`."},"additionalInfo":{"type":"string","description":"Additional information or comment.","maxLength":255},"details":{"type":"array","description":"Array of existing order items.","minItems":1,"items":{"type":"object","additionalProperties":false,"properties":{"objectId":{"type":"string","format":"uuid","description":"Product UUID in WMS.\n\n🔹Required if `quantity` is specified.\n"},"quantity":{"type":"integer","description":"Quantity of the product.\n\n🔹Required if `objectId` is specified.\n","minimum":1,"maximum":1000},"price":{"type":"number","format":"float","description":"Unit price.","minimum":0.01,"maximum":100000000},"sum":{"type":"number","format":"float","description":"Total amount for the order item.","minimum":0.01,"maximum":100000000}},"required":["objectId","quantity"]}}},"minProperties":1}}}},"responses":{"200":{"description":"The customer order was successfully updated.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier of the customer order."},"externalNumber":{"type":"string","description":"Customer's internal order number."},"destWarehouse":{"type":"string","description":"Warehouse code."},"deliveryType":{"type":"integer","description":"Delivery type."},"waybillNumber":{"type":"string","nullable":true,"description":"Nova Post waybill number."},"additionalInfo":{"type":"string","description":"Additional information or comment."},"createdAt":{"type":"string","format":"date-time","description":"Order creation date and time."},"updatedAt":{"type":"string","format":"date-time","description":"Last update date and time."},"details":{"type":"array","description":"List of order items.","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier of the order item."},"objectId":{"type":"string","format":"uuid","description":"Product UUID in WMS."},"quantity":{"type":"integer","description":"Quantity of the product."},"price":{"type":"number","format":"float","description":"Unit price."},"sum":{"type":"number","format":"float","description":"Total amount for the order item."}},"required":["id","objectId","quantity"]}}},"required":["id","externalNumber","destWarehouse","deliveryType","details"]}},"required":["data"]}}}}}}}}}
```
## Delete Goods from Order
> This endpoint is used to remove one or more product items from a order that is currently in status \`13\` \*\*(Incomplete)\*\*.\
> \
> Removing all product items from the order is allowed. In this case, the order status remains \`13\` \*\*(Incomplete)\*\*.\
> \
> The response (\`200 OK\`) returns only the product items remaining in the order.
```json
{"openapi":"3.0.0","info":{"title":"API Nova Post","version":"1.0.0"},"tags":[{"name":"Fulfillment"}],"servers":[{"description":"sandbox","url":"https://api-stage.novapost.com/v.1.0/"},{"description":"production","url":"https://api.novapost.com/v.1.0/"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"Authorization","description":"Authorization JWT-token with a lifetime of 1 hour in header"}}},"paths":{"/fulfillment/{countrycode}/v1/orders/{id}/details/multiple-delete":{"post":{"summary":"Delete Goods from Order","description":"This endpoint is used to remove one or more product items from a order that is currently in status `13` **(Incomplete)**.\n\nRemoving all product items from the order is allowed. In this case, the order status remains `13` **(Incomplete)**.\n\nThe response (`200 OK`) returns only the product items remaining in the order.\n","operationId":"deleteGoodsFromClientOrder","tags":["Fulfillment"],"parameters":[{"name":"id","in":"path","required":true,"description":"Unique identifier of the order.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","description":"Root-level array of product items to be removed from the order.\nAt least one product item must be provided.\n","minItems":1,"items":{"type":"object","additionalProperties":false,"properties":{"objectId":{"type":"string","description":"Product identifier."}},"required":["objectId"]}}}}},"responses":{"200":{"description":"Product items were successfully removed from the order.\nReturns only the product items remaining in the order.\n","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier of the order item."},"objectId":{"type":"string","description":"Product identifier."},"quantity":{"type":"integer","description":"Quantity of product."},"price":{"type":"number","format":"float","description":"Unit price."},"sum":{"type":"number","format":"float","description":"Total amount for the line item."}},"required":["id","objectId","quantity"]}}}}}}}}}}
```
## Check Stock Remains
> This endpoint is used to retrieve information about stock remains in warehouses with optional filtering.\
> \
> Filter values within the same parameter are combined using \*\*OR\*\*, while different filter parameters are combined using \*\*AND\*\*.\
> \
> Available quantity is calculated using the following formula:\
> \`availableQuantity = quantity - reservedQuantity\` (if the result is less than 0, 0 is returned).\
> \
> 🔹If no product-specific filters (\`objectIds\`, \`objectArts\`, \`objectTitles\`) are provided, only products with \`quantity > 0\`, \`reservedQuantity > 0\`, or \`availableQuantity > 0\` are returned.\
> \
> 🔹If product-specific filters (\`objectIds\`, \`objectArts\`, \`objectTitles\`) are provided, the requested products are always returned, even if all stock values are equal to 0.\
> \
> Stock information is returned regardless of whether a product has a barcode. Stock remains are grouped by \`expiryDate\`.\
> \
> Invalid or unknown filter values are ignored and do not cause errors.
```json
{"openapi":"3.0.0","info":{"title":"API Nova Post","version":"1.0.0"},"tags":[{"name":"Fulfillment"}],"servers":[{"description":"sandbox","url":"https://api-stage.novapost.com/v.1.0/"},{"description":"production","url":"https://api.novapost.com/v.1.0/"}],"security":[{"JWT":[]}],"components":{"securitySchemes":{"JWT":{"type":"apiKey","in":"header","name":"Authorization","description":"Authorization JWT-token with a lifetime of 1 hour in header"}}},"paths":{"/fulfillment/{countrycode}/v1/stock-remains":{"get":{"summary":"Check Stock Remains","description":"This endpoint is used to retrieve information about stock remains in warehouses with optional filtering.\n\nFilter values within the same parameter are combined using **OR**, while different filter parameters are combined using **AND**.\n\nAvailable quantity is calculated using the following formula:\n`availableQuantity = quantity - reservedQuantity` (if the result is less than 0, 0 is returned).\n\n🔹If no product-specific filters (`objectIds`, `objectArts`, `objectTitles`) are provided, only products with `quantity > 0`, `reservedQuantity > 0`, or `availableQuantity > 0` are returned.\n\n🔹If product-specific filters (`objectIds`, `objectArts`, `objectTitles`) are provided, the requested products are always returned, even if all stock values are equal to 0.\n\nStock information is returned regardless of whether a product has a barcode. Stock remains are grouped by `expiryDate`.\n\nInvalid or unknown filter values are ignored and do not cause errors.\n","operationId":"checkStockRemains","tags":["Fulfillment"],"parameters":[{"name":"objectIds[]","in":"query","required":false,"description":"Array of product IDs.","schema":{"type":"array","items":{"type":"string"}}},{"name":"objectArts[]","in":"query","required":false,"description":"Array of product article numbers.","schema":{"type":"array","items":{"type":"string"}}},{"name":"objectTitles[]","in":"query","required":false,"description":"Array of product names.","schema":{"type":"array","items":{"type":"string"}}},{"name":"destWarehouses[]","in":"query","required":false,"description":"Array of warehouse codes.","schema":{"type":"array","items":{"type":"string"}}},{"name":"remainDate","in":"query","required":false,"description":"Stock validity date in YYYY-MM-DD format.","schema":{"type":"string"}},{"name":"condition","in":"query","required":false,"description":"Product condition:\n- `0` — good;\n- `1` — defective.\n","schema":{"type":"integer","enum":[0,1]}},{"name":"page","in":"query","required":false,"description":"Pagination page number (up to 25 records per page).","schema":{"type":"integer"}}],"responses":{"200":{"description":"Data retrieved successfully.\nReturns stock remains with Laravel pagination.\n","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","description":"List of stock remains.","items":{"type":"object","properties":{"objectId":{"type":"string","description":"Product identifier."},"sku":{"type":"string","description":"Product SKU."},"measureUnitName":{"type":"string","nullable":true,"description":"Unit of measurement."},"quantity":{"type":"integer","description":"Total quantity in stock."},"reservedQuantity":{"type":"integer","description":"Reserved quantity."},"availableQuantity":{"type":"integer","description":"Available quantity."},"destWarehouse":{"type":"string","nullable":true,"description":"Warehouse code."},"expiryDate":{"type":"string","nullable":true,"description":"Expiry date."}}}},"links":{"type":"object","description":"Pagination links."},"meta":{"type":"object","description":"Pagination metadata."}},"required":["data","links","meta"]}}}}}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://api-portal.novapost.com/methods/methods/fullfillment.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.