# 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.

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

### Pagination
Use cursor-based pagination to retrieve large datasets:

```graphql
# 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:

```graphql
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).

### Query Structure
```graphql
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:

```graphql
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)

### 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`

#### `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`

#### `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`

#### `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`)

**Example Query:**
```graphql
{
  returnItem(returnItemUrl: "example-url") {
    returnTotalUnits(
      productUrlList: ["example-value"]
    )
  }
}
```

## Relations
### product
- **Related Collection:** [product](https://developer.finaleinventory.com/reference/graphql-product)
- **Label:** Product
**Example Query:**
```graphql
query {
  returnItemViewConnection(first: 10) {
    edges {
      node {
        product {
          title
          productUrl
        }
      }
    }
  }
}
```