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.

Loading the search index…

Withholdings and perceptions

Objects

TaxWithholding

  • idintegerrequired

    ID of the record, unique among records of its kind in the store.

  • legal_entity_idinteger or nullrequired

    ID of the store legal entity (/v1/legal-entities) the tax was withheld from or that withheld it; null if the legal entity was deleted.

  • directionstringrequired

    suffered — 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
  • kindstringrequired

    withholding — withheld from a payout; perception — added to the amount due.

    Values:
    withholdingperception
  • regimestringrequired

    Which tax was withheld: vat — VAT (IVA), income — income tax (Ganancias), turnover — turnover tax (Ingresos Brutos), municipal — municipal and others.

    Values:
    vatincometurnovermunicipalinternalsocialother
  • jurisdictionstring or nullrequired

    Province or municipality for taxes that need one (turnover, municipal); otherwise null.

  • credit_regimestring or nullrequired

    Which 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_periodstringrequired

    Credit month, YYYY-MM: may differ from the withholding month.

  • amountintegerrequired

    Withheld amount in minor units of the store currency.

  • currencystringrequired

    Currency of the amounts, an ISO 4217 code: the currency of the store.

    Values:
    ARSUSDBRLCLPCOPMXNPENRUB
  • base_amountinteger or nullrequired

    Taxable base the tax was withheld from, in minor units of the currency; null if the basis has none.

  • rate_bpsinteger or nullrequired

    Rate in hundredths of a percent: 250 is 2.5%; null if the basis has no rate.

  • rate_sourcestring or nullrequired

    Where 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 nullrequired

    Tax ID of the counterparty: the agent that withheld from the store, or the supplier the store withheld from; null if unknown.

  • counterparty_namestring or nullrequired

    Counterparty name at the time of withholding, as printed on the certificate; null if unknown.

  • occurred_onstring (date)required

    Withholding date, YYYY-MM-DD.

  • certificate_numberstring or nullrequired

    Certificate 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 nullrequired

    The record that booked the withholding; null — entered by a staff member.

    Fields · 2
    • typestringrequired

      payment_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
    • idintegerrequired

      ID of the source record.

  • notestring or nullrequired

    Staff note; null if there is none.

  • annulled_atstring (date-time) or nullrequired

    When 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)required

    When the record was created.

  • updated_atstring (date-time)required

    When 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

  • limitinteger

    Page size: up to 250 records; 50 by default.

    Minimum:
    1
    Maximum:
    250
  • cursorstring

    Opaque 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_deletedboolean

    true — 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.

  • directionstring

    Only one side of the register: suffered — withheld from the store, practiced — withheld by the store.

    Values:
    sufferedpracticed

Responses

200Success

application/json

  • dataarray of TaxWithholdingrequired

    Records of the page.

  • deletedarray of objectrequired

    Records erased from the database since the cursor, as tombstones: only with include_deleted=true in the continuation by the sync cursor.

    Fields · 2
    • idintegerrequired

      ID of the erased record.

    • deleted_atstring (date-time)required

      When the record was erased.

  • next_cursorstring or nullrequired

    Cursor of the next page; null on the last page.

  • has_morebooleanrequired

    true when there is a next page.

  • sync_cursorstring or nullrequired

    On 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-Authenticatestringrequired

    Authentication 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-Authenticatestring

    Authentication 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-Afterintegerrequired

    Seconds to wait before retrying.

    Minimum:
    0

application/problem+json

Returns RateLimitProblem

503The store is temporarily unavailable

Headers

  • Retry-Afterinteger

    Seconds 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

Example request
curl "https://api.saleya.app/v1/tax-withholdings" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Example response · 200
{
  "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_withholdingintegerrequired

    Withholding or perception ID.

Responses

200Success

application/json

Returns TaxWithholding

401The token is missing, invalid, expired or revoked

Headers

  • WWW-Authenticatestringrequired

    Authentication 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-Authenticatestring

    Authentication 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-Afterintegerrequired

    Seconds to wait before retrying.

    Minimum:
    0

application/problem+json

Returns RateLimitProblem

503The store is temporarily unavailable

Headers

  • Retry-Afterinteger

    Seconds 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

Example request
curl "https://api.saleya.app/v1/tax-withholdings/{tax_withholding}" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Example response · 200
{
  "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_withholdingintegerrequired

    Withholding or perception ID.

Responses

200Success

application/pdf

string (binary)

401The token is missing, invalid, expired or revoked

Headers

  • WWW-Authenticatestringrequired

    Authentication 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-Authenticatestring

    Authentication 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-Afterinteger

    Seconds 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-Afterintegerrequired

    Seconds to wait before retrying.

    Minimum:
    0

application/problem+json

Returns RateLimitProblem

503The store is temporarily unavailable

Headers

  • Retry-Afterinteger

    Seconds 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

Example request
curl "https://api.saleya.app/v1/tax-withholdings/{tax_withholding}/certificate" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"