Consignment settlements

Statements of consignment goods sold over a period, the basis of the supplier invoice: sections, lines and totals.

Loading the search index…

Consignment settlements

Objects

ConsignmentSettlement

  • idintegerrequired

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

  • numberstringrequired

    Settlement number.

  • statusstringrequired

    draft — the period is collected for review, the sales are not yet frozen and the period can change; posted — agreed with the supplier: the sales of the period are frozen into it and a bill can be issued against it; void — voided: its sales are released and go into the next settlement.

    Values:
    draftpostedvoid
  • supplier_idintegerrequired

    Supplier ID (/v1/suppliers).

  • legal_entity_idinteger or nullrequired

    Store legal entity the supplier invoices (/v1/legal-entities); null on older settlements: the default legal entity.

  • supplier_bill_idinteger or nullrequired

    Bill issued against the settlement (/v1/supplier-bills); null — not billed yet or the bill was voided and the settlement can be billed again. A voided bill keeps the link in its consignment_settlement_id.

  • currencystringrequired

    Settlement currency, ISO 4217 — the currency of the supply prices: line prices, amounts and subtotal are in it.

  • period_fromstringrequired

    First day of the period, YYYY-MM-DD.

  • period_tostringrequired

    Last day of the period, YYYY-MM-DD.

  • subtotalintegerrequired

    Settlement total in its currency — the sum of the lines, what the supplier invoices.

  • base_subtotalintegerrequired

    The same total in the store currency.

  • sectionsarray of objectrequired

    Subtotals by section in document order; empty sections are left out.

    Fields · 2
    • kindstringrequired

      sale — goods sold; loss — expired or missing goods the store pays for under the supplier policy; price_adjustment — extra charge for a price fixed by a goods receipt correction after the goods were charged.

      Values:
      salelossprice_adjustment
    • subtotalintegerrequired

      Section subtotal in the settlement currency.

  • linesarray of objectrequired

    Settlement lines in document order: variant × goods receipt × price.

    Fields · 14
    • idintegerrequired

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

    • positionintegerrequired

      Line number in the document.

    • kindstringrequired

      Section of the line, with the codes of sections[].kind.

      Values:
      salelossprice_adjustment
    • variant_idinteger or nullrequired

      Product variant ID (/v1/variants).

    • lot_idinteger or nullrequired

      Lot of the line (/v1/lots); null for a product without lots.

    • goods_receipt_idinteger or nullrequired

      Goods receipt the goods came with (/v1/goods-receipts).

    • namestringrequired

      Item name as in the document: captured when the settlement was built and not changed by later renames.

    • skustring or nullrequired

      Variant SKU captured with the name; null if there is none.

    • unitstring or nullrequired

      Base unit of the line quantity: pcs — pieces, g — grams, ml — milliliters.

    • quantitystring or nullrequired

      Quantity sold, written off or repriced, a decimal string in the base unit; a sale cancelled within the period is subtracted.

    • unit_costinteger or nullrequired

      Supply price in the settlement currency per cost_per_quantity; on a price_adjustment line — the new price. null — the goods receipt has no price, and the line is charged at zero.

    • cost_per_quantitystring or nullrequired

      Quantity in the base unit the price is for: "1000" on a weighed product means per kilogram.

    • amountintegerrequired

      Line amount in the settlement currency; on a price_adjustment line — the difference to what was already charged. Lines add up to subtotal.

    • base_amountintegerrequired

      Line amount in the store currency.

  • notestring or nullrequired

    Staff note; null if there is none.

  • posted_atstring (date-time) or nullrequired

    When the settlement was posted; null on a draft.

  • voided_atstring (date-time) or nullrequired

    When the settlement was voided; null on an active settlement.

  • created_atstring (date-time)required

    When the record was created.

  • updated_atstring (date-time)required

    When the record last changed.

Endpoints

Consignment settlements: consignment goods sold, written off at the store's cost and repriced over a period

get/consignment-settlements

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

    Only documents of this supplier.

    Minimum:
    1

Responses

200Success

application/json

  • dataarray of ConsignmentSettlementrequired

    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/consignment-settlements" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Example response · 200
{
  "data": [
    {
      "id": 0,
      "number": "string",
      "status": "draft",
      "supplier_id": 0,
      "legal_entity_id": 0,
      "supplier_bill_id": 0,
      "currency": "string",
      "period_from": "string",
      "period_to": "string",
      "subtotal": 0,
      "base_subtotal": 0,
      "sections": [
        {
          "kind": "sale",
          "subtotal": 0
        }
      ],
      "lines": [
        {
          "id": 0,
          "position": 0,
          "kind": "sale",
          "variant_id": 0,
          "lot_id": 0,
          "goods_receipt_id": 0,
          "name": "string",
          "sku": "string",
          "unit": "string",
          "quantity": "string",
          "unit_cost": 0,
          "cost_per_quantity": "string",
          "amount": 0,
          "base_amount": 0
        }
      ],
      "note": "string",
      "posted_at": "2026-01-15T12:00:00Z",
      "voided_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"
}

Consignment settlement

get/consignment-settlements/{consignment_settlement}

Scope: procurement:read

Parameters

Path

  • consignment_settlementintegerrequired

    Consignment settlement ID.

Responses

200Success

application/json

Returns ConsignmentSettlement

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/consignment-settlements/{consignment_settlement}" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Example response · 200
{
  "id": 0,
  "number": "string",
  "status": "draft",
  "supplier_id": 0,
  "legal_entity_id": 0,
  "supplier_bill_id": 0,
  "currency": "string",
  "period_from": "string",
  "period_to": "string",
  "subtotal": 0,
  "base_subtotal": 0,
  "sections": [
    {
      "kind": "sale",
      "subtotal": 0
    }
  ],
  "lines": [
    {
      "id": 0,
      "position": 0,
      "kind": "sale",
      "variant_id": 0,
      "lot_id": 0,
      "goods_receipt_id": 0,
      "name": "string",
      "sku": "string",
      "unit": "string",
      "quantity": "string",
      "unit_cost": 0,
      "cost_per_quantity": "string",
      "amount": 0,
      "base_amount": 0
    }
  ],
  "note": "string",
  "posted_at": "2026-01-15T12:00:00Z",
  "voided_at": "2026-01-15T12:00:00Z",
  "created_at": "2026-01-15T12:00:00Z",
  "updated_at": "2026-01-15T12:00:00Z"
}