A Returns Portal Order object
API Specifications
/Returns Experience
/- Returns Portal Orders
Create Returns Portal Orders
Returns Portal Orders
Returns Portal Orders (3.0.0)
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.
Download OpenAPI description
Languages
Servers
Mock server
https://developer.optoro.com/_mock/openapi/returns_portal_orders/openapi
Sandbox
https://orders.sandbox.optiturn.com
Bodyapplication/jsonrequired
An orders object.
Array of orders.
Public facing identifier for this order. Must be a unique value per order.
Example: "1455123AB12"
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.
Example: "Best Brand"
Status of the order as it relates to the RMA portal
Enum"Created""Shipped""Canceled"
Example: "Shipped"
Total order amount including taxes and discounts and shipping.
Example: 100
Total order amount of merchandise purchased.
Example: 100
Total order amount of sales tax on merchandise.
Example: 100
Total order amount of discounts.
Example: 100
Total order amount of shipping costs.
Example: 100
Total order amount of sales tax on shipping.
Example: 100
Currency code. Must be ISO-4217 reference. E.g. "USD"
Example: "USD"
An array of tags associated with the given order. Current supported tags are: FinalSale, gift-card, canceled, Thirdparty, ShippingRateOverride, pickup_in_store
Arbitrary context notes (discount notes, etc.)
Example: "This order was delayed."
Creation date in ISO 8601 format, UTC
Example: "2018-08-30T15:39:42.025Z"
Last updated date in ISO 8601 format, UTC
Example: "2018-08-30T15:39:42.025Z"
An array of order line items.
ID for individual item within the Order. Must be a unique value per item.
Example: "123"
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.
Example: "Best Brand"
UPC that represents the product for this order item. Required unless SKU is present.
Example: "888812345678"
An identifier which matches the catalog and represents the product for this order item. Required unless UPC is present.
Example: "888812345678"
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.
Example: 2
Number of units of a particular line item that have shipped. Must be less than or equal to quantity.
Number of units of a particular line item that have been canceled. Must be less than or equal to quantity.
Number of units of a particular line item that have already been refunded. Must be less than or equal to quantity_shipped.
The tracking number for the package containing this order item. This allows operations to scan the tracking number for undeliverable items.
Example: "1Z9999999999999999"
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.
Example: "1Z9999999999999999"
ID used to track item that was drop shipped.
Example: "4441212"
Date when the order was shipped, in ISO 8601 format, UTC.
Example: "2018-08-30T15:39:42.025Z"
Date when the order item is no longer eligible for return, in ISO 8601 format, UTC.
Example: "2018-08-30T15:39:42.025Z"
Id unique to that product (ex. same SKU from different vendors). Send SKU if no product_identifier exists.
Example: "1234-5678"
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.
Example: "1234-5678"
Array of product variants for the parent item. Including variants improves exchange functionality in the return portal.
Title of product
Example: "Fuzzy red t-shirt"
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).
Example: 100
Line item tax amount in cents.
Example: 100
Line item discount amount in cents.
Example: 100
Unit price amount in cents of a single unit of a product.
Example: 100
An array of tags associated with the given order. Current supported tags are: FinalSale, gift-card, canceled, Thirdparty, pickup_in_store, cs-required
Product image file link.
Example: "https://example.com/img.jpg"
Customer
Reference to customer record in your OMS
Example: "123"
Customer contact email
Example: "customer@example.com"
Reduce customer friction by auto populating package sender details in the return label for the shopper.
Name of person.
Example: "Carmine Customer"
The street address.
Example: "123 Fake St."
An optional second line for the street address, for suite or other similar additions.
Example: "STE 1200"
The city for this address.
Example: "Utiopiannapolis"
The state or province for this address.
Example: "WA"
The zip or postal code for this address.
Example: "99877"
The country code for this address.
Example: "US"
Customer billing address will help support exchange orders.
Name of person.
Example: "Carmine Customer"
The street address.
Example: "123 Fake St."
An optional second line for the street address, for suite or other similar additions.
Example: "STE 1200"
The city for this address.
Example: "Utiopiannapolis"
The state or province for this address.
Example: "WA"
The zip or postal code for this address.
Example: "99877"
The country code for this address.
Example: "US"
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.
Unique identifier for a transaction. These details are used to reconcile instant exchanges.
Example: "adf56c018de8438dbc7d86017cc10f1d"
Example: "a0bf7bddb0928a7e69b51110c14831c0"
Raw amount of a particular transaction - all transactions amounts in a given order should sum to order amount.
Example: 100
Current status of the transaction. E.g. "PENDING" "SUCCESS" "FAILURE".
Example: "PENDING"
Type refers to credit/debit from merchants point of view. E.g. "AUTHORIZATION" "CAPTURE" "SALE" "REFUND" "VOID".
Example: "CAPTURE"
Name of the payment gateway.
Example: "QuikPay"
Denotes if the transaction is programmatically reversible.
Denotes if the transaction is a test.
Creation date in ISO 8601 format, UTC.
Example: "2018-08-30T15:39:42.025Z"
Last updated date in ISO 8601 format, UTC.
Example: "2018-08-30T15:39:42.025Z"
Additional details regarding gateway and transaction
Response code from credit card company for correct AVS
Response code from credit card company for correct CVV
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.
Unique identifier for the refund.
Example: "RF12554113"
The total amount refunded for the returned items.
returns_portal_order.orders[].refunds[].refund_line_itemsArray of objects(refund_line_item)required
List of line items included in the refund.
ID for individual item within the Refund. Must be a unique value per item.
Example: "RF12554113"
Quantity of products refunded for the order item.
Example: 2
Creation date in ISO 8601 format, UTC.
Example: "2018-08-30T15:39:42.025Z"
Identifier of the RMA. Used to help disambiguate if there are multiple RMAs for the same order.
Example: "RMA12345"
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.
Discount type. E.g. "Fixed_amount", "Percentage", "Shipping", "Bonus", "Fixed_Price", "Alt_Pricing".
Example: "Percentage"
Creation date in ISO 8601 format, UTC.
Example: "2018-08-30T15:39:42.025Z"
- Mock serverhttps://developer.optoro.com/_mock/openapi/returns_portal_orders/openapi/returns_portal_orders
- Sandboxhttps://orders.sandbox.optiturn.com/returns_portal_orders
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \
https://developer.optoro.com/_mock/openapi/returns_portal_orders/openapi/returns_portal_orders \
-H 'Api-Version: 3' \
-H 'Content-Type: application/json' \
-d '{
"returns_portal_order": {
"orders": [
{
"identifier": "1455123AB12",
"concept": "Best Brand",
"raw_status": "processing",
"status": "Shipped",
"total_amount_cents": 100,
"product_amount_cents": 100,
"tax_amount_cents": 100,
"discount_amount_cents": 100,
"shipping_amount_cents": 100,
"shipping_tax_amount_cents": 100,
"currency": "USD",
"tags": [
"string"
],
"note": "This order was delayed.",
"created_at": "2018-08-30T15:39:42.025Z",
"updated_at": "2018-08-30T15:39:42.025Z",
"items": [
{
"identifier": "123",
"concept": "Best Brand",
"upc": "888812345678",
"sku": "888812345678",
"quantity": 2,
"quantity_shipped": 0,
"quantity_canceled": 0,
"quantity_refunded": 0,
"tracking_number": "1Z9999999999999999",
"reverse_tracking_number": "1Z9999999999999999",
"dropship_identifier": "4441212",
"shipped_date": "2018-08-30T15:39:42.025Z",
"return_policy_end_date": "2018-08-30T15:39:42.025Z",
"product_identifier": "1234-5678",
"variant_identifier": "1234-5678",
"variants": [
{
"attributes": [],
"image_urls": []
}
],
"title": "Fuzzy red t-shirt",
"product_amount_cents": 100,
"tax_amount_cents": 100,
"discount_amount_cents": 100,
"unit_price_amount_cents": 100,
"tags": [
"string"
],
"image_url": "https://example.com/img.jpg",
"weight": 2.2
}
],
"customer": {
"identifier": "123",
"first_name": "Carmine",
"last_name": "Customer",
"email": "customer@example.com",
"phone": "202-555-1212",
"tags": [
"Tier 1",
"Tier 2"
]
},
"shipping_address": {
"name": "Carmine Customer",
"street1": "123 Fake St.",
"street2": "STE 1200",
"city": "Utiopiannapolis",
"state": "WA",
"zip_code": "99877",
"country_code": "US",
"phone": "202-555-1212"
},
"billing_address": {
"name": "Carmine Customer",
"street1": "123 Fake St.",
"street2": "STE 1200",
"city": "Utiopiannapolis",
"state": "WA",
"zip_code": "99877",
"country_code": "US",
"phone": "202-555-1212"
},
"transactions": [
{
"identifier": "adf56c018de8438dbc7d86017cc10f1d",
"parent_identifier": "a0bf7bddb0928a7e69b51110c14831c0",
"amount_cents": 100,
"status": "PENDING",
"type": "CAPTURE",
"gateway": "QuikPay",
"is_online": true,
"is_test": true,
"created_at": "2018-08-30T15:39:42.025Z",
"updated_at": "2018-08-30T15:39:42.025Z",
"payment_details": {
"avs_result_code": "string",
"cvv_result_code": "string",
"credit_card_company": "string",
"gift_card_id": "string",
"gift_card_code": "string"
}
}
],
"refunds": [
{
"identifier": "RF12554113",
"total_refund_amount_cents": 0,
"refund_line_items": [
{}
],
"note": "string",
"created_at": "2018-08-30T15:39:42.025Z",
"rma_identifier": "RMA12345",
"tags": [
"string"
]
}
],
"discounts": [
{
"identifier": "string",
"code": "string",
"type": "Percentage",
"amount_cents": 100,
"created_at": "2018-08-30T15:39:42.025Z",
"updated_at": "2018-08-30T15:39:42.025Z"
}
]
}
]
}
}'