Draft orders

An order prepared by the app: priced live by the catalog, discounts and delivery, it shows what prevents placing it and becomes an order on completion.

Loading the search index…

Draft orders

Objects

DraftOrder

  • idintegerrequired

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

  • versionintegerrequired

    Revision of the draft: any change of the draft moves it, including a change by the staff in the panel. The draft is changed, deleted and placed under it.

  • statusstringrequired

    open — can be changed and placed; completed — placed, the order is in order_id; cancelled — cancelled without an order.

    Values:
    opencompletedcancelled
  • customer_idinteger or nullrequired

    The customer of the draft (/v1/customers); null until chosen.

  • order_idinteger or nullrequired

    The order placed from the draft; null until it is placed.

  • linesarray of objectrequired

    Items of the draft. An open draft is priced live by the catalog, discounts and delivery; a closed draft keeps its items without prices.

    Fields · 12
    • idintegerrequired

      ID of the line in the draft.

    • variant_idinteger or nullrequired

      Variant of the line; null for a custom line.

    • product_idinteger or nullrequired

      Product of the line; null for a custom line.

    • product_namemap of stringrequired

      Name of the product at the time of the sale, by language.

    • variant_namemap of stringrequired

      Name of the variant at the time of the sale, by language; an empty object when the variant had no name.

    • custom_namestring or nullrequired

      Name of a custom line the staff added without a product; null for a line with a variant.

    • quantitystringrequired

      Quantity, a decimal string in unit: pieces for an item sold by the piece, the measure for an item sold by weight or volume ("480" grams).

    • unitstring or nullrequired

      Unit of quantity: pcs, g or ml; null when the variant no longer knows the unit of its measure.

      Values:
      pcsgmlnull
    • unit_priceinteger or nullrequired

      Price of one unit with its modifiers; null for a closed draft.

    • discountinteger or nullrequired

      Markdown of the line; null for a closed draft.

    • totalinteger or nullrequired

      Amount of the line before the markdown; null for a closed draft.

    • modifiersarray of objectrequired

      Modifiers of the line, such as extra toppings of a dish.

      Fields · 2
      • option_idintegerrequired

        ID of the modifier option.

      • quantityintegerrequired

        How many times the modifier is added.

  • delivery_method_idinteger or nullrequired

    Delivery method (/v1/delivery-methods); null until chosen.

  • address_idinteger or nullrequired

    Address from the address book of the customer, for a method with delivery; null when not chosen.

  • pickup_location_idinteger or nullrequired

    Pickup point for a pickup method. A method with one pickup point uses it by itself; with several the draft must name one.

  • delivery_slotsarray of objectrequired

    Delivery windows chosen for a method that works with windows.

    Fields · 2
    • fromstringrequired

      Start of the window.

    • tostringrequired

      End of the window.

  • delivery_cost_overrideinteger or nullrequired

    Delivery price set by hand instead of the calculation of the method; null — by the rules of the method.

  • payment_methodstring or nullrequired

    Payment method the draft will be placed with: discounts for the method and compatibility with the delivery depend on it.

    Values:
    cashmercadopagocryptobybittrc20balancemodopaywaymercadopago_qrmercadopago_pointmercadopago_transfergift_cardsubscriptiondepositexternalmanualoffseton_accountexchange_creditbonpuntoservice_packagenull
  • manual_payment_method_idinteger or nullrequired

    Manual payment method of the store when payment_method is manual; otherwise null.

  • promocodestring or nullrequired

    Promo code applied to the draft; null when none.

  • customer_commentstring or null

    Comment of the customer to the order. Only with the customers:read scope.

  • notestring or nullrequired

    Internal note of the store: it goes to the order, the customer does not see it.

  • currencystringrequired

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

  • items_totalintegerrequired

    Sum of the lines before the order discount.

  • discountintegerrequired

    Discount of the order.

  • delivery_costinteger or nullrequired

    Delivery to pay; null when it cannot be calculated yet.

  • totalintegerrequired

    Amount to pay.

  • issuesarray of objectrequired

    What prevents placing the draft; empty when nothing does and for a closed draft.

    Fields · 2
    • codestringrequired

      customer_required — no customer; phone_required — the customer has no phone; items_empty — no lines; import_lines_pending, import_parse_running — imported lines are not ready yet; items_unavailable — an item is not for sale; modifier_invalid — a modifier does not fit the item; price_missing — an item has no price; measure_required — an item sold by weight or volume needs its measure; insufficient_stock — not enough stock; presale_not_ready, presale_plan_short — a pre-sale item is not ready or has fewer left than ordered; gift_card_sales_disabled — the store does not sell gift cards; delivery_method_required — no delivery method; address_required — the delivery needs an address; branch_required — the method needs a carrier branch; pickup_location_required — the method has several pickup points, name one; pickup_location_none — the method has no available pickup point; pickup_location_mismatch — the pickup point is not served by the method; slot_required — the method needs a delivery window; slot_invalid — the window is not available; delivery_not_applicable — the method does not deliver this order; delivery_cost_required — the method needs a delivery price set by hand; promocode_invalid — the promo code does not apply; payment_delivery_incompatible — the payment method does not work with the delivery method.

      Values:
      customer_requiredphone_requireditems_emptyimport_lines_pendingimport_parse_runningitems_unavailablemodifier_invalidprice_missingmeasure_requiredinsufficient_stockpresale_not_readypresale_plan_shortgift_card_sales_disableddelivery_method_requiredaddress_requiredbranch_requiredpickup_location_requiredpickup_location_nonepickup_location_mismatchslot_requiredslot_invaliddelivery_not_applicabledelivery_cost_requiredpromocode_invalidpayment_delivery_incompatible
    • line_idinteger or nullrequired

      The line the issue is about; null for an issue of the whole draft.

  • created_atstring (date-time)required

    When the record was created.

  • updated_atstring (date-time)required

    When the record last changed.

Endpoints

Get a draft order: items, totals and what blocks placing it

get/draft-orders/{draft}

Scope: orders:read

Parameters

Path

  • draftintegerrequired

    ID of the draft order.

Responses

200Success

Headers

  • ETagstringrequired

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

    Example:
    "7"

application/json

Returns DraftOrder

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/draft-orders/{draft}" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Example response · 200
{
  "id": 0,
  "version": 0,
  "status": "open",
  "customer_id": 0,
  "order_id": 0,
  "lines": [
    {
      "id": 0,
      "variant_id": 0,
      "product_id": 0,
      "product_name": {
        "key": "string"
      },
      "variant_name": {
        "key": "string"
      },
      "custom_name": "string",
      "quantity": "string",
      "unit": "pcs",
      "unit_price": 0,
      "discount": 0,
      "total": 0,
      "modifiers": [
        {
          "option_id": 0,
          "quantity": 0
        }
      ]
    }
  ],
  "delivery_method_id": 0,
  "address_id": 0,
  "pickup_location_id": 0,
  "delivery_slots": [
    {
      "from": "string",
      "to": "string"
    }
  ],
  "delivery_cost_override": 0,
  "payment_method": "cash",
  "manual_payment_method_id": 0,
  "promocode": "string",
  "customer_comment": "string",
  "note": "string",
  "currency": "string",
  "items_total": 0,
  "discount": 0,
  "delivery_cost": 0,
  "total": 0,
  "issues": [
    {
      "code": "customer_required",
      "line_id": 0
    }
  ],
  "created_at": "2026-01-15T12:00:00Z",
  "updated_at": "2026-01-15T12:00:00Z"
}

Change a draft order: customer, delivery, payment method and items

patch/draft-orders/{draft}

Scope: orders:write

Parameters

Path

  • draftintegerrequired

    ID of the draft order.

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

  • customer_idinteger or null

    The customer of the draft (/v1/customers); null until chosen.

  • delivery_method_idinteger or null

    Delivery method (/v1/delivery-methods); null until chosen.

  • address_idinteger or null

    Address from the address book of the customer, for a method with delivery; null when not chosen.

  • pickup_location_idinteger or null

    Pickup point for a pickup method. A method with one pickup point uses it by itself; with several the draft must name one.

  • delivery_slotsarray of object or null

    Delivery windows chosen for a method that works with windows.

    Max items:
    50
    Fields · 2
    • fromstringrequired

      Start of the window.

    • tostringrequired

      End of the window.

  • delivery_cost_overrideinteger or null

    Delivery price set by hand instead of the calculation of the method; null — by the rules of the method.

    Minimum:
    0
    Maximum:
    10000000000
  • payment_methodstring or null

    Payment method the draft will be placed with: discounts for the method and compatibility with the delivery depend on it.

    Values:
    cashmercadopagocryptobybittrc20balancemodopaywaymercadopago_qrmercadopago_pointmercadopago_transfergift_cardsubscriptiondepositexternalmanualoffseton_accountexchange_creditbonpuntoservice_packagenull
  • manual_payment_method_idinteger or null

    Manual payment method of the store when payment_method is manual; otherwise null.

    Minimum:
    1
  • promocodestring or null

    Promo code applied to the draft; null when none.

    Max length:
    64
  • customer_commentstring or null

    Comment of the customer to the order. Only with the customers:read scope.

    Max length:
    1000
  • notestring or null

    Internal note of the store: it goes to the order, the customer does not see it.

    Max length:
    1000
  • linesarray of object

    Items of the draft. An open draft is priced live by the catalog, discounts and delivery; a closed draft keeps its items without prices.

    Max items:
    200
    No repeats
    Fields · 4
    • idinteger

      ID of the line in the draft.

    • variant_idintegerrequired

      Variant of the line; null for a custom line.

    • quantitystringrequired

      Quantity, a decimal string in unit: pieces for an item sold by the piece, the measure for an item sold by weight or volume ("480" grams).

      Max length:
      32
    • modifiersarray of object

      Modifiers of the line, such as extra toppings of a dish.

      Max items:
      50
      Fields · 2
      • option_idintegerrequired

        ID of the modifier option.

      • quantityinteger

        How many times the modifier is added.

        Minimum:
        1
        Maximum:
        99

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 DraftOrder

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/draft-orders/{draft}" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H 'If-Match: "7"' \
  -H "Content-Type: application/json" \
  -d @body.json
Request body — body.json
{
  "customer_id": 0,
  "delivery_method_id": 0,
  "address_id": 0,
  "pickup_location_id": 0,
  "delivery_slots": [
    {
      "from": "string",
      "to": "string"
    }
  ],
  "delivery_cost_override": 0,
  "payment_method": "cash",
  "manual_payment_method_id": 1,
  "promocode": "string",
  "customer_comment": "string",
  "note": "string",
  "lines": [
    {
      "id": 0,
      "variant_id": 0,
      "quantity": "string",
      "modifiers": [
        {
          "option_id": 0,
          "quantity": 1
        }
      ]
    }
  ]
}
Example response · 200
{
  "id": 0,
  "version": 0,
  "status": "open",
  "customer_id": 0,
  "order_id": 0,
  "lines": [
    {
      "id": 0,
      "variant_id": 0,
      "product_id": 0,
      "product_name": {
        "key": "string"
      },
      "variant_name": {
        "key": "string"
      },
      "custom_name": "string",
      "quantity": "string",
      "unit": "pcs",
      "unit_price": 0,
      "discount": 0,
      "total": 0,
      "modifiers": [
        {
          "option_id": 0,
          "quantity": 0
        }
      ]
    }
  ],
  "delivery_method_id": 0,
  "address_id": 0,
  "pickup_location_id": 0,
  "delivery_slots": [
    {
      "from": "string",
      "to": "string"
    }
  ],
  "delivery_cost_override": 0,
  "payment_method": "cash",
  "manual_payment_method_id": 0,
  "promocode": "string",
  "customer_comment": "string",
  "note": "string",
  "currency": "string",
  "items_total": 0,
  "discount": 0,
  "delivery_cost": 0,
  "total": 0,
  "issues": [
    {
      "code": "customer_required",
      "line_id": 0
    }
  ],
  "created_at": "2026-01-15T12:00:00Z",
  "updated_at": "2026-01-15T12:00:00Z"
}

Delete a draft order

delete/draft-orders/{draft}

Scope: orders:write

Parameters

Path

  • draftintegerrequired

    ID of the draft order.

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/draft-orders/{draft}" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H 'If-Match: "7"'

Create a draft order for a customer

post/draft-orders

Scope: orders: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

  • customer_idinteger or null

    The customer of the draft (/v1/customers); null until chosen.

  • delivery_method_idinteger or null

    Delivery method (/v1/delivery-methods); null until chosen.

  • address_idinteger or null

    Address from the address book of the customer, for a method with delivery; null when not chosen.

  • pickup_location_idinteger or null

    Pickup point for a pickup method. A method with one pickup point uses it by itself; with several the draft must name one.

  • delivery_slotsarray of object or null

    Delivery windows chosen for a method that works with windows.

    Max items:
    50
    Fields · 2
    • fromstringrequired

      Start of the window.

    • tostringrequired

      End of the window.

  • delivery_cost_overrideinteger or null

    Delivery price set by hand instead of the calculation of the method; null — by the rules of the method.

    Minimum:
    0
    Maximum:
    10000000000
  • payment_methodstring or null

    Payment method the draft will be placed with: discounts for the method and compatibility with the delivery depend on it.

    Values:
    cashmercadopagocryptobybittrc20balancemodopaywaymercadopago_qrmercadopago_pointmercadopago_transfergift_cardsubscriptiondepositexternalmanualoffseton_accountexchange_creditbonpuntoservice_packagenull
  • manual_payment_method_idinteger or null

    Manual payment method of the store when payment_method is manual; otherwise null.

    Minimum:
    1
  • promocodestring or null

    Promo code applied to the draft; null when none.

    Max length:
    64
  • customer_commentstring or null

    Comment of the customer to the order. Only with the customers:read scope.

    Max length:
    1000
  • notestring or null

    Internal note of the store: it goes to the order, the customer does not see it.

    Max length:
    1000
  • linesarray of object

    Items of the draft. An open draft is priced live by the catalog, discounts and delivery; a closed draft keeps its items without prices.

    Max items:
    200
    No repeats
    Fields · 4
    • idinteger

      ID of the line in the draft.

    • variant_idintegerrequired

      Variant of the line; null for a custom line.

    • quantitystringrequired

      Quantity, a decimal string in unit: pieces for an item sold by the piece, the measure for an item sold by weight or volume ("480" grams).

      Max length:
      32
    • modifiersarray of object

      Modifiers of the line, such as extra toppings of a dish.

      Max items:
      50
      Fields · 2
      • option_idintegerrequired

        ID of the modifier option.

      • quantityinteger

        How many times the modifier is added.

        Minimum:
        1
        Maximum:
        99

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 DraftOrder

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/draft-orders" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json
Request body — body.json
{
  "customer_id": 0,
  "delivery_method_id": 0,
  "address_id": 0,
  "pickup_location_id": 0,
  "delivery_slots": [
    {
      "from": "string",
      "to": "string"
    }
  ],
  "delivery_cost_override": 0,
  "payment_method": "cash",
  "manual_payment_method_id": 1,
  "promocode": "string",
  "customer_comment": "string",
  "note": "string",
  "lines": [
    {
      "id": 0,
      "variant_id": 0,
      "quantity": "string",
      "modifiers": [
        {
          "option_id": 0,
          "quantity": 1
        }
      ]
    }
  ]
}
Example response · 201
{
  "id": 0,
  "version": 0,
  "status": "open",
  "customer_id": 0,
  "order_id": 0,
  "lines": [
    {
      "id": 0,
      "variant_id": 0,
      "product_id": 0,
      "product_name": {
        "key": "string"
      },
      "variant_name": {
        "key": "string"
      },
      "custom_name": "string",
      "quantity": "string",
      "unit": "pcs",
      "unit_price": 0,
      "discount": 0,
      "total": 0,
      "modifiers": [
        {
          "option_id": 0,
          "quantity": 0
        }
      ]
    }
  ],
  "delivery_method_id": 0,
  "address_id": 0,
  "pickup_location_id": 0,
  "delivery_slots": [
    {
      "from": "string",
      "to": "string"
    }
  ],
  "delivery_cost_override": 0,
  "payment_method": "cash",
  "manual_payment_method_id": 0,
  "promocode": "string",
  "customer_comment": "string",
  "note": "string",
  "currency": "string",
  "items_total": 0,
  "discount": 0,
  "delivery_cost": 0,
  "total": 0,
  "issues": [
    {
      "code": "customer_required",
      "line_id": 0
    }
  ],
  "created_at": "2026-01-15T12:00:00Z",
  "updated_at": "2026-01-15T12:00:00Z"
}

Place the order from a draft: invoice the customer or record the payment as received

post/draft-orders/{draft}/complete

Scope: orders:write

Parameters

Path

  • draftintegerrequired

    ID of the draft order.

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

  • modestringrequired

    invoice — the order waits for payment, the payment details go to the customer through the channels of the store, the payment page is in payment_url of the payment; after_picking — the customer is invoiced the exact total after picking, for goods sold by weight; mark_paid — the money was already received by a manual method, needs the payments:write scope.

    Values:
    invoiceafter_pickingmark_paid
  • expected_totalintegerrequired

    The total you read on the draft: prices, discounts or delivery may change after reading. If it differs, the request gets 422 and no order is created.

    Minimum:
    0
    Maximum:
    100000000000000
  • currencystring

    The currency in which you read the total: the currency field of the draft. A store without orders may change its currency, and the change keeps price numbers as they are; if the currency differs, the request gets 422 and no order is created. Without the field the currency is not checked.

    Min length:
    3
    Max length:
    3

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 Order

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/draft-orders/{draft}/complete" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN" \
  -H 'If-Match: "7"' \
  -H "Content-Type: application/json" \
  -d @body.json
Request body — body.json
{
  "mode": "invoice",
  "expected_total": 0,
  "currency": "string"
}
Example response · 201
{
  "id": 0,
  "number": "string",
  "channel": "web",
  "app_id": 0,
  "location_id": 0,
  "legal_entity_id": 0,
  "status": "string",
  "status_group": "pos_open",
  "payment_status": "unpaid",
  "sale_type": "retail",
  "currency": "string",
  "items_total": 0,
  "discount": 0,
  "applied_discounts": [
    {
      "id": 0,
      "source": "promocode",
      "kind": "promo",
      "name": {},
      "code": "string",
      "reason": "string",
      "order_item_id": 0,
      "amount": 0
    }
  ],
  "delivery_cost": 0,
  "delivery_discount": 0,
  "delivery_discounts": [
    {
      "id": 0,
      "source": "promocode",
      "kind": "promo",
      "name": {},
      "code": "string",
      "amount": 0
    }
  ],
  "delivery_tax_lines": [
    {
      "regime": "vat",
      "kind": "taxed",
      "rate_bps": 0,
      "base": 0,
      "amount": 0,
      "jurisdiction": "string"
    }
  ],
  "platform_discount": 0,
  "platform_service_fee": 0,
  "platform_delivery_fee": 0,
  "total": 0,
  "tax_lines": [
    {
      "regime": "vat",
      "kind": "taxed",
      "rate_bps": 0,
      "base": 0,
      "amount": 0,
      "jurisdiction": "string"
    }
  ],
  "gift_card_issue_amount": 0,
  "reservation_deposit_amount": 0,
  "account_payment_amount": 0,
  "service_package_issue_amount": 0,
  "payment_method": "cash",
  "manual_payment_method_id": 0,
  "delivery_method_id": 0,
  "fulfilment_type": "self_pickup",
  "delivery_slots": [
    {
      "from": "string",
      "to": "string"
    }
  ],
  "shipment": {
    "carrier": "andreani",
    "carrier_name": "string",
    "tracking_number": "string",
    "tracking_url": "string",
    "status": "accepted",
    "status_at": "2026-01-15T12:00:00Z",
    "events": [
      {
        "status": "accepted",
        "description": "string",
        "occurred_at": "2026-01-15T12:00:00Z"
      }
    ],
    "label_available": true
  },
  "previous_shipments": [
    {
      "carrier": "andreani",
      "carrier_name": "string",
      "tracking_number": "string",
      "tracking_url": "string",
      "status": "accepted",
      "status_at": "2026-01-15T12:00:00Z",
      "events": [
        {
          "status": "accepted",
          "description": "string",
          "occurred_at": "2026-01-15T12:00:00Z"
        }
      ]
    }
  ],
  "shipment_attempt": {
    "state": "queued",
    "started_at": "2026-01-15T12:00:00Z",
    "error": {
      "code": "no_carrier",
      "message": "string"
    }
  },
  "merged_into_order_id": 0,
  "cancel_reason": "payment_init_failed",
  "items": [
    {
      "id": 0,
      "variant_id": 0,
      "product_id": 0,
      "product_name": {
        "key": "string"
      },
      "variant_name": {
        "key": "string"
      },
      "quantity": "string",
      "unit": "pcs",
      "unit_price": 0,
      "total": 0,
      "discount": 0,
      "discount_allocations": [
        {
          "applied_discount_id": 0,
          "amount": 0
        }
      ],
      "is_gift": true,
      "tax_lines": [
        {
          "regime": "vat",
          "kind": "taxed",
          "rate_bps": 0,
          "base": 0,
          "amount": 0,
          "jurisdiction": "string"
        }
      ],
      "cost_amount": 0,
      "cost_basis": "variant"
    }
  ],
  "customer": {
    "id": 0,
    "name": "string",
    "phone": "string",
    "email": "string"
  },
  "delivery_address": {
    "kind": "address",
    "recipient": "string",
    "phone": "string",
    "street": "string",
    "house": "string",
    "apartment": "string",
    "floor": "string",
    "entrance": "string",
    "district": "string",
    "city": "string",
    "province": "string",
    "postal_code": "string",
    "address_line": "string",
    "comment": "string",
    "location": {
      "lat": 0,
      "lng": 0
    },
    "branch": {
      "external_id": "string",
      "name": "string"
    }
  },
  "customer_comment": "string",
  "fiscal_receptor": {
    "id_type": "tax_id",
    "id_number": "string",
    "name": "string",
    "tax_status": "registered",
    "address": "string"
  },
  "external_fiscal_document": {
    "issuer": "string",
    "status": "pending",
    "number": "string"
  },
  "placed_at": "2026-01-15T12:00:00Z",
  "confirmed_at": "2026-01-15T12:00:00Z",
  "completed_at": "2026-01-15T12:00:00Z",
  "cancelled_at": "2026-01-15T12:00:00Z",
  "refunded_at": "2026-01-15T12:00:00Z",
  "created_at": "2026-01-15T12:00:00Z",
  "updated_at": "2026-01-15T12:00:00Z"
}