> For the complete documentation index, see [llms.txt](https://docs.hos.accessacloud.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hos.accessacloud.com/evo-stock-api/deliveries.md).

# Deliveries

Delivery management

## List deliveries

> Returns all deliveries for the authenticated organisation, ordered by delivery date descending. Includes supplier, site, and line items.

```json
{"openapi":"3.0.1","info":{"title":"EvoStock APIM Operations API","version":"0.1"},"tags":[{"name":"Deliveries","description":"Delivery management"}],"servers":[{"url":"https://apim-hospitality-prod-uksouth.azure-api.net/evo/stock/v1","description":"Production"},{"url":"https://apim-hospitality-dev-uksouth.azure-api.net/evo/stock/v1","description":"Development"},{"url":"https://apim-hospitality-stg-uksouth.azure-api.net/evo/stock/v1","description":"Staging"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"OAuth2 client credentials JWT obtained from the Access Identity M2M token endpoint (`POST https://api.hos.accessacloud.com/platform/m2m-auth/v1/token`). The token request must use `grant_type=client_credentials` with `audience=fandb-platform-api evo-stock` and `scope=fandb.read fandb.write openid`. The response returns `{ \"access_token\": \"<JWT>\", \"expires_in\": 3599, \"scope\": \"fandb.read fandb.write openid\", \"token_type\": \"bearer\" }`. Tokens expire after `expires_in` seconds (typically ~1 hour). APIM validates the token at the gateway and resolves the calling organisation from the token claims — no additional headers are required."}},"parameters":{"PageSize":{"name":"page_size","in":"query","required":false,"description":"Number of items per page. Clamped to the range [1, 500]. Defaults to 100.","schema":{"type":"integer","minimum":1,"maximum":500,"default":100}},"Cursor":{"name":"cursor","in":"query","required":false,"description":"Opaque cursor for keyset pagination. Pass the next_cursor value from a previous response to fetch the next page.","schema":{"type":"string"}}},"schemas":{"PaginatedResponse":{"type":"object","required":["data","pagination"],"properties":{"data":{"type":"array","items":{}},"pagination":{"$ref":"#/components/schemas/Pagination"}}},"Pagination":{"type":"object","required":["page_size","has_next_page","next_cursor"],"properties":{"page_size":{"type":"integer","description":"The page size used for this request."},"has_next_page":{"type":"boolean","description":"Whether more results exist beyond this page."},"next_cursor":{"type":"string","nullable":true,"description":"Cursor to pass as the cursor query parameter for the next page. Null when there are no more results."}}},"Delivery":{"type":"object","required":["id","tenantId","deliveryNoteNumber","supplierId","siteId","deliveryDate","deliveryTime","receivedBy","source","status","totalItems","totalValue","imageUrls","createdBy","createdAt","updatedAt"],"properties":{"id":{"type":"string","description":"Unique delivery identifier (CUID)."},"tenantId":{"type":"string"},"deliveryNoteNumber":{"type":"string","maxLength":100},"supplierId":{"type":"string"},"siteId":{"type":"string"},"purchaseOrderId":{"type":"string","nullable":true},"integrationId":{"type":"string","nullable":true},"externalOrderId":{"type":"integer","nullable":true,"description":"External order ID from third-party systems."},"locationId":{"type":"string","nullable":true,"description":"Deprecated — use siteId instead. Retained for backward compatibility.","deprecated":true},"deliveryDate":{"type":"string","format":"date-time"},"deliveryTime":{"type":"string","maxLength":10},"receivedBy":{"type":"string","maxLength":255},"source":{"$ref":"#/components/schemas/DeliverySource"},"status":{"$ref":"#/components/schemas/DeliveryStatus"},"expectedDate":{"type":"string","format":"date-time","nullable":true},"confirmedDate":{"type":"string","format":"date-time","nullable":true},"confirmedBy":{"type":"string","nullable":true,"maxLength":255},"totalItems":{"type":"integer"},"totalValue":{"type":"string","format":"decimal"},"notes":{"type":"string","nullable":true},"imageUrls":{"type":"array","items":{"type":"string"}},"createdBy":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"supplier":{"$ref":"#/components/schemas/SupplierRef"},"site":{"$ref":"#/components/schemas/SiteRef"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryLineSummary"}}}},"DeliverySource":{"type":"string","enum":["DELIVERYHUB","MANUAL","SCAN","INTEGRATION"]},"DeliveryStatus":{"type":"string","enum":["PENDING","PARTIALLY_RECEIVED","OVERDUE","COMPLETE","CONFIRMED","CANCELLED"]},"SupplierRef":{"type":"object","description":"Lightweight reference to a supplier.","required":["id","supplierName","supplierCode"],"properties":{"id":{"type":"string"},"supplierName":{"type":"string"},"supplierCode":{"type":"string"}}},"SiteRef":{"type":"object","description":"Lightweight reference to a site.","required":["id","name"],"properties":{"id":{"type":"string"},"name":{"type":"string"}}},"DeliveryLineSummary":{"type":"object","description":"Summary of a delivery line item as returned in list/detail responses.","required":["id","productId","quantityReceived","unitCost","totalCost"],"properties":{"id":{"type":"string"},"productId":{"type":"string"},"quantityReceived":{"type":"string","format":"decimal"},"unitCost":{"type":"string","format":"decimal"},"totalCost":{"type":"string","format":"decimal"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable error message."}}}},"responses":{"Unauthorized":{"description":"Missing, invalid, or expired authorization token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"OrganizationNotFound":{"description":"No tenant found matching the token's subject claim.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalServerError":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/apim/deliveries":{"get":{"operationId":"GetDeliveries","summary":"List deliveries","description":"Returns all deliveries for the authenticated organisation, ordered by delivery date descending. Includes supplier, site, and line items.","tags":["Deliveries"],"parameters":[{"$ref":"#/components/parameters/PageSize"},{"$ref":"#/components/parameters/Cursor"}],"responses":{"200":{"description":"Paginated list of deliveries.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedResponse"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Delivery"}}}}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/OrganizationNotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## Create a delivery

> Creates a new delivery for the authenticated organisation. Optionally include line items in the lines array. Defaults to source INTEGRATION and status PENDING when not provided.

```json
{"openapi":"3.0.1","info":{"title":"EvoStock APIM Operations API","version":"0.1"},"tags":[{"name":"Deliveries","description":"Delivery management"}],"servers":[{"url":"https://apim-hospitality-prod-uksouth.azure-api.net/evo/stock/v1","description":"Production"},{"url":"https://apim-hospitality-dev-uksouth.azure-api.net/evo/stock/v1","description":"Development"},{"url":"https://apim-hospitality-stg-uksouth.azure-api.net/evo/stock/v1","description":"Staging"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"OAuth2 client credentials JWT obtained from the Access Identity M2M token endpoint (`POST https://api.hos.accessacloud.com/platform/m2m-auth/v1/token`). The token request must use `grant_type=client_credentials` with `audience=fandb-platform-api evo-stock` and `scope=fandb.read fandb.write openid`. The response returns `{ \"access_token\": \"<JWT>\", \"expires_in\": 3599, \"scope\": \"fandb.read fandb.write openid\", \"token_type\": \"bearer\" }`. Tokens expire after `expires_in` seconds (typically ~1 hour). APIM validates the token at the gateway and resolves the calling organisation from the token claims — no additional headers are required."}},"schemas":{"CreateDeliveryInput":{"type":"object","required":["deliveryNoteNumber","supplierId","siteId","deliveryDate","deliveryTime","receivedBy","createdBy"],"properties":{"deliveryNoteNumber":{"type":"string","maxLength":100},"supplierId":{"type":"string"},"siteId":{"type":"string"},"deliveryDate":{"type":"string","format":"date","description":"ISO 8601 date (e.g. `2026-04-15`)."},"deliveryTime":{"type":"string","maxLength":10},"receivedBy":{"type":"string","maxLength":255},"createdBy":{"type":"string"},"source":{"type":"string","description":"Delivery source. Defaults to INTEGRATION.","default":"INTEGRATION","enum":["DELIVERYHUB","MANUAL","SCAN","INTEGRATION"]},"status":{"type":"string","description":"Delivery status. Defaults to PENDING.","default":"PENDING","enum":["PENDING","PARTIALLY_RECEIVED","OVERDUE","COMPLETE","CONFIRMED","CANCELLED"]},"expectedDate":{"type":"string","format":"date"},"purchaseOrderId":{"type":"string"},"integrationId":{"type":"string"},"notes":{"type":"string"},"imageUrls":{"type":"array","items":{"type":"string"}},"lines":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryLineInput"}}}},"DeliveryLineInput":{"type":"object","required":["productId","quantityReceived","unitCost","totalCost"],"properties":{"productId":{"type":"string"},"quantityReceived":{"type":"number","format":"decimal"},"unitCost":{"type":"number","format":"decimal"},"totalCost":{"type":"number","format":"decimal"},"currencyCode":{"type":"string","maxLength":3},"expiryDate":{"type":"string","format":"date","description":"ISO 8601 date (e.g. `2026-12-31`)."},"batchNumber":{"type":"string","maxLength":100},"storageLocation":{"type":"string","maxLength":255},"lotCode":{"type":"string","maxLength":100},"lotCodeType":{"$ref":"#/components/schemas/LotCodeType"}}},"LotCodeType":{"type":"string","enum":["NONE","GTIN"]},"Delivery":{"type":"object","required":["id","tenantId","deliveryNoteNumber","supplierId","siteId","deliveryDate","deliveryTime","receivedBy","source","status","totalItems","totalValue","imageUrls","createdBy","createdAt","updatedAt"],"properties":{"id":{"type":"string","description":"Unique delivery identifier (CUID)."},"tenantId":{"type":"string"},"deliveryNoteNumber":{"type":"string","maxLength":100},"supplierId":{"type":"string"},"siteId":{"type":"string"},"purchaseOrderId":{"type":"string","nullable":true},"integrationId":{"type":"string","nullable":true},"externalOrderId":{"type":"integer","nullable":true,"description":"External order ID from third-party systems."},"locationId":{"type":"string","nullable":true,"description":"Deprecated — use siteId instead. Retained for backward compatibility.","deprecated":true},"deliveryDate":{"type":"string","format":"date-time"},"deliveryTime":{"type":"string","maxLength":10},"receivedBy":{"type":"string","maxLength":255},"source":{"$ref":"#/components/schemas/DeliverySource"},"status":{"$ref":"#/components/schemas/DeliveryStatus"},"expectedDate":{"type":"string","format":"date-time","nullable":true},"confirmedDate":{"type":"string","format":"date-time","nullable":true},"confirmedBy":{"type":"string","nullable":true,"maxLength":255},"totalItems":{"type":"integer"},"totalValue":{"type":"string","format":"decimal"},"notes":{"type":"string","nullable":true},"imageUrls":{"type":"array","items":{"type":"string"}},"createdBy":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"supplier":{"$ref":"#/components/schemas/SupplierRef"},"site":{"$ref":"#/components/schemas/SiteRef"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryLineSummary"}}}},"DeliverySource":{"type":"string","enum":["DELIVERYHUB","MANUAL","SCAN","INTEGRATION"]},"DeliveryStatus":{"type":"string","enum":["PENDING","PARTIALLY_RECEIVED","OVERDUE","COMPLETE","CONFIRMED","CANCELLED"]},"SupplierRef":{"type":"object","description":"Lightweight reference to a supplier.","required":["id","supplierName","supplierCode"],"properties":{"id":{"type":"string"},"supplierName":{"type":"string"},"supplierCode":{"type":"string"}}},"SiteRef":{"type":"object","description":"Lightweight reference to a site.","required":["id","name"],"properties":{"id":{"type":"string"},"name":{"type":"string"}}},"DeliveryLineSummary":{"type":"object","description":"Summary of a delivery line item as returned in list/detail responses.","required":["id","productId","quantityReceived","unitCost","totalCost"],"properties":{"id":{"type":"string"},"productId":{"type":"string"},"quantityReceived":{"type":"string","format":"decimal"},"unitCost":{"type":"string","format":"decimal"},"totalCost":{"type":"string","format":"decimal"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable error message."}}}},"responses":{"BadRequest":{"description":"Malformed request body or missing required fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Missing, invalid, or expired authorization token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"OrganizationNotFound":{"description":"No tenant found matching the token's subject claim.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalServerError":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/apim/delivery":{"post":{"operationId":"CreateDelivery","summary":"Create a delivery","description":"Creates a new delivery for the authenticated organisation. Optionally include line items in the lines array. Defaults to source INTEGRATION and status PENDING when not provided.","tags":["Deliveries"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDeliveryInput"}}}},"responses":{"201":{"description":"Delivery created successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Delivery"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/OrganizationNotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## Update a delivery

> Updates an existing delivery for the authenticated organisation. Only provided fields are updated. If a lines array is provided, existing lines are replaced wholesale.

```json
{"openapi":"3.0.1","info":{"title":"EvoStock APIM Operations API","version":"0.1"},"tags":[{"name":"Deliveries","description":"Delivery management"}],"servers":[{"url":"https://apim-hospitality-prod-uksouth.azure-api.net/evo/stock/v1","description":"Production"},{"url":"https://apim-hospitality-dev-uksouth.azure-api.net/evo/stock/v1","description":"Development"},{"url":"https://apim-hospitality-stg-uksouth.azure-api.net/evo/stock/v1","description":"Staging"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"OAuth2 client credentials JWT obtained from the Access Identity M2M token endpoint (`POST https://api.hos.accessacloud.com/platform/m2m-auth/v1/token`). The token request must use `grant_type=client_credentials` with `audience=fandb-platform-api evo-stock` and `scope=fandb.read fandb.write openid`. The response returns `{ \"access_token\": \"<JWT>\", \"expires_in\": 3599, \"scope\": \"fandb.read fandb.write openid\", \"token_type\": \"bearer\" }`. Tokens expire after `expires_in` seconds (typically ~1 hour). APIM validates the token at the gateway and resolves the calling organisation from the token claims — no additional headers are required."}},"schemas":{"UpdateDeliveryInput":{"type":"object","description":"All fields are optional. Only provided fields are updated. If lines is provided, existing lines are deleted and replaced wholesale.","properties":{"deliveryNoteNumber":{"type":"string","maxLength":100},"supplierId":{"type":"string"},"siteId":{"type":"string"},"deliveryDate":{"type":"string","format":"date"},"deliveryTime":{"type":"string","maxLength":10},"receivedBy":{"type":"string","maxLength":255},"source":{"$ref":"#/components/schemas/DeliverySource"},"status":{"$ref":"#/components/schemas/DeliveryStatus"},"expectedDate":{"type":"string","format":"date"},"confirmedDate":{"type":"string","format":"date-time"},"confirmedBy":{"type":"string","maxLength":255},"purchaseOrderId":{"type":"string"},"integrationId":{"type":"string"},"notes":{"type":"string"},"imageUrls":{"type":"array","items":{"type":"string"}},"lines":{"type":"array","description":"If provided, all existing delivery lines are removed and replaced with this array. Omit to leave lines unchanged.","items":{"$ref":"#/components/schemas/DeliveryLineInput"}}}},"DeliverySource":{"type":"string","enum":["DELIVERYHUB","MANUAL","SCAN","INTEGRATION"]},"DeliveryStatus":{"type":"string","enum":["PENDING","PARTIALLY_RECEIVED","OVERDUE","COMPLETE","CONFIRMED","CANCELLED"]},"DeliveryLineInput":{"type":"object","required":["productId","quantityReceived","unitCost","totalCost"],"properties":{"productId":{"type":"string"},"quantityReceived":{"type":"number","format":"decimal"},"unitCost":{"type":"number","format":"decimal"},"totalCost":{"type":"number","format":"decimal"},"currencyCode":{"type":"string","maxLength":3},"expiryDate":{"type":"string","format":"date","description":"ISO 8601 date (e.g. `2026-12-31`)."},"batchNumber":{"type":"string","maxLength":100},"storageLocation":{"type":"string","maxLength":255},"lotCode":{"type":"string","maxLength":100},"lotCodeType":{"$ref":"#/components/schemas/LotCodeType"}}},"LotCodeType":{"type":"string","enum":["NONE","GTIN"]},"Delivery":{"type":"object","required":["id","tenantId","deliveryNoteNumber","supplierId","siteId","deliveryDate","deliveryTime","receivedBy","source","status","totalItems","totalValue","imageUrls","createdBy","createdAt","updatedAt"],"properties":{"id":{"type":"string","description":"Unique delivery identifier (CUID)."},"tenantId":{"type":"string"},"deliveryNoteNumber":{"type":"string","maxLength":100},"supplierId":{"type":"string"},"siteId":{"type":"string"},"purchaseOrderId":{"type":"string","nullable":true},"integrationId":{"type":"string","nullable":true},"externalOrderId":{"type":"integer","nullable":true,"description":"External order ID from third-party systems."},"locationId":{"type":"string","nullable":true,"description":"Deprecated — use siteId instead. Retained for backward compatibility.","deprecated":true},"deliveryDate":{"type":"string","format":"date-time"},"deliveryTime":{"type":"string","maxLength":10},"receivedBy":{"type":"string","maxLength":255},"source":{"$ref":"#/components/schemas/DeliverySource"},"status":{"$ref":"#/components/schemas/DeliveryStatus"},"expectedDate":{"type":"string","format":"date-time","nullable":true},"confirmedDate":{"type":"string","format":"date-time","nullable":true},"confirmedBy":{"type":"string","nullable":true,"maxLength":255},"totalItems":{"type":"integer"},"totalValue":{"type":"string","format":"decimal"},"notes":{"type":"string","nullable":true},"imageUrls":{"type":"array","items":{"type":"string"}},"createdBy":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"supplier":{"$ref":"#/components/schemas/SupplierRef"},"site":{"$ref":"#/components/schemas/SiteRef"},"lines":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryLineSummary"}}}},"SupplierRef":{"type":"object","description":"Lightweight reference to a supplier.","required":["id","supplierName","supplierCode"],"properties":{"id":{"type":"string"},"supplierName":{"type":"string"},"supplierCode":{"type":"string"}}},"SiteRef":{"type":"object","description":"Lightweight reference to a site.","required":["id","name"],"properties":{"id":{"type":"string"},"name":{"type":"string"}}},"DeliveryLineSummary":{"type":"object","description":"Summary of a delivery line item as returned in list/detail responses.","required":["id","productId","quantityReceived","unitCost","totalCost"],"properties":{"id":{"type":"string"},"productId":{"type":"string"},"quantityReceived":{"type":"string","format":"decimal"},"unitCost":{"type":"string","format":"decimal"},"totalCost":{"type":"string","format":"decimal"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Human-readable error message."}}}},"responses":{"BadRequest":{"description":"Malformed request body or missing required fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Missing, invalid, or expired authorization token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalServerError":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/apim/delivery/{deliveryId}":{"post":{"operationId":"UpdateDelivery","summary":"Update a delivery","description":"Updates an existing delivery for the authenticated organisation. Only provided fields are updated. If a lines array is provided, existing lines are replaced wholesale.","tags":["Deliveries"],"parameters":[{"name":"deliveryId","in":"path","required":true,"description":"The unique identifier of the delivery to update.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateDeliveryInput"}}}},"responses":{"200":{"description":"Delivery updated successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Delivery"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Organisation or delivery not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```


---

# 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:

```
GET https://docs.hos.accessacloud.com/evo-stock-api/deliveries.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.