Customer accounts
The store receivables book: each customer balance, credit limit, payment terms and a statement for a period with due dates.
Customer accounts
Objects
CustomerAccount
idintegerrequiredID of the record, unique among records of its kind in the store.
statusstringrequiredState: active means the customer buys on account within the limit; suspended means new sales on account are closed, while the debt stays and can be paid.
- Values:
activesuspended
currencystringrequiredCurrency of the amounts, an ISO 4217 code: the currency of the store.
- Values:
ARSUSDBRLCLPCOPMXNPENRUB
balanceintegerrequiredBalance in minor currency units: positive means the customer owes, negative means an overpayment. Equals the sum of amount over all account entries (/v1/customer-account-entries).
credit_limitinteger or nullrequiredCredit limit in minor currency units; null means no limit. Sales on account over the limit or with an overdue debt need a manager approval.
payment_terms_daysintegerrequiredPayment terms of a sale on account, in days: the charge due date (due_on) is the sale day plus these days.
customer_idintegerCustomer ID (/v1/customers). Only with access to customers.
notestring or nullStaff note about the customer; null if there is none. Only with access to customers: erasing the customer erases it.
created_atstring (date-time)requiredWhen the record was created.
updated_atstring (date-time)requiredWhen the record last changed.
CustomerAccountStatement
customer_account_idintegerrequiredCustomer account ID (/v1/customer-accounts).
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 account operation.
tostringrequiredLast day of the period, YYYY-MM-DD in the store time zone.
opening_balanceintegerrequiredDebt at the start of the period: the sum of operations before from.
closing_balanceintegerrequiredDebt at the end of the period: opening_balance plus the period lines.
chargedintegerrequiredTotal debt increases in the period.
reducedintegerrequiredTotal debt decreases in the period, as a positive number.
linesarray of objectrequiredPeriod entries in operation order (occurred_at) with a running balance.
Fields · 8
entry_idintegerrequiredEntry ID (/v1/customer-account-entries).
kindstringrequiredEntry kind, the same values as kind of an account entry.
- Values:
chargeopening_balanceopening_creditpaymentreturnwrite_offoffsetwithholdingreversal
occurred_atstring (date-time)requiredWhen the operation happened.
order_idinteger or nullrequiredOrder ID (/v1/orders); null if there is no order.
due_onstring (date) or nullrequiredDue date of the charge; null for entries that reduce the debt.
notestring or nullrequiredStaff note; null if there is none.
amountintegerrequiredSigned amount: positive means the debt grew, negative means it went down.
balanceintegerrequiredDebt after this line.
open_itemsarray of objectrequiredCharges still open at the end of the period, by due date. Which payment closed which charge is decided by FIFO allocation within each legal entity.
Fields · 7
entry_idintegerrequiredCharge entry ID (/v1/customer-account-entries).
kindstringrequiredcharge is a sale on account; opening_balance is a debt from the previous books.
- Values:
chargeopening_balance
occurred_atstring (date-time)requiredWhen the operation happened.
order_idinteger or nullrequiredOrder ID (/v1/orders); null if there is no order.
due_onstring (date) or nullrequiredDue date of the charge, YYYY-MM-DD in the store time zone.
open_amountintegerrequiredUnpaid part of the charge at the end of the period.
overduebooleanrequiredThe due date passed before to: the debt is overdue at the end of the period.
Endpoints
Customer accounts in the receivables book: balance, credit limit and payment terms
get/customer-accounts
Scope: finance: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})$
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/customer-accounts" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"data": [
{
"id": 0,
"status": "active",
"currency": "ARS",
"balance": 0,
"credit_limit": 0,
"payment_terms_days": 0,
"customer_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"
}Customer account
get/customer-accounts/{customer_account}
Scope: finance:read
Parameters
Path
customer_accountintegerrequiredCustomer account ID.
Responses
200Success
application/json
Returns CustomerAccount
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/customer-accounts/{customer_account}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"id": 0,
"status": "active",
"currency": "ARS",
"balance": 0,
"credit_limit": 0,
"payment_terms_days": 0,
"customer_id": 0,
"note": "string",
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}Customer account statement for a period: opening and closing balance, entries with a running balance, and open debts with due dates
get/customer-accounts/{customer_account}/statement
Scope: finance:read
Parameters
Path
customer_accountintegerrequiredCustomer account ID.
Query
fromstring (date)First day of the period, YYYY-MM-DD in the store time zone; by default, the day of the first account operation.
tostring (date)Last day of the period, YYYY-MM-DD in the store time zone; today by default.
Responses
200Success
application/json
Returns CustomerAccountStatement
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/customer-accounts/{customer_account}/statement" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"customer_account_id": 0,
"currency": "ARS",
"from": "string",
"to": "string",
"opening_balance": 0,
"closing_balance": 0,
"charged": 0,
"reduced": 0,
"lines": [
{
"entry_id": 0,
"kind": "charge",
"occurred_at": "2026-01-15T12:00:00Z",
"order_id": 0,
"due_on": "2026-01-15",
"note": "string",
"amount": 0,
"balance": 0
}
],
"open_items": [
{
"entry_id": 0,
"kind": "charge",
"occurred_at": "2026-01-15T12:00:00Z",
"order_id": 0,
"due_on": "2026-01-15",
"open_amount": 0,
"overdue": true
}
]
}Record a customer debt payment with money already received: an entry in the receivables book with withholding certificates
post/customer-accounts/{customer_account}/payments
Scope: finance:write
Parameters
Path
customer_accountintegerrequiredCustomer account 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
Request body application/json
amountintegerrequiredHow much money arrived against the debt, in minor units of the store currency.
- Minimum:
- 1
- Maximum:
- 10000000000
payment_methodstringrequiredHow the money arrived: the method must repay debt and be confirmed by hand — for example cash or the manual method.
- Values:
cashmercadopagocryptobybittrc20balancemodopaywaymercadopago_qrmercadopago_pointmercadopago_transfergift_cardsubscriptiondepositexternalmanualoffseton_accountexchange_creditbonpuntoservice_package
manual_payment_method_idinteger or nullID of the manual payment method (/v1/manual-payment-methods) when payment_method=manual, for example a bank transfer.
- Minimum:
- 1
location_idintegerrequiredID of the store location.
legal_entity_idinteger or nullID of the store legal entity (/v1/legal-entities) whose debt is paid: needed when the customer owes several legal entities.
withholdingsarray of objectWithholding certificates the customer agent handed over with the money: they settle the debt like money.
- Min items:
- 1
- Max items:
- 2000
Fields · 4
regimestringrequiredWithheld tax: vat, turnover, income and other TaxRegime codes.
jurisdictionstring or nullJurisdiction of a provincial or municipal tax, for example AR-B; null for national taxes.
- Max length:
- 8
- Pattern:
^[A-Z]{2}-[A-Z0-9]{1,5}$
amountintegerrequiredWithheld amount in minor units of the store currency.
- Minimum:
- 1
certificate_numberstringrequiredNumber of the withholding certificate.
- Max length:
- 64
withheld_onstring (date)Day of the withholding, YYYY-MM-DD: it puts the certificate into a tax period, a closed period is refused.
withholding_agent_tax_idstringCUIT of the customer agent that withheld the tax.
- Max length:
- 20
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 CustomerAccountEntry
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
- 409
idempotency_key_in_useA request with this key is in progress - 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/customer-accounts/{customer_account}/payments" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H "Content-Type: application/json" \
-d @body.json{
"amount": 1,
"payment_method": "cash",
"manual_payment_method_id": 1,
"location_id": 0,
"legal_entity_id": 0,
"withholdings": [
{
"regime": "string",
"jurisdiction": "string",
"amount": 1,
"certificate_number": "string"
}
],
"withheld_on": "2026-01-15",
"withholding_agent_tax_id": "string"
}{
"id": 0,
"customer_account_id": 0,
"kind": "charge",
"amount": 0,
"currency": "ARS",
"legal_entity_id": 0,
"due_on": "2026-01-15",
"occurred_at": "2026-01-15T12:00:00Z",
"order_id": 0,
"payment_id": 0,
"refund_id": 0,
"reverses_entry_id": 0,
"settlement_offset_id": 0,
"tax_withholding_id": 0,
"note": "string",
"created_at": "2026-01-15T12:00:00Z"
}