Returns Portal Orders (3.0.0)

Download OpenAPI specification:Download

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, cs-required

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".

amount_cents
required
integer <int> >= 0
created_at
required
string

Creation date in ISO 8601 format, UTC.

updated_at
string

Last updated date in ISO 8601 format, UTC.

Responses
200

Success

post/returns_portal_orders
Request samples
application/json
{
  • "returns_portal_order": {
    }
}
© 2010 – 2024 Optoro, Inc. For official use only by authorized users. Use subject to terms of license agreement.