Exchange Orders (1.0.0)

Download OpenAPI specification:Download

The Exchange Orders API is used to place an order in your e-commerce platform when the shopper has chosen to exchange for a replacement item or receive their refund via a gift card. Your endpoint should handle all tax and shipping calculations. The endpoint should be idempotent, using original_order_id as the key. Only one exchange order can be placed against an original_order_id.

When it is used:

  • Optoro POSTS an Exchange Orders message to you when the shopper has confirmed an exchange, selected a gift card refund, or both.

Instant Exchange

This is an exchange of one or more items for a variant of the product (ex: different size, different color). This will be represented in the items array by an object like the following:

{
  "sku": "888812345678",
  "quantity": 2,
  "title": "Fuzzy red t-shirt",
  "unit_price_amount_cents": 100,
  "product_amount_cents": 200,
  "discount_amount_cents": 20,
  "tax_amount_cents": 100,
  "product_identifier": "1234-5678",
  "variant_identifier": "1234-5678",
  "original_sku": "888812345678",
  "original_item_identifier": "1234",
  "concept": "acme"
}

Instant Gift Card

This is an exchange of one or more items for a gift card. This will be represented in the items array by an object like the following:

{
  "sku": "OPTOROGIFTCARD",
  "quantity": 1,
  "unit_price_amount_cents": 1000,
  "return_items": [
    {
      "title": "Pink Shirt",
      "original_sku": "888812349672",
      "original_item_identifier": "4567",
      "quantity": 1,
      "concept": "acme"
    }
  ]
}

sku will be the agreed upon value for an Instant Gift Card exchange and return_items will be the list of items being exchanged for the gift card.

Create Exchange Order

Request
header Parameters
X-Optiturn-Id
required
string
Example: Modrno
X-Optiturn-Api-Version
required
string
Value: "1"
Request Body schema: application/json

Exchange order object

currency
required
string

Currency code. Must be ISO-4217 reference. E.g. "USD"

rma_identifier
string

The RMA exchange goods are to be returned under

original_order_id
required
string

The original order id of item(s) to be exchanged

original_secondary_order_id
string

The original secondary order id of item(s) to be exchanged

is_gift
required
boolean

Treat as a gift order, don’t show price or allow refund to original form of payment.

required
Array of objects (exchange_order_item)

An array of order line items.

Array
sku
required
string

An identifier which matches the catalog and represents the product for this order item.

quantity
required
integer

The number of units within the order for each SKU (or UPC). Must be less than or equal to 1000.

title
string

Title of product

unit_price_amount_cents
integer <int> >= 0

Unit price amount in cents of a single unit of a product.

product_amount_cents
integer <int> >= 0

Product amount in cents, before discounts, taxes or shipping costs.

discount_amount_cents
integer <int> >= 0

Line item discount amount in cents.

tax_amount_cents
integer <int> >= 0

Line item tax amount in cents.

product_identifier
string

Id unique to that product (ex. same SKU from different vendors).

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

original_sku
string

SKU of the item from original order that is being exchanged.

original_item_identifier
string

Order line item identifier of the item from original order that is being exchanged.

concept
string

The concept brand that this item belongs to.

Array of objects (exchange_order_return_item)

An array of order line items being exchanged for a gift card. This field is only present for an Uneven Gift Card exchange.

Array
title
string

Title of product

original_sku
required
string

SKU of the item from original order that is being exchanged.

original_item_identifier
required
string

Order line item identifier of the item from original order that is being exchanged.

quantity
required
integer

The number of units within the order for each SKU (or UPC). Must be less than or equal to 1000.

concept
string

The concept brand that this item belongs to.

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 (exchange_order_address)

Address to receive goods

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.

province
required
string

The state or province for this address.

postal_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 (exchange_order_address)

Payment billing address

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.

province
required
string

The state or province for this address.

postal_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 (Exchange Payment)
transaction_id
required
string

Optoro generated number for order payment

Responses
200

Order creation success message

post/exchange_orders
Request samples
application/json
{
  • "currency": "USD",
  • "rma_identifier": "RMA12345",
  • "original_order_id": "OR123456",
  • "original_secondary_order_id": "OR987654",
  • "is_gift": false,
  • "items": [
    ],
  • "customer": {
    },
  • "shipping_address": {
    },
  • "billing_address": {
    },
  • "payment": {
    }
}
Response samples
application/json
{
  • "order_identifier": "OR124567",
  • "total_amount_cents": 100,
  • "product_amount_cents": 100,
  • "tax_amount_cents": 110
}
© 2010 – 2024 Optoro, Inc. For official use only by authorized users. Use subject to terms of license agreement.