RMAs (4.0.0)

Download OpenAPI specification:Download

Introduction

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 API endpoint at the configured URL. The API endpoint will need to return an HTTP 200-299 status for a webhook to be considered 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.

Changelog

Version 4

  • FEATURE: There is a new top-level field bonus_credit_amount_cents (applicable for instant store credit refunds).
  • BREAKING: The UNEVEN_GC item refund type value is renamed to INSTANT_STORE_CREDIT.
  • BREAKING: The EVEN_EXCHANGE item refund type value is renamed to INSTANT_EXCHANGE.

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" "STANDARD_EXCHANGE" "INSTANT_EXCHANGE" "INSTANT_STORE_CREDIT"
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.

bonus_credit_amount_cents
required
integer

The bonus credit granted to the shopper.

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.

concept
string

RMA portal identifier

vendor
string

Vendor name from third party tag. Only present if any of the products of the corresponding order has this type of tag.

Responses
200

Success

post/rmas
Request samples
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": {
    },
  • "return_method": "mail-back",
  • "return_shipping_cost_cents": 100,
  • "bonus_credit_amount_cents": 0,
  • "receiving_complete": false,
  • "gift_refund_only": false,
  • "giftee_email": "testemail@domain.com",
  • "warehouse_id": 1,
  • "vendor": "modrno",
  • "concept": "concept"
}
© 2010 – 2024 Optoro, Inc. For official use only by authorized users. Use subject to terms of license agreement.