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:

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:

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

TODO: Add relation description

Filters

No filters available.