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:

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:

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:

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.

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

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:

Simple Fields

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

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

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

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.

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

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

Label: Status

Sortable: Yes

Possible Values:

Parameterized Fields

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

Relations

customer

order

shipmentList

Filters

customer

location

orderOrderUrl

product

returnDate

returnId

returnUrl

search

searchCustom

Status Filter