Purchase orders
What the store ordered from a supplier: lines with ordered, confirmed and received quantities, price and promised delivery date.
Purchase orders
Objects
PurchaseOrder
idintegerrequiredID of the record, unique among records of its kind in the store.
versionintegerrequiredVersion of the record: it grows with every change. Send it as the ETag in If-Match to change the record.
numberstring or nullrequiredOrder number; null on an order created before numbering.
statusstringrequireddraft — not sent to the supplier; sent — placed, delivery expected; partial — partly received; received — fully received; closed — closed by the store, received in full or short (closed_short); cancelled — cancelled.
- Values:
draftsentpartialreceivedclosedcancelled
supplier_idintegerrequiredSupplier ID (/v1/suppliers).
location_idintegerrequiredLocation the delivery is expected at (/v1/locations).
legal_entity_idinteger or nullrequiredBuying legal entity of the store (/v1/legal-entities); null on an order created before the store had legal entities.
currencystringrequiredOrder currency, ISO 4217: line prices and totals are in it.
prices_include_taxbooleanrequiredtrue — line prices include tax; false — they do not.
ordered_totalintegerrequiredValue of what is ordered and still in force; for a closed line, of what was received.
received_totalintegerrequiredValue of what was received against the order.
expected_onstring (date) or nullrequiredWhen the store expects the delivery, YYYY-MM-DD; null if not set.
next_delivery_onstring (date) or nullrequiredNext expected delivery, taking the dates promised by the supplier into account, YYYY-MM-DD; null if nothing is expected.
placed_atstring (date-time) or nullrequiredWhen the order was first sent to the supplier; null on a draft and on an order cancelled before sending.
closed_shortbooleanrequiredtrue — the order was closed short: the rest is no longer expected.
supplier_responsestring or nullrequiredSupplier answer: awaiting — waiting; confirmed — confirmed as is; changed — confirmed with changes (see confirmed_quantity and promised_on of the lines); declined — declined; null — answers are not tracked.
- Values:
awaitingconfirmedchangeddeclinednull
revisionintegerrequiredRevision of the order terms the supplier sees: grows with each change to a placed order.
notestring or nullrequiredStaff note; null if there is none.
linesarray of objectrequiredOrder lines in document order.
Fields · 12
idintegerrequiredID of the record, unique among records of its kind in the store.
variant_idintegerrequiredProduct variant ID (/v1/variants).
unitstring or nullrequiredBase unit of the line quantities: pcs — pieces, g — grams, ml — milliliters.
ordered_quantitystring or nullrequiredOrdered quantity, a decimal string in the base unit.
confirmed_quantitystring or nullrequiredQuantity confirmed by the supplier; null — no answer for the line.
received_quantitystring or nullrequiredQuantity received against the line.
unit_costinteger or nullrequiredPrice in the order currency per cost_per_quantity; null — no price.
cost_per_quantitystring or nullrequiredQuantity in the base unit the price is for: "1000" on a weighed product means per kilogram.
ordered_amountinteger or nullrequiredValue of the line quantity in force; null without a price. Lines add up to ordered_total.
received_amountinteger or nullrequiredValue of the received quantity; null without a price. Lines add up to received_total.
promised_onstring (date) or nullrequiredDelivery date promised by the supplier, YYYY-MM-DD; null — no promise, expected by expected_on.
closed_atstring (date-time) or nullrequiredWhen the line was closed and the rest no longer expected; null on an open line.
created_atstring (date-time)requiredWhen the record was created.
updated_atstring (date-time)requiredWhen the record last changed.
Endpoints
Purchase orders: ordered, confirmed by the supplier and received, by line
get/purchase-orders
Scope: procurement:read
Parameters
Query
limitintegerPage size: up to 250 records; 50 by default.
- Minimum:
- 1
- Maximum:
- 250
cursorstringOpaque cursor: next_cursor of the previous page, or sync_cursor of the last page saved by the previous sync. The list goes in commit order, so the sync cursor later returns only what changed after it.
- Max length:
- 4096
updated_sincestring (date-time)Only records changed after this moment, ISO 8601 with a time zone. A filter for the first sync; continue with the cursor.
- Pattern:
^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,6})?(Z|[+-]\d{2}:\d{2})$
include_deletedbooleantrue — also return deleted records: archived ones with deleted_at set, and records erased from the database as tombstones {id, deleted_at} in the continuation by the sync cursor. Turn it on for a sync.
supplier_idintegerOnly documents of this supplier.
- Minimum:
- 1
Responses
200Success
application/json
Records of the page.
deletedarray of objectrequiredRecords erased from the database since the cursor, as tombstones: only with include_deleted=true in the continuation by the sync cursor.
Fields · 2
idintegerrequiredID of the erased record.
deleted_atstring (date-time)requiredWhen the record was erased.
next_cursorstring or nullrequiredCursor of the next page; null on the last page.
has_morebooleanrequiredtrue when there is a next page.
sync_cursorstring or nullrequiredOn the last page — the cursor to continue from later: it returns only what changed after this page. null on other pages.
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
410The sync cursor is older than the deletion retention period or was issued before the database was restored
application/problem+json
Returns Problem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Errors of this endpoint
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl "https://api.saleya.app/v1/purchase-orders" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"data": [
{
"id": 0,
"version": 0,
"number": "string",
"status": "draft",
"supplier_id": 0,
"location_id": 0,
"legal_entity_id": 0,
"currency": "string",
"prices_include_tax": true,
"ordered_total": 0,
"received_total": 0,
"expected_on": "2026-01-15",
"next_delivery_on": "2026-01-15",
"placed_at": "2026-01-15T12:00:00Z",
"closed_short": true,
"supplier_response": "awaiting",
"revision": 0,
"note": "string",
"lines": [
{
"id": 0,
"variant_id": 0,
"unit": "string",
"ordered_quantity": "string",
"confirmed_quantity": "string",
"received_quantity": "string",
"unit_cost": 0,
"cost_per_quantity": "string",
"ordered_amount": 0,
"received_amount": 0,
"promised_on": "2026-01-15",
"closed_at": "2026-01-15T12:00:00Z"
}
],
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}
],
"deleted": [
{
"id": 0,
"deleted_at": "2026-01-15T12:00:00Z"
}
],
"next_cursor": "string",
"has_more": true,
"sync_cursor": "string"
}Create a draft purchase order
post/purchase-orders
Scope: procurement:write
Parameters
Header
Idempotency-KeystringUnique key of the attempt, for example a UUID. A retry with the same key and body gets the saved response instead of a second write. Keys live 24 hours.
- Min length:
- 1
- Max length:
- 255
- Example:
8e03978e-40d5-43e8-bc93-6894a57f9324
Request body application/json
supplier_idintegerrequiredSupplier ID (/v1/suppliers).
location_idintegerrequiredLocation the delivery is expected at (/v1/locations).
legal_entity_idinteger or nullBuying legal entity of the store (/v1/legal-entities); null on an order created before the store had legal entities.
currencystringrequiredOrder currency, ISO 4217: line prices and totals are in it.
- Values:
ARSUSDBRLCLPCOPMXNPENRUB
prices_include_taxbooleantrue — line prices include tax; false — they do not.
expected_onstring (date) or nullWhen the store expects the delivery, YYYY-MM-DD; null if not set.
notestring or nullStaff note; null if there is none.
- Max length:
- 2000
linesarray of objectrequiredOrder lines in document order.
- Min items:
- 1
- Max items:
- 500
- No repeats
Fields · 4
variant_idintegerrequiredProduct variant ID (/v1/variants).
ordered_quantitystringrequiredOrdered quantity, a decimal string in the base unit.
- Max length:
- 32
unit_costinteger or nullPrice in the order currency per cost_per_quantity; null — no price.
- Minimum:
- 0
- Maximum:
- 10000000000
cost_per_quantitystringQuantity in the base unit the price is for: "1000" on a weighed product means per kilogram.
- Max length:
- 32
Responses
201Created
Headers
Idempotent-Replayedstringtrue when this is the saved response of an earlier request with the same Idempotency-Key.
- Values:
true
ETagstringrequiredVersion of the record. Send it in If-Match to change the record.
- Example:
"7"
Locationstring (uri)requiredAddress of the created record; for an accepted request (202), the address to follow its outcome.
application/json
Returns PurchaseOrder
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
409A request with the same idempotency key is in progress, the data changed after it was read, the external ID belongs to another record, the plan or webhook endpoint limit is reached, or the change needs consent to its consequences
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns ConflictProblem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Errors of this endpoint
- 403
capability_disabledResource not available to this store - 409
idempotency_key_in_useA request with this key is in progress - 422
idempotency_key_reusedIdempotency key is already used - 422
invalid_idempotency_keyIdempotency key is invalid
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl -X POST "https://api.saleya.app/v1/purchase-orders" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H "Content-Type: application/json" \
-d @body.json{
"supplier_id": 0,
"location_id": 0,
"legal_entity_id": 0,
"currency": "ARS",
"prices_include_tax": true,
"expected_on": "2026-01-15",
"note": "string",
"lines": [
{
"variant_id": 0,
"ordered_quantity": "string",
"unit_cost": 0,
"cost_per_quantity": "string"
}
]
}{
"id": 0,
"version": 0,
"number": "string",
"status": "draft",
"supplier_id": 0,
"location_id": 0,
"legal_entity_id": 0,
"currency": "string",
"prices_include_tax": true,
"ordered_total": 0,
"received_total": 0,
"expected_on": "2026-01-15",
"next_delivery_on": "2026-01-15",
"placed_at": "2026-01-15T12:00:00Z",
"closed_short": true,
"supplier_response": "awaiting",
"revision": 0,
"note": "string",
"lines": [
{
"id": 0,
"variant_id": 0,
"unit": "string",
"ordered_quantity": "string",
"confirmed_quantity": "string",
"received_quantity": "string",
"unit_cost": 0,
"cost_per_quantity": "string",
"ordered_amount": 0,
"received_amount": 0,
"promised_on": "2026-01-15",
"closed_at": "2026-01-15T12:00:00Z"
}
],
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}Purchase order
get/purchase-orders/{purchase_order}
Scope: procurement:read
Parameters
Path
purchase_orderintegerrequiredPurchase order ID.
Responses
200Success
Headers
ETagstringrequiredVersion of the record. Send it in If-Match to change the record.
- Example:
"7"
application/json
Returns PurchaseOrder
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
404The object does not exist or is not available to the app
application/problem+json
Returns Problem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl "https://api.saleya.app/v1/purchase-orders/{purchase_order}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"id": 0,
"version": 0,
"number": "string",
"status": "draft",
"supplier_id": 0,
"location_id": 0,
"legal_entity_id": 0,
"currency": "string",
"prices_include_tax": true,
"ordered_total": 0,
"received_total": 0,
"expected_on": "2026-01-15",
"next_delivery_on": "2026-01-15",
"placed_at": "2026-01-15T12:00:00Z",
"closed_short": true,
"supplier_response": "awaiting",
"revision": 0,
"note": "string",
"lines": [
{
"id": 0,
"variant_id": 0,
"unit": "string",
"ordered_quantity": "string",
"confirmed_quantity": "string",
"received_quantity": "string",
"unit_cost": 0,
"cost_per_quantity": "string",
"ordered_amount": 0,
"received_amount": 0,
"promised_on": "2026-01-15",
"closed_at": "2026-01-15T12:00:00Z"
}
],
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}Change a purchase order: a draft in full, a placed order’s lines, date and note with a revision
patch/purchase-orders/{purchase_order}
Scope: procurement:write
Parameters
Path
purchase_orderintegerrequiredPurchase order ID.
Header
Idempotency-KeystringUnique key of the attempt, for example a UUID. A retry with the same key and body gets the saved response instead of a second write. Keys live 24 hours.
- Min length:
- 1
- Max length:
- 255
- Example:
8e03978e-40d5-43e8-bc93-6894a57f9324
If-MatchstringrequiredETag of the record from the last read, for example "7". The change applies only if nobody changed the record since then; otherwise 412. Without it — 428.
- Example:
"7"
Responses
200Success
Headers
Idempotent-Replayedstringtrue when this is the saved response of an earlier request with the same Idempotency-Key.
- Values:
true
ETagstringrequiredVersion of the record. Send it in If-Match to change the record.
- Example:
"7"
application/json
Returns PurchaseOrder
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
404The object does not exist or is not available to the app
application/problem+json
Returns Problem
409A request with the same idempotency key is in progress, the data changed after it was read, the external ID belongs to another record, the plan or webhook endpoint limit is reached, or the change needs consent to its consequences
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns ConflictProblem
412The record changed after it was read: the version in If-Match is not current
application/problem+json
Returns Problem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
428The request needs If-Match with the ETag of the record
application/problem+json
Returns Problem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Errors of this endpoint
- 403
capability_disabledResource not available to this store - 409
idempotency_key_in_useA request with this key is in progress - 409
purchase_order_refusedThe purchase order does not accept this command - 412
precondition_failedThe record has changed - 422
idempotency_key_reusedIdempotency key is already used - 422
invalid_idempotency_keyIdempotency key is invalid - 428
precondition_requiredIf-Match is required
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl -X PATCH "https://api.saleya.app/v1/purchase-orders/{purchase_order}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H 'If-Match: "7"'{
"id": 0,
"version": 0,
"number": "string",
"status": "draft",
"supplier_id": 0,
"location_id": 0,
"legal_entity_id": 0,
"currency": "string",
"prices_include_tax": true,
"ordered_total": 0,
"received_total": 0,
"expected_on": "2026-01-15",
"next_delivery_on": "2026-01-15",
"placed_at": "2026-01-15T12:00:00Z",
"closed_short": true,
"supplier_response": "awaiting",
"revision": 0,
"note": "string",
"lines": [
{
"id": 0,
"variant_id": 0,
"unit": "string",
"ordered_quantity": "string",
"confirmed_quantity": "string",
"received_quantity": "string",
"unit_cost": 0,
"cost_per_quantity": "string",
"ordered_amount": 0,
"received_amount": 0,
"promised_on": "2026-01-15",
"closed_at": "2026-01-15T12:00:00Z"
}
],
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}Delete a draft purchase order
delete/purchase-orders/{purchase_order}
Scope: procurement:write
Parameters
Path
purchase_orderintegerrequiredPurchase order ID.
Query
consentobjectConsents to the consequences of the change, by kind: consent[<consent_kind>]=<consent_token> from a 409 consent_required response. Keep the consents already given when the next kind is asked.
Fields · 1
purchase_order_follow_upstringThe draft is a follow-up order from a “buy elsewhere” decision on another order’s supplier answer: deleting it withdraws that decision, and the discrepancy on the source order waits for a decision again. source_orders counts the source orders affected.
- Min length:
- 64
- Max length:
- 64
Header
Idempotency-KeystringUnique key of the attempt, for example a UUID. A retry with the same key and body gets the saved response instead of a second write. Keys live 24 hours.
- Min length:
- 1
- Max length:
- 255
- Example:
8e03978e-40d5-43e8-bc93-6894a57f9324
If-MatchstringrequiredETag of the record from the last read, for example "7". The change applies only if nobody changed the record since then; otherwise 412. Without it — 428.
- Example:
"7"
Responses
204Success
Headers
Idempotent-Replayedstringtrue when this is the saved response of an earlier request with the same Idempotency-Key.
- Values:
true
No body
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
404The object does not exist or is not available to the app
application/problem+json
Returns Problem
409A request with the same idempotency key is in progress, the data changed after it was read, the external ID belongs to another record, the plan or webhook endpoint limit is reached, or the change needs consent to its consequences
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns ConflictProblem
412The record changed after it was read: the version in If-Match is not current
application/problem+json
Returns Problem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
428The request needs If-Match with the ETag of the record
application/problem+json
Returns Problem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Errors of this endpoint
- 403
capability_disabledResource not available to this store - 409
consent_requiredConsent to the consequences is required - 409
idempotency_key_in_useA request with this key is in progress - 409
in_use_conflictRecord in use - 409
purchase_order_refusedThe purchase order does not accept this command - 412
precondition_failedThe record has changed - 422
idempotency_key_reusedIdempotency key is already used - 422
invalid_idempotency_keyIdempotency key is invalid - 428
precondition_requiredIf-Match is required
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl -X DELETE "https://api.saleya.app/v1/purchase-orders/{purchase_order}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H 'If-Match: "7"'Mark a draft as placed with the supplier
post/purchase-orders/{purchase_order}/place
Scope: procurement:write
Parameters
Path
purchase_orderintegerrequiredPurchase order ID.
Header
Idempotency-KeystringUnique key of the attempt, for example a UUID. A retry with the same key and body gets the saved response instead of a second write. Keys live 24 hours.
- Min length:
- 1
- Max length:
- 255
- Example:
8e03978e-40d5-43e8-bc93-6894a57f9324
If-MatchstringrequiredETag of the record from the last read, for example "7". The change applies only if nobody changed the record since then; otherwise 412. Without it — 428.
- Example:
"7"
Responses
200Success
Headers
Idempotent-Replayedstringtrue when this is the saved response of an earlier request with the same Idempotency-Key.
- Values:
true
ETagstringrequiredVersion of the record. Send it in If-Match to change the record.
- Example:
"7"
application/json
Returns PurchaseOrder
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
404The object does not exist or is not available to the app
application/problem+json
Returns Problem
409A request with the same idempotency key is in progress, the data changed after it was read, the external ID belongs to another record, the plan or webhook endpoint limit is reached, or the change needs consent to its consequences
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns ConflictProblem
412The record changed after it was read: the version in If-Match is not current
application/problem+json
Returns Problem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
428The request needs If-Match with the ETag of the record
application/problem+json
Returns Problem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Errors of this endpoint
- 403
capability_disabledResource not available to this store - 409
idempotency_key_in_useA request with this key is in progress - 409
purchase_order_refusedThe purchase order does not accept this command - 412
precondition_failedThe record has changed - 422
idempotency_key_reusedIdempotency key is already used - 422
invalid_idempotency_keyIdempotency key is invalid - 428
precondition_requiredIf-Match is required
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl -X POST "https://api.saleya.app/v1/purchase-orders/{purchase_order}/place" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H 'If-Match: "7"'{
"id": 0,
"version": 0,
"number": "string",
"status": "draft",
"supplier_id": 0,
"location_id": 0,
"legal_entity_id": 0,
"currency": "string",
"prices_include_tax": true,
"ordered_total": 0,
"received_total": 0,
"expected_on": "2026-01-15",
"next_delivery_on": "2026-01-15",
"placed_at": "2026-01-15T12:00:00Z",
"closed_short": true,
"supplier_response": "awaiting",
"revision": 0,
"note": "string",
"lines": [
{
"id": 0,
"variant_id": 0,
"unit": "string",
"ordered_quantity": "string",
"confirmed_quantity": "string",
"received_quantity": "string",
"unit_cost": 0,
"cost_per_quantity": "string",
"ordered_amount": 0,
"received_amount": 0,
"promised_on": "2026-01-15",
"closed_at": "2026-01-15T12:00:00Z"
}
],
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}Cancel a placed purchase order
post/purchase-orders/{purchase_order}/cancel
Scope: procurement:write
Parameters
Path
purchase_orderintegerrequiredPurchase order ID.
Header
Idempotency-KeystringUnique key of the attempt, for example a UUID. A retry with the same key and body gets the saved response instead of a second write. Keys live 24 hours.
- Min length:
- 1
- Max length:
- 255
- Example:
8e03978e-40d5-43e8-bc93-6894a57f9324
If-MatchstringrequiredETag of the record from the last read, for example "7". The change applies only if nobody changed the record since then; otherwise 412. Without it — 428.
- Example:
"7"
Responses
200Success
Headers
Idempotent-Replayedstringtrue when this is the saved response of an earlier request with the same Idempotency-Key.
- Values:
true
ETagstringrequiredVersion of the record. Send it in If-Match to change the record.
- Example:
"7"
application/json
Returns PurchaseOrder
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
404The object does not exist or is not available to the app
application/problem+json
Returns Problem
409A request with the same idempotency key is in progress, the data changed after it was read, the external ID belongs to another record, the plan or webhook endpoint limit is reached, or the change needs consent to its consequences
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns ConflictProblem
412The record changed after it was read: the version in If-Match is not current
application/problem+json
Returns Problem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
428The request needs If-Match with the ETag of the record
application/problem+json
Returns Problem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Errors of this endpoint
- 403
capability_disabledResource not available to this store - 409
idempotency_key_in_useA request with this key is in progress - 409
purchase_order_refusedThe purchase order does not accept this command - 412
precondition_failedThe record has changed - 422
idempotency_key_reusedIdempotency key is already used - 422
invalid_idempotency_keyIdempotency key is invalid - 428
precondition_requiredIf-Match is required
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl -X POST "https://api.saleya.app/v1/purchase-orders/{purchase_order}/cancel" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H 'If-Match: "7"'{
"id": 0,
"version": 0,
"number": "string",
"status": "draft",
"supplier_id": 0,
"location_id": 0,
"legal_entity_id": 0,
"currency": "string",
"prices_include_tax": true,
"ordered_total": 0,
"received_total": 0,
"expected_on": "2026-01-15",
"next_delivery_on": "2026-01-15",
"placed_at": "2026-01-15T12:00:00Z",
"closed_short": true,
"supplier_response": "awaiting",
"revision": 0,
"note": "string",
"lines": [
{
"id": 0,
"variant_id": 0,
"unit": "string",
"ordered_quantity": "string",
"confirmed_quantity": "string",
"received_quantity": "string",
"unit_cost": 0,
"cost_per_quantity": "string",
"ordered_amount": 0,
"received_amount": 0,
"promised_on": "2026-01-15",
"closed_at": "2026-01-15T12:00:00Z"
}
],
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}Close a received purchase order
post/purchase-orders/{purchase_order}/close
Scope: procurement:write
Parameters
Path
purchase_orderintegerrequiredPurchase order ID.
Header
Idempotency-KeystringUnique key of the attempt, for example a UUID. A retry with the same key and body gets the saved response instead of a second write. Keys live 24 hours.
- Min length:
- 1
- Max length:
- 255
- Example:
8e03978e-40d5-43e8-bc93-6894a57f9324
If-MatchstringrequiredETag of the record from the last read, for example "7". The change applies only if nobody changed the record since then; otherwise 412. Without it — 428.
- Example:
"7"
Responses
200Success
Headers
Idempotent-Replayedstringtrue when this is the saved response of an earlier request with the same Idempotency-Key.
- Values:
true
ETagstringrequiredVersion of the record. Send it in If-Match to change the record.
- Example:
"7"
application/json
Returns PurchaseOrder
401The token is missing, invalid, expired or revoked
Headers
WWW-AuthenticatestringrequiredAuthentication scheme (RFC 6750).
- Example:
Bearer
application/problem+json
Returns Problem
403The plan, the IP address or the token scopes do not allow the request
Headers
WWW-AuthenticatestringAuthentication scheme (RFC 6750).
- Example:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Returns ForbiddenProblem
404The object does not exist or is not available to the app
application/problem+json
Returns Problem
409A request with the same idempotency key is in progress, the data changed after it was read, the external ID belongs to another record, the plan or webhook endpoint limit is reached, or the change needs consent to its consequences
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns ConflictProblem
412The record changed after it was read: the version in If-Match is not current
application/problem+json
Returns Problem
422A parameter is invalid or unknown
application/problem+json
Returns ValidationProblem
428The request needs If-Match with the ETag of the record
application/problem+json
Returns Problem
429The rate limit is exhausted
Headers
Retry-AfterintegerrequiredSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns RateLimitProblem
503The store is temporarily unavailable
Headers
Retry-AfterintegerSeconds to wait before retrying.
- Minimum:
- 0
application/problem+json
Returns Problem
Errors of this endpoint
- 403
capability_disabledResource not available to this store - 409
idempotency_key_in_useA request with this key is in progress - 409
purchase_order_refusedThe purchase order does not accept this command - 412
precondition_failedThe record has changed - 422
idempotency_key_reusedIdempotency key is already used - 422
invalid_idempotency_keyIdempotency key is invalid - 428
precondition_requiredIf-Match is required
Common errors such as token, access, input validation and rate limit can come from any endpoint; they are listed in the catalog: Errors
curl -X POST "https://api.saleya.app/v1/purchase-orders/{purchase_order}/close" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H 'If-Match: "7"'{
"id": 0,
"version": 0,
"number": "string",
"status": "draft",
"supplier_id": 0,
"location_id": 0,
"legal_entity_id": 0,
"currency": "string",
"prices_include_tax": true,
"ordered_total": 0,
"received_total": 0,
"expected_on": "2026-01-15",
"next_delivery_on": "2026-01-15",
"placed_at": "2026-01-15T12:00:00Z",
"closed_short": true,
"supplier_response": "awaiting",
"revision": 0,
"note": "string",
"lines": [
{
"id": 0,
"variant_id": 0,
"unit": "string",
"ordered_quantity": "string",
"confirmed_quantity": "string",
"received_quantity": "string",
"unit_cost": 0,
"cost_per_quantity": "string",
"ordered_amount": 0,
"received_amount": 0,
"promised_on": "2026-01-15",
"closed_at": "2026-01-15T12:00:00Z"
}
],
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}