Supplier returns
Goods shipped back to a supplier: lines and the expected and received compensation — a credit note, replacement goods or money.
Supplier returns
Objects
SupplierReturn
idintegerrequiredID of the record, unique among records of its kind in the store.
numberstringrequiredReturn number.
statusstringrequireddraft — stock untouched, lines editable; shipped — shipped to the supplier, stock written off, compensation expected; closed — compensation received or the refusal handled; void — voided, stock restored.
- Values:
draftshippedclosedvoid
reasonstringrequiredReturn reason: defect — defective; wrong_item — wrong item; surplus — surplus; recall — batch recall; expiry — expired; other — other.
- Values:
defectwrong_itemsurplusrecallexpiryother
supplier_idintegerrequiredSupplier ID (/v1/suppliers).
legal_entity_idinteger or nullrequiredStore legal entity the credit note is expected for (/v1/legal-entities); null on older returns.
location_idintegerrequiredLocation the goods left from (/v1/locations).
goods_receipt_idinteger or nullrequiredSource goods receipt (/v1/goods-receipts); null — a return without a receipt, priced at cost.
purchase_order_idinteger or nullrequiredPurchase order (/v1/purchase-orders); null without an order.
issued_onstring (date) or nullrequiredDocument date — the day in the statement and on paper, YYYY-MM-DD; null on a draft.
currencystringrequiredReturn currency, ISO 4217: line prices, subtotal and settled_amount are in it.
exchange_ratestring or nullrequiredRate of the return currency to the store currency as a decimal string, captured on shipping; null before shipping.
subtotalintegerrequiredValue of the return lines in the return currency.
base_subtotalintegerrequiredValue of the lines in the store currency at the captured rate.
expected_settlementstring or nullrequiredWhat is expected from the supplier, set on shipping: credit_note — a credit note; replacement — replacement goods; refund — money; none — no compensation; null — not set.
- Values:
credit_notereplacementrefundrejectednonenull
settlementstring or nullrequiredWhat was received on closing: credit_note — a credit note; replacement — replacement; refund — money; rejected — the supplier refused; none — no compensation; null — not closed.
- Values:
credit_notereplacementrefundrejectednonenull
settled_amountinteger or nullrequiredAmount the supplier accepted, in the return currency; null — not yet accepted.
base_settled_amountinteger or nullrequiredAccepted amount in the store currency at the captured rate; null — not yet accepted.
shipped_atstring (date-time) or nullrequiredWhen the goods were shipped to the supplier; null on a draft.
closed_atstring (date-time) or nullrequiredWhen the return was closed; null if not closed.
voided_atstring (date-time) or nullrequiredWhen the return was voided; null on an active return.
void_reasonstring or nullrequiredWhy the return was voided; null on an active return and on older documents.
notestring or nullrequiredStaff note; null if there is none.
linesarray of objectrequiredReturn lines.
Fields · 15
idintegerrequiredID of the record, unique among records of its kind in the store.
variant_idinteger or nullrequiredProduct variant ID (/v1/variants).
lot_idinteger or nullrequiredLot of the line (/v1/lots); null for a product without lots.
goods_receipt_line_idinteger or nullrequiredSource receipt line (lines[].id of the receipt) the price comes from; null on a line without a receipt.
purchase_order_line_idinteger or nullrequiredPurchase order line (lines[].id of the order); null without an order.
unitstring or nullrequiredBase unit of the line quantities: pcs — pieces, g — grams, ml — milliliters.
quantitystring or nullrequiredQuantity shipped to the supplier, a decimal string in the base unit.
settled_quantitystring or nullrequiredHow much of it the supplier accepted.
unit_costinteger or nullrequiredPrice in the return 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.
store_unit_cost_microinteger or nullrequiredThe same price in the store currency, in millionths of the minor unit; null — no price.
amountintegerrequiredValue of what was shipped at the line price; lines add up to subtotal.
settled_amountintegerrequiredValue of what the supplier accepted at the line price.
reasonstring or nullrequiredLine reason with the same codes as the document reason; null — the document reason applies.
- Values:
defectwrong_itemsurplusrecallexpiryothernull
notestring or nullrequiredLine note; null if there is none.
correctionsarray of objectrequiredCorrections of the shipped return in order.
Fields · 7
idintegerrequiredID of the record, unique among records of its kind in the store.
numberstringrequiredCorrection number.
reasonstringrequiredWhy it was corrected; printed on the document and visible to the supplier.
subtotal_beforeintegerrequiredsubtotal before the correction.
subtotal_afterintegerrequiredsubtotal after the correction.
linesarray of objectrequiredCorrected lines, before and after.
Fields · 6
supplier_return_line_idinteger or nullrequiredReturn line ID (lines[].id); null — the correction removed the line.
variant_idinteger or nullrequiredProduct variant of the line (/v1/variants).
quantity_beforestring or nullrequiredQuantity before the correction, in the base unit.
quantity_afterstring or nullrequiredQuantity after the correction, in the base unit.
reason_beforestring or nullrequiredLine reason before the correction; null — the document reason applies.
- Values:
defectwrong_itemsurplusrecallexpiryothernull
reason_afterstring or nullrequiredLine reason after the correction; null — the document reason applies.
- Values:
defectwrong_itemsurplusrecallexpiryothernull
created_atstring (date-time)requiredWhen the correction was posted.
created_atstring (date-time)requiredWhen the record was created.
updated_atstring (date-time)requiredWhen the record last changed.
Endpoints
Supplier returns: goods shipped back to the supplier and the compensation for them
get/supplier-returns
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
goods_receipt_idintegerOnly returns from this goods receipt.
- 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/supplier-returns" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"data": [
{
"id": 0,
"number": "string",
"status": "draft",
"reason": "defect",
"supplier_id": 0,
"legal_entity_id": 0,
"location_id": 0,
"goods_receipt_id": 0,
"purchase_order_id": 0,
"issued_on": "2026-01-15",
"currency": "string",
"exchange_rate": "string",
"subtotal": 0,
"base_subtotal": 0,
"expected_settlement": "credit_note",
"settlement": "credit_note",
"settled_amount": 0,
"base_settled_amount": 0,
"shipped_at": "2026-01-15T12:00:00Z",
"closed_at": "2026-01-15T12:00:00Z",
"voided_at": "2026-01-15T12:00:00Z",
"void_reason": "string",
"note": "string",
"lines": [
{
"id": 0,
"variant_id": 0,
"lot_id": 0,
"goods_receipt_line_id": 0,
"purchase_order_line_id": 0,
"unit": "string",
"quantity": "string",
"settled_quantity": "string",
"unit_cost": 0,
"cost_per_quantity": "string",
"store_unit_cost_micro": 0,
"amount": 0,
"settled_amount": 0,
"reason": "defect",
"note": "string"
}
],
"corrections": [
{
"id": 0,
"number": "string",
"reason": "string",
"subtotal_before": 0,
"subtotal_after": 0,
"lines": [
{
"supplier_return_line_id": 0,
"variant_id": 0,
"quantity_before": "string",
"quantity_after": "string",
"reason_before": "defect",
"reason_after": "defect"
}
],
"created_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"
}Supplier return
get/supplier-returns/{supplier_return}
Scope: procurement:read
Parameters
Path
supplier_returnintegerrequiredSupplier return ID.
Responses
200Success
application/json
Returns SupplierReturn
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/supplier-returns/{supplier_return}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"id": 0,
"number": "string",
"status": "draft",
"reason": "defect",
"supplier_id": 0,
"legal_entity_id": 0,
"location_id": 0,
"goods_receipt_id": 0,
"purchase_order_id": 0,
"issued_on": "2026-01-15",
"currency": "string",
"exchange_rate": "string",
"subtotal": 0,
"base_subtotal": 0,
"expected_settlement": "credit_note",
"settlement": "credit_note",
"settled_amount": 0,
"base_settled_amount": 0,
"shipped_at": "2026-01-15T12:00:00Z",
"closed_at": "2026-01-15T12:00:00Z",
"voided_at": "2026-01-15T12:00:00Z",
"void_reason": "string",
"note": "string",
"lines": [
{
"id": 0,
"variant_id": 0,
"lot_id": 0,
"goods_receipt_line_id": 0,
"purchase_order_line_id": 0,
"unit": "string",
"quantity": "string",
"settled_quantity": "string",
"unit_cost": 0,
"cost_per_quantity": "string",
"store_unit_cost_micro": 0,
"amount": 0,
"settled_amount": 0,
"reason": "defect",
"note": "string"
}
],
"corrections": [
{
"id": 0,
"number": "string",
"reason": "string",
"subtotal_before": 0,
"subtotal_after": 0,
"lines": [
{
"supplier_return_line_id": 0,
"variant_id": 0,
"quantity_before": "string",
"quantity_after": "string",
"reason_before": "defect",
"reason_after": "defect"
}
],
"created_at": "2026-01-15T12:00:00Z"
}
],
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}