Skip to content
API Specifications
/
/
/
Exchange Orders

Exchange Orders (2.0.0)

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.

Download OpenAPI description
openapi.json
openapi.yaml
Languages
Servers
Mock server
https://developer.optoro.com/_mock/openapi/exchange_orders/openapi

Create Exchange Order

Request

Headers
X-Optiturn-Idstringrequired
Example: Modrno
X-Optiturn-Api-Versionstringrequired
Enum"1""2"
Bodyapplication/jsonrequired

Exchange order object

currencystringrequired

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

Example: "USD"
rma_identifierstring

The RMA exchange goods are to be returned under

Example: "RMA12345"
original_order_idstringrequired

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

Example: "OR123456"
original_secondary_order_idstring

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

Example: "OR987654"
is_giftbooleanrequired

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

Example: false
itemsArray of objects(exchange_order_item)required

An array of order line items.

Example: [{"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"}]}]
items[].​skustringrequired

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

Example: "888812345678"
items[].​quantityintegerrequired

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

Example: 2
items[].​titlestring

Title of product

Example: "Fuzzy red t-shirt"
items[].​unit_price_amount_centsinteger(int)>= 0

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

Example: 100
items[].​product_amount_centsinteger(int)>= 0

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

Example: 200
items[].​discount_amount_centsinteger(int)>= 0

Line item discount amount in cents.

Example: 20
items[].​tax_amount_centsinteger(int)>= 0

Line item tax amount in cents.

Example: 100
items[].​bonus_credit_amount_centsinteger(int)>= 0

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

Example: 100
items[].​product_identifierstring

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

Example: "1234-5678"
items[].​variant_identifierstring

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.

Example: "1234-5678"
items[].​original_skustring

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

Example: "888812345678"
items[].​original_item_identifierstring

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

Example: "1234"
items[].​conceptstring

The concept brand that this item belongs to.

Example: "acme"
items[].​return_itemsArray 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.

customerobject(customer)required

Customer

customer.​identifierstringrequired

Reference to customer record in your OMS

Example: "123"
customer.​first_namestring

Customer first name

Example: "Carmine"
customer.​last_namestring

Customer last name

Example: "Customer"
customer.​emailstringrequired

Customer contact email

Example: "customer@example.com"
customer.​phonestring

Customer phone

Example: "202-555-1212"
shipping_addressobject(exchange_order_address)required

Address to receive goods

shipping_address.​namestringrequired

Name of person.

Example: "Carmine Customer"
shipping_address.​street1stringrequired

The street address.

Example: "123 Fake St."
shipping_address.​street2string

An optional second line for the street address, for suite or other similar additions.

Example: "STE 1200"
shipping_address.​citystringrequired

The city for this address.

Example: "Utiopiannapolis"
shipping_address.​provincestringrequired

The state or province for this address.

Example: "WA"
shipping_address.​postal_codestringrequired

The zip or postal code for this address.

Example: "99877"
shipping_address.​country_codestringrequired

The country code for this address.

Example: "US"
shipping_address.​phonestring

Phone number.

Example: "202-555-1212"
billing_addressobject(exchange_order_address)required

Payment billing address

billing_address.​namestringrequired

Name of person.

Example: "Carmine Customer"
billing_address.​street1stringrequired

The street address.

Example: "123 Fake St."
billing_address.​street2string

An optional second line for the street address, for suite or other similar additions.

Example: "STE 1200"
billing_address.​citystringrequired

The city for this address.

Example: "Utiopiannapolis"
billing_address.​provincestringrequired

The state or province for this address.

Example: "WA"
billing_address.​postal_codestringrequired

The zip or postal code for this address.

Example: "99877"
billing_address.​country_codestringrequired

The country code for this address.

Example: "US"
billing_address.​phonestring

Phone number.

Example: "202-555-1212"
paymentobject(Exchange Payment)required
payment.​transaction_idstringrequired

Optoro generated number for order payment

Example: "8ef05fb8-283e-4edd-a3d7-47f9fe520cfe"
curl -i -X POST \
  https://developer.optoro.com/_mock/openapi/exchange_orders/openapi/exchange_orders \
  -H 'Content-Type: application/json' \
  -H 'X-Optiturn-Api-Version: 1' \
  -H 'X-Optiturn-Id: Modrno' \
  -d '{
    "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"
    }
  }'

Responses

Order creation success message

Bodyapplication/json
order_identifierstringrequired

Identifier of created order, should be the same order id given to shoppers

Example: "OR124567"
total_amount_centsinteger(int)>= 0required

Total amount of order in cents, including any gift card bonus credit (if applicable)

Example: 100
product_amount_centsinteger(int)>= 0required

Product amount of order in cents, before discounts, taxes or shipping costs

Example: 100
tax_amount_centsinteger(int)>= 0required

Tax amount of order in cents

Example: 110
Response
application/json
{
  "order_identifier": "OR124567",
  "total_amount_cents": 100,
  "product_amount_cents": 100,
  "tax_amount_cents": 110
}
© 2010 – 2026 Optoro, Inc. For official use only by authorized users. Use subject to terms of license agreement.