RMAs (3.0.0)

Download OpenAPI specification:Download

When an RMA event occurs in the returns portal, Optoro will notify your webhook about the RMA and its details. These events can be at the time your customer has created an RMA or when the RMA has been shipped.

Optoro's system will make an HTTP POST request to the configured URL. The url endpoint will need to return an HTTP 200 to 299 status for a webhook to be successful.

See the Webhook Message Behaviors for more details about aspects to consider regarding message delivery.

When it is used:

Optoro posts an RMAs message to you when the shopper initiates a return.
Optoro posts an RMAs message to you when carrier tracking details are provided (when applicable).
Optoro posts an RMAs message to you when the carrier receives and scans the return.
Optoro posts an RMAs message when the shopper drops off the return at a drop-off location or when a pick-up partner picks up the return from the shopper.
Optoro posts an RMAs message when the item is received (and ready for refund) when you also use Optoro’s Returns Management solution.
Optoro posts an RMAs message to you after you update the order with refund details in the Refunds object of the Returns Portal Order API.

RMA Event

Request

header Parameters

X-Optiturn-Id required	string Example: Modrno
X-Optiturn-Api-Version required	string Value: 3

Request Body schema: application/json

The RMA webhook provides details of the return as it progresses through the various lifecycle events.

On the right you will find example payloads listed that correspond to a specific type of the return. These are not inclusive of events that could happen on the RMA such as a warehouse receipt or tracking event.

rma_identifier

required

string

Identifier of the RMA.

status

required

string

The status of the RMA.

Enum: "PENDING_EXCHANGE" "CREATED" "REFUNDED" "PARTIAL_REFUND" "CANCELED"

created_at

required

string

Creation date in ISO 8601 format, UTC.

updated_at

string

Last updated date in ISO 8601 format, UTC.

required

Array of objects (rma_item)

List of items that are being returned in the RMA.

Array

order_line_item_identifier

required

string

The item's identifier in the order.

order_identifier

required

string

Public facing identifier for the order.

secondary_identifier

string

OMS or backend system identifier for the original order. Used when ecommerce and fulfillment platforms have unique identifiers.

exchange_order_identifier

string

The identifier of the exchange order. Used when the item being returned was chosen to be exchanged.

original_order_identifier

string

Only populated when returning an exchange item. Refers back to the order that was exchanged.

return_reason

required

string

The shopper chosen reason for returning the item.

is_exchange

boolean

Indicates whether the RMA item belongs to an exchange order

sku

required

string

Unique product identifier of item.

upc

required

string

Unique product code of item.

tracking_number

string

Tracking number of the package the item is located in.

package_tracking_status

string

The status of the package that the RMA item is in. For Express Returns, ACCEPTED is when item has been accepted at a dropoff location. For Home Pickups, ACCEPTED is when the item has been picked up by a pickup provider. Upon carrier scan a package status can be moved to TRANSIT

Enum: null "PRE_TRANSIT" "ACCEPTED" "TRANSIT" "DELIVERED" "RETURNED" "FAILURE"

receiving_status

string

The item's receiving status. Only populated when using Optoro's Returns Management.

Enum: "PENDING" "RECEIVED" "NOT_RECEIVED"

required

object

RMA item financial information used for calculating the refund amount.

estimated_refund_amount_cents required	integer Total possible refund amount based on goods returned.
optoro_refund_amount_cents required	integer Amount Optoro will be paid based on instant exchange usage.
shopper_refund_amount_cents required	integer Estimated amount the shopper will be refunded based on instant exchange usage.

refund_type

required

string

The refund type for the item.

Enum: "REFUND" "EVEN_EXCHANGE" "UNEVEN_GC" "STANDARD_EXCHANGE"

return_method

required

string

Return method used to return the RMA.

Enum: "mail-back" "express-returns" "customer-keep" "home-pickup"

return_shipping_cost_cents

integer

The return shipping cost.

gift_refund_only

required

boolean

If true, only issue a gift card and do not refund original purchase payment.

giftee_email

string

Email to send gift card when gift_refund_only is true

warehouse_id

string

Warehouse that return goods will be shipped to when using dynamic package routing

receiving_complete

boolean

This is for RM only.

Responses

200

Success

post/rmas

Request samples

Payload

application/json

A shopper created an RMA and selected all items to be refunded to the shopper's original form of payment.

{"rma_identifier": "rma1234",
"status": "CREATED",
"created_at": "2018-08-30T15:39:42.025Z",
"updated_at": "2018-08-30T15:39:42.025Z",
"items": {"order_line_item_identifier": "1",
"order_identifier": "o12345",
"return_reason": "Too Small",
"sku": "Sku1234",
"upc": "UPC1234",
"tracking_number": "1Z403818413131",
"package_tracking_status": "PRE_TRANSIT",
"receiving_status": "PENDING",
"refund_financials": {"estimated_refund_amount_cents": 1000,
"optoro_refund_amount_cents": 0,
"shopper_refund_amount_cents": 1000
},
"refund_type": "REFUND"
},
"return_method": "mail-back",
"return_shipping_cost_cents": 100,
"receiving_complete": false,
"gift_refund_only": false,
"concept": "concept"
}