Product Returns Queries

Access product returns from customers, including return reasons and received status.

`ProductReturn` — Returns a single product return by `id`

query GetProductReturn($id: ID!) {
  ProductReturn(id: $id) {
    id
    label
    status
    dated_at
    add_in_stock
    total_units
    customer { id label }
    location_label
    line_items {
      id
      variant { id label }
      quantity
    }
  }
}

`ProductReturns` — Returns a paginated list of product returns with sorting and filters

query ProductReturns(
  $where: QueryProductReturnsWhereWhereConditions,
  $orderBy: [QueryProductReturnsOrderByOrderByClause!],
  $search: String,
  $first: Int,
  $page: Int
) {
  ProductReturns(
    where: $where,
    orderBy: $orderBy,
    search: $search,
    first: $first,
    page: $page
  ) {
    paginatorInfo {
      total
      currentPage
    }
    data {
      id
      label
      status
      dated_at
      customer { id label }
    }
  }
}

Available fields

Field	Type	Description
`id`	Int	Unique identifier.
`label`	String	Return document number.
`status`	ProductReturnStatus	Current workflow status.
`add_in_stock`	Boolean	True if returned items increase stock levels.
`total_units`	Float	Total quantity of items returned.
`total_units_aggregate`	Float	Sum of units for filtered returns.
`dated_at`	Date	Document date.
`created_at`	Date	Creation date.
`customer`	Customer	Linked customer.
`location_label`	String	Target location name.
`notes`	String	Public notes for documents.
`internal_notes`	String	Private internal notes.
`credit_status`	CreditStatus	Progress of associated credit notes.
`credited_quantity`	Float	Quantity already processed for credit.
`uncredited_quantity`	Float	Quantity awaiting credit processing.
`credited_amount`	Float	Value already processed for credit.
`uncredited_amount`	Float	Value awaiting credit processing.
`season`	Season	Associated business season.
`account_representative`	AccountRepresentative	Linked sales rep.
`line_items`	[LineItemProductReturn]	List of returned items.
`orders_count`	Int	Number of linked sales orders.
`orders`	[Order]	Linked sales orders history.
`invoices_count`	Int	Number of linked invoices.
`invoices`	[Invoice]	Linked invoices details.
`credit_notes_count`	Int	Number of linked credit notes.
`credit_notes`	[CreditNote]	Associated credit notes.
`refunds_count`	Int	Number of linked refunds.
`refunds`	[Refund]	Associated direct refunds.
`integrations`	[Integration]	External platform links.
`email_histories`	[EmailHistory]	History of sent emails.
`files`	[File]	Attached documents.
`pdf_template`	PdfTemplate	Design used for PDF generation.
`has_batch_numbers`	Boolean	True if items have batch tracking.
`tracking_completed`	Boolean	True if all tracking info is entered.
`custom_fields`	[EntityCustomField]	Custom fields for this entity.

Filters

The following fields can be used in the where parameter:

id, label, status, add_in_stock, total_units, dated_at, created_at, updated_at, customer_id, orders_count, variant_id, variant_label, variant_sku, location_id, batch_number_id, has_batch_numbers, tracking_completed.

Example Filters:

Field	Example
`status`	`{ "column": "STATUS", "operator": "EQ", "value": "pending" }`
`customer_id`	`{ "column": "CUSTOMER_ID", "operator": "EQ", "value": 100050 }`
`variant_id`	`{ "column": "VARIANT_ID", "operator": "EXISTS", "value": 200080 }`

Sorting

You can sort results using the orderBy parameter:

id
label
add_in_stock
total_units
status
dated_at
created_at
customer_id
customer_label

Grouping Options

You can group product returns 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`.

Enums

`ProductReturnStatus`

Value	Description
`unpublished`	Draft status (hidden).
`pending`	Document created, awaiting processing.
`completed`	Return fully processed.
`cancelled`	Document voided.

`CreditStatus`

Value	Description
`not_credited`	No credit processed yet.
`partially_credited`	Partial credit generated.
`credited`	Full value processed for credit.

ProductReturn — Returns a single product return by id

ProductReturns — Returns a paginated list of product returns with sorting and filters