Exchange Orders (2.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": 800,
  "bonus_credit_amount_cents": 200,
  "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 Enum: "1" "2"

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.

bonus_credit_amount_cents

integer <int> >= 0

Gift card bonus credit amount in cents. This field is only present for an Instant Gift Card exchange.

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 Instant 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

Payload

application/json

{"currency": "USD",
"rma_identifier": "RMA12345",
"original_order_id": "OR123456",
"original_secondary_order_id": "OR987654",
"is_gift": false,
"items": [{"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"
},
{"sku": "OPTOROGIFTCARD",
"quantity": 1,
"unit_price_amount_cents": 800,
"bonus_credit_amount_cents": 200,
"return_items": [{"title": "Pink Shirt",
"original_sku": "888812349672",
"original_item_identifier": "4567",
"quantity": 1,
"concept": "acme"
}
]
}
],
"customer": {"identifier": "123",
"first_name": "Carmine",
"last_name": "Customer",
"email": "customer@example.com",
"phone": "202-555-1212"
},
"shipping_address": {"name": "Carmine Customer",
"street1": "123 Fake St.",
"street2": "STE 1200",
"city": "Utiopiannapolis",
"province": "WA",
"postal_code": "99877",
"country_code": "US",
"phone": "202-555-1212"
},
"billing_address": {"name": "Carmine Customer",
"street1": "123 Fake St.",
"street2": "STE 1200",
"city": "Utiopiannapolis",
"province": "WA",
"postal_code": "99877",
"country_code": "US",
"phone": "202-555-1212"
},
"payment": {"transaction_id": "8ef05fb8-283e-4edd-a3d7-47f9fe520cfe"
}
}

Response samples

application/json

{"order_identifier": "OR124567",
"total_amount_cents": 100,
"product_amount_cents": 100,
"tax_amount_cents": 110
}