API reference

Purchasing

35 requests. Each shows the permission a key needs, what to send and what comes back.

On this page

Products and materials charged to clients, newest first, with what is not invoiced yet

GET/v1/client-charges

Permission: purchase.view
Module: purchases
Answers: 200

Parameters

Name	In	Kind
`clientId`	query	uuid
`projectId`	query	uuid
`uninvoiced`	query	enum	One of `true`, `false`

Response object

chargesarray of objectrequired
- iduuidrequired
- clientIduuidrequired
- clientNamestringrequired
- projectIduuidrequiredcan be null
- projectNamestringrequiredcan be null
- bookingIduuidrequiredcan be null
- datedaterequired
  YYYY-MM-DD
- descriptionstringrequired
- quantityX100integerrequired
  -9007199254740991 to 9007199254740991
- unitCostPenceintegerrequired
  -9007199254740991 to 9007199254740991
- unitSellPenceintegerrequired
  -9007199254740991 to 9007199254740991
- netPenceintegerrequired
  -9007199254740991 to 9007199254740991
- vatRateBpintegerrequiredcan be null
  -9007199254740991 to 9007199254740991
- sourceenumrequired
  One of "order", "stock"
- orderIduuidrequiredcan be null
- orderReferencestringrequiredcan be null
- productIduuidrequiredcan be null
- invoiceobjectrequiredcan be null
  - iduuidrequired
  - referencestringrequiredcan be null
  - statusstringrequired
- createdAtstringrequired
uninvoicedPenceintegerrequired
-9007199254740991 to 9007199254740991
uninvoicedCountintegerrequired
-9007199254740991 to 9007199254740991

curl "https://app.workscope.co.uk/v1/client-charges" \
  -H "Authorization: Bearer wsk_your_key_here"

Example response

{
  "charges": [
    {
      "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
      "clientId": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "clientName": "Harbourside Dental",
      "projectId": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
      "projectName": "1 Harbour Road",
      "bookingId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
      "date": "2026-11-06",
      "description": "Side gate code is on the key safe.",
      "quantityX100": -9007199254740991,
      "unitCostPence": 4500,
      "unitSellPence": 4500,
      "netPence": 4500,
      "vatRateBp": 1207,
      "source": "order",
      "orderId": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "orderReference": "INV-0042",
      "productId": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
      "invoice": {
        "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
        "reference": "INV-0042",
        "status": "text"
      },
      "createdAt": "2026-11-06T09:30:00.000Z"
    }
  ],
  "uninvoicedPence": 4500,
  "uninvoicedCount": 3
}

Change a charge that is not on an invoice yet

PATCH/v1/client-charges/{id}

Permission: purchase.manage
Module: purchases
Answers: 200

Parameters

Name	In	Kind
`id`	path	uuidrequired

Request body JSON

descriptionstringoptional
1–500 characters
quantityX100integeroptional
1 to 100000000
unitSellPenceintegeroptional
0 to 100000000
datedateoptional
YYYY-MM-DD
projectIduuidoptionalcan be null

Response object

iduuidrequired
clientIduuidrequired
clientNamestringrequired
projectIduuidrequiredcan be null
projectNamestringrequiredcan be null
bookingIduuidrequiredcan be null
datedaterequired
YYYY-MM-DD
descriptionstringrequired
quantityX100integerrequired
-9007199254740991 to 9007199254740991
unitCostPenceintegerrequired
-9007199254740991 to 9007199254740991
unitSellPenceintegerrequired
-9007199254740991 to 9007199254740991
netPenceintegerrequired
-9007199254740991 to 9007199254740991
vatRateBpintegerrequiredcan be null
-9007199254740991 to 9007199254740991
sourceenumrequired
One of "order", "stock"
orderIduuidrequiredcan be null
orderReferencestringrequiredcan be null
productIduuidrequiredcan be null
invoiceobjectrequiredcan be null
- iduuidrequired
- referencestringrequiredcan be null
- statusstringrequired
createdAtstringrequired

curl -X PATCH "https://app.workscope.co.uk/v1/client-charges/ID" \
  -H "Authorization: Bearer wsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Side gate code is on the key safe.",
    "quantityX100": 1,
    "unitSellPence": 4500,
    "date": "2026-11-06",
    "projectId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41"
  }'

Example response

{
  "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "clientId": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "clientName": "Harbourside Dental",
  "projectId": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
  "projectName": "1 Harbour Road",
  "bookingId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "date": "2026-11-06",
  "description": "Side gate code is on the key safe.",
  "quantityX100": -9007199254740991,
  "unitCostPence": 4500,
  "unitSellPence": 4500,
  "netPence": 4500,
  "vatRateBp": 1207,
  "source": "order",
  "orderId": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "orderReference": "INV-0042",
  "productId": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
  "invoice": {
    "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
    "reference": "INV-0042",
    "status": "text"
  },
  "createdAt": "2026-11-06T09:30:00.000Z"
}

Take off a charge that is not on an invoice (one from stock goes back into stock)

DELETE/v1/client-charges/{id}

Permission: purchase.manage
Module: purchases
Answers: 200

Parameters

Name	In	Kind
`id`	path	uuidrequired

Response object

okconstantrequired
Always true

curl -X DELETE "https://app.workscope.co.uk/v1/client-charges/ID" \
  -H "Authorization: Bearer wsk_your_key_here"

Example response

{
  "ok": true
}

A client's own markup on purchases (null: the company's)

GET/v1/clients/{id}/markup

Permission: purchase.view
Module: purchases
Answers: 200

Parameters

Name	In	Kind
`id`	path	uuidrequired

Response object

markupBpintegerrequiredcan be null
-9007199254740991 to 9007199254740991

curl "https://app.workscope.co.uk/v1/clients/ID/markup" \
  -H "Authorization: Bearer wsk_your_key_here"

Example response

{
  "markupBp": 1207
}

Set a client's own markup, or null for the company's

PUT/v1/clients/{id}/markup

Permission: purchase.manage
Module: purchases
Answers: 200

Parameters

Name	In	Kind
`id`	path	uuidrequired

Request body JSON

markupBpintegerrequiredcan be null
0 to 100000

Response object

markupBpintegerrequiredcan be null
-9007199254740991 to 9007199254740991

curl -X PUT "https://app.workscope.co.uk/v1/clients/ID/markup" \
  -H "Authorization: Bearer wsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "markupBp": 1207
  }'

Example response

{
  "markupBp": 1207
}

Products by name, with stock on hand (archived ones with archived=true)

GET/v1/products

Permission: purchase.view
Module: purchases
Answers: 200

Parameters

Name	In	Kind
`archived`	query	enum	One of `true`, `false`

Response array of object

iduuidrequired
namestringrequired
codestringrequiredcan be null
unitstringrequired
supplierIduuidrequiredcan be null
supplierNamestringrequiredcan be null
costPenceintegerrequiredcan be null
-9007199254740991 to 9007199254740991
sellPenceintegerrequiredcan be null
-9007199254740991 to 9007199254740991
sellAtMarkupPenceintegerrequiredcan be null
-9007199254740991 to 9007199254740991
vatRateBpintegerrequiredcan be null
-9007199254740991 to 9007199254740991
trackStockbooleanrequired
reorderLevelX100integerrequiredcan be null
-9007199254740991 to 9007199254740991
onHandX100integerrequired
-9007199254740991 to 9007199254740991
avgCostPenceintegerrequiredcan be null
-9007199254740991 to 9007199254740991
lowbooleanrequired
archivedbooleanrequired

curl "https://app.workscope.co.uk/v1/products" \
  -H "Authorization: Bearer wsk_your_key_here"

Example response

[
  {
    "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
    "name": "Harbourside Dental",
    "code": "text",
    "unit": "text",
    "supplierId": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
    "supplierName": "Harbourside Dental",
    "costPence": 4500,
    "sellPence": 4500,
    "sellAtMarkupPence": 4500,
    "vatRateBp": 1207,
    "trackStock": false,
    "reorderLevelX100": -9007199254740991,
    "onHandX100": -9007199254740991,
    "avgCostPence": 4500,
    "low": false,
    "archived": false
  }
]

Add a product

POST/v1/products

Permission: purchase.manage
Module: purchases
Answers: 201

Request body JSON

namestringrequired
1–200 characters
codestringoptionalcan be null
Up to 100 characters
unitstringoptional
1–30 characters · Default "each"
supplierIduuidoptionalcan be null
costPenceintegeroptionalcan be null
0 to 100000000
sellPenceintegeroptionalcan be null
0 to 100000000
vatRateBpintegeroptionalcan be null
0 to 10000
trackStockbooleanoptional
Default false
reorderLevelX100integeroptionalcan be null
0 to 100000000

Response object

iduuidrequired
namestringrequired
codestringrequiredcan be null
unitstringrequired
supplierIduuidrequiredcan be null
supplierNamestringrequiredcan be null
costPenceintegerrequiredcan be null
-9007199254740991 to 9007199254740991
sellPenceintegerrequiredcan be null
-9007199254740991 to 9007199254740991
sellAtMarkupPenceintegerrequiredcan be null
-9007199254740991 to 9007199254740991
vatRateBpintegerrequiredcan be null
-9007199254740991 to 9007199254740991
trackStockbooleanrequired
reorderLevelX100integerrequiredcan be null
-9007199254740991 to 9007199254740991
onHandX100integerrequired
-9007199254740991 to 9007199254740991
avgCostPenceintegerrequiredcan be null
-9007199254740991 to 9007199254740991
lowbooleanrequired
archivedbooleanrequired

curl -X POST "https://app.workscope.co.uk/v1/products" \
  -H "Authorization: Bearer wsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Harbourside Dental",
    "code": "text",
    "unit": "each",
    "supplierId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
    "costPence": 4500,
    "sellPence": 4500,
    "vatRateBp": 1207,
    "trackStock": false,
    "reorderLevelX100": 0
  }'

Example response

{
  "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "name": "Harbourside Dental",
  "code": "text",
  "unit": "text",
  "supplierId": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "supplierName": "Harbourside Dental",
  "costPence": 4500,
  "sellPence": 4500,
  "sellAtMarkupPence": 4500,
  "vatRateBp": 1207,
  "trackStock": false,
  "reorderLevelX100": -9007199254740991,
  "onHandX100": -9007199254740991,
  "avgCostPence": 4500,
  "low": false,
  "archived": false
}

Change or archive a product

PATCH/v1/products/{id}

Permission: purchase.manage
Module: purchases
Answers: 200

Parameters

Name	In	Kind
`id`	path	uuidrequired

Request body JSON

namestringoptional
1–200 characters
codestringoptionalcan be null
Up to 100 characters
unitstringoptional
1–30 characters · Default "each"
supplierIduuidoptionalcan be null
costPenceintegeroptionalcan be null
0 to 100000000
sellPenceintegeroptionalcan be null
0 to 100000000
vatRateBpintegeroptionalcan be null
0 to 10000
trackStockbooleanoptional
Default false
reorderLevelX100integeroptionalcan be null
0 to 100000000
archivedbooleanoptional

Response object

iduuidrequired
namestringrequired
codestringrequiredcan be null
unitstringrequired
supplierIduuidrequiredcan be null
supplierNamestringrequiredcan be null
costPenceintegerrequiredcan be null
-9007199254740991 to 9007199254740991
sellPenceintegerrequiredcan be null
-9007199254740991 to 9007199254740991
sellAtMarkupPenceintegerrequiredcan be null
-9007199254740991 to 9007199254740991
vatRateBpintegerrequiredcan be null
-9007199254740991 to 9007199254740991
trackStockbooleanrequired
reorderLevelX100integerrequiredcan be null
-9007199254740991 to 9007199254740991
onHandX100integerrequired
-9007199254740991 to 9007199254740991
avgCostPenceintegerrequiredcan be null
-9007199254740991 to 9007199254740991
lowbooleanrequired
archivedbooleanrequired

curl -X PATCH "https://app.workscope.co.uk/v1/products/ID" \
  -H "Authorization: Bearer wsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Harbourside Dental",
    "code": "text",
    "unit": "each",
    "supplierId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
    "costPence": 4500,
    "sellPence": 4500,
    "vatRateBp": 1207,
    "trackStock": false,
    "reorderLevelX100": 0,
    "archived": false
  }'

Example response

{
  "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "name": "Harbourside Dental",
  "code": "text",
  "unit": "text",
  "supplierId": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "supplierName": "Harbourside Dental",
  "costPence": 4500,
  "sellPence": 4500,
  "sellAtMarkupPence": 4500,
  "vatRateBp": 1207,
  "trackStock": false,
  "reorderLevelX100": -9007199254740991,
  "onHandX100": -9007199254740991,
  "avgCostPence": 4500,
  "low": false,
  "archived": false
}

Delete a product never ordered or stocked (archive it otherwise)

DELETE/v1/products/{id}

Permission: purchase.manage
Module: purchases
Answers: 200

Parameters

Name	In	Kind
`id`	path	uuidrequired

Response object

okconstantrequired
Always true

curl -X DELETE "https://app.workscope.co.uk/v1/products/ID" \
  -H "Authorization: Bearer wsk_your_key_here"

Example response

{
  "ok": true
}

Count the stock of a product, or add or take some away, saying why

POST/v1/products/{id}/adjust

Permission: purchase.manage
Module: purchases
Answers: 200

Parameters

Name	In	Kind
`id`	path	uuidrequired

Request body JSON

modeenumrequired
One of "count", "change"
quantityX100integerrequired
-100000000 to 100000000
reasonstringrequired
1–500 characters
unitCostPenceintegeroptional
0 to 100000000

Response object

iduuidrequired
namestringrequired
codestringrequiredcan be null
unitstringrequired
supplierIduuidrequiredcan be null
supplierNamestringrequiredcan be null
costPenceintegerrequiredcan be null
-9007199254740991 to 9007199254740991
sellPenceintegerrequiredcan be null
-9007199254740991 to 9007199254740991
sellAtMarkupPenceintegerrequiredcan be null
-9007199254740991 to 9007199254740991
vatRateBpintegerrequiredcan be null
-9007199254740991 to 9007199254740991
trackStockbooleanrequired
reorderLevelX100integerrequiredcan be null
-9007199254740991 to 9007199254740991
onHandX100integerrequired
-9007199254740991 to 9007199254740991
avgCostPenceintegerrequiredcan be null
-9007199254740991 to 9007199254740991
lowbooleanrequired
archivedbooleanrequired

curl -X POST "https://app.workscope.co.uk/v1/products/ID/adjust" \
  -H "Authorization: Bearer wsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "count",
    "quantityX100": -100000000,
    "reason": "text",
    "unitCostPence": 4500
  }'

Example response

{
  "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "name": "Harbourside Dental",
  "code": "text",
  "unit": "text",
  "supplierId": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "supplierName": "Harbourside Dental",
  "costPence": 4500,
  "sellPence": 4500,
  "sellAtMarkupPence": 4500,
  "vatRateBp": 1207,
  "trackStock": false,
  "reorderLevelX100": -9007199254740991,
  "onHandX100": -9007199254740991,
  "avgCostPence": 4500,
  "low": false,
  "archived": false
}

Take some from stock for a client: it becomes a charge on their next invoice

POST/v1/products/{id}/issue

Permission: purchase.manage
Module: purchases
Answers: 201

Parameters

Name	In	Kind
`id`	path	uuidrequired

Request body JSON

quantityX100integerrequired
1 to 100000000
clientIduuidrequired
projectIduuidoptionalcan be null
bookingIduuidoptionalcan be null
datedateoptional
YYYY-MM-DD
unitSellPenceintegeroptionalcan be null
0 to 100000000
descriptionstringoptionalcan be null
Up to 500 characters

Response object

iduuidrequired
clientIduuidrequired
clientNamestringrequired
projectIduuidrequiredcan be null
projectNamestringrequiredcan be null
bookingIduuidrequiredcan be null
datedaterequired
YYYY-MM-DD
descriptionstringrequired
quantityX100integerrequired
-9007199254740991 to 9007199254740991
unitCostPenceintegerrequired
-9007199254740991 to 9007199254740991
unitSellPenceintegerrequired
-9007199254740991 to 9007199254740991
netPenceintegerrequired
-9007199254740991 to 9007199254740991
vatRateBpintegerrequiredcan be null
-9007199254740991 to 9007199254740991
sourceenumrequired
One of "order", "stock"
orderIduuidrequiredcan be null
orderReferencestringrequiredcan be null
productIduuidrequiredcan be null
invoiceobjectrequiredcan be null
- iduuidrequired
- referencestringrequiredcan be null
- statusstringrequired
createdAtstringrequired

curl -X POST "https://app.workscope.co.uk/v1/products/ID/issue" \
  -H "Authorization: Bearer wsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "quantityX100": 1,
    "clientId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
    "projectId": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
    "bookingId": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
    "date": "2026-11-06",
    "unitSellPence": 4500,
    "description": "Side gate code is on the key safe."
  }'

Example response

{
  "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "clientId": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "clientName": "Harbourside Dental",
  "projectId": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
  "projectName": "1 Harbour Road",
  "bookingId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "date": "2026-11-06",
  "description": "Side gate code is on the key safe.",
  "quantityX100": -9007199254740991,
  "unitCostPence": 4500,
  "unitSellPence": 4500,
  "netPence": 4500,
  "vatRateBp": 1207,
  "source": "order",
  "orderId": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "orderReference": "INV-0042",
  "productId": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
  "invoice": {
    "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
    "reference": "INV-0042",
    "status": "text"
  },
  "createdAt": "2026-11-06T09:30:00.000Z"
}

A product's stock movements, newest first

GET/v1/products/{id}/movements

Permission: purchase.view
Module: purchases
Answers: 200

Parameters

Name	In	Kind
`id`	path	uuidrequired

Response array of object

iduuidrequired
kindenumrequired
One of "received", "issued", "adjusted", "returned"
quantityX100integerrequired
-9007199254740991 to 9007199254740991
unitCostPenceintegerrequiredcan be null
-9007199254740991 to 9007199254740991
reasonstringrequiredcan be null
referencestringrequiredcan be null
clientNamestringrequiredcan be null
byNamestringrequiredcan be null
atstringrequired

curl "https://app.workscope.co.uk/v1/products/ID/movements" \
  -H "Authorization: Bearer wsk_your_key_here"

Example response

[
  {
    "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
    "kind": "received",
    "quantityX100": -9007199254740991,
    "unitCostPence": 4500,
    "reason": "text",
    "reference": "INV-0042",
    "clientName": "Harbourside Dental",
    "byName": "Harbourside Dental",
    "at": "2026-11-06T09:30:00.000Z"
  }
]

Purchase orders, newest first

GET/v1/purchase-orders

Permission: purchase.view
Module: purchases
Answers: 200

Parameters

Name	In	Kind
`status`	query	enum	One of `draft`, `ordered`, `part_received`, `received`, `cancelled`, `open`
`supplierId`	query	uuid
`clientId`	query	uuid
`q`	query	string

Response array of object

iduuidrequired
referencestringrequiredcan be null
statusenumrequired
One of "draft", "ordered", "part_received", "received", "cancelled"
supplierIduuidrequiredcan be null
supplierNamestringrequired
fromStockbooleanrequired
destinationenumrequired
One of "stock", "client"
clientIduuidrequiredcan be null
clientNamestringrequiredcan be null
projectIduuidrequiredcan be null
projectNamestringrequiredcan be null
mixedbooleanrequired
orderDatedaterequiredcan be null
YYYY-MM-DD
expectedDatedaterequiredcan be null
YYYY-MM-DD
supplierRefstringrequiredcan be null
netPenceintegerrequired
-9007199254740991 to 9007199254740991
vatPenceintegerrequired
-9007199254740991 to 9007199254740991
grossPenceintegerrequired
-9007199254740991 to 9007199254740991
lineCountintegerrequired
-9007199254740991 to 9007199254740991
destinationsstringrequired
createdAtstringrequired

curl "https://app.workscope.co.uk/v1/purchase-orders" \
  -H "Authorization: Bearer wsk_your_key_here"

Example response

[
  {
    "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
    "reference": "INV-0042",
    "status": "draft",
    "supplierId": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
    "supplierName": "Harbourside Dental",
    "fromStock": false,
    "destination": "stock",
    "clientId": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
    "clientName": "Harbourside Dental",
    "projectId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
    "projectName": "1 Harbour Road",
    "mixed": false,
    "orderDate": "2026-11-06",
    "expectedDate": "2026-11-06",
    "supplierRef": "text",
    "netPence": 4500,
    "vatPence": 4500,
    "grossPence": 4500,
    "lineCount": 3,
    "destinations": "text",
    "createdAt": "2026-11-06T09:30:00.000Z"
  }
]

Start an order (a draft, no number yet)

POST/v1/purchase-orders

Permission: purchase.manage
Module: purchases
Answers: 201

Request body JSON

supplierIduuidoptionalcan be null
newSupplierobjectoptional
- namestringrequired
  1–200 characters
- emailemail or constantoptionalcan be null
- phonestringoptionalcan be null
  Up to 100 characters
fromStockbooleanoptional
Default false
destinationenumoptional
One of "stock", "client"
clientIduuidoptionalcan be null
projectIduuidoptionalcan be null
orderDatedateoptionalcan be null
YYYY-MM-DD
expectedDatedateoptionalcan be null
YYYY-MM-DD
deliverTostringoptionalcan be null
Up to 2000 characters
notesstringoptionalcan be null
Up to 2000 characters
linesarray of objectrequired
Up to 200 items
- iduuidoptionalcan be null
- productIduuidoptionalcan be null
- descriptionstringrequired
  1–500 characters
- supplierCodestringoptionalcan be null
  Up to 100 characters
- unitstringoptional
  1–30 characters · Default "each"
- quantityX100integerrequired
  1 to 100000000
- unitCostPenceintegeroptional
  0 to 100000000 · Default 0
- vatRateBpintegeroptional
  0 to 10000 · Default 2000
- destinationenumoptional
  One of "stock", "client"
- clientIduuidoptionalcan be null
- projectIduuidoptionalcan be null
- markupBpintegeroptionalcan be null
  0 to 100000
- saveAsProductbooleanoptional
  Default false

Response object

iduuidrequired
referencestringrequiredcan be null
statusenumrequired
One of "draft", "ordered", "part_received", "received", "cancelled"
supplierIduuidrequiredcan be null
supplierNamestringrequired
fromStockbooleanrequired
destinationenumrequired
One of "stock", "client"
clientIduuidrequiredcan be null
clientNamestringrequiredcan be null
projectIduuidrequiredcan be null
projectNamestringrequiredcan be null
mixedbooleanrequired
orderDatedaterequiredcan be null
YYYY-MM-DD
expectedDatedaterequiredcan be null
YYYY-MM-DD
supplierRefstringrequiredcan be null
netPenceintegerrequired
-9007199254740991 to 9007199254740991
vatPenceintegerrequired
-9007199254740991 to 9007199254740991
grossPenceintegerrequired
-9007199254740991 to 9007199254740991
lineCountintegerrequired
-9007199254740991 to 9007199254740991
destinationsstringrequired
createdAtstringrequired
supplierEmailstringrequiredcan be null
deliverTostringrequiredcan be null
notesstringrequiredcan be null
linesarray of objectrequired
- iduuidrequired
- productIduuidrequiredcan be null
- codestringrequiredcan be null
- supplierCodestringrequiredcan be null
- descriptionstringrequired
- unitstringrequired
- quantityX100integerrequired
  -9007199254740991 to 9007199254740991
- receivedX100integerrequired
  -9007199254740991 to 9007199254740991
- unitCostPenceintegerrequired
  -9007199254740991 to 9007199254740991
- vatRateBpintegerrequired
  -9007199254740991 to 9007199254740991
- netPenceintegerrequired
  -9007199254740991 to 9007199254740991
- destinationenumrequired
  One of "stock", "client"
- clientIduuidrequiredcan be null
- clientNamestringrequiredcan be null
- projectIduuidrequiredcan be null
- projectNamestringrequiredcan be null
- markupBpintegerrequiredcan be null
  -9007199254740991 to 9007199254740991
- unitSellPenceintegerrequiredcan be null
  -9007199254740991 to 9007199254740991
- lockedBystringrequiredcan be null
receiptsarray of objectrequired
- iduuidrequired
- receivedOndaterequired
  YYYY-MM-DD
- supplierRefstringrequiredcan be null
- byNamestringrequiredcan be null
- linesarray of objectrequired
  - descriptionstringrequired
  - quantityX100integerrequired
    -9007199254740991 to 9007199254740991
  - unitCostPenceintegerrequired
    -9007199254740991 to 9007199254740991
sentAtstringrequiredcan be null
cancelReasonstringrequiredcan be null

curl -X POST "https://app.workscope.co.uk/v1/purchase-orders" \
  -H "Authorization: Bearer wsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "supplierId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
    "newSupplier": {
      "name": "Harbourside Dental",
      "email": "office@example.co.uk",
      "phone": "0117 496 0123"
    },
    "fromStock": false,
    "destination": "stock",
    "clientId": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
    "projectId": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
    "orderDate": "2026-11-06",
    "expectedDate": "2026-11-06",
    "deliverTo": "text",
    "notes": "Side gate code is on the key safe.",
    "lines": [
      {
        "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
        "productId": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
        "description": "Side gate code is on the key safe.",
        "supplierCode": "text",
        "unit": "each",
        "quantityX100": 1,
        "unitCostPence": 0,
        "vatRateBp": 2000,
        "destination": "stock",
        "clientId": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
        "projectId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
        "markupBp": 1207,
        "saveAsProduct": false
      }
    ]
  }'

Example response

{
  "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "reference": "INV-0042",
  "status": "draft",
  "supplierId": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "supplierName": "Harbourside Dental",
  "fromStock": false,
  "destination": "stock",
  "clientId": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
  "clientName": "Harbourside Dental",
  "projectId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "projectName": "1 Harbour Road",
  "mixed": false,
  "orderDate": "2026-11-06",
  "expectedDate": "2026-11-06",
  "supplierRef": "text",
  "netPence": 4500,
  "vatPence": 4500,
  "grossPence": 4500,
  "lineCount": 3,
  "destinations": "text",
  "createdAt": "2026-11-06T09:30:00.000Z",
  "supplierEmail": "office@example.co.uk",
  "deliverTo": "text",
  "notes": "Side gate code is on the key safe.",
  "lines": [
    {
      "id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "productId": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
      "code": "text",
      "supplierCode": "text",
      "description": "Side gate code is on the key safe.",
      "unit": "text",
      "quantityX100": -9007199254740991,
      "receivedX100": -9007199254740991,
      "unitCostPence": 4500,
      "vatRateBp": 1207,
      "netPence": 4500,
      "destination": "stock",
      "clientId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
      "clientName": "Harbourside Dental",
      "projectId": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "projectName": "1 Harbour Road",
      "markupBp": 1207,
      "unitSellPence": 4500,
      "lockedBy": "text"
    }
  ],
  "receipts": [
    {
      "id": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
      "receivedOn": "2026-11-06",
      "supplierRef": "text",
      "byName": "Harbourside Dental",
      "lines": [
        {
          "description": "Side gate code is on the key safe.",
          "quantityX100": -9007199254740991,
          "unitCostPence": 4500
        }
      ]
    }
  ],
  "sentAt": "2026-11-06T09:30:00.000Z",
  "cancelReason": "text"
}

One order, its lines and what has arrived

GET/v1/purchase-orders/{id}

Permission: purchase.view
Module: purchases
Answers: 200

Parameters

Name	In	Kind
`id`	path	uuidrequired

Response object

iduuidrequired
referencestringrequiredcan be null
statusenumrequired
One of "draft", "ordered", "part_received", "received", "cancelled"
supplierIduuidrequiredcan be null
supplierNamestringrequired
fromStockbooleanrequired
destinationenumrequired
One of "stock", "client"
clientIduuidrequiredcan be null
clientNamestringrequiredcan be null
projectIduuidrequiredcan be null
projectNamestringrequiredcan be null
mixedbooleanrequired
orderDatedaterequiredcan be null
YYYY-MM-DD
expectedDatedaterequiredcan be null
YYYY-MM-DD
supplierRefstringrequiredcan be null
netPenceintegerrequired
-9007199254740991 to 9007199254740991
vatPenceintegerrequired
-9007199254740991 to 9007199254740991
grossPenceintegerrequired
-9007199254740991 to 9007199254740991
lineCountintegerrequired
-9007199254740991 to 9007199254740991
destinationsstringrequired
createdAtstringrequired
supplierEmailstringrequiredcan be null
deliverTostringrequiredcan be null
notesstringrequiredcan be null
linesarray of objectrequired
- iduuidrequired
- productIduuidrequiredcan be null
- codestringrequiredcan be null
- supplierCodestringrequiredcan be null
- descriptionstringrequired
- unitstringrequired
- quantityX100integerrequired
  -9007199254740991 to 9007199254740991
- receivedX100integerrequired
  -9007199254740991 to 9007199254740991
- unitCostPenceintegerrequired
  -9007199254740991 to 9007199254740991
- vatRateBpintegerrequired
  -9007199254740991 to 9007199254740991
- netPenceintegerrequired
  -9007199254740991 to 9007199254740991
- destinationenumrequired
  One of "stock", "client"
- clientIduuidrequiredcan be null
- clientNamestringrequiredcan be null
- projectIduuidrequiredcan be null
- projectNamestringrequiredcan be null
- markupBpintegerrequiredcan be null
  -9007199254740991 to 9007199254740991
- unitSellPenceintegerrequiredcan be null
  -9007199254740991 to 9007199254740991
- lockedBystringrequiredcan be null
receiptsarray of objectrequired
- iduuidrequired
- receivedOndaterequired
  YYYY-MM-DD
- supplierRefstringrequiredcan be null
- byNamestringrequiredcan be null
- linesarray of objectrequired
  - descriptionstringrequired
  - quantityX100integerrequired
    -9007199254740991 to 9007199254740991
  - unitCostPenceintegerrequired
    -9007199254740991 to 9007199254740991
sentAtstringrequiredcan be null
cancelReasonstringrequiredcan be null

curl "https://app.workscope.co.uk/v1/purchase-orders/ID" \
  -H "Authorization: Bearer wsk_your_key_here"

Example response

{
  "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "reference": "INV-0042",
  "status": "draft",
  "supplierId": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "supplierName": "Harbourside Dental",
  "fromStock": false,
  "destination": "stock",
  "clientId": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
  "clientName": "Harbourside Dental",
  "projectId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "projectName": "1 Harbour Road",
  "mixed": false,
  "orderDate": "2026-11-06",
  "expectedDate": "2026-11-06",
  "supplierRef": "text",
  "netPence": 4500,
  "vatPence": 4500,
  "grossPence": 4500,
  "lineCount": 3,
  "destinations": "text",
  "createdAt": "2026-11-06T09:30:00.000Z",
  "supplierEmail": "office@example.co.uk",
  "deliverTo": "text",
  "notes": "Side gate code is on the key safe.",
  "lines": [
    {
      "id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "productId": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
      "code": "text",
      "supplierCode": "text",
      "description": "Side gate code is on the key safe.",
      "unit": "text",
      "quantityX100": -9007199254740991,
      "receivedX100": -9007199254740991,
      "unitCostPence": 4500,
      "vatRateBp": 1207,
      "netPence": 4500,
      "destination": "stock",
      "clientId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
      "clientName": "Harbourside Dental",
      "projectId": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "projectName": "1 Harbour Road",
      "markupBp": 1207,
      "unitSellPence": 4500,
      "lockedBy": "text"
    }
  ],
  "receipts": [
    {
      "id": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
      "receivedOn": "2026-11-06",
      "supplierRef": "text",
      "byName": "Harbourside Dental",
      "lines": [
        {
          "description": "Side gate code is on the key safe.",
          "quantityX100": -9007199254740991,
          "unitCostPence": 4500
        }
      ]
    }
  ],
  "sentAt": "2026-11-06T09:30:00.000Z",
  "cancelReason": "text"
}

Change an order. A draft's lines are replaced as a whole; a placed or arrived order's lines are amended in place (send each line's id), with stock and client charges following

PATCH/v1/purchase-orders/{id}

Permission: purchase.manage
Module: purchases
Answers: 200

Parameters

Name	In	Kind
`id`	path	uuidrequired

Request body JSON

supplierIduuidoptionalcan be null
newSupplierobjectoptional
- namestringrequired
  1–200 characters
- emailemail or constantoptionalcan be null
- phonestringoptionalcan be null
  Up to 100 characters
destinationenumoptional
One of "stock", "client"
clientIduuidoptionalcan be null
projectIduuidoptionalcan be null
orderDatedateoptionalcan be null
YYYY-MM-DD
expectedDatedateoptionalcan be null
YYYY-MM-DD
deliverTostringoptionalcan be null
Up to 2000 characters
notesstringoptionalcan be null
Up to 2000 characters
linesarray of objectoptional
Up to 200 items
- iduuidoptionalcan be null
- productIduuidoptionalcan be null
- descriptionstringrequired
  1–500 characters
- supplierCodestringoptionalcan be null
  Up to 100 characters
- unitstringoptional
  1–30 characters · Default "each"
- quantityX100integerrequired
  1 to 100000000
- unitCostPenceintegeroptional
  0 to 100000000 · Default 0
- vatRateBpintegeroptional
  0 to 10000 · Default 2000
- destinationenumoptional
  One of "stock", "client"
- clientIduuidoptionalcan be null
- projectIduuidoptionalcan be null
- markupBpintegeroptionalcan be null
  0 to 100000
- saveAsProductbooleanoptional
  Default false

Response object

iduuidrequired
referencestringrequiredcan be null
statusenumrequired
One of "draft", "ordered", "part_received", "received", "cancelled"
supplierIduuidrequiredcan be null
supplierNamestringrequired
fromStockbooleanrequired
destinationenumrequired
One of "stock", "client"
clientIduuidrequiredcan be null
clientNamestringrequiredcan be null
projectIduuidrequiredcan be null
projectNamestringrequiredcan be null
mixedbooleanrequired
orderDatedaterequiredcan be null
YYYY-MM-DD
expectedDatedaterequiredcan be null
YYYY-MM-DD
supplierRefstringrequiredcan be null
netPenceintegerrequired
-9007199254740991 to 9007199254740991
vatPenceintegerrequired
-9007199254740991 to 9007199254740991
grossPenceintegerrequired
-9007199254740991 to 9007199254740991
lineCountintegerrequired
-9007199254740991 to 9007199254740991
destinationsstringrequired
createdAtstringrequired
supplierEmailstringrequiredcan be null
deliverTostringrequiredcan be null
notesstringrequiredcan be null
linesarray of objectrequired
- iduuidrequired
- productIduuidrequiredcan be null
- codestringrequiredcan be null
- supplierCodestringrequiredcan be null
- descriptionstringrequired
- unitstringrequired
- quantityX100integerrequired
  -9007199254740991 to 9007199254740991
- receivedX100integerrequired
  -9007199254740991 to 9007199254740991
- unitCostPenceintegerrequired
  -9007199254740991 to 9007199254740991
- vatRateBpintegerrequired
  -9007199254740991 to 9007199254740991
- netPenceintegerrequired
  -9007199254740991 to 9007199254740991
- destinationenumrequired
  One of "stock", "client"
- clientIduuidrequiredcan be null
- clientNamestringrequiredcan be null
- projectIduuidrequiredcan be null
- projectNamestringrequiredcan be null
- markupBpintegerrequiredcan be null
  -9007199254740991 to 9007199254740991
- unitSellPenceintegerrequiredcan be null
  -9007199254740991 to 9007199254740991
- lockedBystringrequiredcan be null
receiptsarray of objectrequired
- iduuidrequired
- receivedOndaterequired
  YYYY-MM-DD
- supplierRefstringrequiredcan be null
- byNamestringrequiredcan be null
- linesarray of objectrequired
  - descriptionstringrequired
  - quantityX100integerrequired
    -9007199254740991 to 9007199254740991
  - unitCostPenceintegerrequired
    -9007199254740991 to 9007199254740991
sentAtstringrequiredcan be null
cancelReasonstringrequiredcan be null

curl -X PATCH "https://app.workscope.co.uk/v1/purchase-orders/ID" \
  -H "Authorization: Bearer wsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "supplierId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
    "newSupplier": {
      "name": "Harbourside Dental",
      "email": "office@example.co.uk",
      "phone": "0117 496 0123"
    },
    "destination": "stock",
    "clientId": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
    "projectId": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
    "orderDate": "2026-11-06",
    "expectedDate": "2026-11-06",
    "deliverTo": "text",
    "notes": "Side gate code is on the key safe.",
    "lines": [
      {
        "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
        "productId": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
        "description": "Side gate code is on the key safe.",
        "supplierCode": "text",
        "unit": "each",
        "quantityX100": 1,
        "unitCostPence": 0,
        "vatRateBp": 2000,
        "destination": "stock",
        "clientId": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
        "projectId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
        "markupBp": 1207,
        "saveAsProduct": false
      }
    ]
  }'

Example response

{
  "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "reference": "INV-0042",
  "status": "draft",
  "supplierId": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "supplierName": "Harbourside Dental",
  "fromStock": false,
  "destination": "stock",
  "clientId": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
  "clientName": "Harbourside Dental",
  "projectId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "projectName": "1 Harbour Road",
  "mixed": false,
  "orderDate": "2026-11-06",
  "expectedDate": "2026-11-06",
  "supplierRef": "text",
  "netPence": 4500,
  "vatPence": 4500,
  "grossPence": 4500,
  "lineCount": 3,
  "destinations": "text",
  "createdAt": "2026-11-06T09:30:00.000Z",
  "supplierEmail": "office@example.co.uk",
  "deliverTo": "text",
  "notes": "Side gate code is on the key safe.",
  "lines": [
    {
      "id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "productId": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
      "code": "text",
      "supplierCode": "text",
      "description": "Side gate code is on the key safe.",
      "unit": "text",
      "quantityX100": -9007199254740991,
      "receivedX100": -9007199254740991,
      "unitCostPence": 4500,
      "vatRateBp": 1207,
      "netPence": 4500,
      "destination": "stock",
      "clientId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
      "clientName": "Harbourside Dental",
      "projectId": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "projectName": "1 Harbour Road",
      "markupBp": 1207,
      "unitSellPence": 4500,
      "lockedBy": "text"
    }
  ],
  "receipts": [
    {
      "id": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
      "receivedOn": "2026-11-06",
      "supplierRef": "text",
      "byName": "Harbourside Dental",
      "lines": [
        {
          "description": "Side gate code is on the key safe.",
          "quantityX100": -9007199254740991,
          "unitCostPence": 4500
        }
      ]
    }
  ],
  "sentAt": "2026-11-06T09:30:00.000Z",
  "cancelReason": "text"
}

Delete a draft order

DELETE/v1/purchase-orders/{id}

Permission: purchase.manage
Module: purchases
Answers: 200

Parameters

Name	In	Kind
`id`	path	uuidrequired

Response object

okconstantrequired
Always true

curl -X DELETE "https://app.workscope.co.uk/v1/purchase-orders/ID" \
  -H "Authorization: Bearer wsk_your_key_here"

Example response

{
  "ok": true
}

Mark the order as arrived (on a date, today if not given), at the costs on it; a draft is placed first

POST/v1/purchase-orders/{id}/arrived

Permission: purchase.manage
Module: purchases
Answers: 200

Parameters

Name	In	Kind
`id`	path	uuidrequired

Request body JSON

receivedOndateoptional
YYYY-MM-DD
supplierRefstringoptionalcan be null
Up to 100 characters

Response object

iduuidrequired
referencestringrequiredcan be null
statusenumrequired
One of "draft", "ordered", "part_received", "received", "cancelled"
supplierIduuidrequiredcan be null
supplierNamestringrequired
fromStockbooleanrequired
destinationenumrequired
One of "stock", "client"
clientIduuidrequiredcan be null
clientNamestringrequiredcan be null
projectIduuidrequiredcan be null
projectNamestringrequiredcan be null
mixedbooleanrequired
orderDatedaterequiredcan be null
YYYY-MM-DD
expectedDatedaterequiredcan be null
YYYY-MM-DD
supplierRefstringrequiredcan be null
netPenceintegerrequired
-9007199254740991 to 9007199254740991
vatPenceintegerrequired
-9007199254740991 to 9007199254740991
grossPenceintegerrequired
-9007199254740991 to 9007199254740991
lineCountintegerrequired
-9007199254740991 to 9007199254740991
destinationsstringrequired
createdAtstringrequired
supplierEmailstringrequiredcan be null
deliverTostringrequiredcan be null
notesstringrequiredcan be null
linesarray of objectrequired
- iduuidrequired
- productIduuidrequiredcan be null
- codestringrequiredcan be null
- supplierCodestringrequiredcan be null
- descriptionstringrequired
- unitstringrequired
- quantityX100integerrequired
  -9007199254740991 to 9007199254740991
- receivedX100integerrequired
  -9007199254740991 to 9007199254740991
- unitCostPenceintegerrequired
  -9007199254740991 to 9007199254740991
- vatRateBpintegerrequired
  -9007199254740991 to 9007199254740991
- netPenceintegerrequired
  -9007199254740991 to 9007199254740991
- destinationenumrequired
  One of "stock", "client"
- clientIduuidrequiredcan be null
- clientNamestringrequiredcan be null
- projectIduuidrequiredcan be null
- projectNamestringrequiredcan be null
- markupBpintegerrequiredcan be null
  -9007199254740991 to 9007199254740991
- unitSellPenceintegerrequiredcan be null
  -9007199254740991 to 9007199254740991
- lockedBystringrequiredcan be null
receiptsarray of objectrequired
- iduuidrequired
- receivedOndaterequired
  YYYY-MM-DD
- supplierRefstringrequiredcan be null
- byNamestringrequiredcan be null
- linesarray of objectrequired
  - descriptionstringrequired
  - quantityX100integerrequired
    -9007199254740991 to 9007199254740991
  - unitCostPenceintegerrequired
    -9007199254740991 to 9007199254740991
sentAtstringrequiredcan be null
cancelReasonstringrequiredcan be null

curl -X POST "https://app.workscope.co.uk/v1/purchase-orders/ID/arrived" \
  -H "Authorization: Bearer wsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "receivedOn": "2026-11-06",
    "supplierRef": "text"
  }'

Example response

{
  "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "reference": "INV-0042",
  "status": "draft",
  "supplierId": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "supplierName": "Harbourside Dental",
  "fromStock": false,
  "destination": "stock",
  "clientId": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
  "clientName": "Harbourside Dental",
  "projectId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "projectName": "1 Harbour Road",
  "mixed": false,
  "orderDate": "2026-11-06",
  "expectedDate": "2026-11-06",
  "supplierRef": "text",
  "netPence": 4500,
  "vatPence": 4500,
  "grossPence": 4500,
  "lineCount": 3,
  "destinations": "text",
  "createdAt": "2026-11-06T09:30:00.000Z",
  "supplierEmail": "office@example.co.uk",
  "deliverTo": "text",
  "notes": "Side gate code is on the key safe.",
  "lines": [
    {
      "id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "productId": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
      "code": "text",
      "supplierCode": "text",
      "description": "Side gate code is on the key safe.",
      "unit": "text",
      "quantityX100": -9007199254740991,
      "receivedX100": -9007199254740991,
      "unitCostPence": 4500,
      "vatRateBp": 1207,
      "netPence": 4500,
      "destination": "stock",
      "clientId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
      "clientName": "Harbourside Dental",
      "projectId": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "projectName": "1 Harbour Road",
      "markupBp": 1207,
      "unitSellPence": 4500,
      "lockedBy": "text"
    }
  ],
  "receipts": [
    {
      "id": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
      "receivedOn": "2026-11-06",
      "supplierRef": "text",
      "byName": "Harbourside Dental",
      "lines": [
        {
          "description": "Side gate code is on the key safe.",
          "quantityX100": -9007199254740991,
          "unitCostPence": 4500
        }
      ]
    }
  ],
  "sentAt": "2026-11-06T09:30:00.000Z",
  "cancelReason": "text"
}

Cancel a whole order: stock it brought in comes back out and its clients' charges go (none may be on an issued invoice)

POST/v1/purchase-orders/{id}/cancel

Permission: purchase.manage
Module: purchases
Answers: 200

Parameters

Name	In	Kind
`id`	path	uuidrequired

Request body JSON

reasonstringoptionalcan be null
Up to 500 characters

Response object

iduuidrequired
referencestringrequiredcan be null
statusenumrequired
One of "draft", "ordered", "part_received", "received", "cancelled"
supplierIduuidrequiredcan be null
supplierNamestringrequired
fromStockbooleanrequired
destinationenumrequired
One of "stock", "client"
clientIduuidrequiredcan be null
clientNamestringrequiredcan be null
projectIduuidrequiredcan be null
projectNamestringrequiredcan be null
mixedbooleanrequired
orderDatedaterequiredcan be null
YYYY-MM-DD
expectedDatedaterequiredcan be null
YYYY-MM-DD
supplierRefstringrequiredcan be null
netPenceintegerrequired
-9007199254740991 to 9007199254740991
vatPenceintegerrequired
-9007199254740991 to 9007199254740991
grossPenceintegerrequired
-9007199254740991 to 9007199254740991
lineCountintegerrequired
-9007199254740991 to 9007199254740991
destinationsstringrequired
createdAtstringrequired
supplierEmailstringrequiredcan be null
deliverTostringrequiredcan be null
notesstringrequiredcan be null
linesarray of objectrequired
- iduuidrequired
- productIduuidrequiredcan be null
- codestringrequiredcan be null
- supplierCodestringrequiredcan be null
- descriptionstringrequired
- unitstringrequired
- quantityX100integerrequired
  -9007199254740991 to 9007199254740991
- receivedX100integerrequired
  -9007199254740991 to 9007199254740991
- unitCostPenceintegerrequired
  -9007199254740991 to 9007199254740991
- vatRateBpintegerrequired
  -9007199254740991 to 9007199254740991
- netPenceintegerrequired
  -9007199254740991 to 9007199254740991
- destinationenumrequired
  One of "stock", "client"
- clientIduuidrequiredcan be null
- clientNamestringrequiredcan be null
- projectIduuidrequiredcan be null
- projectNamestringrequiredcan be null
- markupBpintegerrequiredcan be null
  -9007199254740991 to 9007199254740991
- unitSellPenceintegerrequiredcan be null
  -9007199254740991 to 9007199254740991
- lockedBystringrequiredcan be null
receiptsarray of objectrequired
- iduuidrequired
- receivedOndaterequired
  YYYY-MM-DD
- supplierRefstringrequiredcan be null
- byNamestringrequiredcan be null
- linesarray of objectrequired
  - descriptionstringrequired
  - quantityX100integerrequired
    -9007199254740991 to 9007199254740991
  - unitCostPenceintegerrequired
    -9007199254740991 to 9007199254740991
sentAtstringrequiredcan be null
cancelReasonstringrequiredcan be null

curl -X POST "https://app.workscope.co.uk/v1/purchase-orders/ID/cancel" \
  -H "Authorization: Bearer wsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "text"
  }'

Example response

{
  "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "reference": "INV-0042",
  "status": "draft",
  "supplierId": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "supplierName": "Harbourside Dental",
  "fromStock": false,
  "destination": "stock",
  "clientId": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
  "clientName": "Harbourside Dental",
  "projectId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "projectName": "1 Harbour Road",
  "mixed": false,
  "orderDate": "2026-11-06",
  "expectedDate": "2026-11-06",
  "supplierRef": "text",
  "netPence": 4500,
  "vatPence": 4500,
  "grossPence": 4500,
  "lineCount": 3,
  "destinations": "text",
  "createdAt": "2026-11-06T09:30:00.000Z",
  "supplierEmail": "office@example.co.uk",
  "deliverTo": "text",
  "notes": "Side gate code is on the key safe.",
  "lines": [
    {
      "id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "productId": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
      "code": "text",
      "supplierCode": "text",
      "description": "Side gate code is on the key safe.",
      "unit": "text",
      "quantityX100": -9007199254740991,
      "receivedX100": -9007199254740991,
      "unitCostPence": 4500,
      "vatRateBp": 1207,
      "netPence": 4500,
      "destination": "stock",
      "clientId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
      "clientName": "Harbourside Dental",
      "projectId": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "projectName": "1 Harbour Road",
      "markupBp": 1207,
      "unitSellPence": 4500,
      "lockedBy": "text"
    }
  ],
  "receipts": [
    {
      "id": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
      "receivedOn": "2026-11-06",
      "supplierRef": "text",
      "byName": "Harbourside Dental",
      "lines": [
        {
          "description": "Side gate code is on the key safe.",
          "quantityX100": -9007199254740991,
          "unitCostPence": 4500
        }
      ]
    }
  ],
  "sentAt": "2026-11-06T09:30:00.000Z",
  "cancelReason": "text"
}

A ready-to-send email of the order to its supplier, in the company's wording

GET/v1/purchase-orders/{id}/email

Permission: purchase.manage
Module: purchases
Answers: 200

Parameters

Name	In	Kind
`id`	path	uuidrequired

Response object

toarray of objectrequired
- emailstringrequired
- namestringrequiredcan be null
subjectstringrequired
messagestringrequired
pdfbooleanrequired
linkstringrequiredcan be null

curl "https://app.workscope.co.uk/v1/purchase-orders/ID/email" \
  -H "Authorization: Bearer wsk_your_key_here"

Example response

{
  "to": [
    {
      "email": "office@example.co.uk",
      "name": "Harbourside Dental"
    }
  ],
  "subject": "text",
  "message": "text",
  "pdf": false,
  "link": "text"
}

Mark a draft as placed with the supplier (on its order date, or today): it gets its number

POST/v1/purchase-orders/{id}/order

Permission: purchase.manage
Module: purchases
Answers: 200

Parameters

Name	In	Kind
`id`	path	uuidrequired

Response object

iduuidrequired
referencestringrequiredcan be null
statusenumrequired
One of "draft", "ordered", "part_received", "received", "cancelled"
supplierIduuidrequiredcan be null
supplierNamestringrequired
fromStockbooleanrequired
destinationenumrequired
One of "stock", "client"
clientIduuidrequiredcan be null
clientNamestringrequiredcan be null
projectIduuidrequiredcan be null
projectNamestringrequiredcan be null
mixedbooleanrequired
orderDatedaterequiredcan be null
YYYY-MM-DD
expectedDatedaterequiredcan be null
YYYY-MM-DD
supplierRefstringrequiredcan be null
netPenceintegerrequired
-9007199254740991 to 9007199254740991
vatPenceintegerrequired
-9007199254740991 to 9007199254740991
grossPenceintegerrequired
-9007199254740991 to 9007199254740991
lineCountintegerrequired
-9007199254740991 to 9007199254740991
destinationsstringrequired
createdAtstringrequired
supplierEmailstringrequiredcan be null
deliverTostringrequiredcan be null
notesstringrequiredcan be null
linesarray of objectrequired
- iduuidrequired
- productIduuidrequiredcan be null
- codestringrequiredcan be null
- supplierCodestringrequiredcan be null
- descriptionstringrequired
- unitstringrequired
- quantityX100integerrequired
  -9007199254740991 to 9007199254740991
- receivedX100integerrequired
  -9007199254740991 to 9007199254740991
- unitCostPenceintegerrequired
  -9007199254740991 to 9007199254740991
- vatRateBpintegerrequired
  -9007199254740991 to 9007199254740991
- netPenceintegerrequired
  -9007199254740991 to 9007199254740991
- destinationenumrequired
  One of "stock", "client"
- clientIduuidrequiredcan be null
- clientNamestringrequiredcan be null
- projectIduuidrequiredcan be null
- projectNamestringrequiredcan be null
- markupBpintegerrequiredcan be null
  -9007199254740991 to 9007199254740991
- unitSellPenceintegerrequiredcan be null
  -9007199254740991 to 9007199254740991
- lockedBystringrequiredcan be null
receiptsarray of objectrequired
- iduuidrequired
- receivedOndaterequired
  YYYY-MM-DD
- supplierRefstringrequiredcan be null
- byNamestringrequiredcan be null
- linesarray of objectrequired
  - descriptionstringrequired
  - quantityX100integerrequired
    -9007199254740991 to 9007199254740991
  - unitCostPenceintegerrequired
    -9007199254740991 to 9007199254740991
sentAtstringrequiredcan be null
cancelReasonstringrequiredcan be null

curl -X POST "https://app.workscope.co.uk/v1/purchase-orders/ID/order" \
  -H "Authorization: Bearer wsk_your_key_here"

Example response

{
  "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "reference": "INV-0042",
  "status": "draft",
  "supplierId": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "supplierName": "Harbourside Dental",
  "fromStock": false,
  "destination": "stock",
  "clientId": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
  "clientName": "Harbourside Dental",
  "projectId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "projectName": "1 Harbour Road",
  "mixed": false,
  "orderDate": "2026-11-06",
  "expectedDate": "2026-11-06",
  "supplierRef": "text",
  "netPence": 4500,
  "vatPence": 4500,
  "grossPence": 4500,
  "lineCount": 3,
  "destinations": "text",
  "createdAt": "2026-11-06T09:30:00.000Z",
  "supplierEmail": "office@example.co.uk",
  "deliverTo": "text",
  "notes": "Side gate code is on the key safe.",
  "lines": [
    {
      "id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "productId": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
      "code": "text",
      "supplierCode": "text",
      "description": "Side gate code is on the key safe.",
      "unit": "text",
      "quantityX100": -9007199254740991,
      "receivedX100": -9007199254740991,
      "unitCostPence": 4500,
      "vatRateBp": 1207,
      "netPence": 4500,
      "destination": "stock",
      "clientId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
      "clientName": "Harbourside Dental",
      "projectId": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "projectName": "1 Harbour Road",
      "markupBp": 1207,
      "unitSellPence": 4500,
      "lockedBy": "text"
    }
  ],
  "receipts": [
    {
      "id": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
      "receivedOn": "2026-11-06",
      "supplierRef": "text",
      "byName": "Harbourside Dental",
      "lines": [
        {
          "description": "Side gate code is on the key safe.",
          "quantityX100": -9007199254740991,
          "unitCostPence": 4500
        }
      ]
    }
  ],
  "sentAt": "2026-11-06T09:30:00.000Z",
  "cancelReason": "text"
}

The order as a PDF, as the supplier sees it

GET/v1/purchase-orders/{id}/pdf

Permission: purchase.view
Module: purchases
Answers: 200 with a file (image/jpeg)

Parameters

Name	In	Kind
`id`	path	uuidrequired

curl "https://app.workscope.co.uk/v1/purchase-orders/ID/pdf" \
  -H "Authorization: Bearer wsk_your_key_here"

Record what arrived (at what it actually cost): stock lines go into stock, clients' lines become charges to them

POST/v1/purchase-orders/{id}/receive

Permission: purchase.manage
Module: purchases
Answers: 200

Parameters

Name	In	Kind
`id`	path	uuidrequired

Request body JSON

receivedOndateoptional
YYYY-MM-DD
supplierRefstringoptionalcan be null
Up to 100 characters
linesarray of objectrequired
At least 1 item
- lineIduuidrequired
- quantityX100integerrequired
  0 to 100000000
- unitCostPenceintegeroptional
  0 to 100000000

Response object

iduuidrequired
referencestringrequiredcan be null
statusenumrequired
One of "draft", "ordered", "part_received", "received", "cancelled"
supplierIduuidrequiredcan be null
supplierNamestringrequired
fromStockbooleanrequired
destinationenumrequired
One of "stock", "client"
clientIduuidrequiredcan be null
clientNamestringrequiredcan be null
projectIduuidrequiredcan be null
projectNamestringrequiredcan be null
mixedbooleanrequired
orderDatedaterequiredcan be null
YYYY-MM-DD
expectedDatedaterequiredcan be null
YYYY-MM-DD
supplierRefstringrequiredcan be null
netPenceintegerrequired
-9007199254740991 to 9007199254740991
vatPenceintegerrequired
-9007199254740991 to 9007199254740991
grossPenceintegerrequired
-9007199254740991 to 9007199254740991
lineCountintegerrequired
-9007199254740991 to 9007199254740991
destinationsstringrequired
createdAtstringrequired
supplierEmailstringrequiredcan be null
deliverTostringrequiredcan be null
notesstringrequiredcan be null
linesarray of objectrequired
- iduuidrequired
- productIduuidrequiredcan be null
- codestringrequiredcan be null
- supplierCodestringrequiredcan be null
- descriptionstringrequired
- unitstringrequired
- quantityX100integerrequired
  -9007199254740991 to 9007199254740991
- receivedX100integerrequired
  -9007199254740991 to 9007199254740991
- unitCostPenceintegerrequired
  -9007199254740991 to 9007199254740991
- vatRateBpintegerrequired
  -9007199254740991 to 9007199254740991
- netPenceintegerrequired
  -9007199254740991 to 9007199254740991
- destinationenumrequired
  One of "stock", "client"
- clientIduuidrequiredcan be null
- clientNamestringrequiredcan be null
- projectIduuidrequiredcan be null
- projectNamestringrequiredcan be null
- markupBpintegerrequiredcan be null
  -9007199254740991 to 9007199254740991
- unitSellPenceintegerrequiredcan be null
  -9007199254740991 to 9007199254740991
- lockedBystringrequiredcan be null
receiptsarray of objectrequired
- iduuidrequired
- receivedOndaterequired
  YYYY-MM-DD
- supplierRefstringrequiredcan be null
- byNamestringrequiredcan be null
- linesarray of objectrequired
  - descriptionstringrequired
  - quantityX100integerrequired
    -9007199254740991 to 9007199254740991
  - unitCostPenceintegerrequired
    -9007199254740991 to 9007199254740991
sentAtstringrequiredcan be null
cancelReasonstringrequiredcan be null

curl -X POST "https://app.workscope.co.uk/v1/purchase-orders/ID/receive" \
  -H "Authorization: Bearer wsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "receivedOn": "2026-11-06",
    "supplierRef": "text",
    "lines": [
      {
        "lineId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
        "quantityX100": 0,
        "unitCostPence": 4500
      }
    ]
  }'

Example response

{
  "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "reference": "INV-0042",
  "status": "draft",
  "supplierId": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "supplierName": "Harbourside Dental",
  "fromStock": false,
  "destination": "stock",
  "clientId": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
  "clientName": "Harbourside Dental",
  "projectId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "projectName": "1 Harbour Road",
  "mixed": false,
  "orderDate": "2026-11-06",
  "expectedDate": "2026-11-06",
  "supplierRef": "text",
  "netPence": 4500,
  "vatPence": 4500,
  "grossPence": 4500,
  "lineCount": 3,
  "destinations": "text",
  "createdAt": "2026-11-06T09:30:00.000Z",
  "supplierEmail": "office@example.co.uk",
  "deliverTo": "text",
  "notes": "Side gate code is on the key safe.",
  "lines": [
    {
      "id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "productId": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
      "code": "text",
      "supplierCode": "text",
      "description": "Side gate code is on the key safe.",
      "unit": "text",
      "quantityX100": -9007199254740991,
      "receivedX100": -9007199254740991,
      "unitCostPence": 4500,
      "vatRateBp": 1207,
      "netPence": 4500,
      "destination": "stock",
      "clientId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
      "clientName": "Harbourside Dental",
      "projectId": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "projectName": "1 Harbour Road",
      "markupBp": 1207,
      "unitSellPence": 4500,
      "lockedBy": "text"
    }
  ],
  "receipts": [
    {
      "id": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
      "receivedOn": "2026-11-06",
      "supplierRef": "text",
      "byName": "Harbourside Dental",
      "lines": [
        {
          "description": "Side gate code is on the key safe.",
          "quantityX100": -9007199254740991,
          "unitCostPence": 4500
        }
      ]
    }
  ],
  "sentAt": "2026-11-06T09:30:00.000Z",
  "cancelReason": "text"
}

Email the order to the supplier with its PDF (a draft is marked ordered and numbered first)

POST/v1/purchase-orders/{id}/send

Permission: purchase.manage
Module: purchases
Answers: 200

Parameters

Name	In	Kind
`id`	path	uuidrequired

Request body JSON

toarray of emailrequired
1–5 items
subjectstringrequired
1–300 characters
messagestringrequired
1–10000 characters

Response object

iduuidrequired
referencestringrequiredcan be null
statusenumrequired
One of "draft", "ordered", "part_received", "received", "cancelled"
supplierIduuidrequiredcan be null
supplierNamestringrequired
fromStockbooleanrequired
destinationenumrequired
One of "stock", "client"
clientIduuidrequiredcan be null
clientNamestringrequiredcan be null
projectIduuidrequiredcan be null
projectNamestringrequiredcan be null
mixedbooleanrequired
orderDatedaterequiredcan be null
YYYY-MM-DD
expectedDatedaterequiredcan be null
YYYY-MM-DD
supplierRefstringrequiredcan be null
netPenceintegerrequired
-9007199254740991 to 9007199254740991
vatPenceintegerrequired
-9007199254740991 to 9007199254740991
grossPenceintegerrequired
-9007199254740991 to 9007199254740991
lineCountintegerrequired
-9007199254740991 to 9007199254740991
destinationsstringrequired
createdAtstringrequired
supplierEmailstringrequiredcan be null
deliverTostringrequiredcan be null
notesstringrequiredcan be null
linesarray of objectrequired
- iduuidrequired
- productIduuidrequiredcan be null
- codestringrequiredcan be null
- supplierCodestringrequiredcan be null
- descriptionstringrequired
- unitstringrequired
- quantityX100integerrequired
  -9007199254740991 to 9007199254740991
- receivedX100integerrequired
  -9007199254740991 to 9007199254740991
- unitCostPenceintegerrequired
  -9007199254740991 to 9007199254740991
- vatRateBpintegerrequired
  -9007199254740991 to 9007199254740991
- netPenceintegerrequired
  -9007199254740991 to 9007199254740991
- destinationenumrequired
  One of "stock", "client"
- clientIduuidrequiredcan be null
- clientNamestringrequiredcan be null
- projectIduuidrequiredcan be null
- projectNamestringrequiredcan be null
- markupBpintegerrequiredcan be null
  -9007199254740991 to 9007199254740991
- unitSellPenceintegerrequiredcan be null
  -9007199254740991 to 9007199254740991
- lockedBystringrequiredcan be null
receiptsarray of objectrequired
- iduuidrequired
- receivedOndaterequired
  YYYY-MM-DD
- supplierRefstringrequiredcan be null
- byNamestringrequiredcan be null
- linesarray of objectrequired
  - descriptionstringrequired
  - quantityX100integerrequired
    -9007199254740991 to 9007199254740991
  - unitCostPenceintegerrequired
    -9007199254740991 to 9007199254740991
sentAtstringrequiredcan be null
cancelReasonstringrequiredcan be null

curl -X POST "https://app.workscope.co.uk/v1/purchase-orders/ID/send" \
  -H "Authorization: Bearer wsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "to": [
      "office@example.co.uk"
    ],
    "subject": "text",
    "message": "text"
  }'

Example response

{
  "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "reference": "INV-0042",
  "status": "draft",
  "supplierId": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "supplierName": "Harbourside Dental",
  "fromStock": false,
  "destination": "stock",
  "clientId": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
  "clientName": "Harbourside Dental",
  "projectId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "projectName": "1 Harbour Road",
  "mixed": false,
  "orderDate": "2026-11-06",
  "expectedDate": "2026-11-06",
  "supplierRef": "text",
  "netPence": 4500,
  "vatPence": 4500,
  "grossPence": 4500,
  "lineCount": 3,
  "destinations": "text",
  "createdAt": "2026-11-06T09:30:00.000Z",
  "supplierEmail": "office@example.co.uk",
  "deliverTo": "text",
  "notes": "Side gate code is on the key safe.",
  "lines": [
    {
      "id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "productId": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
      "code": "text",
      "supplierCode": "text",
      "description": "Side gate code is on the key safe.",
      "unit": "text",
      "quantityX100": -9007199254740991,
      "receivedX100": -9007199254740991,
      "unitCostPence": 4500,
      "vatRateBp": 1207,
      "netPence": 4500,
      "destination": "stock",
      "clientId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
      "clientName": "Harbourside Dental",
      "projectId": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "projectName": "1 Harbour Road",
      "markupBp": 1207,
      "unitSellPence": 4500,
      "lockedBy": "text"
    }
  ],
  "receipts": [
    {
      "id": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
      "receivedOn": "2026-11-06",
      "supplierRef": "text",
      "byName": "Harbourside Dental",
      "lines": [
        {
          "description": "Side gate code is on the key safe.",
          "quantityX100": -9007199254740991,
          "unitCostPence": 4500
        }
      ]
    }
  ],
  "sentAt": "2026-11-06T09:30:00.000Z",
  "cancelReason": "text"
}

Products, and things bought before, matching what is typed on an order line (the same supplier first)

GET/v1/purchase-orders/suggest

Permission: purchase.view
Module: purchases
Answers: 200

Parameters

Name	In	Kind
`q`	query	stringrequired
`supplierId`	query	uuid

Response array of object

sourceenumrequired
One of "product", "history"
productIduuidrequiredcan be null
descriptionstringrequired
supplierCodestringrequiredcan be null
unitstringrequired
supplierIduuidrequiredcan be null
supplierNamestringrequiredcan be null
unitCostPenceintegerrequiredcan be null
-9007199254740991 to 9007199254740991
vatRateBpintegerrequired
-9007199254740991 to 9007199254740991
lastDatedaterequiredcan be null
YYYY-MM-DD
trackStockbooleanrequired
onHandX100integerrequiredcan be null
-9007199254740991 to 9007199254740991

curl "https://app.workscope.co.uk/v1/purchase-orders/suggest?q=text" \
  -H "Authorization: Bearer wsk_your_key_here"

Example response

[
  {
    "source": "product",
    "productId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
    "description": "Side gate code is on the key safe.",
    "supplierCode": "text",
    "unit": "text",
    "supplierId": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
    "supplierName": "Harbourside Dental",
    "unitCostPence": 4500,
    "vatRateBp": 1207,
    "lastDate": "2026-11-06",
    "trackStock": false,
    "onHandX100": -9007199254740991
  }
]

Draft an order to each product's supplier for everything at or below its reorder level

POST/v1/purchasing/low-stock-orders

Permission: purchase.manage
Module: purchases
Answers: 200

Response object

ordersarray of objectrequired
- iduuidrequired
- supplierNamestringrequired
- linesintegerrequired
  -9007199254740991 to 9007199254740991
skippedarray of stringrequired

curl -X POST "https://app.workscope.co.uk/v1/purchasing/low-stock-orders" \
  -H "Authorization: Bearer wsk_your_key_here"

Example response

{
  "orders": [
    {
      "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
      "supplierName": "Harbourside Dental",
      "lines": -9007199254740991
    }
  ],
  "skipped": [
    "text"
  ]
}

Download what was received, by supplier and month, as CSV

GET/v1/purchasing/reports/purchases

Permission: purchase.view
Module: purchases
Answers: 200 with a file (image/jpeg)

curl "https://app.workscope.co.uk/v1/purchasing/reports/purchases" \
  -H "Authorization: Bearer wsk_your_key_here"

Download the stock on hand and its value as CSV

GET/v1/purchasing/reports/stock

Permission: purchase.view
Module: purchases
Answers: 200 with a file (image/jpeg)

curl "https://app.workscope.co.uk/v1/purchasing/reports/stock" \
  -H "Authorization: Bearer wsk_your_key_here"

The markup, order numbering, when client purchases are charged, and where orders are delivered

GET/v1/purchasing/settings

Permission: purchase.view
Module: purchases
Answers: 200

Response object

markupBpintegerrequired
-9007199254740991 to 9007199254740991
poPrefixstringrequired
nextPoNumberintegerrequired
-9007199254740991 to 9007199254740991
chargeOnenumrequired
One of "receipt", "order"
deliverTostringrequiredcan be null

curl "https://app.workscope.co.uk/v1/purchasing/settings" \
  -H "Authorization: Bearer wsk_your_key_here"

Example response

{
  "markupBp": 1207,
  "poPrefix": "text",
  "nextPoNumber": -9007199254740991,
  "chargeOn": "receipt",
  "deliverTo": "text"
}

Change the purchasing settings

PATCH/v1/purchasing/settings

Permission: purchase.manage
Module: purchases
Answers: 200

Request body JSON

markupBpintegeroptional
0 to 100000
poPrefixstringoptional
1–10 characters
nextPoNumberintegeroptional
1 to 10000000
chargeOnenumoptional
One of "receipt", "order"
deliverTostringoptionalcan be null
Up to 2000 characters

Response object

markupBpintegerrequired
-9007199254740991 to 9007199254740991
poPrefixstringrequired
nextPoNumberintegerrequired
-9007199254740991 to 9007199254740991
chargeOnenumrequired
One of "receipt", "order"
deliverTostringrequiredcan be null

curl -X PATCH "https://app.workscope.co.uk/v1/purchasing/settings" \
  -H "Authorization: Bearer wsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "markupBp": 1207,
    "poPrefix": "text",
    "nextPoNumber": 1,
    "chargeOn": "receipt",
    "deliverTo": "text"
  }'

Example response

{
  "markupBp": 1207,
  "poPrefix": "text",
  "nextPoNumber": -9007199254740991,
  "chargeOn": "receipt",
  "deliverTo": "text"
}

Client orders, and stock given to clients, not invoiced in full yet

GET/v1/purchasing/to-recharge

Permission: purchase.view
Module: purchases
Answers: 200

Parameters

Name	In	Kind
`clientId`	query	uuid

Response object

rowsarray of objectrequired
- kindenumrequired
  One of "order", "stock"
- keystringrequired
- orderIduuidrequiredcan be null
- referencestringrequiredcan be null
- fromStockbooleanrequired
- supplierNamestringrequiredcan be null
- clientIduuidrequired
- clientNamestringrequired
- datedaterequired
  YYYY-MM-DD
- uninvoicedPenceintegerrequired
  -9007199254740991 to 9007199254740991
- uninvoicedCountintegerrequired
  -9007199254740991 to 9007199254740991
- partlyInvoicedbooleanrequired
- onDraftbooleanrequired
countintegerrequired
-9007199254740991 to 9007199254740991
penceintegerrequired
-9007199254740991 to 9007199254740991

curl "https://app.workscope.co.uk/v1/purchasing/to-recharge" \
  -H "Authorization: Bearer wsk_your_key_here"

Example response

{
  "rows": [
    {
      "kind": "order",
      "key": "example-slug",
      "orderId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
      "reference": "INV-0042",
      "fromStock": false,
      "supplierName": "Harbourside Dental",
      "clientId": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "clientName": "Harbourside Dental",
      "date": "2026-11-06",
      "uninvoicedPence": 4500,
      "uninvoicedCount": 3,
      "partlyInvoiced": false,
      "onDraft": false
    }
  ],
  "count": 3,
  "pence": 4500
}

Suppliers by name (archived ones with archived=true)

GET/v1/suppliers

Permission: purchase.view
Module: purchases
Answers: 200

Parameters

Name	In	Kind
`archived`	query	enum	One of `true`, `false`

Response array of object

iduuidrequired
namestringrequired
contactNamestringrequiredcan be null
emailstringrequiredcan be null
phonestringrequiredcan be null
addressstringrequiredcan be null
accountRefstringrequiredcan be null
notesstringrequiredcan be null
archivedbooleanrequired
ordersintegerrequired
-9007199254740991 to 9007199254740991

curl "https://app.workscope.co.uk/v1/suppliers" \
  -H "Authorization: Bearer wsk_your_key_here"

Example response

[
  {
    "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
    "name": "Harbourside Dental",
    "contactName": "Harbourside Dental",
    "email": "office@example.co.uk",
    "phone": "0117 496 0123",
    "address": "1 Harbour Road, Bristol",
    "accountRef": "text",
    "notes": "Side gate code is on the key safe.",
    "archived": false,
    "orders": -9007199254740991
  }
]

Add a supplier

POST/v1/suppliers

Permission: purchase.manage
Module: purchases
Answers: 201

Request body JSON

namestringrequired
1–200 characters
contactNamestringoptionalcan be null
Up to 200 characters
emailemail or constantoptionalcan be null
phonestringoptionalcan be null
Up to 100 characters
addressstringoptionalcan be null
Up to 2000 characters
accountRefstringoptionalcan be null
Up to 100 characters
notesstringoptionalcan be null
Up to 2000 characters

Response object

iduuidrequired
namestringrequired
contactNamestringrequiredcan be null
emailstringrequiredcan be null
phonestringrequiredcan be null
addressstringrequiredcan be null
accountRefstringrequiredcan be null
notesstringrequiredcan be null
archivedbooleanrequired
ordersintegerrequired
-9007199254740991 to 9007199254740991

curl -X POST "https://app.workscope.co.uk/v1/suppliers" \
  -H "Authorization: Bearer wsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Harbourside Dental",
    "contactName": "Harbourside Dental",
    "email": "office@example.co.uk",
    "phone": "0117 496 0123",
    "address": "1 Harbour Road, Bristol",
    "accountRef": "text",
    "notes": "Side gate code is on the key safe."
  }'

Example response

{
  "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "name": "Harbourside Dental",
  "contactName": "Harbourside Dental",
  "email": "office@example.co.uk",
  "phone": "0117 496 0123",
  "address": "1 Harbour Road, Bristol",
  "accountRef": "text",
  "notes": "Side gate code is on the key safe.",
  "archived": false,
  "orders": -9007199254740991
}

Change or archive a supplier

PATCH/v1/suppliers/{id}

Permission: purchase.manage
Module: purchases
Answers: 200

Parameters

Name	In	Kind
`id`	path	uuidrequired

Request body JSON

namestringoptional
1–200 characters
contactNamestringoptionalcan be null
Up to 200 characters
emailemail or constantoptionalcan be null
phonestringoptionalcan be null
Up to 100 characters
addressstringoptionalcan be null
Up to 2000 characters
accountRefstringoptionalcan be null
Up to 100 characters
notesstringoptionalcan be null
Up to 2000 characters
archivedbooleanoptional

Response object

iduuidrequired
namestringrequired
contactNamestringrequiredcan be null
emailstringrequiredcan be null
phonestringrequiredcan be null
addressstringrequiredcan be null
accountRefstringrequiredcan be null
notesstringrequiredcan be null
archivedbooleanrequired
ordersintegerrequired
-9007199254740991 to 9007199254740991

curl -X PATCH "https://app.workscope.co.uk/v1/suppliers/ID" \
  -H "Authorization: Bearer wsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Harbourside Dental",
    "contactName": "Harbourside Dental",
    "email": "office@example.co.uk",
    "phone": "0117 496 0123",
    "address": "1 Harbour Road, Bristol",
    "accountRef": "text",
    "notes": "Side gate code is on the key safe.",
    "archived": false
  }'

Example response

{
  "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "name": "Harbourside Dental",
  "contactName": "Harbourside Dental",
  "email": "office@example.co.uk",
  "phone": "0117 496 0123",
  "address": "1 Harbour Road, Bristol",
  "accountRef": "text",
  "notes": "Side gate code is on the key safe.",
  "archived": false,
  "orders": -9007199254740991
}

Delete a supplier with no orders (archive it otherwise)

DELETE/v1/suppliers/{id}

Permission: purchase.manage
Module: purchases
Answers: 200

Parameters

Name	In	Kind
`id`	path	uuidrequired

Response object

okconstantrequired
Always true

curl -X DELETE "https://app.workscope.co.uk/v1/suppliers/ID" \
  -H "Authorization: Bearer wsk_your_key_here"

Example response

{
  "ok": true
}