Withholdings and perceptions
Tax withheld from the store, which it credits, and tax the store withheld from suppliers, which it remits; the store certificates in PDF.
Withholdings and perceptions
Objects
TaxWithholding
idintegerrequiredID of the record, unique among records of its kind in the store.
legal_entity_idinteger or nullrequiredID of the store legal entity (/v1/legal-entities) the tax was withheld from or that withheld it; null if the legal entity was deleted.
directionstringrequiredsuffered — withheld from the store (settlement provider, bank, customer acting as an agent): its tax advance; practiced — the store withheld it by paying a supplier less: an obligation to remit to the tax authority, with no credit.
- Values:
sufferedpracticed
kindstringrequiredwithholding — withheld from a payout; perception — added to the amount due.
- Values:
withholdingperception
regimestringrequiredWhich tax was withheld: vat — VAT (IVA), income — income tax (Ganancias), turnover — turnover tax (Ingresos Brutos), municipal — municipal and others.
- Values:
vatincometurnovermunicipalinternalsocialother
jurisdictionstring or nullrequiredProvince or municipality for taxes that need one (turnover, municipal); otherwise null.
credit_regimestring or nullrequiredWhich tax the store credits the withholding against; null — nothing to credit it against (a refund claim) or the store withheld it (practiced).
- Values:
vatincometurnovermunicipalinternalsocialothernull
credit_periodstringrequiredCredit month, YYYY-MM: may differ from the withholding month.
amountintegerrequiredWithheld amount in minor units of the store currency.
currencystringrequiredCurrency of the amounts, an ISO 4217 code: the currency of the store.
- Values:
ARSUSDBRLCLPCOPMXNPENRUB
base_amountinteger or nullrequiredTaxable base the tax was withheld from, in minor units of the currency; null if the basis has none.
rate_bpsinteger or nullrequiredRate in hundredths of a percent: 250 is 2.5%; null if the basis has no rate.
rate_sourcestring or nullrequiredWhere the rate comes from: padron — the tax authority register; default — the default rate in the agent settings; manual — a staff member set the amount; import — the rate from the agent paper. null if there is no rate.
- Values:
padrondefaultmanualimportnull
counterparty_tax_idstring or nullrequiredTax ID of the counterparty: the agent that withheld from the store, or the supplier the store withheld from; null if unknown.
counterparty_namestring or nullrequiredCounterparty name at the time of withholding, as printed on the certificate; null if unknown.
occurred_onstring (date)requiredWithholding date, YYYY-MM-DD.
certificate_numberstring or nullrequiredCertificate number: the agent paper number for tax withheld from the store, a number from the store series for tax the store withheld; null if there is no certificate.
sourceobject or nullrequiredThe record that booked the withholding; null — entered by a staff member.
Fields · 2
typestringrequiredpayment_settlement — provider settlement of a payment (id is /v1/payments); supplier_bill_payment — a supplier bill payment (id is /v1/supplier-bill-payments); money_transaction — a payout in the money journal (id is /v1/money-transactions); statement_line — a bank statement line; import_row — a row of an uploaded agent register; account_payment_withholding — a certificate given with a customer debt payment: the customer account entry points to it with tax_withholding_id. The last three have an internal id.
- Values:
payment_settlementsupplier_bill_paymentmoney_transactionstatement_lineimport_rowaccount_payment_withholding
idintegerrequiredID of the source record.
notestring or nullrequiredStaff note; null if there is none.
annulled_atstring (date-time) or nullrequiredWhen the store annulled its certificate: the amount is no longer to remit, and the number stays taken. null for a live record.
created_atstring (date-time)requiredWhen the record was created.
updated_atstring (date-time)requiredWhen the record last changed.
Endpoints
List withholdings and perceptions changed since a given moment: tax withheld from the store, to credit, and tax the store withheld, to remit
get/tax-withholdings
Scope: fiscal: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.
directionstringOnly one side of the register: suffered — withheld from the store, practiced — withheld by the store.
- Values:
sufferedpracticed
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/tax-withholdings" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"data": [
{
"id": 0,
"legal_entity_id": 0,
"direction": "suffered",
"kind": "withholding",
"regime": "vat",
"jurisdiction": "string",
"credit_regime": "vat",
"credit_period": "string",
"amount": 0,
"currency": "ARS",
"base_amount": 0,
"rate_bps": 0,
"rate_source": "padron",
"counterparty_tax_id": "string",
"counterparty_name": "string",
"occurred_on": "2026-01-15",
"certificate_number": "string",
"source": {
"type": "payment_settlement",
"id": 0
},
"note": "string",
"annulled_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"
}Get a withholding or perception
get/tax-withholdings/{tax_withholding}
Scope: fiscal:read
Parameters
Path
tax_withholdingintegerrequiredWithholding or perception ID.
Responses
200Success
application/json
Returns TaxWithholding
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/tax-withholdings/{tax_withholding}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"id": 0,
"legal_entity_id": 0,
"direction": "suffered",
"kind": "withholding",
"regime": "vat",
"jurisdiction": "string",
"credit_regime": "vat",
"credit_period": "string",
"amount": 0,
"currency": "ARS",
"base_amount": 0,
"rate_bps": 0,
"rate_source": "padron",
"counterparty_tax_id": "string",
"counterparty_name": "string",
"occurred_on": "2026-01-15",
"certificate_number": "string",
"source": {
"type": "payment_settlement",
"id": 0
},
"note": "string",
"annulled_at": "2026-01-15T12:00:00Z",
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}Download the PDF withholding certificate the store issues to the counterparty
get/tax-withholdings/{tax_withholding}/certificate
Scope: fiscal:read
Parameters
Path
tax_withholdingintegerrequiredWithholding or perception ID.
Responses
200Success
application/pdf
string (binary)
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
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/tax-withholdings/{tax_withholding}/certificate" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"