Return Item

Overview

Return Items are the line items on a return shipment, specifying which products are being returned, in what quantities, and for what reasons. While the return shipment represents the overall return transaction, return items provide the product-level detail needed for inventory updates, quality analysis, and financial reconciliation.

Each return item specifies a product and quantity being returned. For lot-tracked products, the item can specify which lot is being returned, supporting lot-level inventory accuracy and traceability. For serialized products, specific serial numbers can be recorded, ensuring you know exactly which units came back. This detail supports warranty tracking and defect analysis.

Return reasons can be captured at the item level rather than just the shipment level. This is important for mixed returns where different products are coming back for different reasons. One item might be defective, another damaged in shipping, another simply unwanted. Item-level reason tracking lets you analyze return patterns by product and reason, identifying systemic issues.

Disposition information indicates what should happen to each returned item. Some items go back to regular stock, others to damaged goods, others to a return-to-vendor area. Some might be marked for disposal. The disposition determines which inventory location receives the product and affects how it's valued. Items going to damaged goods might be written down in value.

The cost of returned items affects inventory valuation and financial reporting. When products come back, they're typically valued at their original sale cost or current average cost depending on accounting policies. Return items track this cost information, supporting accurate inventory and cost of goods sold adjustments. For customer returns of sold goods, this cost information helps calculate the impact of the return on gross margin.

Return items can reference the original sale shipment line items, creating a direct link between the outbound sale and the inbound return. This linkage supports RMA (return merchandise authorization) processing, warranty tracking, and defect analysis. You can see which original shipment a return came from, what was originally sold, and what specifically is coming back.

Quality control workflows often involve return item inspection. As items are received, inspectors check their condition and update the return item records with inspection results. This information drives the disposition decision and affects whether customers receive full credit or partial credit based on condition.

GraphQL API

The returnItem collection provides access to returnItem data via the GraphQL API. All queries use the Relay connection specification with cursor-based pagination.

Query Name: returnItemViewConnection

Available Features:

Cursor-based pagination (first/last/after/before)
1 relations to other collections

Query Examples

Basic Query

The returnItem collection is accessed via the returnItemViewConnection query, which returns a Relay-style connection with pagination support.

query {
  returnItemViewConnection(first: 10) {
    edges {
      node {
        itemIndex
        lotId
        lotIdUnprefixed
        packing
        price
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Pagination

Use cursor-based pagination to retrieve large datasets:

# First page
query {
  returnItemViewConnection(first: 50) {
    edges {
      node { lotId }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

# Subsequent pages
query {
  returnItemViewConnection(first: 50, after: "cursor-from-previous-page") {
    edges {
      node { lotId }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Relations

Query related data (see Relations section for all available relations):

query {
  returnItemViewConnection(first: 10) {
    edges {
      node {
        lotId
        product {
          title
          productUrl
        }
      }
    }
  }
}

Summary and Aggregation

This collection supports data aggregation and dimensional analysis through the summary field. You can calculate metrics (like totals, averages, counts) and group them by dimensions (like category, date, status).

For a comprehensive guide to using aggregations, see the Aggregation Concept Guide.

Query Structure

returnItemViewConnection(filters...) {
  summary {
    errorCode
    errorMessage
    groupBy {
      # Group by dimensions (see table below)
    }
    metrics {
      # Calculated metrics (see table below)
    }
  }
}

Available Metrics

This collection provides 26 metrics that can be aggregated:

Metric	Parameters	Description
`returnSubtotal`	`transform`, `operator`	returnSubtotal for returnItem
`returnTotalUnits`	`transform`, `operator`, `productUrlList`	returnTotalUnits for returnItem
`productNeqPerUnit`	`transform`, `operator`	productNeqPerUnit for returnItem
`productLastPurchaseLandedCostPerUnit`	`transform`, `operator`	productLastPurchaseLandedCostPerUnit for returnItem
`productLastPurchasePrice`	`transform`, `operator`	productLastPurchasePrice for returnItem
`productAverageGrossSalesPerUnit`	`transform`, `operator`, `dateRange`, `facilityUrlList`	productAverageGrossSalesPerUnit for returnItem
`productAverageUnitsPerSale`	`transform`, `operator`, `dateRange`, `facilityUrlList`	productAverageUnitsPerSale for returnItem
`productCogsSales`	`transform`, `operator`, `dateRange`, `facilityUrlList`	productCogsSales for returnItem
`productCountSales`	`transform`, `operator`, `dateRange`, `facilityUrlList`	productCountSales for returnItem
`productGrossSales`	`transform`, `operator`, `dateRange`, `facilityUrlList`	productGrossSales for returnItem
`productMarginSales`	`transform`, `operator`, `dateRange`, `facilityUrlList`	productMarginSales for returnItem
`productUnitSales`	`transform`, `operator`, `dateRange`, `facilityUrlList`	productUnitSales for returnItem
`productUnitSalesForSalesVelocity`	`transform`, `operator`, `dateRange`, `facilityUrlList`	productUnitSalesForSalesVelocity for returnItem
`productReorderQuantityToOrder`	`transform`, `operator`, `facilityUrlList`, `facilityUrl`, `reservedSublocationFacilityUrlList`	productReorderQuantityToOrder for returnItem
`productReorderQuantityToOrderEditable`	`transform`, `operator`, `facilityUrlList`, `facilityUrl`, `reservedSublocationFacilityUrlList`	productReorderQuantityToOrderEditable for returnItem
`productReplenishmentQuantityToOrder`	`transform`, `operator`, `facilityUrlList`, `facilityUrl`, `reservedSublocationFacilityUrlList`	productReplenishmentQuantityToOrder for returnItem
`productReplenishmentQuantityToOrderEditable`	`transform`, `operator`, `facilityUrlList`, `facilityUrl`, `reservedSublocationFacilityUrlList`	productReplenishmentQuantityToOrderEditable for returnItem
`productStock`	`transform`, `operator`, `aggregate`, `count`, `facilityUrlList`, `includeBom`, `includeSupplier`, `lotIdSearch`, `stockType`	productStock for returnItem
`productStockOnHand`	`transform`, `operator`, `aggregate`, `count`, `facilityUrlList`, `includeBom`, `includeSupplier`, `lotIdSearch`, `reservedSublocationFacilityUrlList`	productStockOnHand for returnItem
`productStockReserved`	`transform`, `operator`, `aggregate`, `count`, `facilityUrlList`, `includeBom`, `lotIdSearch`, `reservationType`	productStockReserved for returnItem
`productStockOnOrder`	`transform`, `operator`, `aggregate`, `count`, `facilityUrlList`, `includeBom`, `lotIdSearch`	productStockOnOrder for returnItem
`productStockAvailable`	`transform`, `operator`, `aggregate`, `count`, `facilityUrlList`, `includeBom`, `includeSupplier`, `lotIdSearch`, `reservedSublocationFacilityUrlList`	productStockAvailable for returnItem
`productStockRemaining`	`transform`, `operator`, `aggregate`, `count`, `facilityUrlList`, `includeBom`, `includeSupplier`, `lotIdSearch`	productStockRemaining for returnItem
`productAverageCost`	`transform`, `operator`	productAverageCost for returnItem
`productValuation`	`transform`, `operator`, `facilityUrlList`, `lotIdSearch`	productValuation for returnItem
`count`	None	Count of items in the result set

Common Parameters:

operator - Aggregation function: sum, mean, min, max
transform - Mathematical transformation: abs
dateRange - Filter to specific date range
facilityUrlList - Filter to specific facilities

GroupBy Dimensions

Group metrics by these dimensions:

Dimension	Description
`productCategory`	productCategory for returnItem
`productSupplier1`	productSupplier1 for returnItem
`productSupplier2`	productSupplier2 for returnItem
`productSupplier3`	productSupplier3 for returnItem

All dimensions accept a formatter parameter: "html", "none", "abbreviated", "blank-zero".

Examples

Example 1: Basic Aggregation

Calculate metrics for returnItem:

query {
  returnItemViewConnection(first: 1) {
    summary {
      errorCode
      errorMessage
      groupBy {
        # Add dimensions here
      }
      metrics {
        totalCount: count
      }
    }
  }
}

Fields

This collection has 19 fields:

17 simple fields
1 enum fields (with predefined values)
1 parameterized fields (accept query options)

Note on Field Formatting: All scalar fields support the formatter argument to control output format. Available options: "html", "none", "abbreviated", "blank-zero". Some fields have a default formatter (shown below). See the Formatting guide for details.

Note on Sorting: Field sortability may vary depending on the UI context and query parameters used. Some parameter options explicitly disable sorting (marked with ⚠️ not sortable).

Simple Fields

These fields return values directly without additional options.

`itemIndex`

Sequential position of the product line item within the return's item list. Used to identify and reference specific items when modifying or querying return details.

Label: Item index
Sortable: No

`lotId`

Lot or batch identifier assigned to the returned product, including any prefix. Tracks inventory by lot for quality control, expiration tracking, and traceability requirements.

Label: Lot ID
Sortable: No

`lotIdUnprefixed`

The lot identifier without any system-added prefix, displaying only the core lot number. Used for display and import purposes when the prefix should be omitted.

Label: Lot ID unprefixed
Sortable: No

`packing`

Normalized packing configuration for the returned item, indicating whether the product is returned as cases, units, or other packaging formats. Formatted as a structured packing string for consistency.

Label: Packing
Sortable: No

`price`

Unit price for the returned item, representing the per-unit monetary value. Used to calculate the return subtotal and process refunds or credits to customers.

Label: Price
Sortable: No

`quantity`

Number of units being returned for this line item. Combined with the packing format to determine the total quantity returned in the specified packaging configuration.

Label: Quantity
Sortable: No

`returnHasAttachment`

Indicates whether the parent return record has any file attachments such as images, documents, or receipts. Displays as 'Attachment' when files are present, useful for identifying returns with supporting documentation.

Label: Has attachment
Type: ##iconWithTooltip
Sortable: No

`returnNotes`

Internal notes from the parent return record, providing context or instructions visible only to staff. Available at the item level for convenience when analyzing individual return line items.

Label: Internal notes
Sortable: No
Default Formatter: html

Example Query:

{
  returnItem(returnItemUrl: "example-url") {
    returnNotes    # Uses default formatter: html
    returnNotesRaw: returnNotes(formatter: "none")  # Get raw value
  }
}

`returnPublicNotes`

Customer-visible notes associated with the return that can be displayed on invoices, packing slips, or customer portals. These notes provide information that is appropriate to share with customers, unlike internal private notes.

Label: Public notes
Sortable: No
Default Formatter: html

Example Query:

{
  returnItem(returnItemUrl: "example-url") {
    returnPublicNotes    # Uses default formatter: html
    returnPublicNotesRaw: returnPublicNotes(formatter: "none")  # Get raw value
  }
}

`returnReason`

The reason code explaining why the product is being returned, selected from a customizable list of return reasons such as "Wrong product", "Defective item", "Late delivery", or "Other". This field maps to returnReasonId internally and is used for tracking return patterns and quality control.

Label: Return reason
Sortable: No

`returnRecordCreated`

Label: Record created
Sortable: No

`returnRecordLastUpdated`

Label: Record last updated
Sortable: No

`returnReturnDate`

Label: Return date
Sortable: No

`returnReturnId`

Label: Return ID
Sortable: No
Default Formatter: html

Example Query:

{
  returnItem(returnItemUrl: "example-url") {
    returnReturnId    # Uses default formatter: html
    returnReturnIdRaw: returnReturnId(formatter: "none")  # Get raw value
  }
}

`returnReturnUrl`

Label: Return Url
Sortable: No

`returnStatusExtended`

A human-readable version of the return status that provides more descriptive labels than the raw status codes. For example, RETURN_CREATED is displayed as "Draft" and RETURN_COMPLETED is shown in a more user-friendly format.

Label: Status extended
Sortable: No

`returnSubtotal`

Label: Subtotal
Sortable: No

Enum Fields

These fields return one of a predefined set of values.

`returnStatus`

The current processing status of the return, indicating where the return is in its lifecycle. Common status values include RETURN_CREATED (draft), RETURN_COMPLETED (processed), and RETURN_CANCELLED (voided).

Label: Status
Sortable: No

Possible Values:

RETURN_CREATED - Draft
RETURN_COMPLETED - Closed
RETURN_CANCELLED - Canceled

Parameterized Fields

These fields accept parameters to customize the returned data. Parameters allow filtering by location, date ranges, aggregation methods, and more.

`returnTotalUnits`

Label: Total units
Sortable: No

Parameters:

productUrlList (List|ProductUrlString) Product(s)

Example Query:

{
  returnItem(returnItemUrl: "example-url") {
    returnTotalUnits(
      productUrlList: ["example-value"]
    )
  }
}

Relations

product

Related Collection: product
Label: Product

Example Query:

query {
  returnItemViewConnection(first: 10) {
    edges {
      node {
        product {
          title
          productUrl
        }
      }
    }
  }
}

Filters

No filters available.