Returns portal allows shoppers to create a return based on their order history. An online experience guides them through creating the return and provides the data needed to receive goods in a warehouse and process eligible refunds.
When it is used:
You post a Returns Portal Orders message to Optoro with the full snapshot of the order at the first shipped event of the order. At initial implementation, orders for the previous six months (usually) are posted and then orders are posted as they ship.
You post a Returns Portal Orders message to Optoro with the full snapshot of the order when order lifecycle events occur. This includes: fulfillments, transactions, adjustments, and order line item modifications. Updates should be as close to real time as possible.
You post a Returns Portal Orders message to Optoro when the order and/or items within the order are refunded. However, when the order is an exchange one, you should not neccesarily receive refunds.
Create Returns Portal Orders
Request
header Parameters
Api-Version
required
string
Value:3
Request Body schema: application/json
A Returns Portal Order object
required
object
An orders object.
required
Array of objects (order)
Array of orders.
Array
identifier
required
string
Public facing identifier for this order. Must be a unique value per order.
concept
string
A unique identifier for the retail ‘concept’ or ‘brand’ to which the product belongs. This differentiates similar products when the your company has multiple retail concepts. Must work with Professional Services when using this field to uniquely identify catalog entries.
raw_status
string
Order status in raw form
status
required
string
Status of the order as it relates to the RMA portal
Enum:"Created""Shipped""Canceled"
total_amount_cents
required
integer <int> >= 0
Total order amount including taxes and discounts and shipping.
product_amount_cents
required
integer <int> >= 0
Total order amount of merchandise purchased.
tax_amount_cents
required
integer <int> >= 0
Total order amount of sales tax on merchandise.
discount_amount_cents
required
integer <int> >= 0
Total order amount of discounts.
shipping_amount_cents
required
integer <int> >= 0
Total order amount of shipping costs.
shipping_tax_amount_cents
required
integer <int> >= 0
Total order amount of sales tax on shipping.
currency
required
string
Currency code. Must be ISO-4217 reference. E.g. "USD"
tags
required
Array of strings
An array of tags associated with the given order. Current supported tags are: FinalSale, gift-card, canceled, Thirdparty, ShippingRateOverride, pickup_in_store
note
string
Arbitrary context notes (discount notes, etc.)
created_at
required
string
Creation date in ISO 8601 format, UTC
updated_at
required
string
Last updated date in ISO 8601 format, UTC
required
Array of objects (item)
An array of order line items.
Array
identifier
required
string
ID for individual item within the Order. Must be a unique value per item.
concept
string
A unique identifier for the retail "concept" or "brand" to which the product belongs. This differentiates similar products when the your company has multiple retail concepts. Must work with Professional Services when using this field to uniquely identify catalog entries.
upc
string
UPC that represents the product for this order item. Required unless SKU is present.
sku
string
An identifier which matches the catalog and represents the product for this order item. Required unless UPC is present.
quantity
required
integer
Number of units of a particular line item that has been ordered. Must be less than or equal to 1000. Must be greater than or equal to the sum of quantity_shipped and quantity_canceled.
quantity_shipped
required
integer
Number of units of a particular line item that have shipped. Must be less than or equal to quantity.
quantity_canceled
required
integer
Number of units of a particular line item that have been canceled. Must be less than or equal to quantity.
quantity_refunded
integer
Number of units of a particular line item that have already been refunded. Must be less than or equal to quantity_shipped.
tracking_number
string
The tracking number for the package containing this order item. This allows operations to scan the tracking number for undeliverable items.
reverse_tracking_number
string
The return tracking number for the package containing this order item. This allows operations to scan the tracking number for items returned by the customer.
dropship_identifier
string
ID used to track item that was drop shipped.
shipped_date
string
Date when the order was shipped, in ISO 8601 format, UTC.
return_policy_end_date
string
Date when the order item is no longer eligible for return, in ISO 8601 format, UTC.
product_identifier
required
string
Id unique to that product (ex. same SKU from different vendors). Send SKU if no product_identifier exists.
variant_identifier
required
string
Variant can help disambiguate specific variant of a product class (e.g. blue color of a sweater product) -- product_identifier can be the same as variant_identifier in some systems. Send SKU if no variant_identifier exists.
Array of objects (product_variant)
Array of product variants for the parent item. Including variants improves exchange functionality in the return portal.
Array
required
Array of objects
A list of attributes that describe the variant. Such as colors or sizes. See variant attributes.
Array
name
required
string
Name of attribute describing the variant.
value
required
string
Value of the attribute name.
allow_backorder
required
boolean
Specifies if the variant is allowed to be backordered if out of stock.
product_identifier
required
string
Id unique to that product (ex. same SKU from different vendors). Send SKU if no product_identifier exists.
variant_identifier
required
string
Id unique to that variant. product_identifier can be the same as variant_identifier in some systems. Send SKU if no variant_identifier exists.
product_amount_cents
required
integer <int> >= 0
Unit price amount in cents for a single unit of a product.
currency
string
Currency code. Must be ISO-4217 reference. E.g. "USD".
quantity_in_stock
required
integer
The quantity in stock for the specific variant.
inventory_managed_by_platform
required
boolean
True if Inventory is managed by Returns Portal provider.
sku
string
The SKU for the variant.
title
required
string
The title for the variant
unit_price_amount_cents
integer <int> >= 0
Unit price amount in cents of a single unit of a product.
image_urls
Array of strings
An array of image strings associated with the given parent.
image_hash
string
Hash value of the product image.
weight
number
Product weight, in lbs.
height
number
Product height, in inches.
width
number
Product width, in inches.
length
number
Product length, in inches.
product_url
string
Product page link.
harmonized_system_code
string
Product harmonized system code
country_code_of_origin
string
Used in conjunction with harmonized system code for International Returns
title
required
string
Title of product
product_amount_cents
required
integer <int> >= 0
Raw product amount without taxes or discounts. Sum of all the units for that line item (quantity x unit_price_amount for a given product).
tax_amount_cents
required
integer <int> >= 0
Line item tax amount in cents.
discount_amount_cents
required
integer <int> >= 0
Line item discount amount in cents.
unit_price_amount_cents
required
integer <int> >= 0
Unit price amount in cents of a single unit of a product.
tags
required
Array of strings
An array of tags associated with the given order. Current supported tags are: FinalSale, gift-card, canceled, Thirdparty, pickup_in_store
image_url
string
Product image file link.
weight
number
Product weight, in lbs.
required
object (customer)
Customer
identifier
required
string
Reference to customer record in your OMS
first_name
string
Customer first name
last_name
string
Customer last name
email
required
string
Customer contact email
phone
string
Customer phone
required
object (address)
Reduce customer friction by auto populating package sender details in the return label for the shopper.
name
required
string
Name of person.
street1
required
string
The street address.
street2
string
An optional second line for the street address, for suite or other similar additions.
city
required
string
The city for this address.
state
required
string
The state or province for this address.
zip_code
required
string
The zip or postal code for this address.
country_code
required
string
The country code for this address.
phone
string
Phone number.
required
object (address)
Customer billing address will help support exchange orders.
name
required
string
Name of person.
street1
required
string
The street address.
street2
string
An optional second line for the street address, for suite or other similar additions.
city
required
string
The city for this address.
state
required
string
The state or province for this address.
zip_code
required
string
The zip or postal code for this address.
country_code
required
string
The country code for this address.
phone
string
Phone number.
required
Array of objects (transaction)
Enables uneven exchanges across multiple payments methods (gift cards). If no data is available, send an empty array. If an object is provided, it must be valid.
Array
identifier
required
string
Unique identifier for a transaction. These details are used to reconcile instant exchanges.
parent_identifier
required
string
amount_cents
required
integer <int> >= 0
Raw amount of a particular transaction - all transactions amounts in a given order should sum to order amount.
status
required
string
Current status of the transaction. E.g. "PENDING" "SUCCESS" "FAILURE".
type
required
string
Type refers to credit/debit from merchants point of view. E.g. "AUTHORIZATION" "CAPTURE" "SALE" "REFUND" "VOID".
gateway
required
string
Name of the payment gateway.
is_online
required
boolean
Denotes if the transaction is programmatically reversible.
is_test
required
boolean
Denotes if the transaction is a test.
created_at
required
string
Creation date in ISO 8601 format, UTC.
updated_at
required
string
Last updated date in ISO 8601 format, UTC.
required
object (payment_details)
Additional details regarding gateway and transaction
avs_result_code
string
Response code from credit card company for correct AVS
cvv_result_code
string
Response code from credit card company for correct CVV
credit_card_company
string
gift_card_id
string
gift_card_code
string
required
Array of objects (refund)
Refunds associated with line items on the order. Helps avoid customers getting double-refunds through multiple channels. For any items on order that are refunded outside of Optoro (e.g. customer call). Refund objects are not updatable. If no data is available, send an empty array. If an object is provided, it must be valid.
Array
identifier
required
string
Unique identifier for the refund.
total_refund_amount_cents
required
integer <int> >= 0
The total amount refunded for the returned items.
required
Array of objects (refund_line_item)
List of line items included in the refund.
Array
identifier
required
string
ID for individual item within the Refund. Must be a unique value per item.
quantity
required
integer
Quantity of products refunded for the order item.
order_item_identifier
required
string
Order item identifier for product that has been refunded.
note
string
Description of the refund.
created_at
required
string
Creation date in ISO 8601 format, UTC.
rma_identifier
string
Identifier of the RMA. Used to help disambiguate if there are multiple RMAs for the same order.
tags
Array of strings
Tags associated with the given refund. Current supported tags are:
ignore_refund: refund is ignored and does not influence return eligibility
required
Array of objects (discount)
Details of any discounts (coupons or offers) that may affect the shoppers refund amount. If no data is available, send an empty array. If an object is provided, it must be valid.
Array
identifier
required
string
code
required
string
type
string
Discount type. E.g. "Fixed_amount", "Percentage", "Shipping", "Bonus", "Fixed_Price", "Alt_Pricing".
