POST
Submit a purchase
Company space For: Buyer, Manager · Permission: purchases.try-pending Conditions
  • The purchase must be in draft or rejected status.
  • For a credit purchase, when the supplier has max_debt_balance or max_order_amount and the new debt (supplier computed debt plus the payable total) or the payable total exceeds it, the call is refused with a validation error on need_approval unless need_approval is true. Callers with vendors.bypass_debt_limits skip this check.
What else happens
  • Without limit problems the purchase becomes pending, need_approval is cleared, and the supplier invoice is recognised: invoice_total, remaining_amount (invoice total minus amount_paid and amount_debt_adjusted), invoiced_at and payment_status are set the first time.
  • When a limit is exceeded and need_approval is true, the purchase becomes awaiting_approval, need_approval is set to true and remaining_amount is set to 0; it must then be approved or rejected.
  • If need_approval is true but no limit is exceeded, the purchase still becomes pending.
  • For a credit purchase, once pending the remaining amount counts in the supplier’s computed debt.
  • No stock movement or accounting entry is created.
Part of Create and approve purchases.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

purchase
string
required

Identifier of the purchase to submit.

Query Parameters

response
enum<string>
default:none

Response mode. Default none; none answers 204 No Content.

Available options:
none,
resource
fields
string

Comma-separated JSON keys of the root resource (id is always rendered). Available: id, company_id, vendor_id, reference, purchase_date, notes, status, is_credit, cost_total, cost_total_includes_vat, vat_total, vat_is_recoverable, invoice_total, cost_leftover, invoiced_at, amount_paid, amount_debt_adjusted, remaining_amount, due_date, payment_status, need_approval, cost_strategy, created_at, updated_at.

include
string

Comma-separated include paths, each optionally followed by its fields in parentheses: units(id,sku),units.uomUnit(id,name). Max depth 6, max 40 paths. Available: items, items.stockable, items.stockableUnit, debtAdjustments, debtAdjustments.purchase, returns, returns.items, pickups, pickups.items, pickups.costs, deliveries, deliveries.items, deliveries.costs, vendor.

Body

application/json
need_approval
boolean | null

Set to true to accept sending the purchase for approval when a credit purchase exceeds the supplier's debt limits. When omitted it is false, and exceeding a limit is refused with a validation error. Ignored when no limit is exceeded.

Response

Resource (only with response=resource).

id

Identifier of the purchase (27-character KSUID).

company_id

Identifier of the company the record belongs to.

vendor_id

Identifier of the supplier the goods are bought from.

reference

Free reference of the purchase (for example the supplier's order number); unique among the company's purchases when set.

purchase_date

Date of the purchase (ISO 8601 date), null when not given.

notes

Free notes, up to 1000 characters.

status

Workflow status: draft (editable), awaiting_approval (waiting for a manager when a credit limit was exceeded), rejected (editable again), pending (confirmed, goods can be received), completed, closed.

is_credit
boolean

True when the purchase is bought on credit from the supplier, so the unpaid amount counts as a debt.

cost_total
number

Cost of the purchase as entered. Under the unit cost strategy it is the sum of the line costs before VAT; under the total strategy it is the amount entered by the caller, which includes VAT when cost_total_includes_vat is true. In major units (the stored minor-unit amount divided by 10 to the power currency_exponent).

cost_total_includes_vat
boolean | null

Whether cost_total already includes VAT. Only meaningful under the total cost strategy; null under the unit strategy.

vat_total
number

VAT of the purchase. Computed from the lines under the unit strategy; entered by the caller under the total strategy. In major units (the stored minor-unit amount divided by 10 to the power currency_exponent).

vat_is_recoverable
boolean | null

Whether the VAT of this purchase can be recovered. Required when VAT is above zero; null when never set.

invoice_total
number | null

Amount invoiced by the supplier, VAT included: the sum of the line totals (unit strategy) or cost_total plus VAT when VAT is not included (total strategy). Recomputed while the purchase is editable; null while not yet computed. In major units (the stored minor-unit amount divided by 10 to the power currency_exponent).

cost_leftover
number

Remainder in the division of the invoice total by the total quantity under the total cost strategy, which cannot be spread evenly over the units. 0 under the unit strategy. In major units (the stored minor-unit amount divided by 10 to the power currency_exponent).

invoiced_at

When the supplier invoice was recognised (ISO 8601), set the first time the purchase becomes pending; null before that.

amount_paid
number

Cash paid so far against the purchase. In major units (the stored minor-unit amount divided by 10 to the power currency_exponent).

amount_debt_adjusted
number

Total of debt adjustments applied to the purchase. In major units (the stored minor-unit amount divided by 10 to the power currency_exponent).

remaining_amount
number

Amount still to be paid to the supplier. 0 before the invoice is recognised and while awaiting approval. In major units (the stored minor-unit amount divided by 10 to the power currency_exponent).

due_date

Date by which a credit purchase must be paid (ISO 8601 date); when omitted on a credit purchase, filled from the purchase date (or the creation day) plus the supplier's standard payment terms, if those are above 0.

payment_status

Payment state: unpaid, partial or paid.

need_approval
boolean

True while the purchase waits for a manager's approval because a supplier debt limit was exceeded.

cost_strategy

How costs are entered: unit (a unit_cost per line) or total (one cost_total for the whole purchase).

items
array

Lines of the purchase. Present only when requested with include=items.

debt_adjustments
array

Debt adjustments of the purchase. Present only when requested with include.

returns
array

Returns made against the purchase. Present only when requested with include.

pickups
array

Pickup receptions of the purchase. Present only when requested with include.

deliveries
array

Delivery receptions of the purchase. Present only when requested with include.

vendor
object

The supplier of the purchase. Present only when requested with include=vendor.

created_at

Date and time the record was created (ISO 8601, UTC).

updated_at

Date and time the record was last changed (ISO 8601, UTC).