Standard RMA webhook

Standardized/default payload for RMA webhooks from Narvar

POST - send return data

POST /rma

Authentication

basicAuth

This is Standard payload as of Feb 2021. The Standard payload contains what we believe is a sensible default set of attributes.

Request body

application/json

RMA details

Object

return_tracking_status

string required

This represents the status of the return during its journey to the distribution centre.

Enumeration:

return_initiated_standard

This field is populated right after a return is initiated.

return_on_its_way_standard

This field is populated when we receive a first scan event from the carrier.

return_delivered_standard

This field is populated when we receive a delivered scan event from the carrier.

return_cancellation_standard

This field is populated when an user chooses to cancel the return.

Example:

returned

rma_number

string

When Narvar creates the RMA number it will be passed in this field

Example:

993338

order_number

string required

Original order number for the order

Example:

70074401

return_creation_date

string required

Date when a return was created on the Narvar platform

Example:

2018-02-24T13:25:31Z

retailer_name

string required

Retailer name as it is stored in the Narvar system

Example:

peninsula

package

Object

This object will contain details package containing the returned item/s

tracking_number

string

The carrier tracking number for the package

Example:

1Z453087998799333

tracking_url

string

This URL can be used to track the package status on the Narvar platform

Example:

https://peninsula.narvar.com/peninsula/tracking/UPS?tracking_numbers=1Z6W11111650E0319580262&type=ret&order_number=70074401&rma=993338

carrier

string

Carrier used to delivery the package

Example:

UPS

carrier_service_method

string

Class of service used for the package

Example:

Ground

destination_zip

string

Destination area of the return

Example:

01810

destination_city

string

Destination city for the return

Example:

Andover

destination_country

string

Destination country for the return

Example:

shipping_fee

string

Fee associated with the return shown to the end user in the returns process

Example:

5.99

return_method

string required

Method selected for the return. Only if MAIL is selected will a corresponding “package” object be sent

Enumeration:

mail

When customer ships the product via mail.

store

When the customer returns it in store.

self

When the customer returns on their own.

printerless_mail

When customer choose the printerless option.

keeptheitem

When customer gets the keep the item and the refund is issued without receiving items to the DC

Example:

mail

gift

boolean

Sent as “true” if the return was initiated by a gift recipient

Example:

true

string

Email associated with the return. When “gift” is “true” this will contain the gift recipient email collected by Narvar during the returns flow.

Example:

johndoe@narvar.com

locale

string required

Locale that was used to initiate the return

Example:

en_US

origin_zip

string

Zip code of the return package origin

Example:

94117

origin_city

string

City of the return package origin

Example:

San Francisco

origin_country

string

Country of the return package origin

Example:

estimated_refund

string

Amount shown to the end user in the returns process as the estimated refund

Example:

305.93

restocking_fee

string

Restocking fee shown to the end user during the returns process

Example:

label_url

string

Narvar will host the packing slip and label URL as a PDF. This is the URL to access that PDF

Example:

https://narvar.com/retailer/label.pdf

refund_method

string

This is the refund method the user chose at the last step of the returns workflow.

Enumeration:

store_credit

If the user chose to receive the refund via Store Credit.

credit_card

If the user chose to receive the refund in the original payment method.

items

Array required

Array of the items being returned

Object

sku

string required

SKU of the item being returned

Example:

3423423

item_id

string

Unique identifier of the item being returned

Example:

line_number

string

Line number for the item

Example:

quantity

string

Quantity being returned

Example:

reason

string

Reason for the return selected by the end user

Example:

Did not Like

reason_code

string

Reason code for the return selected by the end user

Example:

2OF

comment

string

Comments entered by the end user during the return process. 300 character max

Example:

Comments entered by user

unit_price

string

Unit price of the item being returned

Example:

49.99

total_item_price

string

Unit price * Quantity being returned

Example:

299.94

transaction_type

string

This denotes if the item is a return or exchange

Enumeration:

return

If the item is a return

exchange

If the item is an exchange

exchange_item

Object

variant_title

string

Title of the exchange item

Example:

Sweatshirt

variant_id

string

Variant ID of the exchange item.

Example:

0123

variant_sku

string

Variant SKU

Example:

1234

exchange_option

Object

Exchange options chosen by the user.
Note: color and size are examples - fields may vary based on the Inventory API integration.

color

string

Color of the exchange item

Example:

blue

size

string

Size of the exchange item

Example:

medium

item_custom_attributes

Object

All the custom attributes at the item level. This is populated from Orders API.

order_custom_attributes

Object

All the custom attributes at the order level. This is populated from Orders API.

shipment_info

Array

List of all return shipments generated for this return

Object

label_url

string

barcode_url

string

printerless_info_url

string

tracking_url

string

tracking_number

string

Tracking Number of this shipment

items

Array

List of items in this return shipment

Object

quantity

integer

item_id

string

product_sku

string

ship_to

Object

Destination address for this shipment

address

Object

city

string

state

string

country

string

street1

string

street2

string

zipcode

string

ship_from

Object

Sender address for this shipment

first_name

string

address

Object

city

string

state

string

country

string

street1

string

street2

string

zipcode

string

carrier

string

Carrier moniker for this shipment

status

string

Current status of this shipment

created_date

number

timestamp from epoch

modified_date

number

timestamp from epoch

Examples

Responses

200 200

ITEM CREATED

Body

application/json

No payload is required in the response to Narvar. We will ignore any data sent back.

Object

400 400

BAD REQUEST

application/json

401 401

UNAUTHORIZED

application/json

403 403

FORBIDDEN

application/json

500 500

INTERNAL SERVER ERROR

Body

application/json

Any 5xx response will be considered a failure

Examples

Narvar generates the RMA number will be passed in the payload

POST /rma HTTP/1.1 

Content-Type: application/json

{
    "return_tracking_status": "returned",
    "rma_number": "993338",
    "order_number": "70074401",
    "return_creation_date": "2018-02-24T13:25:31Z",
    "retailer_name": "peninsula",
    "package": {
        "tracking_number": "1Z453087998799333",
        "tracking_url": "https://peninsula.narvar.com/peninsula/tracking/UPS?tracking_numbers=1Z6W11111650E0319580262&type=ret&order_number=70074401&rma=993338",
        "carrier": "UPS",
        "carrier_service_method": "Ground",
        "destination_zip": "01810",
        "destination_city": "Andover",
        "destination_country": "US",
        "shipping_fee": "5.99"
    },
    "return_method": "mail",
    "gift": true,
    "email": "johndoe@narvar.com",
    "locale": "en_US",
    "origin_zip": "94117",
    "origin_city": "San Francisco",
    "origin_country": "US",
    "estimated_refund": "305.93",
    "restocking_fee": "0",
    "label_url": "https://narvar.com/retailer/label.pdf",
    "refund_method": "store_credit",
    "items": [
        {
            "sku": 3423423,
            "item_id": "3",
            "line_number": "1",
            "quantity": "1",
            "reason": "Did not Like",
            "reason_code": "2OF",
            "comment": "Comments entered by user",
            "unit_price": "49.99",
            "total_item_price": "299.94",
            "transaction_type": "exchange",
            "exchange_item": {
                "variant_title": "Sweatshirt",
                "variant_id": "0123",
                "variant_sku": "1234",
                "exchange_option": {
                    "color": "blue",
                    "size": "medium"
                }
            },
            "item_custom_attributes": {}
        }
    ],
    "order_custom_attributes": {},
    "shipment_info": [
        {
            "label_url": "",
            "barcode_url": "",
            "printerless_info_url": "",
            "tracking_url": "",
            "tracking_number": "709a390231c7cb341",
            "items": [
                {
                    "quantity": 1,
                    "item_id": "",
                    "product_sku": ""
                }
            ],
            "ship_to": {
                "address": {
                    "city": "Seattle",
                    "state": "WA",
                    "country": "US",
                    "street1": "3211 W Mcgraw St",
                    "street2": "",
                    "zipcode": "98199"
                }
            },
            "ship_from": {
                "first_name": "",
                "email": "",
                "address": {
                    "city": "",
                    "state": "",
                    "country": "",
                    "street1": "",
                    "street2": "",
                    "zipcode": ""
                }
            },
            "carrier": "fedex",
            "status": "shipped",
            "created_date": 1,
            "modified_date": 1
        },
        {
            "label_url": "",
            "barcode_url": "",
            "printerless_info_url": "",
            "tracking_url": "",
            "tracking_number": "709a390231c7cb342",
            "items": [
                {
                    "quantity": 1,
                    "item_id": "",
                    "product_sku": ""
                }
            ],
            "ship_to": {
                "address": {
                    "city": "Seattle",
                    "state": "WA",
                    "country": "US",
                    "street1": "3211 W Mcgraw St",
                    "street2": "",
                    "zipcode": "98199"
                }
            },
            "ship_from": {
                "first_name": "",
                "email": "",
                "address": {
                    "city": "",
                    "state": "",
                    "country": "",
                    "street1": "",
                    "street2": "",
                    "zipcode": ""
                }
            },
            "carrier": "fedex",
            "status": "delivered",
            "created_date": 1,
            "modified_date": 1
        }
    ]
}