Suppliers

Supplier directory: tax details, purchase currency, payment term and settlement mode, plus balance and statement. Contact person and notes are not exposed.

Loading the search index…

Suppliers

Objects

Supplier

  • idintegerrequired

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

  • versionintegerrequired

    Version of the record: it grows with every change. Send it as the ETag in If-Match to change the record.

  • external_idstring or nullrequired

    External ID: the ID of the record in your system; null when the app has not set one. Every app sees only its own IDs.

  • namestringrequired

    Supplier name as the store sees it.

  • legal_namestring or nullrequired

    Legal name; null if not set.

  • tax_idstring or nullrequired

    Tax number as the store entered it (CUIT in Argentina); null if not set.

  • tax_id_countrystring or nullrequired

    Country of the tax number, ISO 3166-1 alpha-2; null if the number is not set.

  • is_activebooleanrequired

    false — the supplier is turned off: no new orders are placed with it, documents remain.

  • currencystringrequired

    Purchase currency with the supplier, ISO 4217: min_order_amount and its order prices are in it.

  • payment_term_daysinteger or nullrequired

    Payment term in days: the bill due date due_on is calculated from it. null — no term.

  • prices_include_taxboolean or nullrequired

    true — the supplier quotes prices with tax, false — without tax; null — by the store rule.

  • settlement_modestringrequired

    on_receipt — regular purchase: the debt arises on receipt; on_sale — consignment: the store pays for what was sold under a consignment settlement.

    Values:
    on_receipton_sale
  • consignment_loss_policystringrequired

    Who pays for expired and missing consignment goods: return_to_supplier — goods go back to the supplier; our_cost — the store bears the loss.

    Values:
    return_to_supplierour_cost
  • lead_time_daysinteger or nullrequired

    Delivery lead time in days from the order; null if not set.

  • min_order_amountinteger or nullrequired

    Minimum order amount in minor units of currency; null — no minimum.

  • customer_idinteger or null

    ID of the same counterparty as a customer (/v1/customers): the store offsets mutual debts through it. null if not linked. Requires access to customers.

  • created_atstring (date-time)required

    When the record was created.

  • updated_atstring (date-time)required

    When the record last changed.

SupplierBalance

  • supplier_idintegerrequired

    Supplier ID (/v1/suppliers).

  • legal_entity_idinteger or nullrequired

    Store legal entity the balance is limited to; null — all legal entities.

  • as_ofstringrequired

    Store day the overdue aging is computed for, YYYY-MM-DD.

  • currencystringrequired

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

    Values:
    ARSUSDBRLCLPCOPMXNPENRUB
  • total_dueintegerrequired

    Total debt: bills_outstanding + settled_pending_bill + accrued_unsettled + received_unbilled − returns_expected − advances_unapplied − payments_unapplied.

  • has_open_itemsbooleanrequired

    Whether there are open items: the total may be zero when items offset each other.

  • bills_outstandingintegerrequired

    Unpaid posted bills — what can be paid now; credit notes reduce it.

  • overdueintegerrequired

    Part of bills_outstanding past its due date; by overdue age it splits into overdue_1_30, overdue_31_60, overdue_61_90 and overdue_90_plus, which add up to overdue.

  • overdue_1_30integerrequired

    Overdue age bucket of overdue; its bounds in store calendar days are in the field name.

  • overdue_31_60integerrequired

    Overdue age bucket of overdue; its bounds in store calendar days are in the field name.

  • overdue_61_90integerrequired

    Overdue age bucket of overdue; its bounds in store calendar days are in the field name.

  • overdue_90_plusintegerrequired

    Last overdue age bucket of overdue: everything older than overdue_61_90.

  • not_dueintegerrequired

    Part of bills_outstanding not yet due (today or later).

  • due_soonintegerrequired

    Part of not_due due within the next week.

  • no_due_dateintegerrequired

    Part of bills_outstanding without a due date.

  • settled_pending_billintegerrequired

    Recognized by a consignment settlement, no posted bill yet.

  • accrued_unsettledintegerrequired

    Sold on consignment and not yet included in a settlement.

  • received_unbilledintegerrequired

    Received in deliveries not covered by any posted bill: debt without a document.

  • returns_expectedintegerrequired

    Counterclaim for shipped returns not yet compensated; reduces the debt.

  • advances_unappliedintegerrequired

    Purchase order advances not yet applied to bills; reduce the debt.

  • payments_unappliedintegerrequired

    Money journal payments not yet applied to bills, net of money the supplier returned; reduce the debt.

SupplierStatement

  • supplier_idintegerrequired

    Supplier ID (/v1/suppliers).

  • legal_entity_idinteger or nullrequired

    Store legal entity the statement is built for; null — all legal entities.

  • 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 statement line.

  • 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 lines before from.

  • closing_balanceintegerrequired

    Debt at the end of the period: opening_balance plus the period lines. For today it equals total_due of the balance.

  • increase_totalintegerrequired

    Sum of debt increases in the period.

  • decrease_totalintegerrequired

    Sum of debt decreases in the period, as a positive number.

  • linesarray of objectrequired

    Period lines by date: within a day, what creates debt comes first, then what settles it.

    Fields · 9
    • datestringrequired

      Line date, YYYY-MM-DD in the store time zone.

    • kindstringrequired

      bill — posted invoice or debit note; credit_note — credit note; payment — money payment from the bill; offset — offset; out_of_band_payment — paid outside the system; journal_payment — money journal payment; supplier_refund — money the supplier returned; advance — purchase order advance; fx_difference — exchange difference; unbilled_receipt — delivery without a posted bill; settlement — consignment settlement without a posted bill; accrual — sold and not yet settled; return_claim — shipped return not yet compensated.

      Values:
      billcredit_notepaymentoffsetout_of_band_paymentjournal_paymentsupplier_refundadvancefx_differenceunbilled_receiptsettlementaccrualreturn_claim
    • amountintegerrequired

      Signed line amount: plus — the debt grew, minus — it shrank.

    • balanceintegerrequired

      Debt after the line.

    • documentobject or nullrequired

      Line document; null for consignment accruals.

      Fields · 3
      • typestringrequired

        Document kind: supplier_bill, money_transaction, purchase_order, goods_receipt, consignment_settlement or supplier_return.

        Values:
        supplier_billmoney_transactionpurchase_ordergoods_receiptconsignment_settlementsupplier_return
      • idintegerrequired

        Document ID.

      • numberstring or nullrequired

        Document number; null if it has none.

    • supplier_bill_payment_idinteger or nullrequired

      Bill payment ID (/v1/supplier-bill-payments) on a payment line; null otherwise.

    • money_transaction_idinteger or nullrequired

      ID of the money journal transaction (/v1/money-transactions) that paid the advance, on an advance line; null otherwise.

    • settlement_offset_idinteger or nullrequired

      Offset ID (/v1/settlement-offsets) on an offset line; null otherwise.

    • document_amountobject or nullrequired

      Amount in the document currency when it is not the store currency; null — store currency.

      Fields · 2
      • currencystringrequired

        Document currency, ISO 4217.

      • amountintegerrequired

        Amount in minor units of the document currency.

Endpoints

Store suppliers: tax details and payment terms

get/suppliers

Scope: procurement: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.

Responses

200Success

application/json

  • dataarray of Supplierrequired

    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/suppliers" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Example response · 200
{
  "data": [
    {
      "id": 0,
      "version": 0,
      "external_id": "string",
      "name": "string",
      "legal_name": "string",
      "tax_id": "string",
      "tax_id_country": "string",
      "is_active": true,
      "currency": "string",
      "payment_term_days": 0,
      "prices_include_tax": true,
      "settlement_mode": "on_receipt",
      "consignment_loss_policy": "return_to_supplier",
      "lead_time_days": 0,
      "min_order_amount": 0,
      "customer_id": 0,
      "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"
}

Create a supplier: tax details and payment terms

post/suppliers

Scope: procurement:write

Parameters

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

  • namestringrequired

    Supplier name as the store sees it.

    Max length:
    200
  • tax_idstring or null

    Tax number as the store entered it (CUIT in Argentina); null if not set.

    Max length:
    32
  • tax_id_countrystring or null

    Country of the tax number, ISO 3166-1 alpha-2; null if the number is not set.

    Values:
    ARBRCLCOMXPERUnull
  • legal_namestring or null

    Legal name; null if not set.

    Max length:
    200
  • settlement_modestring

    on_receipt — regular purchase: the debt arises on receipt; on_sale — consignment: the store pays for what was sold under a consignment settlement.

    Values:
    on_receipton_sale
  • consignment_loss_policystring

    Who pays for expired and missing consignment goods: return_to_supplier — goods go back to the supplier; our_cost — the store bears the loss.

    Values:
    return_to_supplierour_cost
  • prices_include_taxboolean or null

    true — the supplier quotes prices with tax, false — without tax; null — by the store rule.

  • payment_term_daysinteger or null

    Payment term in days: the bill due date due_on is calculated from it. null — no term.

    Minimum:
    0
    Maximum:
    365
  • min_order_amountinteger or null

    Minimum order amount in minor units of currency; null — no minimum.

    Maximum:
    100000000000000
  • lead_time_daysinteger or null

    Delivery lead time in days from the order; null if not set.

    Minimum:
    1
    Maximum:
    365
  • is_activeboolean

    false — the supplier is turned off: no new orders are placed with it, documents remain.

  • currencystring

    Purchase currency with the supplier, ISO 4217: min_order_amount and its order prices are in it.

    Values:
    ARSUSDBRLCLPCOPMXNPENRUB
  • external_idstring or null

    External ID: the ID of the record in your system; null when the app has not set one. Every app sees only its own IDs.

Responses

201Created

Headers

  • Idempotent-Replayedstring

    true when this is the saved response of an earlier request with the same Idempotency-Key.

    Values:
    true
  • ETagstringrequired

    Version of the record. Send it in If-Match to change the record.

    Example:
    "7"
  • Locationstring (uri)required

    Address of the created record; for an accepted request (202), the address to follow its outcome.

application/json

Returns Supplier

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

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/suppliers" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json
Request body — body.json
{
  "name": "string",
  "tax_id": "string",
  "tax_id_country": "AR",
  "legal_name": "string",
  "settlement_mode": "on_receipt",
  "consignment_loss_policy": "return_to_supplier",
  "prices_include_tax": true,
  "payment_term_days": 0,
  "min_order_amount": 0,
  "lead_time_days": 1,
  "is_active": true,
  "currency": "ARS",
  "external_id": "string"
}
Example response · 201
{
  "id": 0,
  "version": 0,
  "external_id": "string",
  "name": "string",
  "legal_name": "string",
  "tax_id": "string",
  "tax_id_country": "string",
  "is_active": true,
  "currency": "string",
  "payment_term_days": 0,
  "prices_include_tax": true,
  "settlement_mode": "on_receipt",
  "consignment_loss_policy": "return_to_supplier",
  "lead_time_days": 0,
  "min_order_amount": 0,
  "customer_id": 0,
  "created_at": "2026-01-15T12:00:00Z",
  "updated_at": "2026-01-15T12:00:00Z"
}

Supplier

get/suppliers/{supplier}

Scope: procurement:read

Parameters

Path

  • supplierintegerrequired

    Supplier ID.

Responses

200Success

Headers

  • ETagstringrequired

    Version of the record. Send it in If-Match to change the record.

    Example:
    "7"

application/json

Returns Supplier

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/suppliers/{supplier}" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Example response · 200
{
  "id": 0,
  "version": 0,
  "external_id": "string",
  "name": "string",
  "legal_name": "string",
  "tax_id": "string",
  "tax_id_country": "string",
  "is_active": true,
  "currency": "string",
  "payment_term_days": 0,
  "prices_include_tax": true,
  "settlement_mode": "on_receipt",
  "consignment_loss_policy": "return_to_supplier",
  "lead_time_days": 0,
  "min_order_amount": 0,
  "customer_id": 0,
  "created_at": "2026-01-15T12:00:00Z",
  "updated_at": "2026-01-15T12:00:00Z"
}

Update a supplier's tax details, payment terms and external ID

patch/suppliers/{supplier}

Scope: procurement:write

Parameters

Path

  • supplierintegerrequired

    Supplier 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
  • If-Matchstringrequired

    ETag 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

  • namestring

    Supplier name as the store sees it.

    Max length:
    200
  • legal_namestring or null

    Legal name; null if not set.

    Max length:
    200
  • tax_idstring or null

    Tax number as the store entered it (CUIT in Argentina); null if not set.

    Max length:
    32
  • tax_id_countrystring or null

    Country of the tax number, ISO 3166-1 alpha-2; null if the number is not set.

  • is_activeboolean

    false — the supplier is turned off: no new orders are placed with it, documents remain.

  • payment_term_daysinteger or null

    Payment term in days: the bill due date due_on is calculated from it. null — no term.

    Minimum:
    0
    Maximum:
    365
  • prices_include_taxboolean or null

    true — the supplier quotes prices with tax, false — without tax; null — by the store rule.

  • settlement_modestring

    on_receipt — regular purchase: the debt arises on receipt; on_sale — consignment: the store pays for what was sold under a consignment settlement.

    Values:
    on_receipton_sale
  • consignment_loss_policystring

    Who pays for expired and missing consignment goods: return_to_supplier — goods go back to the supplier; our_cost — the store bears the loss.

    Values:
    return_to_supplierour_cost
  • lead_time_daysinteger or null

    Delivery lead time in days from the order; null if not set.

    Minimum:
    1
    Maximum:
    365
  • min_order_amountinteger or null

    Minimum order amount in minor units of currency; null — no minimum.

  • currencystring

    Purchase currency with the supplier, ISO 4217: min_order_amount and its order prices are in it.

  • external_idstring or null

    External ID: the ID of the record in your system; null when the app has not set one. Every app sees only its own IDs.

Responses

200Success

Headers

  • Idempotent-Replayedstring

    true when this is the saved response of an earlier request with the same Idempotency-Key.

    Values:
    true
  • ETagstringrequired

    Version of the record. Send it in If-Match to change the record.

    Example:
    "7"

application/json

Returns Supplier

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

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-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 PATCH "https://api.saleya.app/v1/suppliers/{supplier}" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H 'If-Match: "7"' \
  -H "Content-Type: application/json" \
  -d @body.json
Request body — body.json
{
  "name": "string",
  "legal_name": "string",
  "tax_id": "string",
  "tax_id_country": "string",
  "is_active": true,
  "payment_term_days": 0,
  "prices_include_tax": true,
  "settlement_mode": "on_receipt",
  "consignment_loss_policy": "return_to_supplier",
  "lead_time_days": 1,
  "min_order_amount": 0,
  "currency": "string",
  "external_id": "string"
}
Example response · 200
{
  "id": 0,
  "version": 0,
  "external_id": "string",
  "name": "string",
  "legal_name": "string",
  "tax_id": "string",
  "tax_id_country": "string",
  "is_active": true,
  "currency": "string",
  "payment_term_days": 0,
  "prices_include_tax": true,
  "settlement_mode": "on_receipt",
  "consignment_loss_policy": "return_to_supplier",
  "lead_time_days": 0,
  "min_order_amount": 0,
  "customer_id": 0,
  "created_at": "2026-01-15T12:00:00Z",
  "updated_at": "2026-01-15T12:00:00Z"
}

Supplier by its external ID

get/suppliers/by-external-id/{external_id}

Scope: procurement:read

Parameters

Path

  • external_idstringrequired

    External ID: the ID of the record in your system.

Responses

200Success

Headers

  • ETagstringrequired

    Version of the record. Send it in If-Match to change the record.

    Example:
    "7"

application/json

Returns Supplier

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/suppliers/by-external-id/{external_id}" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Example response · 200
{
  "id": 0,
  "version": 0,
  "external_id": "string",
  "name": "string",
  "legal_name": "string",
  "tax_id": "string",
  "tax_id_country": "string",
  "is_active": true,
  "currency": "string",
  "payment_term_days": 0,
  "prices_include_tax": true,
  "settlement_mode": "on_receipt",
  "consignment_loss_policy": "return_to_supplier",
  "lead_time_days": 0,
  "min_order_amount": 0,
  "customer_id": 0,
  "created_at": "2026-01-15T12:00:00Z",
  "updated_at": "2026-01-15T12:00:00Z"
}

Create or update a supplier by its external ID

patch/suppliers/by-external-id/{external_id}

Scope: procurement:write

Parameters

Path

  • external_idstringrequired

    External ID: the ID of the record in your system.

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
  • If-Matchstring

    ETag of the record from the last read. Required when a record with this external ID exists (otherwise 428) and must be absent when it does not.

    Example:
    "7"
  • If-None-Matchstring

    * — create only: if a record with this external ID already exists, the request gets 412.

    Values:
    *

Responses

200Success

Headers

  • Idempotent-Replayedstring

    true when this is the saved response of an earlier request with the same Idempotency-Key.

    Values:
    true
  • ETagstringrequired

    Version of the record. Send it in If-Match to change the record.

    Example:
    "7"

application/json

Returns Supplier

201Created

Headers

  • Idempotent-Replayedstring

    true when this is the saved response of an earlier request with the same Idempotency-Key.

    Values:
    true
  • ETagstringrequired

    Version of the record. Send it in If-Match to change the record.

    Example:
    "7"
  • Locationstring (uri)required

    Address of the created record; for an accepted request (202), the address to follow its outcome.

application/json

Returns Supplier

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

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

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-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 PATCH "https://api.saleya.app/v1/suppliers/by-external-id/{external_id}" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Example response · 200
{
  "id": 0,
  "version": 0,
  "external_id": "string",
  "name": "string",
  "legal_name": "string",
  "tax_id": "string",
  "tax_id_country": "string",
  "is_active": true,
  "currency": "string",
  "payment_term_days": 0,
  "prices_include_tax": true,
  "settlement_mode": "on_receipt",
  "consignment_loss_policy": "return_to_supplier",
  "lead_time_days": 0,
  "min_order_amount": 0,
  "customer_id": 0,
  "created_at": "2026-01-15T12:00:00Z",
  "updated_at": "2026-01-15T12:00:00Z"
}

Supplier balance: what the store owes right now, by component and due date

get/suppliers/{supplier}/balance

Scope: procurement:read

Parameters

Path

  • supplierintegerrequired

    Supplier ID.

Query

  • legal_entity_idinteger

    Only the debt to this store legal entity.

Responses

200Success

application/json

Returns SupplierBalance

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/suppliers/{supplier}/balance" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Example response · 200
{
  "supplier_id": 0,
  "legal_entity_id": 0,
  "as_of": "string",
  "currency": "ARS",
  "total_due": 0,
  "has_open_items": true,
  "bills_outstanding": 0,
  "overdue": 0,
  "overdue_1_30": 0,
  "overdue_31_60": 0,
  "overdue_61_90": 0,
  "overdue_90_plus": 0,
  "not_due": 0,
  "due_soon": 0,
  "no_due_date": 0,
  "settled_pending_bill": 0,
  "accrued_unsettled": 0,
  "received_unbilled": 0,
  "returns_expected": 0,
  "advances_unapplied": 0,
  "payments_unapplied": 0
}

Supplier statement for a period: opening and closing balance, lines with a running balance

get/suppliers/{supplier}/statement

Scope: procurement:read

Parameters

Path

  • supplierintegerrequired

    Supplier ID.

Query

  • fromstring (date)

    First day of the period, YYYY-MM-DD in the store time zone; by default, the day of the first statement line.

  • tostring (date)

    Last day of the period, YYYY-MM-DD in the store time zone; today by default.

  • legal_entity_idinteger

    Statement for this store legal entity: only its share of lines and balances.

Responses

200Success

application/json

Returns SupplierStatement

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/suppliers/{supplier}/statement" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Example response · 200
{
  "supplier_id": 0,
  "legal_entity_id": 0,
  "currency": "ARS",
  "from": "string",
  "to": "string",
  "opening_balance": 0,
  "closing_balance": 0,
  "increase_total": 0,
  "decrease_total": 0,
  "lines": [
    {
      "date": "string",
      "kind": "bill",
      "amount": 0,
      "balance": 0,
      "document": {
        "type": "supplier_bill",
        "id": 0,
        "number": "string"
      },
      "supplier_bill_payment_id": 0,
      "money_transaction_id": 0,
      "settlement_offset_id": 0,
      "document_amount": {
        "currency": "string",
        "amount": 0
      }
    }
  ]
}