Introduction

Stock API

Overview

Organisation-scoped inventory (balances, takes, movements, delivery notes). Venue paths use Directory location ids as siteId. Catalogue rows are owned by Listings and projected into Stock. See docs/SERVICE_BOUNDARY.md.

Integration guide: Stock service docs

OpenAPI v0.1.0 · source openapi/stock.json

OpenAPI 3.0.0 · v0.1.0 · 56 operations

Operations

System

Liveness and documentation.

get/health

Health check

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/stock/health"

Unauthenticated liveness probe.

Operation ID: getHealth

Responses

200
Service is running
application/json

get/v1/health

Health check (versioned)

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/stock/v1/health"

Unauthenticated liveness probe.

Operation ID: getHealthV1

Responses

200
Service is running
application/json

Takes

Stock take sessions.

get/v1/sites/{siteId}/takes

List stock takes for a site

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/stock/v1/sites/example-id/takes"

Operation ID: listStockTakes

Parameters

Name	In	Type	Description
siteId*	path	string (uuid)	Directory location id for venue stock (see docs/SERVICE_BOUNDARY.md).
limit	query	integer	—
offset	query	integer	—

Responses

200
Takes
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/sites/{siteId}/takes

Start a stock take

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/stock/v1/sites/example-id/takes"

Operation ID: createStockTake

Parameters

Name	In	Type	Description
siteId*	path	string (uuid)	Directory location id for venue stock (see docs/SERVICE_BOUNDARY.md).

Request body(required)

application/jsonStockTakeCreate

Responses

201
Created take
application/json
400
Malformed request. `error.code` is typically INVALID_REQUEST.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is a resource-specific *_NOT_FOUND value.
application/json
409
The change conflicts with current state. `error.code`: CONFLICT or RECEIPT_ALREADY_CONFIRMED.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

get/v1/takes/{id}

Get a stock take

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/stock/v1/takes/example-id"

Operation ID: getStockTake

Parameters

Name	In	Type	Description
id*	path	string (uuid)	—

Responses

200
Take
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is a resource-specific *_NOT_FOUND value.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/takes/{id}/lines

Add an item to an open stock take

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/stock/v1/takes/example-id/lines"

Operation ID: addStockTakeLine

Parameters

Name	In	Type	Description
id*	path	string (uuid)	—

Request body(required)

application/jsonStockTakeLineCreate

Responses

201
Created line
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is a resource-specific *_NOT_FOUND value.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

patch/v1/takes/{id}/lines

Update counted quantities

Example request

curl -sS \
  -X PATCH \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/stock/v1/takes/example-id/lines"

Operation ID: patchStockTakeLines

Parameters

Name	In	Type	Description
id*	path	string (uuid)	—

Request body(required)

application/jsonStockTakeLinesPatch

Responses

200
Updated take
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is a resource-specific *_NOT_FOUND value.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/takes/{id}/submit

Submit a stock take

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/stock/v1/takes/example-id/submit"

Operation ID: submitStockTake

Parameters

Name	In	Type	Description
id*	path	string (uuid)	—

Responses

200
Submitted take
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is a resource-specific *_NOT_FOUND value.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

Inventory

On-hand balances and stock movements.

get/v1/sites/{siteId}/balances

List on-hand stock balances for a site

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/stock/v1/sites/example-id/balances"

Operation ID: listStockBalances

Parameters

Name	In	Type	Description
siteId*	path	string (uuid)	Directory location id for venue stock (see docs/SERVICE_BOUNDARY.md).

Responses

200
Balances
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is a resource-specific *_NOT_FOUND value.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

get/v1/brands/{brandId}/distribution

Brand on-hand and venue distribution summary

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/stock/v1/brands/example-id/distribution"

Operation ID: getBrandDistribution

Parameters

Name	In	Type	Description
brandId*	path	string (uuid)	Directory location group id.

Responses

200
Distribution
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/sites/{siteId}/receipts

Receive stock at a site

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/stock/v1/sites/example-id/receipts"

Operation ID: receiveStock

Parameters

Name	In	Type	Description
siteId*	path	string (uuid)	Directory location id for venue stock (see docs/SERVICE_BOUNDARY.md).

Request body(required)

application/jsonStockReceiptCreate

Responses

201
Received
application/json
400
Malformed request. `error.code` is typically INVALID_REQUEST.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is a resource-specific *_NOT_FOUND value.
application/json
409
The change conflicts with current state. `error.code`: CONFLICT or RECEIPT_ALREADY_CONFIRMED.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/transfers

Transfer stock from brand site to venue site

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/stock/v1/transfers"

Operation ID: transferStock

Request body(required)

application/jsonStockTransferCreate

Responses

201
Transferred
application/json
400
Malformed request. `error.code` is typically INVALID_REQUEST.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is a resource-specific *_NOT_FOUND value.
application/json
409
The change conflicts with current state. `error.code`: CONFLICT or RECEIPT_ALREADY_CONFIRMED.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/returns

Return stock from venue site to brand site

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/stock/v1/returns"

Operation ID: returnStock

Request body(required)

application/jsonStockReturnCreate

Responses

201
Returned
application/json
400
Malformed request. `error.code` is typically INVALID_REQUEST.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is a resource-specific *_NOT_FOUND value.
application/json
409
The change conflicts with current state. `error.code`: CONFLICT or RECEIPT_ALREADY_CONFIRMED.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/sites/{siteId}/adjustments

Adjust on-hand stock at a site

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/stock/v1/sites/example-id/adjustments"

Operation ID: adjustStock

Parameters

Name	In	Type	Description
siteId*	path	string (uuid)	Directory location id for venue stock (see docs/SERVICE_BOUNDARY.md).

Request body(required)

application/jsonStockAdjustCreate

Responses

201
Adjusted
application/json
400
Malformed request. `error.code` is typically INVALID_REQUEST.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is a resource-specific *_NOT_FOUND value.
application/json
409
The change conflicts with current state. `error.code`: CONFLICT or RECEIPT_ALREADY_CONFIRMED.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/sites/{siteId}/waste

Record wasted stock (reduces on-hand quantity)

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/stock/v1/sites/example-id/waste"

Operation ID: wasteStock

Parameters

Name	In	Type	Description
siteId*	path	string (uuid)	Directory location id for venue stock (see docs/SERVICE_BOUNDARY.md).

Request body(required)

application/jsonStockWasteCreate

Responses

201
Wasted
application/json
400
Malformed request. `error.code` is typically INVALID_REQUEST.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is a resource-specific *_NOT_FOUND value.
application/json
409
The change conflicts with current state. `error.code`: CONFLICT or RECEIPT_ALREADY_CONFIRMED.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

get/v1/sites/{siteId}/movements

List stock movements for a site

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/stock/v1/sites/example-id/movements"

Operation ID: listStockMovements

Parameters

Name	In	Type	Description
siteId*	path	string (uuid)	Directory location id for venue stock (see docs/SERVICE_BOUNDARY.md).
limit	query	integer	—
offset	query	integer	—

Responses

200
Movements
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

get/v1/brands/{brandId}/dispatch-batches

List dispatch QR codes for a group

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/stock/v1/brands/example-id/dispatch-batches"

Operation ID: listDispatchBatches

Parameters

Name	In	Type	Description
brandId*	path	string (uuid)	Directory location group id.

Responses

200
Dispatch batches
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/brands/{brandId}/dispatch-batches

Create or link a reusable dispatch QR code

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
  
}' \
  "https://api.mayawealth.co.uk/stock/v1/brands/example-id/dispatch-batches"

Operation ID: createDispatchBatch

Parameters

Name	In	Type	Description
brandId*	path	string (uuid)	Directory location group id.

Request body(required)

application/jsonobject

Responses

201
Created batch
application/json
400
Malformed request. `error.code` is typically INVALID_REQUEST.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is a resource-specific *_NOT_FOUND value.
application/json
409
The change conflicts with current state. `error.code`: CONFLICT or RECEIPT_ALREADY_CONFIRMED.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

get/v1/stock-items/{stockItemId}/dispatch-batches

List dispatch QR codes linked to a stock item

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/stock/v1/stock-items/example-id/dispatch-batches"

Operation ID: listStockItemDispatchBatches

Parameters

Name	In	Type	Description
stockItemId*	path	string (uuid)	—

Responses

200
Dispatch batches
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

delete/v1/dispatch-batches/{batchId}

Delete a dispatch QR code

Example request

curl -sS \
  -X DELETE \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/stock/v1/dispatch-batches/example-id"

Operation ID: deleteDispatchBatch

Parameters

Name	In	Type	Description
batchId*	path	string (uuid)	—

Responses

204
Deleted
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is a resource-specific *_NOT_FOUND value.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/dispatch-batches/{batchId}/items/{stockItemId}

Link a stock item to a dispatch QR code

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/stock/v1/dispatch-batches/example-id/items/example-id"

Operation ID: linkDispatchBatchItem

Parameters

Name	In	Type	Description
batchId*	path	string (uuid)	—
stockItemId*	path	string (uuid)	—

Responses

200
Updated batch
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is a resource-specific *_NOT_FOUND value.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

delete/v1/dispatch-batches/{batchId}/items/{stockItemId}

Remove a stock item link from a dispatch QR code

Example request

curl -sS \
  -X DELETE \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/stock/v1/dispatch-batches/example-id/items/example-id"

Operation ID: unlinkDispatchBatchItem

Parameters

Name	In	Type	Description
batchId*	path	string (uuid)	—
stockItemId*	path	string (uuid)	—

Responses

200
Updated batch
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is a resource-specific *_NOT_FOUND value.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

get/v1/dispatch-batches/by-qr/{qrToken}

Get a dispatch batch by QR token

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/stock/v1/dispatch-batches/by-qr/example-id"

Operation ID: getDispatchBatchByQr

Parameters

Name	In	Type	Description
qrToken*	path	string (uuid)	—

Responses

200
Dispatch batch
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is a resource-specific *_NOT_FOUND value.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/dispatch-batches/by-qr/{qrToken}/claim

Transfer stock from group to a location via dispatch QR

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
  
}' \
  "https://api.mayawealth.co.uk/stock/v1/dispatch-batches/by-qr/example-id/claim"

Operation ID: claimDispatchBatch

Parameters

Name	In	Type	Description
qrToken*	path	string (uuid)	—

Request body(required)

application/jsonobject

Responses

200
Claimed batch
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is a resource-specific *_NOT_FOUND value.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

Stock spots

QR-scannable storage locations within venue sites.

get/v1/sites/{siteId}/spots

List scannable stock spots for a venue site

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/stock/v1/sites/example-id/spots"

Operation ID: listStockSpots

Parameters

Name	In	Type	Description
siteId*	path	string (uuid)	Directory location id for venue stock (see docs/SERVICE_BOUNDARY.md).

Responses

200
Spots
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is a resource-specific *_NOT_FOUND value.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/sites/{siteId}/spots

Create a scannable stock spot

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/stock/v1/sites/example-id/spots"

Operation ID: createStockSpot

Parameters

Name	In	Type	Description
siteId*	path	string (uuid)	Directory location id for venue stock (see docs/SERVICE_BOUNDARY.md).

Request body(required)

application/jsonStockSpotCreate

Responses

201
Spot
application/json
400
Malformed request. `error.code` is typically INVALID_REQUEST.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is a resource-specific *_NOT_FOUND value.
application/json
409
The change conflicts with current state. `error.code`: CONFLICT or RECEIPT_ALREADY_CONFIRMED.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

patch/v1/spots/{spotId}

Update a stock spot

Example request

curl -sS \
  -X PATCH \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/stock/v1/spots/example-id"

Operation ID: updateStockSpot

Parameters

Name	In	Type	Description
spotId*	path	string (uuid)	—

Request body(required)

application/jsonStockSpotUpdate

Responses

200
Spot
application/json
400
Malformed request. `error.code` is typically INVALID_REQUEST.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is a resource-specific *_NOT_FOUND value.
application/json
409
The change conflicts with current state. `error.code`: CONFLICT or RECEIPT_ALREADY_CONFIRMED.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

get/v1/spots/by-qr/{qrToken}

Resolve a stock spot from its QR token

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/stock/v1/spots/by-qr/example-id"

Operation ID: getStockSpotByQr

Parameters

Name	In	Type	Description
qrToken*	path	string (uuid)	—

Responses

200
Spot
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is a resource-specific *_NOT_FOUND value.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

get/v1/spots/{spotId}/balances

List on-hand stock at a spot

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/stock/v1/spots/example-id/balances"

Operation ID: listStockSpotBalances

Parameters

Name	In	Type	Description
spotId*	path	string (uuid)	—

Responses

200
Spot balances
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is a resource-specific *_NOT_FOUND value.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

get/v1/sites/{siteId}/unassigned-balances

List site stock not yet placed at a spot

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/stock/v1/sites/example-id/unassigned-balances"

Operation ID: listUnassignedBalances

Parameters

Name	In	Type	Description
siteId*	path	string (uuid)	Directory location id for venue stock (see docs/SERVICE_BOUNDARY.md).

Responses

200
Unassigned balances
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is a resource-specific *_NOT_FOUND value.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

get/v1/sites/{siteId}/spot-summary

Spot list with on-hand totals

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/stock/v1/sites/example-id/spot-summary"

Operation ID: getStockSpotSummary

Parameters

Name	In	Type	Description
siteId*	path	string (uuid)	Directory location id for venue stock (see docs/SERVICE_BOUNDARY.md).

Responses

200
Spot summary
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is a resource-specific *_NOT_FOUND value.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/sites/{siteId}/spot-relocations

Place or move stock between spots and unassigned pool

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/stock/v1/sites/example-id/spot-relocations"

Operation ID: relocateStockAtSite

Parameters

Name	In	Type	Description
siteId*	path	string (uuid)	Directory location id for venue stock (see docs/SERVICE_BOUNDARY.md).

Request body(required)

application/jsonStockSpotRelocationCreate

Responses

201
Relocated
application/json
400
Malformed request. `error.code` is typically INVALID_REQUEST.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is a resource-specific *_NOT_FOUND value.
application/json
409
The change conflicts with current state. `error.code`: CONFLICT or RECEIPT_ALREADY_CONFIRMED.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

Delivery notes

Upload delivery notes and receive stock from extracted lines.

post/v1/delivery-notes

Upload a delivery note and extract stock lines

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/stock/v1/delivery-notes"

Operation ID: uploadDeliveryNote

Request body(required)

multipart/form-dataDeliveryNoteUpload

Responses

201
Delivery note draft
application/json
400
Malformed request. `error.code` is typically INVALID_REQUEST.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is a resource-specific *_NOT_FOUND value.
application/json
409
The change conflicts with current state. `error.code`: CONFLICT or RECEIPT_ALREADY_CONFIRMED.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

get/v1/delivery-notes/{id}

Get a delivery note draft

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/stock/v1/delivery-notes/example-id"

Operation ID: getDeliveryNote

Parameters

Name	In	Type	Description
id*	path	string (uuid)	—

Responses

200
Delivery note
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is a resource-specific *_NOT_FOUND value.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

patch/v1/delivery-notes/{id}

Correct extracted delivery note values

Example request

curl -sS \
  -X PATCH \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/stock/v1/delivery-notes/example-id"

Operation ID: updateDeliveryNote

Parameters

Name	In	Type	Description
id*	path	string (uuid)	—

Request body(required)

application/jsonDeliveryNotePatch

Responses

200
Updated delivery note
application/json
400
Malformed request. `error.code` is typically INVALID_REQUEST.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is a resource-specific *_NOT_FOUND value.
application/json
409
The change conflicts with current state. `error.code`: CONFLICT or RECEIPT_ALREADY_CONFIRMED.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

get/v1/delivery-notes/{id}/file

Download the original delivery note file

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/stock/v1/delivery-notes/example-id/file"

Operation ID: getDeliveryNoteFile

Parameters

Name	In	Type	Description
id*	path	string (uuid)	—

Responses

200
Original file
application/octet-stream
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is a resource-specific *_NOT_FOUND value.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/delivery-notes/{id}/extract

Re-run delivery note extraction

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/stock/v1/delivery-notes/example-id/extract"

Operation ID: extractDeliveryNote

Parameters

Name	In	Type	Description
id*	path	string (uuid)	—

Responses

200
Delivery note with extraction
application/json
400
Malformed request. `error.code` is typically INVALID_REQUEST.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is a resource-specific *_NOT_FOUND value.
application/json
409
The change conflicts with current state. `error.code`: CONFLICT or RECEIPT_ALREADY_CONFIRMED.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/delivery-notes/{id}/confirm

Confirm a delivery note and receive stock

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/stock/v1/delivery-notes/example-id/confirm"

Operation ID: confirmDeliveryNote

Parameters

Name	In	Type	Description
id*	path	string (uuid)	—

Request body(required)

application/jsonDeliveryNoteConfirm

Responses

201
Confirmed delivery note
application/json
400
Malformed request. `error.code` is typically INVALID_REQUEST.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is a resource-specific *_NOT_FOUND value.
application/json
409
The change conflicts with current state. `error.code`: CONFLICT or RECEIPT_ALREADY_CONFIRMED.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

get/v1/sites/{siteId}/delivery-notes

List delivery notes for a site

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/stock/v1/sites/example-id/delivery-notes"

Operation ID: listDeliveryNotes

Parameters

Name	In	Type	Description
siteId*	path	string (uuid)	Directory location id for venue stock (see docs/SERVICE_BOUNDARY.md).
limit	query	integer	—
offset	query	integer	—

Responses

200
Delivery notes
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

Audit

Immutable activity log for stock operations.

get/v1/audit

Stock audit trail

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/stock/v1/audit"

Operation ID: listStockAudit

Responses

200
Audit events
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

Financials

Sales, cash-up, waste cost, and profit vs target.

get/v1/sites/{siteId}/sales

List recorded sales

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/stock/v1/sites/example-id/sales"

Operation ID: listStockSales

Parameters

Name	In	Type	Description
siteId*	path	string (uuid)	Directory location id for venue stock (see docs/SERVICE_BOUNDARY.md).
limit	query	integer	—
offset	query	integer	—

Responses

200
Sales
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/sites/{siteId}/sales

Record sales for a business day (manual or POS ingest)

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/stock/v1/sites/example-id/sales"

Operation ID: recordStockSale

Parameters

Name	In	Type	Description
siteId*	path	string (uuid)	Directory location id for venue stock (see docs/SERVICE_BOUNDARY.md).

Request body(required)

application/jsonStockSaleCreate

Responses

201
Sale recorded
application/json
400
Malformed request. `error.code` is typically INVALID_REQUEST.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is a resource-specific *_NOT_FOUND value.
application/json
409
The change conflicts with current state. `error.code`: CONFLICT or RECEIPT_ALREADY_CONFIRMED.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

get/v1/sites/{siteId}/cash-ups

List cash-ups

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/stock/v1/sites/example-id/cash-ups"

Operation ID: listStockCashUps

Parameters

Name	In	Type	Description
siteId*	path	string (uuid)	Directory location id for venue stock (see docs/SERVICE_BOUNDARY.md).
limit	query	integer	—
offset	query	integer	—

Responses

200
Cash-ups
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/sites/{siteId}/cash-ups

Record a cash-up (float, till count, POS Z-read variance)

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/stock/v1/sites/example-id/cash-ups"

Operation ID: recordStockCashUp

Parameters

Name	In	Type	Description
siteId*	path	string (uuid)	Directory location id for venue stock (see docs/SERVICE_BOUNDARY.md).

Request body(required)

application/jsonStockCashUpCreate

Responses

201
Cash-up recorded
application/json
400
Malformed request. `error.code` is typically INVALID_REQUEST.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is a resource-specific *_NOT_FOUND value.
application/json
409
The change conflicts with current state. `error.code`: CONFLICT or RECEIPT_ALREADY_CONFIRMED.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

get/v1/sites/{siteId}/profit-loss

Profit and loss summary for a date range

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/stock/v1/sites/example-id/profit-loss"

Operation ID: getSiteProfitLoss

Parameters

Name	In	Type	Description
siteId*	path	string (uuid)	Directory location id for venue stock (see docs/SERVICE_BOUNDARY.md).
fromDate*	query	string	—
toDate*	query	string	—

Responses

200
Profit and loss
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

get/v1/sites/{siteId}/weekly-profit

Weekly profit vs target

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/stock/v1/sites/example-id/weekly-profit"

Operation ID: getSiteWeeklyProfit

Parameters

Name	In	Type	Description
siteId*	path	string (uuid)	Directory location id for venue stock (see docs/SERVICE_BOUNDARY.md).
weekStart*	query	string	—

Responses

200
Weekly profit
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

put/v1/sites/{siteId}/profit-targets

Set weekly profit target

Example request

curl -sS \
  -X PUT \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/stock/v1/sites/example-id/profit-targets"

Operation ID: upsertSiteProfitTarget

Parameters

Name	In	Type	Description
siteId*	path	string (uuid)	Directory location id for venue stock (see docs/SERVICE_BOUNDARY.md).

Request body(required)

application/jsonProfitTargetUpsert

Responses

200
Target saved
application/json
400
Malformed request. `error.code` is typically INVALID_REQUEST.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is a resource-specific *_NOT_FOUND value.
application/json
409
The change conflicts with current state. `error.code`: CONFLICT or RECEIPT_ALREADY_CONFIRMED.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

Ordering

Delivery schedules, calendar, and order lists.

get/v1/sites/{siteId}/delivery-schedules

List delivery schedules

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/stock/v1/sites/example-id/delivery-schedules"

Operation ID: listDeliverySchedules

Parameters

Name	In	Type	Description
siteId*	path	string (uuid)	Directory location id for venue stock (see docs/SERVICE_BOUNDARY.md).
limit	query	integer	—
offset	query	integer	—

Responses

200
Schedules
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/sites/{siteId}/delivery-schedules

Create a delivery schedule

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/stock/v1/sites/example-id/delivery-schedules"

Operation ID: createDeliverySchedule

Parameters

Name	In	Type	Description
siteId*	path	string (uuid)	Directory location id for venue stock (see docs/SERVICE_BOUNDARY.md).

Request body(required)

application/jsonDeliveryScheduleCreate

Responses

201
Schedule
application/json
400
Malformed request. `error.code` is typically INVALID_REQUEST.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is a resource-specific *_NOT_FOUND value.
application/json
409
The change conflicts with current state. `error.code`: CONFLICT or RECEIPT_ALREADY_CONFIRMED.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

patch/v1/delivery-schedules/{id}

Update a delivery schedule

Example request

curl -sS \
  -X PATCH \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/stock/v1/delivery-schedules/example-id"

Operation ID: updateDeliverySchedule

Parameters

Name	In	Type	Description
id*	path	string (uuid)	—

Request body(required)

application/jsonDeliveryScheduleUpdate

Responses

200
Schedule
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is a resource-specific *_NOT_FOUND value.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

get/v1/sites/{siteId}/delivery-calendar

Delivery calendar occurrences

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/stock/v1/sites/example-id/delivery-calendar"

Operation ID: getDeliveryCalendar

Parameters

Name	In	Type	Description
siteId*	path	string (uuid)	Directory location id for venue stock (see docs/SERVICE_BOUNDARY.md).
fromDate*	query	string	—
toDate*	query	string	—

Responses

200
Calendar
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

post/v1/sites/{siteId}/order-lists/generate

Generate a recommended order list

Example request

curl -sS \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/stock/v1/sites/example-id/order-lists/generate"

Operation ID: generateOrderList

Parameters

Name	In	Type	Description
siteId*	path	string (uuid)	Directory location id for venue stock (see docs/SERVICE_BOUNDARY.md).

Request body(required)

application/jsonOrderListGenerate

Responses

201
Order list
application/json
400
Malformed request. `error.code` is typically INVALID_REQUEST.
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is a resource-specific *_NOT_FOUND value.
application/json
409
The change conflicts with current state. `error.code`: CONFLICT or RECEIPT_ALREADY_CONFIRMED.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

get/v1/sites/{siteId}/order-lists

List order lists

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/stock/v1/sites/example-id/order-lists"

Operation ID: listOrderLists

Parameters

Name	In	Type	Description
siteId*	path	string (uuid)	Directory location id for venue stock (see docs/SERVICE_BOUNDARY.md).
limit	query	integer	—
offset	query	integer	—

Responses

200
Order lists
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

get/v1/order-lists/{id}

Get an order list

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/stock/v1/order-lists/example-id"

Operation ID: getOrderList

Parameters

Name	In	Type	Description
id*	path	string (uuid)	—

Responses

200
Order list
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is a resource-specific *_NOT_FOUND value.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

get/v1/takes/{id}/order-list

Order list generated from a stock take

Example request

curl -sS \
  -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  "https://api.mayawealth.co.uk/stock/v1/takes/example-id/order-list"

Operation ID: getTakeOrderList

Parameters

Name	In	Type	Description
id*	path	string (uuid)	—

Responses

200
Order list
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is a resource-specific *_NOT_FOUND value.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json

patch/v1/order-lists/{id}/lines

Update order quantities

Example request

curl -sS \
  -X PATCH \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  "https://api.mayawealth.co.uk/stock/v1/order-lists/example-id/lines"

Operation ID: patchOrderListLines

Parameters

Name	In	Type	Description
id*	path	string (uuid)	—

Request body(required)

application/jsonOrderListLinesPatch

Responses

200
Order list
application/json
401
Missing or invalid JWT. `error.code`: UNAUTHORIZED. Send `Authorization: Bearer <jwt>`.
application/json
403
Authenticated but not permitted. `error.code`: FORBIDDEN. Actor types: admin, area-manager, manager, member.
application/json
404
The requested resource was not found. `error.code` is a resource-specific *_NOT_FOUND value.
application/json
422
Validation failed. `error.code`: VALIDATION_ERROR. Typical cause: organisation not created yet or invalid body.
application/json
429
Rate limit exceeded. `error.code`: RATE_LIMITED.
application/json
500
Unexpected server error. `error.code`: INTERNAL.
application/json