Exchange Service
by Narvar

Exchange Service

Exchange Service
Operations
Exchange Inventory
GET /v1/exchange_inventory
Calculate Cart
POST /v1/calculate_cart
Create Order
POST /v1/create_order
Place Order
POST /v1/place_order
RMA Events
POST /v1/rma/{rma_id}/events
Exchange Inventory
POST /v1/exchange_inventory
Exchange Inventory
GET /v1/exchange_inventory

Given a product_id and order_id return a list of all products eligible for exchange

Limit: 10 products options with 4 variants each

Request parameters

product_id
string required
order_id
string required
variant_id
string required

sku

same_price
boolean optional
Default:
true
higher_price
boolean optional
Default:
true
lower_price
boolean optional
Default:
true
locations
string optional

warehouse_id, bins, country_code

lang
string optional
locale
string required
Default:
en_US
exchange_config
Exchange Config optional

Request headers

retailer_moniker
string required

Responses

200 OK
Body
Object
inventory
Array
Object
product_id
string
Example:
6960134914122
variant_id
string
Example:
40006399590474
display_name
string
Example:
Tribble
sku
string
Example:
TRB-ML
available_for_sale
boolean

Need to check the business logic for this

Example:
true
inventory_quantity
integer
Example:
5
options
Object
size
string
Example:
Medium
color
string
Example:
Longhair
material
unknown nullable
images
Array
Object
image_src
string
image_alt
string
option
string
price
Object
amount
string

price in cents(lowest currency denomination)

currency
string
Example:
USD
variant_options
Array
Object
title
string
Example:
Size
code
string
Example:
size
values
Array
Example: 
["10","20","30"]
string
Example:
10
show more
Example 1
GET /v1/exchange_inventory?product_id=p1&order_id=o1&variant_id=v1&locale=en_US HTTP/1.1 

retailer_moniker: r1

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "inventory": [
        {
            "product_id": "6960134914122",
            "variant_id": "40006399590474",
            "display_name": "Tribble",
            "sku": "TRB-ML",
            "available_for_sale": true,
            "inventory_quantity": 5,
            "options": {
                "size": "Medium",
                "color": "Longhair",
                "material": null
            },
            "images": [
                {
                    "image_src": "",
                    "image_alt": "",
                    "option": ""
                }
            ],
            "price": {
                "amount": "",
                "currency": "USD"
            }
        }
    ],
    "variant_options": [
        {
            "title": "Size",
            "code": "size",
            "values":
            [
                "10",
                "20",
                "30"
            ]
        },
        {
            "title": "Color",
            "code": "color",
            "values":
            [
                "White",
                "Blue"
            ]
        },
        {
            "title": "Material",
            "code": "material",
            "values":
            [
                "Cotton",
                "Polyester"
            ]
        }
    ]
}
show more
Calculate Cart
POST /v1/calculate_cart

Request headers

retailer_moniker
string optional

Request body

application/json
Object
return_items
Array

Object containing items to be returned.

Object
variant_id
string required

sku

product_id
string
line_item_id
string
Example:
123456789
return_reason
string required
Example:
I don't like it
return_reason_id
string
Example:
123456789
child_return_reason
string
Example:
It's too big
child_return_reason_id
string
Example:
123456789
comment
string
Example:
I don't like it
quantity
integer required
Example:
1
image_srcs
Array
Example: 
["https://cdn.shopify.com/s/files/1/0566/6324/4874/products/ST_TroubleWithTribbles.jpg?v=1662058136"]
string
Example:
https://cdn.shopify.com/s/files/1/0566/6324/4874/products/ST_TroubleWithTribbles.jpg?v=1662058136
price
Money Object
discount
Money Object
exchange_items
Array

Object containing items to be exchanged.

Object
product_id
string required
Example:
6960134914122
variant_id
string required
Example:
40006399590474
new_product_id
string required
new_variant_id
string required
new_sku
string
display_name
string

New Item

Example:
Tribble
image_src
string

New Item

Example:
https://cdn.shopify.com/s/files/1/0566/6324/4874/products/ST_TroubleWithTribbles.jpg?v=1662058136
options
Array

New Item

Object
size
string
Example:
Medium
color
string
Example:
Longhair
material
unknown nullable
price
Money Object
quantity
number required
new_price
Money Object
order_information
Object

Object containing order details including customer information and shipping address.

order_number
string required
Example:
SD123456789
order_date
string
Example:
2021-10-01T12:00:00Z
customer_email
string
from_address
Object
ext_order_id
string
fees
Object

Object containing any applicable fees such as restocking fee or shipping fee.

shipping_fee
Money Object
return_fee
Money Object
restocking_fee
Money Object
exchange_fee
Money Object
return_method
string required
refund_method
Any of
string
Default:
original_form_of_payment
show more
Examples

Responses

200 200

Calculation result

Body
application/json
Object
summary
Object
fees
Array of Fee Object

List of Money Object

discounts
Array of Money Object
subtotal
Money Object

Total amount of all the exchange items adjusted agains return items excluding the tax

subtotal_tax
Money Object

Total tax on all the exchange items adjusted agains return items

total
Money Object

Net total which includes subtotal and fees including taxes. Intent would be created on this amount

cart
Cart Object
payment_client_secret
string
payment_intent_id
string
payment_publishable_key
string
show more
Example 1
POST /v1/calculate_cart HTTP/1.1 

Content-Type: application/json

{
    "return_items": [
        {
            "variant_id": "",
            "product_id": "",
            "line_item_id": "123456789",
            "return_reason": "I don't like it",
            "return_reason_id": "123456789",
            "child_return_reason": "It's too big",
            "child_return_reason_id": "123456789",
            "comment": "I don't like it",
            "quantity": 1,
            "image_srcs": [
                "https://cdn.shopify.com/s/files/1/0566/6324/4874/products/ST_TroubleWithTribbles.jpg?v=1662058136"
            ],
            "price": {
                "price_in_cents": 1,
                "currency": ""
            },
            "discount": {
                "price_in_cents": 1,
                "currency": ""
            }
        }
    ],
    "exchange_items": [
        {
            "product_id": "6960134914122",
            "variant_id": "40006399590474",
            "new_product_id": "",
            "new_variant_id": "",
            "new_sku": "",
            "display_name": "Tribble",
            "image_src": "https://cdn.shopify.com/s/files/1/0566/6324/4874/products/ST_TroubleWithTribbles.jpg?v=1662058136",
            "options": [
                {
                    "size": "Medium",
                    "color": "Longhair",
                    "material": null
                }
            ],
            "price": {
                "price_in_cents": 1,
                "currency": ""
            },
            "quantity": 1,
            "new_price": {
                "price_in_cents": 1,
                "currency": ""
            }
        }
    ],
    "order_information": {
        "order_number": "SD123456789",
        "order_date": "2021-10-01T12:00:00Z",
        "customer_email": "",
        "from_address": {},
        "ext_order_id": ""
    },
    "fees": {
        "shipping_fee": {
            "price_in_cents": 1,
            "currency": ""
        },
        "return_fee": {
            "price_in_cents": 1,
            "currency": ""
        },
        "restocking_fee": {
            "price_in_cents": 1,
            "currency": ""
        },
        "exchange_fee": {
            "price_in_cents": 1,
            "currency": ""
        }
    },
    "return_method": "",
    "refund_method": "original_form_of_payment"
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "summary": {
        "fees": [
            {
                "price_in_cents": 1,
                "currency": "",
                "fee_type": "RESTOCKING_FEE",
                "tax_in_cents": 1
            }
        ],
        "discounts": [
            {
                "price_in_cents": 1,
                "currency": ""
            }
        ],
        "subtotal": {
            "price_in_cents": 1,
            "currency": ""
        },
        "subtotal_tax": {
            "price_in_cents": 1,
            "currency": ""
        },
        "total": {
            "price_in_cents": 1,
            "currency": ""
        }
    },
    "cart": {
        "return_items": "",
        "exchange_items": "",
        "cart_id": ""
    }
}
show more
Create Order
POST /v1/create_order

Request body

application/json
Cart Object

Responses

200 200

Order submission result

Body
application/json
Object
order_id
string required

Unique identifier for the draft order created./Basket

payment_infomation
Money Object required

Total payment amount calculated, including taxes and fees.

cart_id
string required
payment_intent_id
string

Stripe payment intent for the total in Calculate Cart

Example 1
POST /v1/submit_order HTTP/1.1 

Content-Type: application/json

{
    "return_items": "",
    "exchange_items": "",
    "cart_id": ""
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "order_id": "",
    "payment_infomation": {
        "price_in_cents": 1,
        "currency": ""
    },
    "cart_id": "",
    "payment_intent_id": ""
}
Place Order
POST /v1/place_order

Request body

application/json
Object
payment_gateway
string required

Name of the payment gateway.

price
Money Object

Amount to be captured.

payment_authorization_token
string

Reference transaction ID/payment ID associated with the order.

order_id
string required

Reference to the Cart created in Submit Order

rma_number
string
return_tracking_number
string

Responses

200 200

Payment capture result

Body
application/json
Object
status
string

Status of the payment capture.

Example 1
POST /v1/place_order HTTP/1.1 

Content-Type: application/json

{
    "payment_gateway": "",
    "price": {
        "price_in_cents": 1,
        "currency": ""
    },
    "payment_authorization_token": {},
    "order_id": "",
    "payment_id": ""
}

HTTP/1.1 200 OK 

Content-Type: application/json

{
    "status": ""
}
RMA Events
POST /v1/rma/{rma_id}/events

Path variables

rma_id
string required

The ID of the Return Merchandise Authorization.

Request body

application/json
Object
event
string

Description of the event occurring.

rma
Object

Object containing RMA details.

Responses

200 200

RMA event processing result

Body
application/json
Object
event_status
string

Status of the event reported.

message
string

A descriptive message about the outcome of the event processing.

Exchange Inventory
POST /v1/exchange_inventory

Given a product_id and order_id return a list of all products eligible for exchange

Limit: 10 products options with 4 variants each

Request headers

retailer_moniker
string required

Request body

Object
product_id
string required
order_id
string required
exchange_config
Exchange Config
locale
string required
variant_id
string required
locations
string

warehouse_id, bins, country_code

Example 1
POST /v1/exchange_inventory HTTP/1.1 

Content-Type: application/json

{
    "product_id": "",
    "order_id": "",
    "exchange_config": {
        "uneven_variant_exchange_enabled": true,
        "even_variant_exchange_enabled": "",
        "uneven_recommended_product_exchange_enabled": "",
        "even_recommended_product_exchange_enabled": "",
        "full_store_exchange_enabled": ""
    },
    "locale": "",
    "variant_id": "",
    "locations": ""
}
Money Object
Object
price_in_cents
number
currency
string
Cart Object
Object
return_items
string
exchange_items
string
cart_id
string
Fee Object
Object
price_in_cents
integer
currency
string
fee_type
Any of
string
Examples:
SHIPPING_FEERETURN_FEERESTOCKING_FEEEXCHANGE_FEERETURN_SHIPPING_FEE
tax_in_cents
integer
Exchange Config
Object
uneven_variant_exchange_enabled
boolean
even_variant_exchange_enabled
string
uneven_recommended_product_exchange_enabled
string
even_recommended_product_exchange_enabled
string
full_store_exchange_enabled
string