Returns (RMA) — Overview

An RMA Order (Return Merchandise Authorization) represents a customer's return request. It drives the full return lifecycle: from creation, through acceptance, warehouse receiving, inspection, and financial resolution. RMA orders aggregate one or more return lines (product + quantity + reason), sender and delivery contacts, and resolution metadata.

RMA Order Flow

RMA Order State Machine

Processing Status

Status	Description
`NEW`	RMA order created but not yet submitted. Can be freely edited or cancelled.
`REQUESTED`	RMA order submitted for review. Awaiting acceptance or rejection.
`ACCEPTED`	RMA order accepted. Ready for fulfillment (customer can ship items back).
`PROCESSING`	Items are being received and inspected at the warehouse.
`REJECTED`	RMA order rejected. Terminal state.
`CANCELED`	RMA order cancelled. Terminal state.
`COMPLETE`	RMA order fully processed. All inspections and resolutions done. Terminal state.
`ON_HOLD`	RMA order temporarily paused. Can be resumed.
`ANOMALY`	An anomaly was detected during processing. Requires manual intervention.
`DELETED`	RMA order soft-deleted. Terminal state.

Delivery Status

Tracks the physical return shipment from the customer back to the warehouse.

Status	Description
`PENDING`	No shipment initiated yet.
`HANDLED`	Return shipment has been handed off to the carrier.
`PROCESSING`	Return shipment is being processed by the carrier.
`DELIVERING`	Return shipment is in transit.
`DELIVERED`	Return shipment delivered to the warehouse.
`DELIVERED_TO_SENDER`	Return shipment was returned to the sender (customer).
`CANCELED`	Return shipment cancelled.
`ERROR`	An error occurred during return shipping.

Financial Status

Tracks the financial resolution (refund, voucher, etc.) for the RMA order.

Status	Description
`PENDING`	Financial resolution is pending.
`REFUNDED`	Full refund has been processed.
`PARTIALLY_REFUNDED`	Partial refund has been processed.
`REFUND_REJECTED`	Refund request was rejected.
`CANCELED`	Financial resolution cancelled.
`NONE`	No financial resolution applicable.
`EXECUTION_ERROR`	An error occurred while executing the financial resolution.

Fulfillment Status

Tracks the warehouse fulfillment process for the return.

Status	Description
`PENDING`	Fulfillment not yet started.
`IN_PROGRESS`	Fulfillment is in progress (items being received/inspected).
`ERROR`	An error occurred during fulfillment.
`CANCELED`	Fulfillment cancelled.
`COMPLETE`	Fulfillment complete. All items received and inspected.

Expected Resolution

Defines what the customer expects as resolution for the return.

Value	Description
`NONE`	No resolution expected.
`VOUCHER`	Store credit / voucher.
`REPLACE`	Product replacement.
`REFUND`	Monetary refund.

Return Reasons

Value	Description
`WRONG_ITEM`	Wrong item was received.
`NOT_RECEIVED`	Item was not received.
`SIZE_PROBLEM`	Size does not fit.
`COLOR_PROBLEM`	Color does not match expectations.
`DEFECTIVE`	Item is defective (manufacturing fault).
`DAMAGED_PRODUCT`	Item was damaged during shipping or handling.
`UNSATISFIED`	Customer is generally unsatisfied with the product.
`ITEMS_NOT_SOLD`	Items were not sold (B2B returns).

Product States

Value	Description
`BRAND_NEW_WITH_LABEL`	Product is brand new with original labels attached.
`BRAND_NEW_WITHOUT_LABEL`	Product is brand new but labels have been removed.
`WORE`	Product has been worn or used.
`DAMAGED`	Product is damaged.
`DEFECTIVE`	Product has a manufacturing defect.

Line States

Value	Description
`FULFILLED`	Line has been fully processed.
`PARTIALLY_FULFILLED`	Line has been partially processed.
`PENDING`	Line has not yet been processed.

GraphQL Types

RmaOrderType

graphql

type RmaOrderType {
  id: ID!
  organization: Organization!
  configurationId: String!
  location: Location!
  lines: [RmaOrderLine!]!
  linkedOrders: [RmaOrderLinkedOrder]
  shipments: [RmaShipment]
  financialResolutions: [RmaFinancialResolutionRequest]
  externalId: String
  externalReference: String
  returnNumber: Int!
  returnReference: String!
  returnSlipUrl: String
  currency: String
  applyReturnFee: Boolean!
  deliveryContact: RmaContact!
  sender: RmaContact!
  owner: RmaContact
  billingContact: RmaContact
  receivedAt: DateTime!
  issuedAt: DateTime!
  expectedResolution: RmaOrderExpectedResolution!
  processingStatus: RmaOrderProcessingStatus!
  deliveryStatus: RmaOrderDeliveryStatus
  financialStatus: RmaOrderFinancialStatus
  fulfillmentStatus: RmaOrderFulfillmentStatus
  comment: String
  autoGenerateFinancialResolution: Boolean!
  autoExecuteFinancialResolution: Boolean!
  retainedAmountForShipping: Float!
}

Operations

Operation	Type	Description
rmaOrder	Query	Fetch a single RMA order by ID or external ID
rmaOrderCreate	Mutation	Create a new RMA order
rmaOrderSubmit	Mutation	Submit an RMA order for review
rmaOrderAccept	Mutation	Accept an RMA order
rmaOrderReject	Mutation	Reject an RMA order
rmaOrderCancel	Mutation	Cancel an RMA order
rmaOrderStartFulfillment	Mutation	Start fulfillment processing
rmaOrderCompleteProcessing	Mutation	Mark processing as complete
rmaOrderRequestFulfillment	Mutation	Request fulfillment for the return
rmaConfigurationCreate	Mutation	Create an RMA configuration
rmaConfigurationUpdate	Mutation	Update an RMA configuration

Best Practices

TIP

Always set expectedResolution to match your business intent. This drives downstream automation for financial resolution and replacement order creation.

WARNING

Once an RMA order reaches PROCESSING status, it cannot be cancelled. Ensure the return is valid before accepting it.

Use autoGenerateFinancialResolution to automatically create refund or voucher requests when the return is completed. This reduces manual work for high-volume merchants.
Use autoExecuteFinancialResolution with caution — it will automatically execute the refund without manual review. Only enable this for trusted return flows.
Set retainedAmountForShipping to deduct return shipping costs from the refund amount when applicable.
Link original orders via linkedOrders to maintain traceability between the original sale and the return.
Use the return portal (rmaConfiguration.portalIsActive) to let customers self-serve their returns. Configure authorizationDelay to enforce your return policy window.
Track all four status dimensions — processing, delivery, financial, and fulfillment — to get a complete picture of each return's lifecycle.

Returns (RMA) — Overview ​

RMA Order Flow ​

RMA Order State Machine ​

Processing Status ​

Delivery Status ​

Financial Status ​

Fulfillment Status ​

Expected Resolution ​

Return Reasons ​

Product States ​

Line States ​

GraphQL Types ​

RmaOrderType ​

Operations ​

Best Practices ​