Ankorstore Fulfillment API

ℹ️ Here you can find the information and endpoint specification related to fulfillment of the orders. ## 💡 About Fulfillment _Fulfillment_ is the process of preparing and shipping orders to customers via Ankorstore Fulfillment Centers. Brands that use fulfillment send their inventory to a warehouse in advance, and when orders come in, the warehouse picks, packs, and ships on the brand's behalf. ### What does "fulfillable" mean? The concept of a "fulfillable" is _that which is required to prepare and ship a product (variant)_. While a Fulfillment Centre deals exclusively with items, which represents a single item that an employee can pick up and prepare for shipping. A fulfillable is simply a set of one or more items, that together represent a product as ordered. Use the [List Fulfillables](#tag/Fulfillment/operation/fulfillment-list-fulfillable) endpoint to check stock availability for specific product variants before creating orders. For more detailed stock information — including quantities by location, status, and lot — use the [Stock State endpoint](/api/astral/v1/stock/state) from the Ankorstore Stock Tracking and Logistics API (ASTRAL). ### Fulfillments When a _Master Order_ has fulfillment requested, one or more _Fulfillments_ are created. Multiple fulfillments can be associated with a single master order (many-to-one). You can retrieve their details and track progress through the following statuses: | Status | Description | | --- | --- | | `requested` | Fulfillment has been requested for the order | | `created` | Fulfillment has been created in the warehouse system | | `scheduled` | Fulfillment is scheduled for picking | | `released` | Fulfillment has been released for picking | | `shipped` | Fulfillment has been shipped from the warehouse | | `cancelled` | Fulfillment has been cancelled | | `cancellation_requested` | A cancellation has been requested but not yet processed | Pass `?include=statusUpdates` when retrieving a fulfillment to see the full history of status transitions. ### Lots If your products are lot-tracked or expiry-tracked, the [List Lots](#tag/Fulfillment/operation/fulfillment-list-lots) endpoint shows the current lot inventory in the warehouse, including lot numbers, available quantities, and expiry/sell-by dates. You can filter and sort by available quantity, sell-by date range, and product name. ### Fulfillment Costs Use the [Get Fulfillment Costs](#tag/Fulfillment/operation/fulfillment-costs-get-specifications) endpoint to estimate fulfillment costs before committing to an order. Provide the destination country, parcel dimensions, and picking quantity to receive a cost breakdown by category (shipping, pick fees by quantity tier). > ⚠️ The cost estimation does **not** include packing consumables. The actual invoiced amount may differ. ## Replenishments Replenishments are required to send inventory to the warehouse. They follow a specific workflow: ### Replenishment Workflow stateDiagram-v2 direction LR [*] --> created created --> confirmed : Brand confirms confirmed --> sent : Sent to warehouse sent --> delivered : Arrives at warehouse delivered --> received : Items put into stock received --> [*] * **Created**: When a replenishment is initially created, it will be at status `created` and is considered a draft. In this state, it can be edited via PATCH requests or deleted. * **Confirmed**: Once editing is complete, the status should be updated to `confirmed` as part of a PATCH request. At this point, the replenishment information will be sent to the warehouse (asynchronously). * **Sent**: Once the replenishment information is sent to the warehouse, the status changes to `sent`. The replenishment will remain in this status while waiting for delivery. * **Delivered**: When the replenishment physically arrives at the warehouse, its status will be automatically updated to `delivered`. * **Received**: Once the items are put into stock at the warehouse, the status will be updated to `received`. At this stage, receipts are added with the received stock quantities and lots. ### Creating a Replenishment Each replenishment requires a carrier name, shipment type, and a list of items with their fulfillment item IDs and quantities: ```json5 // POST /api/v1/fulfillment/replenishments { "fulfillmentBrandId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "warehouseId": "98765432-abcd-ef01-2345-678901234567", "shippingCarrierName": "DHL", "shipmentType": "PARCEL", // "LTL", "FTL", or "PARCEL" "items": [ { "fulfillmentItemId": "d290f1ee-6c54-4b01-90e6-d701748f0851", "quantity": 100 } ] } ``` After creating a replenishment, update its status to `confirmed` via PATCH when you are ready to notify the warehouse. ### How Fulfillment Connects to Orders The diagram below shows how fulfillment fits into the order lifecycle: graph LR A[Master Order] --> D[Fulfillment 1] A --> E[Fulfillment 2] F[Replenishment] --> G[Warehouse Stock] G --> D G --> E 1. Brands send inventory to the warehouse via _Replenishments_ 2. When fulfillment is requested for a _Master Order_, one or more _Fulfillments_ are created 3. The warehouse picks items from stock and ships each fulfillment 4. Use the fulfillment endpoints to track both your inventory and fulfillment status