Customer accounts

The store receivables book: each customer balance, credit limit, payment terms and a statement for a period with due dates.

Loading the search index…

Customer accounts

Objects

CustomerAccount

  • idintegerrequired

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

  • statusstringrequired

    State: 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
  • currencystringrequired

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

    Values:
    ARSUSDBRLCLPCOPMXNPENRUB
  • balanceintegerrequired

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

    Credit 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_daysintegerrequired

    Payment terms of a sale on account, in days: the charge due date (due_on) is the sale day plus these days.

  • customer_idinteger

    Customer ID (/v1/customers). Only with access to customers.

  • notestring or null

    Staff note about the customer; null if there is none. Only with access to customers: erasing the customer erases it.

  • created_atstring (date-time)required

    When the record was created.

  • updated_atstring (date-time)required

    When the record last changed.

CustomerAccountStatement

  • customer_account_idintegerrequired

    Customer account ID (/v1/customer-accounts).

  • currencystringrequired

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

    Values:
    ARSUSDBRLCLPCOPMXNPENRUB
  • fromstringrequired

    First day of the period, YYYY-MM-DD in the store time zone; without from in the request, the day of the first account operation.

  • tostringrequired

    Last day of the period, YYYY-MM-DD in the store time zone.

  • opening_balanceintegerrequired

    Debt at the start of the period: the sum of operations before from.

  • closing_balanceintegerrequired

    Debt at the end of the period: opening_balance plus the period lines.

  • chargedintegerrequired

    Total debt increases in the period.

  • reducedintegerrequired

    Total debt decreases in the period, as a positive number.

  • linesarray of objectrequired

    Period entries in operation order (occurred_at) with a running balance.

    Fields · 8
    • entry_idintegerrequired

      Entry ID (/v1/customer-account-entries).

    • kindstringrequired

      Entry kind, the same values as kind of an account entry.

      Values:
      chargeopening_balanceopening_creditpaymentreturnwrite_offoffsetwithholdingreversal
    • occurred_atstring (date-time)required

      When the operation happened.

    • order_idinteger or nullrequired

      Order ID (/v1/orders); null if there is no order.

    • due_onstring (date) or nullrequired

      Due date of the charge; null for entries that reduce the debt.

    • notestring or nullrequired

      Staff note; null if there is none.

    • amountintegerrequired

      Signed amount: positive means the debt grew, negative means it went down.

    • balanceintegerrequired

      Debt after this line.

  • open_itemsarray of objectrequired

    Charges 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_idintegerrequired

      Charge entry ID (/v1/customer-account-entries).

    • kindstringrequired

      charge is a sale on account; opening_balance is a debt from the previous books.

      Values:
      chargeopening_balance
    • occurred_atstring (date-time)required

      When the operation happened.

    • order_idinteger or nullrequired

      Order ID (/v1/orders); null if there is no order.

    • due_onstring (date) or nullrequired

      Due date of the charge, YYYY-MM-DD in the store time zone.

    • open_amountintegerrequired

      Unpaid part of the charge at the end of the period.

    • overduebooleanrequired

      The 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

  • 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})$

Responses

200Success

application/json

  • dataarray of CustomerAccountrequired

    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/customer-accounts" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Example response · 200
{
  "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_accountintegerrequired

    Customer account ID.

Responses

200Success

application/json

Returns CustomerAccount

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/customer-accounts/{customer_account}" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Example response · 200
{
  "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_accountintegerrequired

    Customer 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-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/customer-accounts/{customer_account}/statement" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Example response · 200
{
  "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_accountintegerrequired

    Customer account ID.

Header

  • Idempotency-Keystring

    Unique 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

  • amountintegerrequired

    How much money arrived against the debt, in minor units of the store currency.

    Minimum:
    1
    Maximum:
    10000000000
  • payment_methodstringrequired

    How 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 null

    ID of the manual payment method (/v1/manual-payment-methods) when payment_method=manual, for example a bank transfer.

    Minimum:
    1
  • location_idintegerrequired

    ID of the store location.

  • legal_entity_idinteger or null

    ID of the store legal entity (/v1/legal-entities) whose debt is paid: needed when the customer owes several legal entities.

  • withholdingsarray of object

    Withholding certificates the customer agent handed over with the money: they settle the debt like money.

    Min items:
    1
    Max items:
    2000
    Fields · 4
    • regimestringrequired

      Withheld tax: vat, turnover, income and other TaxRegime codes.

    • jurisdictionstring or null

      Jurisdiction 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}$
    • amountintegerrequired

      Withheld amount in minor units of the store currency.

      Minimum:
      1
    • certificate_numberstringrequired

      Number 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_idstring

    CUIT of the customer agent that withheld the tax.

    Max length:
    20

Responses

201Created

Headers

  • Idempotent-Replayedstring

    true 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-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 -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
Request body — 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"
}
Example response · 201
{
  "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"
}