Purchases Queries

Query purchase orders, supplier information, delivery status, and validation workflow.

Purchase — Returns a single purchase order by id

Example Query:

GraphQL

query GetPurchase($id: ID!) {
  Purchase(id: $id) {
    id
    label
    status
    dated_at
    shipping_at
    total_units
    update_incoming
    subtotal
    total
    currency { id label }
    supplier { id label }
    line_items {
      id
      variant { id label }
      quantity
      price
    }
    purchase_receipts {
      paginatorInfo { total }
      data { id label }
    }
  }
}

Purchases — Returns a paginated list of purchase orders with sorting and filters

GraphQL

query Purchases(
  $where: QueryPurchasesWhereWhereConditions,
  $orderBy: [QueryPurchasesOrderByOrderByClause!],
  $search: String,
  $first: Int,
  $page: Int
) {
  Purchases(
    where: $where,
    orderBy: $orderBy,
    search: $search,
    first: $first,
    page: $page
  ) {
    paginatorInfo {
      total
      currentPage
    }
    data {
      id
      label
      status
      dated_at
      supplier { id label }
    }
  }
}

---

Available fields

Field	Type	Description
id	Int	Unique identifier.
label	String	Purchase order number.
status	PurchaseStatus	Current status.
dated_at	Date	Document date.
created_at	DateTime	Creation time.
updated_at	DateTime	Last update time.
shipping_at	Date	Expected delivery date.
total_units	Float	Total quantity ordered.
total_units_aggregate	Float	Sum of units for filtered orders.
update_incoming	Boolean	True if items update incoming stock levels.
update_stock	Boolean	True if this purchase updates stock levels.
notes	String	Public notes for documents.
internal_notes	String	Private notes.
for_the_attention_of	String	Specific recipient name.
external_reference	String	Merchant internal reference.
tax_type	TaxType	Tax calculation method (Exclusive/Inclusive).
discount_type	DiscountType	Global discount type (Fixed/Percentage).
total_without_tax	Float	Total excluding taxes.
total_ecotax	Float	Total environmental tax.
subtotal	Float	Value before taxes and discounts.
total	Float	Grand total.
exchange_rate	Float	Currency exchange rate.
currency	Currency	Document currency.
supplier	Supplier	Linked supplier.
line_items	[LineItemPurchase]	List of items.
location_label	String	Source/Target location label.
drop_shipping	Boolean	True if drop shipping is active.
committed_quantity	Float	Quantity committed to stock.
uncommitted_quantity	Float	Quantity awaiting commitment.
reserved_quantity	Float	Quantity currently reserved.
delivered_quantity	Float	Quantity physically delivered.
remaining_shipping_cost	Float	Unallocated shipping costs.
integrations	[Integration]	Linked external platforms.
purchase_receipts_count	Int	Number of linked purchase receipts.
purchase_receipts	[PurchaseReceipt]	Linked receipts history.
orders_count	Int	Number of linked sales orders.
orders	[Order]	Linked sales orders.
has_batch_numbers	Boolean	True if items have batch tracking.
tracking_completed	Boolean	True if all tracking info is entered.
stock_allocation_status	StockAllocationStatus	Stock commitment progress.
delivery_status	DeliveryStatus	Physical reception progress.
custom_fields	[EntityCustomField]	Custom fields for this entity.
validation_rules_steps	[DocumentValidationRuleStep]	Approval workflow progress.

---

Filters

The following fields can be used in the where parameter:

id, label, status, total_units, update_incoming, dated_at, created_at, updated_at, supplier_id, currency, shipping_at, season_id, committed_quantity, uncommitted_quantity, delivered_quantity, reserved_quantity, orders_count, purchase_receipts_count, variant_id, variant_label, variant_sku, location_id, drop_shipping, batch_number_id, has_batch_numbers, tracking_completed, valider, stock_allocation_status, delivery_status.

Example Filters:

Field	Example
status	{ "column": "STATUS", "operator": "EQ", "value": "active" }
supplier_id	{ "column": "SUPPLIER_ID", "operator": "EQ", "value": 100002 }
variant_id	{ "column": "VARIANT_ID", "operator": "EXISTS", "value": 200050 }
season_id	{ "column": "SEASON_ID", "operator": "EXISTS", "value": 200001 }
delivery_status	{ "column": "DELIVERY_STATUS", "operator": "EQ", "value": "partially_delivered" }

---

Sorting

You can sort results using the orderBy parameter:

• id
• label
• notes
• status
• dated_at
• created_at
• shipping_at
• total_units
• update_incoming
• exchange_rate
• currency
• supplier_id
• supplier_label
• location_label
• committed_quantity
• uncommitted_quantity
• delivered_quantity
• reserved_quantity

---

Grouping Options

You can group purchase orders using the groupBy parameter for reports:

Field	Description
id	Group by internal ID.
year	Group by year of dated_at.
month	Group by month of dated_at.
day	Group by day of dated_at.

---

Data Types

ValidationRule

Field	Type	Description
id	Int!	Unique identifier.
label	String!	Rule name.
description	String	Detailed description.
document_type	String	Applies to this document type (e.g. Purchase).
amount_min	Int	Minimum amount threshold.
amount_max	Int	Maximum amount threshold.
send_alert	Boolean	Whether to send an alert on trigger.
users	[UserProfile]	Users assigned to this rule.
steps	[ValidationRuleStep]	Approval steps.

ValidationRuleWarning

Field	Type	Description
message	String!	Warning message describing the validation failure.
document_id	Int	ID of the related document, if applicable.
validation_rules	[[ValidationRule!]!]	List of validation rules that triggered this warning.

---

Enums

PurchaseStatus

Value	Description
unpublished	Draft status (hidden).
draft	Document created, awaiting internal processing.
validation	Awaiting supervisor validation.
rejected	Document rejected by supervisor.
active	Published and confirmed.
completed	All items fully received and processed.
archived	Moved to long-term storage.
cancelled	Document voided.

StockAllocationStatus

Value	Description
not_allocated	No stock impact yet.
partially_allocated	Some items confirmed in stock.
allocated	Full order quantity confirmed in stock.

DeliveryStatus

Value	Description
not_delivered	No items received yet.
partially_delivered	Partial reception processed.
delivered	All items physically received.

DiscountType

Value	Description
amount	Fixed discount amount.
percentage	Percentage-based discount.

TaxType

Value	Description
exclusive	Tax calculated on top of the net price.
inclusive	Tax included in the displayed price.

---

Data Types

DocumentValidationRuleStep

Represents a validation step attached to a document.

Field	Type	Description
id	Int	Validation step ID.
status	String	Current status of the validation step.
validation_rules_step	ValidationRuleStep	Step definition linked to this document step.

ValidationRuleStep

Field	Type	Description
id	Int	Unique identifier.
step	Int	Step number in the validation workflow.
validers	[ValidationRuleStepValider]	Users who can validate this step.
send_alert	Boolean	Whether to send alerts for this step.

ValidationRuleStepValider

Field	Type	Description
user_profile_id	Int	User profile ID.
user_profile	UserProfile	Associated user profile.