Suppliers
Supplier directory: tax details, purchase currency, payment term and settlement mode, plus balance and statement. Contact person and notes are not exposed.
Suppliers
Objects
Supplier
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.
external_idstring or nullrequiredExternal ID: the ID of the record in your system; null when the app has not set one. Every app sees only its own IDs.
namestringrequiredSupplier name as the store sees it.
legal_namestring or nullrequiredLegal name; null if not set.
tax_idstring or nullrequiredTax number as the store entered it (CUIT in Argentina); null if not set.
tax_id_countrystring or nullrequiredCountry of the tax number, ISO 3166-1 alpha-2; null if the number is not set.
is_activebooleanrequiredfalse — the supplier is turned off: no new orders are placed with it, documents remain.
currencystringrequiredPurchase currency with the supplier, ISO 4217: min_order_amount and its order prices are in it.
payment_term_daysinteger or nullrequiredPayment term in days: the bill due date due_on is calculated from it. null — no term.
prices_include_taxboolean or nullrequiredtrue — the supplier quotes prices with tax, false — without tax; null — by the store rule.
settlement_modestringrequiredon_receipt — regular purchase: the debt arises on receipt; on_sale — consignment: the store pays for what was sold under a consignment settlement.
- Values:
on_receipton_sale
consignment_loss_policystringrequiredWho pays for expired and missing consignment goods: return_to_supplier — goods go back to the supplier; our_cost — the store bears the loss.
- Values:
return_to_supplierour_cost
lead_time_daysinteger or nullrequiredDelivery lead time in days from the order; null if not set.
min_order_amountinteger or nullrequiredMinimum order amount in minor units of currency; null — no minimum.
customer_idinteger or nullID of the same counterparty as a customer (/v1/customers): the store offsets mutual debts through it. null if not linked. Requires access to customers.
created_atstring (date-time)requiredWhen the record was created.
updated_atstring (date-time)requiredWhen the record last changed.
SupplierBalance
supplier_idintegerrequiredSupplier ID (/v1/suppliers).
legal_entity_idinteger or nullrequiredStore legal entity the balance is limited to; null — all legal entities.
as_ofstringrequiredStore day the overdue aging is computed for, YYYY-MM-DD.
currencystringrequiredCurrency of the amounts, an ISO 4217 code: the currency of the store.
- Values:
ARSUSDBRLCLPCOPMXNPENRUB
total_dueintegerrequiredTotal debt: bills_outstanding + settled_pending_bill + accrued_unsettled + received_unbilled − returns_expected − advances_unapplied − payments_unapplied.
has_open_itemsbooleanrequiredWhether there are open items: the total may be zero when items offset each other.
bills_outstandingintegerrequiredUnpaid posted bills — what can be paid now; credit notes reduce it.
overdueintegerrequiredPart of bills_outstanding past its due date; by overdue age it splits into overdue_1_30, overdue_31_60, overdue_61_90 and overdue_90_plus, which add up to overdue.
overdue_1_30integerrequiredOverdue age bucket of overdue; its bounds in store calendar days are in the field name.
overdue_31_60integerrequiredOverdue age bucket of overdue; its bounds in store calendar days are in the field name.
overdue_61_90integerrequiredOverdue age bucket of overdue; its bounds in store calendar days are in the field name.
overdue_90_plusintegerrequiredLast overdue age bucket of overdue: everything older than overdue_61_90.
not_dueintegerrequiredPart of bills_outstanding not yet due (today or later).
due_soonintegerrequiredPart of not_due due within the next week.
no_due_dateintegerrequiredPart of bills_outstanding without a due date.
settled_pending_billintegerrequiredRecognized by a consignment settlement, no posted bill yet.
accrued_unsettledintegerrequiredSold on consignment and not yet included in a settlement.
received_unbilledintegerrequiredReceived in deliveries not covered by any posted bill: debt without a document.
returns_expectedintegerrequiredCounterclaim for shipped returns not yet compensated; reduces the debt.
advances_unappliedintegerrequiredPurchase order advances not yet applied to bills; reduce the debt.
payments_unappliedintegerrequiredMoney journal payments not yet applied to bills, net of money the supplier returned; reduce the debt.
SupplierStatement
supplier_idintegerrequiredSupplier ID (/v1/suppliers).
legal_entity_idinteger or nullrequiredStore legal entity the statement is built for; null — all legal entities.
currencystringrequiredCurrency of the amounts, an ISO 4217 code: the currency of the store.
- Values:
ARSUSDBRLCLPCOPMXNPENRUB
fromstringrequiredFirst day of the period, YYYY-MM-DD in the store time zone; without from in the request — the day of the first statement line.
tostringrequiredLast day of the period, YYYY-MM-DD in the store time zone.
opening_balanceintegerrequiredDebt at the start of the period: the sum of lines before from.
closing_balanceintegerrequiredDebt at the end of the period: opening_balance plus the period lines. For today it equals total_due of the balance.
increase_totalintegerrequiredSum of debt increases in the period.
decrease_totalintegerrequiredSum of debt decreases in the period, as a positive number.
linesarray of objectrequiredPeriod lines by date: within a day, what creates debt comes first, then what settles it.
Fields · 9
datestringrequiredLine date, YYYY-MM-DD in the store time zone.
kindstringrequiredbill — posted invoice or debit note; credit_note — credit note; payment — money payment from the bill; offset — offset; out_of_band_payment — paid outside the system; journal_payment — money journal payment; supplier_refund — money the supplier returned; advance — purchase order advance; fx_difference — exchange difference; unbilled_receipt — delivery without a posted bill; settlement — consignment settlement without a posted bill; accrual — sold and not yet settled; return_claim — shipped return not yet compensated.
- Values:
billcredit_notepaymentoffsetout_of_band_paymentjournal_paymentsupplier_refundadvancefx_differenceunbilled_receiptsettlementaccrualreturn_claim
amountintegerrequiredSigned line amount: plus — the debt grew, minus — it shrank.
balanceintegerrequiredDebt after the line.
documentobject or nullrequiredLine document; null for consignment accruals.
Fields · 3
typestringrequiredDocument kind: supplier_bill, money_transaction, purchase_order, goods_receipt, consignment_settlement or supplier_return.
- Values:
supplier_billmoney_transactionpurchase_ordergoods_receiptconsignment_settlementsupplier_return
idintegerrequiredDocument ID.
numberstring or nullrequiredDocument number; null if it has none.
supplier_bill_payment_idinteger or nullrequiredBill payment ID (/v1/supplier-bill-payments) on a payment line; null otherwise.
money_transaction_idinteger or nullrequiredID of the money journal transaction (/v1/money-transactions) that paid the advance, on an advance line; null otherwise.
settlement_offset_idinteger or nullrequiredOffset ID (/v1/settlement-offsets) on an offset line; null otherwise.
document_amountobject or nullrequiredAmount in the document currency when it is not the store currency; null — store currency.
Fields · 2
currencystringrequiredDocument currency, ISO 4217.
amountintegerrequiredAmount in minor units of the document currency.
Endpoints
Store suppliers: tax details and payment terms
get/suppliers
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.
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/suppliers" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"data": [
{
"id": 0,
"version": 0,
"external_id": "string",
"name": "string",
"legal_name": "string",
"tax_id": "string",
"tax_id_country": "string",
"is_active": true,
"currency": "string",
"payment_term_days": 0,
"prices_include_tax": true,
"settlement_mode": "on_receipt",
"consignment_loss_policy": "return_to_supplier",
"lead_time_days": 0,
"min_order_amount": 0,
"customer_id": 0,
"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 supplier: tax details and payment terms
post/suppliers
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
namestringrequiredSupplier name as the store sees it.
- Max length:
- 200
tax_idstring or nullTax number as the store entered it (CUIT in Argentina); null if not set.
- Max length:
- 32
tax_id_countrystring or nullCountry of the tax number, ISO 3166-1 alpha-2; null if the number is not set.
- Values:
ARBRCLCOMXPERUnull
legal_namestring or nullLegal name; null if not set.
- Max length:
- 200
settlement_modestringon_receipt — regular purchase: the debt arises on receipt; on_sale — consignment: the store pays for what was sold under a consignment settlement.
- Values:
on_receipton_sale
consignment_loss_policystringWho pays for expired and missing consignment goods: return_to_supplier — goods go back to the supplier; our_cost — the store bears the loss.
- Values:
return_to_supplierour_cost
prices_include_taxboolean or nulltrue — the supplier quotes prices with tax, false — without tax; null — by the store rule.
payment_term_daysinteger or nullPayment term in days: the bill due date due_on is calculated from it. null — no term.
- Minimum:
- 0
- Maximum:
- 365
min_order_amountinteger or nullMinimum order amount in minor units of currency; null — no minimum.
- Maximum:
- 100000000000000
lead_time_daysinteger or nullDelivery lead time in days from the order; null if not set.
- Minimum:
- 1
- Maximum:
- 365
is_activebooleanfalse — the supplier is turned off: no new orders are placed with it, documents remain.
currencystringPurchase currency with the supplier, ISO 4217: min_order_amount and its order prices are in it.
- Values:
ARSUSDBRLCLPCOPMXNPENRUB
external_idstring or nullExternal ID: the ID of the record in your system; null when the app has not set one. Every app sees only its own IDs.
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 Supplier
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
- 409
external_id_in_useThe external ID is taken - 409
idempotency_key_in_useA request with this key is in progress - 409
record_limit_reachedThe record limit is reached - 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/suppliers" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H "Content-Type: application/json" \
-d @body.json{
"name": "string",
"tax_id": "string",
"tax_id_country": "AR",
"legal_name": "string",
"settlement_mode": "on_receipt",
"consignment_loss_policy": "return_to_supplier",
"prices_include_tax": true,
"payment_term_days": 0,
"min_order_amount": 0,
"lead_time_days": 1,
"is_active": true,
"currency": "ARS",
"external_id": "string"
}{
"id": 0,
"version": 0,
"external_id": "string",
"name": "string",
"legal_name": "string",
"tax_id": "string",
"tax_id_country": "string",
"is_active": true,
"currency": "string",
"payment_term_days": 0,
"prices_include_tax": true,
"settlement_mode": "on_receipt",
"consignment_loss_policy": "return_to_supplier",
"lead_time_days": 0,
"min_order_amount": 0,
"customer_id": 0,
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}Supplier
get/suppliers/{supplier}
Scope: procurement:read
Parameters
Path
supplierintegerrequiredSupplier ID.
Responses
200Success
Headers
ETagstringrequiredVersion of the record. Send it in If-Match to change the record.
- Example:
"7"
application/json
Returns Supplier
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/suppliers/{supplier}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"id": 0,
"version": 0,
"external_id": "string",
"name": "string",
"legal_name": "string",
"tax_id": "string",
"tax_id_country": "string",
"is_active": true,
"currency": "string",
"payment_term_days": 0,
"prices_include_tax": true,
"settlement_mode": "on_receipt",
"consignment_loss_policy": "return_to_supplier",
"lead_time_days": 0,
"min_order_amount": 0,
"customer_id": 0,
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}Update a supplier's tax details, payment terms and external ID
patch/suppliers/{supplier}
Scope: procurement:write
Parameters
Path
supplierintegerrequiredSupplier 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"
Request body application/json
namestringSupplier name as the store sees it.
- Max length:
- 200
legal_namestring or nullLegal name; null if not set.
- Max length:
- 200
tax_idstring or nullTax number as the store entered it (CUIT in Argentina); null if not set.
- Max length:
- 32
tax_id_countrystring or nullCountry of the tax number, ISO 3166-1 alpha-2; null if the number is not set.
is_activebooleanfalse — the supplier is turned off: no new orders are placed with it, documents remain.
payment_term_daysinteger or nullPayment term in days: the bill due date due_on is calculated from it. null — no term.
- Minimum:
- 0
- Maximum:
- 365
prices_include_taxboolean or nulltrue — the supplier quotes prices with tax, false — without tax; null — by the store rule.
settlement_modestringon_receipt — regular purchase: the debt arises on receipt; on_sale — consignment: the store pays for what was sold under a consignment settlement.
- Values:
on_receipton_sale
consignment_loss_policystringWho pays for expired and missing consignment goods: return_to_supplier — goods go back to the supplier; our_cost — the store bears the loss.
- Values:
return_to_supplierour_cost
lead_time_daysinteger or nullDelivery lead time in days from the order; null if not set.
- Minimum:
- 1
- Maximum:
- 365
min_order_amountinteger or nullMinimum order amount in minor units of currency; null — no minimum.
currencystringPurchase currency with the supplier, ISO 4217: min_order_amount and its order prices are in it.
external_idstring or nullExternal ID: the ID of the record in your system; null when the app has not set one. Every app sees only its own IDs.
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 Supplier
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
- 409
external_id_in_useThe external ID is taken - 409
idempotency_key_in_useA request with this key is in progress - 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/suppliers/{supplier}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H 'If-Match: "7"' \
-H "Content-Type: application/json" \
-d @body.json{
"name": "string",
"legal_name": "string",
"tax_id": "string",
"tax_id_country": "string",
"is_active": true,
"payment_term_days": 0,
"prices_include_tax": true,
"settlement_mode": "on_receipt",
"consignment_loss_policy": "return_to_supplier",
"lead_time_days": 1,
"min_order_amount": 0,
"currency": "string",
"external_id": "string"
}{
"id": 0,
"version": 0,
"external_id": "string",
"name": "string",
"legal_name": "string",
"tax_id": "string",
"tax_id_country": "string",
"is_active": true,
"currency": "string",
"payment_term_days": 0,
"prices_include_tax": true,
"settlement_mode": "on_receipt",
"consignment_loss_policy": "return_to_supplier",
"lead_time_days": 0,
"min_order_amount": 0,
"customer_id": 0,
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}Supplier by its external ID
get/suppliers/by-external-id/{external_id}
Scope: procurement:read
Parameters
Path
external_idstringrequiredExternal ID: the ID of the record in your system.
Responses
200Success
Headers
ETagstringrequiredVersion of the record. Send it in If-Match to change the record.
- Example:
"7"
application/json
Returns Supplier
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/suppliers/by-external-id/{external_id}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"id": 0,
"version": 0,
"external_id": "string",
"name": "string",
"legal_name": "string",
"tax_id": "string",
"tax_id_country": "string",
"is_active": true,
"currency": "string",
"payment_term_days": 0,
"prices_include_tax": true,
"settlement_mode": "on_receipt",
"consignment_loss_policy": "return_to_supplier",
"lead_time_days": 0,
"min_order_amount": 0,
"customer_id": 0,
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}Create or update a supplier by its external ID
patch/suppliers/by-external-id/{external_id}
Scope: procurement:write
Parameters
Path
external_idstringrequiredExternal ID: the ID of the record in your system.
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-MatchstringETag of the record from the last read. Required when a record with this external ID exists (otherwise 428) and must be absent when it does not.
- Example:
"7"
If-None-Matchstring* — create only: if a record with this external ID already exists, the request gets 412.
- Values:
*
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 Supplier
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 Supplier
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
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
- 409
idempotency_key_in_useA request with this key is in progress - 409
record_limit_reachedThe record limit is reached - 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/suppliers/by-external-id/{external_id}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"id": 0,
"version": 0,
"external_id": "string",
"name": "string",
"legal_name": "string",
"tax_id": "string",
"tax_id_country": "string",
"is_active": true,
"currency": "string",
"payment_term_days": 0,
"prices_include_tax": true,
"settlement_mode": "on_receipt",
"consignment_loss_policy": "return_to_supplier",
"lead_time_days": 0,
"min_order_amount": 0,
"customer_id": 0,
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}Supplier balance: what the store owes right now, by component and due date
get/suppliers/{supplier}/balance
Scope: procurement:read
Parameters
Path
supplierintegerrequiredSupplier ID.
Query
legal_entity_idintegerOnly the debt to this store legal entity.
Responses
200Success
application/json
Returns SupplierBalance
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/suppliers/{supplier}/balance" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"supplier_id": 0,
"legal_entity_id": 0,
"as_of": "string",
"currency": "ARS",
"total_due": 0,
"has_open_items": true,
"bills_outstanding": 0,
"overdue": 0,
"overdue_1_30": 0,
"overdue_31_60": 0,
"overdue_61_90": 0,
"overdue_90_plus": 0,
"not_due": 0,
"due_soon": 0,
"no_due_date": 0,
"settled_pending_bill": 0,
"accrued_unsettled": 0,
"received_unbilled": 0,
"returns_expected": 0,
"advances_unapplied": 0,
"payments_unapplied": 0
}Supplier statement for a period: opening and closing balance, lines with a running balance
get/suppliers/{supplier}/statement
Scope: procurement:read
Parameters
Path
supplierintegerrequiredSupplier ID.
Query
fromstring (date)First day of the period, YYYY-MM-DD in the store time zone; by default, the day of the first statement line.
tostring (date)Last day of the period, YYYY-MM-DD in the store time zone; today by default.
legal_entity_idintegerStatement for this store legal entity: only its share of lines and balances.
Responses
200Success
application/json
Returns SupplierStatement
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/suppliers/{supplier}/statement" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"supplier_id": 0,
"legal_entity_id": 0,
"currency": "ARS",
"from": "string",
"to": "string",
"opening_balance": 0,
"closing_balance": 0,
"increase_total": 0,
"decrease_total": 0,
"lines": [
{
"date": "string",
"kind": "bill",
"amount": 0,
"balance": 0,
"document": {
"type": "supplier_bill",
"id": 0,
"number": "string"
},
"supplier_bill_payment_id": 0,
"money_transaction_id": 0,
"settlement_offset_id": 0,
"document_amount": {
"currency": "string",
"amount": 0
}
}
]
}