Return

Overview

Returns handle the reverse logistics of products coming back from customers or going back to suppliers. They represent the physical return of goods, updating inventory and creating the foundation for financial credits or refunds. Returns are essentially reverse shipments with special handling for the unique aspects of reverse logistics.

Customer returns are the most common type. A customer sends back defective, damaged, or unwanted products. When you receive the return, you create a return shipment that adds the products back to inventory. This updates stock levels and creates stock history entries documenting the return. The return can reference the original sale, linking it to the initial transaction for tracking and analysis.

Return reasons are critical for operational improvement. Each return captures why the product came back - defective, damaged in shipping, wrong item sent, customer changed mind, or other reasons. Analyzing return patterns helps identify quality issues, fulfillment errors, or product problems that need addressing. This data drives process improvement and product development.

Returns support different dispositioning based on the reason. Products in good condition might go back to regular stock for resale. Damaged items might go to a damaged goods location for refurbishment or disposal. Defective products might be segregated for return to the manufacturer. The return specifies the receiving location and sublocation, supporting these different flows.

The relationship between returns and credits is important but separate. A physical return (return shipment) updates inventory. A financial credit (credit memo) reduces what the customer owes. Sometimes these happen together - customer returns product and receives a credit. Sometimes they're separate - customer receives a credit without returning the product (for damage they'll dispose of themselves), or returns product without receiving a credit (warranty exchange). This separation gives you flexibility to handle different business scenarios.

Return inspection and processing workflows vary by business. Some companies inspect returns immediately upon arrival, updating inventory only for items that pass inspection. Others receive all returns into inventory and then disposition them through separate processes. The system supports both approaches through flexible status tracking and inventory transactions.

Supplier returns flip the scenario - you're sending products back to a supplier due to defects, overages, or other issues. These returns ship out like customer returns ship in, reducing your inventory and creating history entries. They typically lead to supplier credits that reduce your accounts payable obligations.

GraphQL API

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

Query Name: returnViewConnection

Available Features:

Cursor-based pagination (first/last/after/before)
10 filter options
7 sortable fields
3 relations to other collections

Query Examples

Basic Query

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

query {
  returnViewConnection(first: 10) {
    edges {
      node {
        notes
        publicNotes
        recordCreated
        recordLastUpdated
        returnDate
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Pagination

Use cursor-based pagination to retrieve large datasets:

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

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

Filtering

Apply filters to narrow results (see Filters section for all available options):

query {
  returnViewConnection(
    first: 10
    customer: "ACME Corporation"
  ) {
    edges {
      node { returnId }
    }
  }
}

Sorting

Sort results by one or more fields:

query {
  returnViewConnection(
    first: 10
    sort: [{ field: "recordCreated", mode: "desc" }]
  ) {
    edges {
      node {
        returnId
        recordCreated
      }
    }
  }
}

Relations

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

query {
  returnViewConnection(first: 10) {
    edges {
      node {
        returnId
        customer {
          name
          partyUrl
        }
      }
    }
  }
}

Summary and Aggregation

This collection supports metrics aggregation through the summary field. You can calculate totals, averages, counts, and other aggregate values across filtered data.

Note: This collection does not support groupBy dimensions. For dimensional analysis, use collections like product, order, or invoice.

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

Query Structure

returnViewConnection(filters...) {
  summary {
    errorCode
    errorMessage
    metrics {
      # Calculated metrics (see table below)
    }
  }
}

Available Metrics

This collection provides 3 metrics that can be aggregated:

Metric	Parameters	Description
`subtotal`	`transform`, `operator`	Subtotal amount (before taxes and fees)
`totalUnits`	`transform`, `operator`, `productUrlList`	Total number of units
`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

Examples

Example 1: Total return Metrics

Calculate aggregate metrics across all return records:

query {
  returnViewConnection(first: 1) {
    summary {
      errorCode
      errorMessage
      metrics {
        totalCount: count
      }
    }
  }
}

Expected result structure:

{
  "data": {
    "returnViewConnection": {
      "summary": {
        "errorCode": null,
        "errorMessage": null,
        "metrics": {
          "totalCount": [1523]
        }
      }
    }
  }
}

Fields

This collection has 12 fields:

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

`hasAttachment`

Indicates whether the return has any attachments by filtering content items for attachment type. Returns a special marker value '##hasAttachment' when attachments are present, which the formatter displays as 'Attachment', otherwise returns null.

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

`notes`

Internal notes (private) for a return, stored in the notes field. The field is displayed with HTML-escaped newlines and is editable through the returnNotes dimension key.

Label: Internal notes
Sortable: No
Default Formatter: html

Example Query:

{
  return(returnUrl: "example-url") {
    notes    # Uses default formatter: html
    notesRaw: notes(formatter: "none")  # Get raw value
  }
}

`publicNotes`

A text field containing public-facing notes for the return. The field is formatted as a string with HTML formatting applied to escape newlines for proper display.

Label: Public notes
Sortable: No
Default Formatter: html

Example Query:

{
  return(returnUrl: "example-url") {
    publicNotes    # Uses default formatter: html
    publicNotesRaw: publicNotes(formatter: "none")  # Get raw value
  }
}

`recordCreated`

Timestamp field representing when the return record was originally created in the system. Uses the createdDate attribute from the return object and formats it as a date-time value.

Label: Record created
Sortable: Yes

`recordLastUpdated`

Timestamp field representing when the return record was last modified in the system. Uses the lastUpdatedDate attribute from the return object and formats it as a date-time value.

Label: Record last updated
Sortable: Yes

`returnDate`

Date dimension field representing when a return transaction occurred. This field is configured with a memory store for date handling and is not suppressed in return sale sort lists.

Label: Return date
Sortable: Yes

`returnId`

Unique identifier for a return record, displayed as 'Return ID' in the UI. Used for lookups to retrieve the return URL and rendered as an internal link to the return detail page.

Label: Return ID
Sortable: Yes
Default Formatter: html

Example Query:

{
  return(returnUrl: "example-url") {
    returnId    # Uses default formatter: html
    returnIdRaw: returnId(formatter: "none")  # Get raw value
  }
}

`returnUrl`

Unique identifier serving as the primary key for return records. This field is automatically generated by the server and used throughout the system for lookups, relationships with other collections (orders, shipments, payments), grouping operations, and generating internal links to return detail pages.

IMPORTANT: Treat URL values as opaque strings supplied by the server. Do not attempt to parse, interpret, or construct URL values manually:

ID values embedded in URLs may differ from entity ID values
The URL structure is an internal implementation detail subject to change
Manually constructing URLs can lead to bugs and system errors
Always use URL values exactly as provided by the API

Label: Return Url
Sortable: No

`statusExtended`

Extended status information for the return that provides additional detail beyond the basic status field. This field is not sortable and displays supplementary status context to users.

Label: Status extended
Sortable: No

`subtotal`

The sum of all line item amounts before taxes, fees, and discounts are applied. This represents the total value of returned products based on their individual unit prices and quantities.

Label: Subtotal
Sortable: Yes

Enum Fields

These fields return one of a predefined set of values.

`status`

Indicates the processing stage of a return transaction. Returns can have one of three statuses: Created (RETURN_CREATED, the default), Completed (RETURN_COMPLETED), or Cancelled (RETURN_CANCELLED). The status field is used for filtering return lists, determining transaction finality, and tracking return workflow progression.

Label: Status
Sortable: Yes

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.

`totalUnits`

The total count of individual product units across all items in the order or return. This counts each unit separately regardless of how products are packaged (cases versus individual units).

Label: Total units
Sortable: Yes

Parameters:

productUrlList (List|ProductUrlString) Product(s)

Example Query:

{
  return(returnUrl: "example-url") {
    totalUnits(
      productUrlList: ["example-value"]
    )
  }
}

Relations

customer

Related Collection: party
Label: Customer

Example Query:

query {
  returnViewConnection(first: 10) {
    edges {
      node {
        customer {
          name
          partyUrl
        }
      }
    }
  }
}

order

Related Collection: order
Label: Order

Example Query:

query {
  returnViewConnection(first: 10) {
    edges {
      node {
        order {
          orderId
          orderUrl
        }
      }
    }
  }
}

shipmentList

Related Collection: shipment
Label: Shipments

Example Query:

query {
  returnViewConnection(first: 10) {
    edges {
      node {
        shipmentList {
          shipmentId
          shipmentUrl
        }
      }
    }
  }
}

Filters

customer

Label: Customer
Type: List|PartyUrlCustomerString
Enabled: Yes

Filter Type: Reference to party collection

Note: Filters to customers only

This filter accepts values from the partyViewConnection query. To get available values:

query {
  partyViewConnection(
    first: 100
    role: ["CUSTOMER"]
    status: "PARTY_ENABLED"
  ) {
    edges {
      node {
        partyUrl    # Use this value in the filter
        name
      }
    }
  }
}

Usage Example:

query {
  returnViewConnection(
    first: 10
    customer: ["PARTY_URL_VALUE"]
  ) {
    edges {
      node {
        returnId
        party {
          name
        }
      }
    }
  }
}

location

Label: Location
Type: FacilityUrlLocationString
Enabled: Yes

Filter Type: Reference to facility collection

Note: Filters to locations only

This filter accepts values from the facilityViewConnection query. To get available values:

query {
  facilityViewConnection(
    first: 100
    type: "FACILITY_LOCATION"
    status: "FACILITY_ACTIVE"
  ) {
    edges {
      node {
        facilityUrl    # Use this value in the filter
        name
      }
    }
  }
}

Usage Example:

query {
  returnViewConnection(
    first: 10
    location: "FACILITY_URL_VALUE"
  ) {
    edges {
      node {
        returnId
        facility {
          name
        }
      }
    }
  }
}

orderOrderUrl

Label: Order
Type: OrderUrlSaleString
Enabled: Yes

Filter Type: Reference to order collection

Note: Filters to sales orders only

This filter accepts values from the orderViewConnection query. To get available values:

query {
  orderViewConnection(
    first: 100
    type: "SALES_ORDER"
  ) {
    edges {
      node {
        orderUrl    # Use this value in the filter
        orderId
      }
    }
  }
}

Usage Example:

query {
  returnViewConnection(
    first: 10
    orderOrderUrl: "ORDER_URL_VALUE"
  ) {
    edges {
      node {
        returnId
        order {
          orderId
        }
      }
    }
  }
}

product

Label: Product
Type: List|ProductUrlString
Enabled: Yes

Filter Type: Reference to product collection

This filter accepts values from the productViewConnection query. To get available values:

query {
  productViewConnection(
    first: 100
  ) {
    edges {
      node {
        productUrl    # Use this value in the filter
        title
      }
    }
  }
}

Usage Example:

query {
  returnViewConnection(
    first: 10
    product: ["PRODUCT_URL_VALUE"]
  ) {
    edges {
      node {
        returnId
        product {
          title
        }
      }
    }
  }
}

returnDate

Label: Return date
Type: dateRangeWithFutureInput
Enabled: Yes

Filter Type: Date range

Input Structure:

{
  begin: string  // ISO date format: "2024-01-01"
  end: string    // ISO date format: "2024-12-31"
}

Usage Example:

query {
  returnViewConnection(
    first: 10
    returnDate: {
      begin: "2024-01-01"
      end: "2024-12-31"
    }
  ) {
    edges {
      node {
        returnId
        returnDate
      }
    }
  }
}

returnId

Label: Return ID
Type: List|String
Enabled: No

Filter Type: Text value

This filter accepts freeform text values.

Usage Example:

query {
  returnViewConnection(
    first: 10
    returnId: "12"
  ) {
    edges {
      node {
        returnId
        returnId
      }
    }
  }
}

returnUrl

Label: Return
Type: List|ReturnUrlString
Enabled: Yes

Filter Type: Reference to return collection

This filter accepts values from the returnViewConnection query. To get available values:

query {
  returnViewConnection(
    first: 100
  ) {
    edges {
      node {
        returnUrl    # Use this value in the filter
        returnId
      }
    }
  }
}

Usage Example:

query {
  returnViewConnection(
    first: 10
    returnUrl: ["RETURN_URL_VALUE"]
  ) {
    edges {
      node {
        returnId
        return {
          returnId
        }
      }
    }
  }
}

search

Label: Not specified
Type: SearchString
Enabled: Yes

Filter Type: Search text

This filter performs a text search across multiple fields.

Usage Example:

query {
  returnViewConnection(
    first: 10
    search: "search term"
  ) {
    edges {
      node {
        returnId
      }
    }
  }
}

searchCustom

Label: Not specified
Type: searchCustomFilter
Enabled: Yes

Filter Type: Advanced search with result expansion

See the Advanced Search guide for complete documentation on how this filter works.

Collection-Specific Examples:

Example 1: Basic search:

query {
  returnViewConnection(
    first: 10
    searchCustom: {
      terms: "red widget"
    }
  ) {
    edges {
      node {
        returnId
      }
    }
  }
}

Example 2: Include additional fields in search:

# Searches defaults PLUS custom fields
query {
  returnViewConnection(
    first: 10
    searchCustom: {
      terms: "acme"
      include: ["customField1", "customField2"]
    }
  ) {
    edges {
      node {
        returnId
      }
    }
  }
}

Example 3: Expand results to include related records:

# For each match, also return the related record
query {
  returnViewConnection(
    first: 10
    searchCustom: {
      terms: "urgent"
      extend: ["relatedRecordUrl"]
    }
  ) {
    edges {
      node {
        returnId
      }
    }
  }
}

Example 4: Combine include and extend:

# Search in defaults + additional fields, then expand to related records
query {
  returnViewConnection(
    first: 10
    searchCustom: {
      terms: "acme corp"
      include: ["customField1"]
      extend: ["relatedRecordUrl"]
    }
  ) {
    edges {
      node {
        returnId
      }
    }
  }
}

status

Label: Status
Type: List|String
Enabled: Yes
Options:
- Canceled (RETURN_CANCELLED)
- Closed (RETURN_COMPLETED)
- Draft (RETURN_CREATED)

Filter Type: Predefined options

Get Current Options:

These options may vary by account configuration. To get the current list:

query {
  dataSetMeta(purpose: "uiReturnSale") {
    dataSets(name: "return") {
      filters {
        name
        optionList {
          value
          label
        }
      }
    }
  }
}

Usage Example:

query {
  returnViewConnection(
    first: 10
    status: ["RETURN_CREATED", "RETURN_COMPLETED"]
  ) {
    edges {
      node {
        returnId
        status
      }
    }
  }
}