Supplier bill payments
What settled a supplier bill and by how much: money, offset, credit note, advance, journal expense or outside the system.
Supplier bill payments
Objects
SupplierBillPayment
idintegerrequiredID of the record, unique among records of its kind in the store.
supplier_bill_idintegerrequiredSupplier bill ID (/v1/supplier-bills).
kindstringrequiredWhat settled the debt: money — money from a money account; offset — offset against a mutual debt; credit_note — a credit note (the line exists on both the invoice and the note); advance — a purchase order advance; journal — an expense already recorded in the money journal; out_of_band — paid outside the system, without a money account.
- Values:
moneyoffsetcredit_noteadvancejournalout_of_band
amountintegerrequiredSettled amount in the supplier bill currency.
currencystringrequiredSupplier bill currency, ISO 4217.
withheld_amountintegerrequiredWithheld on payment, in the supplier bill currency; the supplier received amount minus withheld_amount.
money_account_idinteger or nullrequiredID of the money account (/v1/money-accounts) the payment came from; null for payments without store money.
account_amountstring or nullrequiredTransferred from the money account, in its currency, as a decimal string; null if there is no money account.
base_amountintegerrequiredEquivalent in the store currency on the payment date.
exchange_ratestring or nullrequiredRate on the payment date as a decimal string; null if no conversion took place.
paid_onstring (date)requiredPayment date, YYYY-MM-DD in the store time zone.
settlement_offset_idinteger or nullrequiredID of the offset document for kind offset; null for others.
counterpart_bill_idinteger or nullrequiredID of the counterpart document for kind credit_note: the note on an invoice, the invoice on a note; null for others.
purchase_order_idinteger or nullrequiredID of the purchase order whose advance settled the document, for kind advance; null for others.
money_transaction_idinteger or nullrequiredID of the money journal expense (/v1/money-transactions) applied to the bill, for kind journal; null for others. Money of kind money is a journal transaction with source supplier_bill_payment and the ID of this payment.
notestring or nullrequiredStaff note; null if there is none.
created_atstring (date-time)requiredWhen the record was created.
updated_atstring (date-time)requiredWhen the record last changed.
Endpoints
Supplier bill payments: money, offset, credit note, advance, journal expense or paid outside the system
get/supplier-bill-payments
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_bill_idintegerOnly payments of this supplier bill.
- 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-bill-payments" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"data": [
{
"id": 0,
"supplier_bill_id": 0,
"kind": "money",
"amount": 0,
"currency": "string",
"withheld_amount": 0,
"money_account_id": 0,
"account_amount": "string",
"base_amount": 0,
"exchange_rate": "string",
"paid_on": "2026-01-15",
"settlement_offset_id": 0,
"counterpart_bill_id": 0,
"purchase_order_id": 0,
"money_transaction_id": 0,
"note": "string",
"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 bill payment
get/supplier-bill-payments/{supplier_bill_payment}
Scope: procurement:read
Parameters
Path
supplier_bill_paymentintegerrequiredSupplier bill payment ID.
Responses
200Success
application/json
Returns SupplierBillPayment
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-bill-payments/{supplier_bill_payment}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"id": 0,
"supplier_bill_id": 0,
"kind": "money",
"amount": 0,
"currency": "string",
"withheld_amount": 0,
"money_account_id": 0,
"account_amount": "string",
"base_amount": 0,
"exchange_rate": "string",
"paid_on": "2026-01-15",
"settlement_offset_id": 0,
"counterpart_bill_id": 0,
"purchase_order_id": 0,
"money_transaction_id": 0,
"note": "string",
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}Mark a supplier bill as paid outside the system
post/supplier-bills/{supplier_bill}/payments/out-of-band
Scope: procurement:pay
Parameters
Path
supplier_billintegerrequiredSupplier bill 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
amountintegerrequiredHow much of the debt is settled, in minor units of the supplier bill currency: no more than the amount due (outstanding). Withholdings are part of this amount: the supplier received amount minus the withholdings.
- Maximum:
- 10000000000
paid_onstring (date)requiredPayment day, YYYY-MM-DD in the store time zone, not in the future: it puts the withholdings into a tax period, and a closed period is a refusal.
notestring or nullA note on the payment, such as the bank transfer number; null for no note.
- Max length:
- 1000
withholdingsarray of object or nullWithholdings the store made on this payout to the supplier. For a withholding-agent legal entity the list is required: an empty list means no withholding was made, a missing field is a refusal. Other legal entities do not need the field.
- Max items:
- 20
Fields · 6
regimestringrequiredWithheld tax: vat, turnover, income and other TaxRegime codes.
- Values:
vatincometurnovermunicipalinternalsocialother
amountintegerrequiredWithholding amount in minor units of the supplier bill currency; the withholdings total is less than amount. It is deducted from the payment to the supplier. For a bill in another currency, tax-withholdings records the store-currency equivalent at the payment day rate; without a rate, 422.
- Maximum:
- 10000000000
jurisdictionstring or nullJurisdiction of a provincial or municipal tax, for example AR-B: required for turnover and municipal. null for national taxes.
- Max length:
- 8
- Pattern:
^[A-Z]{2}-[A-Z0-9]{1,5}$
certificate_numberstring or nullNumber of the withholding certificate given to the supplier; null to let the store issue a number from its own series.
- Max length:
- 64
rate_bpsinteger or nullWithholding rate in hundredths of a percent (250 is 2.5%); null when the rate is unknown.
- Minimum:
- 0
- Maximum:
- 10000
rate_sourcestring or nullWhere the rate comes from: padron is the ARCA or provincial register, default is the default rate, manual is entered by hand; null when not stated.
- Values:
padrondefaultmanualnull
Responses
201Created
Headers
Idempotent-Replayedstringtrue when this is the saved response of an earlier request with the same Idempotency-Key.
- Values:
true
application/json
Returns SupplierBillPayment
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
idempotency_key_in_useA request with this key is in progress - 409
supplier_bill_refusedThe supplier bill 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/supplier-bills/{supplier_bill}/payments/out-of-band" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H 'If-Match: "7"' \
-H "Content-Type: application/json" \
-d @body.json{
"amount": 0,
"paid_on": "2026-01-15",
"note": "string",
"withholdings": [
{
"regime": "vat",
"amount": 0,
"jurisdiction": "string",
"certificate_number": "string",
"rate_bps": 0,
"rate_source": "padron"
}
]
}{
"id": 0,
"supplier_bill_id": 0,
"kind": "money",
"amount": 0,
"currency": "string",
"withheld_amount": 0,
"money_account_id": 0,
"account_amount": "string",
"base_amount": 0,
"exchange_rate": "string",
"paid_on": "2026-01-15",
"settlement_offset_id": 0,
"counterpart_bill_id": 0,
"purchase_order_id": 0,
"money_transaction_id": 0,
"note": "string",
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}Cancel a supplier bill payment
delete/supplier-bills/{supplier_bill}/payments/{supplier_bill_payment}
Scope: procurement:pay
Parameters
Path
supplier_billintegerrequiredSupplier bill ID.
supplier_bill_paymentintegerrequiredSupplier bill payment 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
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
- 409
idempotency_key_in_useA request with this key is in progress - 409
in_use_conflictRecord in use - 409
supplier_bill_payment_lockedThe bill payment cannot be cancelled directly - 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/supplier-bills/{supplier_bill}/payments/{supplier_bill_payment}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H 'If-Match: "7"'