Purchase orders

What the store ordered from a supplier: lines with ordered, confirmed and received quantities, price and promised delivery date.

Loading the search index…

Purchase orders

Objects

PurchaseOrder

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

  • numberstring or nullrequired

    Order number; null on an order created before numbering.

  • statusstringrequired

    draft — not sent to the supplier; sent — placed, delivery expected; partial — partly received; received — fully received; closed — closed by the store, received in full or short (closed_short); cancelled — cancelled.

    Values:
    draftsentpartialreceivedclosedcancelled
  • supplier_idintegerrequired

    Supplier ID (/v1/suppliers).

  • location_idintegerrequired

    Location the delivery is expected at (/v1/locations).

  • legal_entity_idinteger or nullrequired

    Buying legal entity of the store (/v1/legal-entities); null on an order created before the store had legal entities.

  • currencystringrequired

    Order currency, ISO 4217: line prices and totals are in it.

  • prices_include_taxbooleanrequired

    true — line prices include tax; false — they do not.

  • ordered_totalintegerrequired

    Value of what is ordered and still in force; for a closed line, of what was received.

  • received_totalintegerrequired

    Value of what was received against the order.

  • expected_onstring (date) or nullrequired

    When the store expects the delivery, YYYY-MM-DD; null if not set.

  • next_delivery_onstring (date) or nullrequired

    Next expected delivery, taking the dates promised by the supplier into account, YYYY-MM-DD; null if nothing is expected.

  • placed_atstring (date-time) or nullrequired

    When the order was first sent to the supplier; null on a draft and on an order cancelled before sending.

  • closed_shortbooleanrequired

    true — the order was closed short: the rest is no longer expected.

  • supplier_responsestring or nullrequired

    Supplier answer: awaiting — waiting; confirmed — confirmed as is; changed — confirmed with changes (see confirmed_quantity and promised_on of the lines); declined — declined; null — answers are not tracked.

    Values:
    awaitingconfirmedchangeddeclinednull
  • revisionintegerrequired

    Revision of the order terms the supplier sees: grows with each change to a placed order.

  • notestring or nullrequired

    Staff note; null if there is none.

  • linesarray of objectrequired

    Order lines in document order.

    Fields · 12
    • idintegerrequired

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

    • variant_idintegerrequired

      Product variant ID (/v1/variants).

    • unitstring or nullrequired

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

    • ordered_quantitystring or nullrequired

      Ordered quantity, a decimal string in the base unit.

    • confirmed_quantitystring or nullrequired

      Quantity confirmed by the supplier; null — no answer for the line.

    • received_quantitystring or nullrequired

      Quantity received against the line.

    • unit_costinteger or nullrequired

      Price in the order currency per cost_per_quantity; null — no price.

    • cost_per_quantitystring or nullrequired

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

    • ordered_amountinteger or nullrequired

      Value of the line quantity in force; null without a price. Lines add up to ordered_total.

    • received_amountinteger or nullrequired

      Value of the received quantity; null without a price. Lines add up to received_total.

    • promised_onstring (date) or nullrequired

      Delivery date promised by the supplier, YYYY-MM-DD; null — no promise, expected by expected_on.

    • closed_atstring (date-time) or nullrequired

      When the line was closed and the rest no longer expected; null on an open line.

  • created_atstring (date-time)required

    When the record was created.

  • updated_atstring (date-time)required

    When the record last changed.

Endpoints

Purchase orders: ordered, confirmed by the supplier and received, by line

get/purchase-orders

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.

  • supplier_idinteger

    Only documents of this supplier.

    Minimum:
    1

Responses

200Success

application/json

  • dataarray of PurchaseOrderrequired

    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/purchase-orders" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Example response · 200
{
  "data": [
    {
      "id": 0,
      "version": 0,
      "number": "string",
      "status": "draft",
      "supplier_id": 0,
      "location_id": 0,
      "legal_entity_id": 0,
      "currency": "string",
      "prices_include_tax": true,
      "ordered_total": 0,
      "received_total": 0,
      "expected_on": "2026-01-15",
      "next_delivery_on": "2026-01-15",
      "placed_at": "2026-01-15T12:00:00Z",
      "closed_short": true,
      "supplier_response": "awaiting",
      "revision": 0,
      "note": "string",
      "lines": [
        {
          "id": 0,
          "variant_id": 0,
          "unit": "string",
          "ordered_quantity": "string",
          "confirmed_quantity": "string",
          "received_quantity": "string",
          "unit_cost": 0,
          "cost_per_quantity": "string",
          "ordered_amount": 0,
          "received_amount": 0,
          "promised_on": "2026-01-15",
          "closed_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"
}

Create a draft purchase order

post/purchase-orders

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

  • supplier_idintegerrequired

    Supplier ID (/v1/suppliers).

  • location_idintegerrequired

    Location the delivery is expected at (/v1/locations).

  • legal_entity_idinteger or null

    Buying legal entity of the store (/v1/legal-entities); null on an order created before the store had legal entities.

  • currencystringrequired

    Order currency, ISO 4217: line prices and totals are in it.

    Values:
    ARSUSDBRLCLPCOPMXNPENRUB
  • prices_include_taxboolean

    true — line prices include tax; false — they do not.

  • expected_onstring (date) or null

    When the store expects the delivery, YYYY-MM-DD; null if not set.

  • notestring or null

    Staff note; null if there is none.

    Max length:
    2000
  • linesarray of objectrequired

    Order lines in document order.

    Min items:
    1
    Max items:
    500
    No repeats
    Fields · 4
    • variant_idintegerrequired

      Product variant ID (/v1/variants).

    • ordered_quantitystringrequired

      Ordered quantity, a decimal string in the base unit.

      Max length:
      32
    • unit_costinteger or null

      Price in the order currency per cost_per_quantity; null — no price.

      Minimum:
      0
      Maximum:
      10000000000
    • cost_per_quantitystring

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

      Max length:
      32

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 PurchaseOrder

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/purchase-orders" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json
Request body — body.json
{
  "supplier_id": 0,
  "location_id": 0,
  "legal_entity_id": 0,
  "currency": "ARS",
  "prices_include_tax": true,
  "expected_on": "2026-01-15",
  "note": "string",
  "lines": [
    {
      "variant_id": 0,
      "ordered_quantity": "string",
      "unit_cost": 0,
      "cost_per_quantity": "string"
    }
  ]
}
Example response · 201
{
  "id": 0,
  "version": 0,
  "number": "string",
  "status": "draft",
  "supplier_id": 0,
  "location_id": 0,
  "legal_entity_id": 0,
  "currency": "string",
  "prices_include_tax": true,
  "ordered_total": 0,
  "received_total": 0,
  "expected_on": "2026-01-15",
  "next_delivery_on": "2026-01-15",
  "placed_at": "2026-01-15T12:00:00Z",
  "closed_short": true,
  "supplier_response": "awaiting",
  "revision": 0,
  "note": "string",
  "lines": [
    {
      "id": 0,
      "variant_id": 0,
      "unit": "string",
      "ordered_quantity": "string",
      "confirmed_quantity": "string",
      "received_quantity": "string",
      "unit_cost": 0,
      "cost_per_quantity": "string",
      "ordered_amount": 0,
      "received_amount": 0,
      "promised_on": "2026-01-15",
      "closed_at": "2026-01-15T12:00:00Z"
    }
  ],
  "created_at": "2026-01-15T12:00:00Z",
  "updated_at": "2026-01-15T12:00:00Z"
}

Purchase order

get/purchase-orders/{purchase_order}

Scope: procurement:read

Parameters

Path

  • purchase_orderintegerrequired

    Purchase order ID.

Responses

200Success

Headers

  • ETagstringrequired

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

    Example:
    "7"

application/json

Returns PurchaseOrder

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/purchase-orders/{purchase_order}" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Example response · 200
{
  "id": 0,
  "version": 0,
  "number": "string",
  "status": "draft",
  "supplier_id": 0,
  "location_id": 0,
  "legal_entity_id": 0,
  "currency": "string",
  "prices_include_tax": true,
  "ordered_total": 0,
  "received_total": 0,
  "expected_on": "2026-01-15",
  "next_delivery_on": "2026-01-15",
  "placed_at": "2026-01-15T12:00:00Z",
  "closed_short": true,
  "supplier_response": "awaiting",
  "revision": 0,
  "note": "string",
  "lines": [
    {
      "id": 0,
      "variant_id": 0,
      "unit": "string",
      "ordered_quantity": "string",
      "confirmed_quantity": "string",
      "received_quantity": "string",
      "unit_cost": 0,
      "cost_per_quantity": "string",
      "ordered_amount": 0,
      "received_amount": 0,
      "promised_on": "2026-01-15",
      "closed_at": "2026-01-15T12:00:00Z"
    }
  ],
  "created_at": "2026-01-15T12:00:00Z",
  "updated_at": "2026-01-15T12:00:00Z"
}

Change a purchase order: a draft in full, a placed order’s lines, date and note with a revision

patch/purchase-orders/{purchase_order}

Scope: procurement:write

Parameters

Path

  • purchase_orderintegerrequired

    Purchase order 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"

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 PurchaseOrder

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/purchase-orders/{purchase_order}" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H 'If-Match: "7"'
Example response · 200
{
  "id": 0,
  "version": 0,
  "number": "string",
  "status": "draft",
  "supplier_id": 0,
  "location_id": 0,
  "legal_entity_id": 0,
  "currency": "string",
  "prices_include_tax": true,
  "ordered_total": 0,
  "received_total": 0,
  "expected_on": "2026-01-15",
  "next_delivery_on": "2026-01-15",
  "placed_at": "2026-01-15T12:00:00Z",
  "closed_short": true,
  "supplier_response": "awaiting",
  "revision": 0,
  "note": "string",
  "lines": [
    {
      "id": 0,
      "variant_id": 0,
      "unit": "string",
      "ordered_quantity": "string",
      "confirmed_quantity": "string",
      "received_quantity": "string",
      "unit_cost": 0,
      "cost_per_quantity": "string",
      "ordered_amount": 0,
      "received_amount": 0,
      "promised_on": "2026-01-15",
      "closed_at": "2026-01-15T12:00:00Z"
    }
  ],
  "created_at": "2026-01-15T12:00:00Z",
  "updated_at": "2026-01-15T12:00:00Z"
}

Delete a draft purchase order

delete/purchase-orders/{purchase_order}

Scope: procurement:write

Parameters

Path

  • purchase_orderintegerrequired

    Purchase order ID.

Query

  • consentobject

    Consents to the consequences of the change, by kind: consent[<consent_kind>]=<consent_token> from a 409 consent_required response. Keep the consents already given when the next kind is asked.

    Fields · 1
    • purchase_order_follow_upstring

      The draft is a follow-up order from a “buy elsewhere” decision on another order’s supplier answer: deleting it withdraws that decision, and the discrepancy on the source order waits for a decision again. source_orders counts the source orders affected.

      Min length:
      64
      Max length:
      64

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"

Responses

204Success

Headers

  • Idempotent-Replayedstring

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

    Values:
    true

No body

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 DELETE "https://api.saleya.app/v1/purchase-orders/{purchase_order}" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H 'If-Match: "7"'

Mark a draft as placed with the supplier

post/purchase-orders/{purchase_order}/place

Scope: procurement:write

Parameters

Path

  • purchase_orderintegerrequired

    Purchase order 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"

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 PurchaseOrder

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 POST "https://api.saleya.app/v1/purchase-orders/{purchase_order}/place" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H 'If-Match: "7"'
Example response · 200
{
  "id": 0,
  "version": 0,
  "number": "string",
  "status": "draft",
  "supplier_id": 0,
  "location_id": 0,
  "legal_entity_id": 0,
  "currency": "string",
  "prices_include_tax": true,
  "ordered_total": 0,
  "received_total": 0,
  "expected_on": "2026-01-15",
  "next_delivery_on": "2026-01-15",
  "placed_at": "2026-01-15T12:00:00Z",
  "closed_short": true,
  "supplier_response": "awaiting",
  "revision": 0,
  "note": "string",
  "lines": [
    {
      "id": 0,
      "variant_id": 0,
      "unit": "string",
      "ordered_quantity": "string",
      "confirmed_quantity": "string",
      "received_quantity": "string",
      "unit_cost": 0,
      "cost_per_quantity": "string",
      "ordered_amount": 0,
      "received_amount": 0,
      "promised_on": "2026-01-15",
      "closed_at": "2026-01-15T12:00:00Z"
    }
  ],
  "created_at": "2026-01-15T12:00:00Z",
  "updated_at": "2026-01-15T12:00:00Z"
}

Cancel a placed purchase order

post/purchase-orders/{purchase_order}/cancel

Scope: procurement:write

Parameters

Path

  • purchase_orderintegerrequired

    Purchase order 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"

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 PurchaseOrder

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 POST "https://api.saleya.app/v1/purchase-orders/{purchase_order}/cancel" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H 'If-Match: "7"'
Example response · 200
{
  "id": 0,
  "version": 0,
  "number": "string",
  "status": "draft",
  "supplier_id": 0,
  "location_id": 0,
  "legal_entity_id": 0,
  "currency": "string",
  "prices_include_tax": true,
  "ordered_total": 0,
  "received_total": 0,
  "expected_on": "2026-01-15",
  "next_delivery_on": "2026-01-15",
  "placed_at": "2026-01-15T12:00:00Z",
  "closed_short": true,
  "supplier_response": "awaiting",
  "revision": 0,
  "note": "string",
  "lines": [
    {
      "id": 0,
      "variant_id": 0,
      "unit": "string",
      "ordered_quantity": "string",
      "confirmed_quantity": "string",
      "received_quantity": "string",
      "unit_cost": 0,
      "cost_per_quantity": "string",
      "ordered_amount": 0,
      "received_amount": 0,
      "promised_on": "2026-01-15",
      "closed_at": "2026-01-15T12:00:00Z"
    }
  ],
  "created_at": "2026-01-15T12:00:00Z",
  "updated_at": "2026-01-15T12:00:00Z"
}

Close a received purchase order

post/purchase-orders/{purchase_order}/close

Scope: procurement:write

Parameters

Path

  • purchase_orderintegerrequired

    Purchase order 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"

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 PurchaseOrder

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 POST "https://api.saleya.app/v1/purchase-orders/{purchase_order}/close" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H 'If-Match: "7"'
Example response · 200
{
  "id": 0,
  "version": 0,
  "number": "string",
  "status": "draft",
  "supplier_id": 0,
  "location_id": 0,
  "legal_entity_id": 0,
  "currency": "string",
  "prices_include_tax": true,
  "ordered_total": 0,
  "received_total": 0,
  "expected_on": "2026-01-15",
  "next_delivery_on": "2026-01-15",
  "placed_at": "2026-01-15T12:00:00Z",
  "closed_short": true,
  "supplier_response": "awaiting",
  "revision": 0,
  "note": "string",
  "lines": [
    {
      "id": 0,
      "variant_id": 0,
      "unit": "string",
      "ordered_quantity": "string",
      "confirmed_quantity": "string",
      "received_quantity": "string",
      "unit_cost": 0,
      "cost_per_quantity": "string",
      "ordered_amount": 0,
      "received_amount": 0,
      "promised_on": "2026-01-15",
      "closed_at": "2026-01-15T12:00:00Z"
    }
  ],
  "created_at": "2026-01-15T12:00:00Z",
  "updated_at": "2026-01-15T12:00:00Z"
}