Narvar Shopify RMA Spec

Narvar RMA Spec for Returns app on Shopify
General

Hostname

https://szero.narvar.com/

Authentication

Authentication is via HTTP Basic Auth. Credentials are created on the Settings -> Advanced -> RMA Post Credentials page.

RMA webhook

You can use webhook subscriptions to receive notifications about particular events on your product returns. There are two endpoints here – one is the RMA webhook to receive updates from Narvar, and the other is the Refund Approval endpoint for your warehouse to send updates to Narvar. These are decribed below.

After you configure a webhook subscription, the events that you specified will trigger a webhook notification each time they occur. This notification contains a JSON payload, and HTTP headers that provide context. The following are the headers that you can expect:

X-Narvar-Topic: initiated
X-Narvar-Timestamp: 1614146162
X-Narvar-Shop-Domain: mycrofood.myshopify.com
X-Narvar-API-Version: 1.07
X-Narvar-Webhook-Id: b54557e4-bdd9-4b37-8a5f-bf7d70bcd043

List of supported webhook events and topics

You can retrieve data only in JSON format. Webhooks are available for the following events:

  • initiated - This event is called when a new return is initiated by a customer.
  • on_its_way_to_retailer - This event is called when a return is dropped off by a customer at a carrier.
  • delivered_to_retailer - This event is called when a return is delivered by a carrier to the merchant, or is dropped off by the customer at the retailer store
  • approved - This event is called when a return is approved by the retailer
  • cancelled_by_retailer - This event is called when a return is cancelled by the retailer
  • cancelled_by_user - This event is called when a return is cancelled by the user ( prior to drop off or return to retailer).
  • rejected - This event is called when a return is rejected by the retailer
  • exception - This event is called when Narvar encounters an error in processing the return
  • out_of_stock_exception - This event is called when an exchange cannot be completed because an item is out of stock
  • resolve_manually_without_automation - This event is called when a retailer decides to handle an exception manually

Retries

Webhooks are retried when the HTTP response code is unsuccessful ( > 299) or if the request is timed out (no response within 6 seconds). The webhook will be retried up to nine times with the same payload. The delay between retries is one hour.

Refund Approval endpoint

You will use this endpoint to send updates from your warehouse to Narvar. This endpoint is hosted by Narvar. You can set the status of the items received for refund as well as change the refund amounts at the item-level and order-level as needed.

Operations
POST /api/returns
GET /api/returns
POST /retailer_provided_endpoint
POST /merchant/returns/approval
POST /merchant/returns/shipment_status
Create a return or exchange
POST /api/returns

Authentication

basicAuth

This API allows you to programatically create returns and exchanges on your shop

Request headers

X-Narvar-Shop-Domain
string required

Your shopify domain

Example:
your-shop.myshopify.com

Request body

Object
locale
string required

Locale

Example:
en
exchangeItems
Array required

Items being exchanged (if any)

Min items: 0
Object
returnItem
Object
returnReason
string

Return Reason ( from Narvar Return Reasons page)

Example:
Product does not match description
returnReasonId
string

Return Reason ID ( from Narvar Return Reasons page)

Example:
W6BW
lineItemId
string

Line item ID

Example:
gid://shopify/LineItem/1156296586054
newProductId
string

Replacement product ID

Example:
gid://shopify/Product/24674392474
newProductVariantId
string

Replacement product Variant ID

Example:
gid://shopify/ProductVariant/3209637268695
newProductVariantInfo
Array

Replacement product Variant Info

Object
name
string
Example:
Product
value
string
Example:
Sherpa Fleece Jacket
newProductSku
string

Replacement product SKU

Example:
sdsf0923ff-37
newProductName
string

Replacement product Name

Example:
Sherpa Fleece Jacket
newProductImage
string

Replacement product Image

Example:
https://cdn.shopify.com/s/files/1/0767/5695/products/gray_2.jpg?v=1602266411
newProductPriceAmount
integer

Replacement product amount

Example:
50
newProductPriceCurrency
string

Currency

Example:
USD
returnItems
Array required
Min items: 0
Object
quantity
integer

Number of items returned

Example:
1
returnReason
string

Return Reason

Example:
Company shipped wrong product or size
returnReasonId
string

Return Reason ID

Example:
NR8N
lineItemId
string

Line Item ID returned

Example:
gid://shopify/LineItem/1156296586054
orderNumber
string

Order Number

Example:
3019
email
string

Customer Email

Example:
test@test.com
shippingPrice
number

Shipping Price

shippingMethod
string required

Shipping method

Enumeration:
usps_returns

USPS

fedex

Fedex

ups

UPS ( ask Narvar for additional carriers)

keep_the_item

Keep the item

return_in_store

In-store return

ship_on_your_own

Ship on your own

selectedRefundMethod
string

Selected Refund Method ( assuming available according to Narvar Refund Rules)

Enumeration:
original_payment

Refund in original form of payment

gift_card

Refund as gift card

fromAddress
Object

From Address is only required if there is an issue with the address in the order

address1
string
Example:
6499 SADDLE CREEK CT
address2
unknown nullable
companyName
string
Example:
Peninsula Trading Co.
provinceCode
string
Example:
NC
city
string
Example:
HARRISBURG
countryCode
unknown nullable
postalCode
string
Example:
28075-6660
name
string
Example:
Peninsula Trading Co.
phone
unknown nullable

Responses

201 Created
Body
Object
shipping_label
string

URL to Image

qr_code
string

URL to Image

rma_number
string

RMA Number

400 Error creating Return

Error creating return

Get Returns
GET /api/returns

Authentication

basicAuth

This API can be used for getting details of a return. refund or exchange by RMA Number, email address or order number. You can use this endpoint to get the status of a single RMA ( by specifying RMA endpoint), or a randge of RMAs by specifying the order number or email that the RMA belongs to. If you do not specify the RMA number, you also have to specify filters to set the minimum creation time or minimum update time for your search results.

Paging next_timestamp in the results indicates that there are more results past the first page, and you can use the value as an input parameter for the next call.

The response is the same as the webhook payload described in the webhook section.

Request parameters

rma_number
string optional

RMA Number to retrieve (required if Order Number and email are not present)

order_number
string optional

Order number (required if RMA number and email are not present)

email
string email optional

Email address of the customer (required if Order Number and RMA number are not present)

created_since
string date-time optional

Date-time in ISO 8601 format. Only one of created_since, created_max, updated_since or updated_max can be specified

created_max
string date-time optional

Date-time in ISO 8601 format. This will return returns created before this time stamp in reverse chronological order. Only one of created_since, created_max, updated_since or updated_max can be specified

updated_since
string date-time optional

Date-time in ISO 8601 format. Only one of created_since, created_max, updated_since or updated_max can be specified

limit
integer optional

Limit number of results

Min: 1
Max: 50
Default:
50
updated_max
string date-time optional

Date-time in ISO 8601 format. This will return returns updated before this time stamp in reverse chronological order. Only one of created_since, created_max, updated_since or updated_max can be specified

Request headers

X-Narvar-Shop-Domain
string required

Your shopify domain name or retailer moniker

Example:
mycrofood.myshopify.com

Responses

200 OK
RMA Webhook triggered by Narvar
POST /retailer_provided_endpoint

Authentication

basicAuth

This endpoint is used to send the status of the return, refunds and exchanges to third party systems. The webhook is triggered by Narvar whenever there is a change in the returns data due to data received by Narvar, or a user action on the Narvar platform.

The endpoint is provided by you. Narvar will POST the request to your endpoint.

Basic Auth Username Password Verification

You will provide Narvar with a username and password that Narvar will encode using Base64 and pass as the Basic Auth parameter. Pseudocode is given below.

header = "#{webhook.basic_username}:#{webhook.basic_password}"
b64 = Base64.encode64(header)
{
    'Authorization' => "Basic " + b64,
    'Content-Type' => 'application/json'
}

Request headers

X-Narvar-Shop-Domain
string required

Your shopify domain name or retailer moniker

Example:
mydomain.myshopify.com

Request body

application/json

RMA details

Object
return_status
string required

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

Enumeration:
initiated

This field is populated right after a return is initiated.

on_its_way_to_retailer

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

delivered_to_retailer

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

approved

This event is called when a return is approved by the retailer.

cancelled_by_retailer

This event is called when a return is cancelled by the retailer.

cancelled_by_user

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

rejected

This event is called when a return is rejected by the retailer.

exception

This event is called when Narvar encounters an error in processing the return.

out_of_stock_exception

This event is called when an exchange cannot be completed because an item is out of stock.

resolve_manually_without_automation

This event is called when a retailer decides to handle an exception manually.

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
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:
US
shipping_fee
string

Fee associated with the return shown to the end user in the returns process. This is set only when you use Narvar’s carrier accounts.

Example:
5.99
destination_id
string

Location ID of the destination

estimated_actual_shipping_fee
string

(deprecated) - use shipping_fee

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.

in_store

When the customer returns it in store.

self

When the customer returns on their own.

printerless_mail

When customer choose the printerless option.

keep_the_item

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
email
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:
US
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:
0
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:
gift_card

If the user chose to receive the refund via Gift Card.

original_payment

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:
3
quantity
integer required

Quantity being returned

Example:
6
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
Array

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

Object
name
string

Name of the variant

Example:
color
value
string

Value

Example:
red
product_id
string

Product ID of the exchange item

exchange_quantity
number

Quantity of items exchanged

keep_the_item
boolean

Indicates whether the item is kept

child reason
string

Child reason if any

child_reason_code
string

Child reason code if any

current_processing_state
Array
Object
status
string

Status of the item

Example:
approved
quantity
number

Number of items in this status

Example:
1
timestamp
number

epoch when event was recorded

Example:
16000012110
unit_price_original_shop
string

Original price of a single quantity of an item prior to markdown in shop currency

unit_discount_shop
string

Discount attached to product

unit_price_discounted_shop
string

Unit price of item after discounts

unit_tax_shop
string

Tax and duties paid per unit of an item

unit_final_shop
string

unit_price_discounted added with tax calculated above.

unit_price_original_presentment
string

Original price of a single quantity of an item prior to markdown in checkout currency

unit_discount_presentment
string

Discount attached to product in checkout currency

unit_price_discounted_presentment
string

Discounted price of item after applying above discounts

unit_tax_presentment
string

Tax and duties paid per unit of an item paid in checkout currency

unit_final_presentment
string

Final amount ( inc. tax and duties) paid py the consumer

policy
Object

This part of the RMA payload indicates what rules were configured for automating processing of returns.

refund_at
string

The event at which the refund should be issued

Example:
initiated
refund_automation_until
string date-time

Number of days after inititation refund can be issued

mark_as_paid_at
string

The return status when the exchange draft order was completed as a paid order.

mark_as_paid_automation_until
string date-time

Number of days after inititation draft order can be mark as paid ( in case of an exchange)

restock_at
string

The return status when the returned item will be restocked.

restock_automation_until
string date-time

Number of days after inititation restock automation can be done

reserve_inventory_at
string

The return status when the inventory will be held for the new exchanged items.

reserve_automation_until
string date-time

Number of days after inititation inventory for an exchange will be held

transactions
Array

List of all transactions that have happened

Object
id
string

Unique ID of the transaction

timestamp
number

Epoch at which this transaction occured

Example:
160012202
source
string

Source that originated this event

Enumeration:
narvar

Autoamtion Rule inititated

narvar_agent

An agent issued on our platform

shopify_webhook

From Shopify

api

Third party API

amount
number

Amount that was refunded

currency
string

Currency of transaction

refund_method
string
Enumeration:
original_payment

Refund back to original payment

gift_card

Issue a Shopify Gift Card

narvar_instant_refund

Issue an instant refund in good faith

narvar_instant_refund_reversal

Adjust an instant refund

giftcard_id
string

ID of the gift card issued

issued_refund_gateway
string

Gateway that was used to issue refund

authorization
string

Authorization token if any

conversion_rate_to_shop
number

Currency conversion for presentment currency to shop currency

shopify_order_id
integer

Universal order ID used to reference shopify orders ( usually part of the URL in Shopify)

original_shopify_order_id
string

In case of exchanges ( and subsequent exchanges), this holds the pointer to the original shopify order ID.

currency
string

This is the currency in which the order was paid

shop_currency
string

The currency in which the Shop’s accounting is done

charge_payment_id
string

Reference to Stripe charge id if enabled on uour account

transaction_id
string

Unique ID denoting this transaction

packages
Array
Object
carrier_service_name
string
Example:
FedEx Ground
destination_city
string
Example:
San Francisco
destination_country_code
string
Example:
US
destination_gid
string
Example:
gid://shopify/Location/99999
destination_postal_code
string
Example:
12345
estimated_actual_shipping_fee
unknown nullable

Reserved for future use

letter
string
Example:
A
return_method
string
Example:
mail
return_tracking_company
string
Example:
fedex
return_tracking_number
string
Example:
abc123
shipping_fee
unknown nullable

Reserved for future use

tracking_link
string

A link to the tracking page for this package.

Examples

Responses

200 200

SUCCESS

Body
application/json

No payload is required in the response to Narvar. We will ignore any data sent back. Any request that is not a 200 will be treated as an error, and will be retried.

Object
Send updates from Warehouse to Narvar
POST /merchant/returns/approval

Authentication

basicAuth

This API endpoint allows you to send Narvar approval of items after receiving them in your warehouse. This can also be triggered by your ERP systems. By default, if an item is marked as not_received, then that item won’t be refunded.

Partial Refund

As of May 2023, a partial refund can be issued by specifying process_refund, process_refund_override, and total_refund_override_amount. The Return will be Approved.

Request headers

X-Narvar-Shop-Domain
string required

Your shopify domain name.

Example:
my-shop.myshopify.com

Request body

Object
rma_number
string required

RMA Number previously created by Narvar

Example:
TP1233APQW
call_reference_id
string uuid required

Unique reference ID that indicates this transaction. We will ignore additional updates with the same ID.

process_refund
boolean

Issue refund in Shopify. If set to false, no refund is issued.

Default:
true
refund_adjustment_amount
number

Obsolete, ignored.

refund_adjustment_currency
string

Obsolete, ignored.

total_refund_override_amount
number

Total refund amount that will be issued to the customer. Specify in primary currency units. For example specify $3.10 as 3.1. Must not exceed the refund calculated at the time of return.

Example:
3.1
total_refund_override_currency
string

Currency for the above total refund amount, ISO 4217.

Example:
USD
items
Array required

Line items in the return

Min items: 1
Object
item_id
number

Shopify Item ID of the item. This field is required if the item SKU is not provided.

item_sku
string

Item SKU if required if the item ID is not specified.

quantity
number required

Number of items received. If mutliple items are returned where the items are in different statuses e.g. one received in good condition, and one is rejected, then break them into separate entries.

status
string required

Status of the received items.

Enumeration:
approved

Approved for refund and restock if restock automation is set.

approved_no_restock

Approved for refund but do not restock even if automation is set. If the Return has a Restock Timing, transition the Return to Exception status. If the Return does not have a Restock Timing, the Return will either stay in the same status, or transition to Exception status, depending on other factors.

rejected

Not approved for refund or restock

not_received

Item was missing / not received

exception

Needs manual intervention from retailer

invalid_item

Item was not part of the RMA

claim

Return was processed but then determined to be invalid

refund_override_amount
number

Obsolete, ignored.

refund_override_currency
string

Obsolete, ignored.

override_note
string

Obsolete, ignored.

auto_approve
boolean

Automatically approve return as soon as all items are approved. Setting to true will assume that as soon as all items are approved, the return is approved. Note that this will cause incomplete orders to sit in unapproved state.

Default:
false
process_refund_override
boolean

Enable partial refund via total_refund_override_amount

Change Shipment status
POST /merchant/returns/shipment_status

Authentication

basicAuth

This API allows you to programatically set the shipment status to one of delivered_to_retailer, on_its_way_to_retailer or received_by_retailer.

Request parameters

rma_number
string required

RMA number of the return for which you are setting the shipment status.

shipment_status
string required

Optional if the note field in the request is not empty. Valid status are:
cancelled_by_retailer, cancelled_by_user, delivered_to_retailer, exception, initiated, on_its_way_to_retailer, out_of_stock_exception, received_by_retailer, rejected, resolve_manually_without_automation

note
string optional

Merchant RMA text to append

Request headers

X-Narvar-Shop-Domain
string required

Your shopify domain name or retailer moniker

Manage Return Locations

If management of return locations is enabled on your account, you can use this API to add return locations to your account.

POST /api/return_locations
GET /api/return_locations
GET /api/return_locations/:id
DELETE /api/return_locations/:id
PUT /api/return_locations/:id
Create a new return location
POST /api/return_locations

Authentication

basicAuth

Add a new location available for returns.

Request body

Object
location
Object required

Location information

address1
string required

Address line 1

Example:
1211 Main Road
address2
string

Address line 2

Example:
Suite 4
city
string required

City

Example:
Reading
latitude
number required

Latitude

Example:
12.22
longitude
number required

Longitude

Example:
-24.33
phone
string required

Phone number for shipping ( E.164 format)

Example:
1-415-555-5555
state
string required

State of province

Example:
California
state_code
string required

ISO 3166-1 alpha-2 formatted state code without country code prefix

Example:
CA
zip
string required

Zip or postal code

Example:
94105
country_code
string required

ISO 3166-1 alpha-2 formatted country code

Example:
US
country
string required

Country

Example:
United States
accept_in_store_returns
boolean required

Is this an in-store location accepting returns

accept_mail_in_returns
boolean required

Is this a location that can be used to mail in returns

name
string required

Name of the location

List all return locations
GET /api/return_locations

Authentication

basicAuth

List all return locations live on your store

Responses

200 OK
Body
Array
Object
accept_in_store_returns
boolean

Is this an in-store location accepting returns

accept_mail_in_returns
boolean

Is this a location that can be used to mail in returns

id
string

Narvar ID of the location

Example:
YXWN
location
Object

Address of the location

address1
string

Address line 1

Example:
1214 Main Road
address2
string

Address line 2

Example:
Suite 4
city
string

City

Example:
San Francisco
latitude
number

Latitude

Example:
12.22
longitude
number

Longitude

Example:
-93.11
phone
string

Phone number in E.164 format

Example:
1-415-555-5555
state
string

State or Province

Example:
California
state_code
string

State Code

Example:
CA
zip
string

Zip or postal code

Example:
94105
country_code
string

2-digit country code

Example:
US
country
string

Country

Example:
United States
name
string required

Name of the location

Get a return location
GET /api/return_locations/:id

Authentication

basicAuth

Get the specified return location

Responses

200 OK
Body
Object
location
Object

Address of the location

address1
string

Address line 1

Example:
12 Main Road
address2
string

Address line 2

Example:
Suite 4
city
string

City

Example:
San Francisco
latitude
number

Latitude

longitude
number

Longitude

phone
string

Phone number ( E.164 format)

state
string

State

Example:
California
state_code
string

ISO code

Example:
CA
zip
string

Zip or postal code

Example:
94105
country_code
string

ISO Country code

Example:
US
country
string

Country

Example:
United States
accept_in_store_returns
boolean

Is this an in-store location accepting returns

accept_mail_in_returns
boolean

Is this a location that can be used to mail in returns

id
string

ID of the return location

name
string

Name of the location

Delete a return location
DELETE /api/return_locations/:id

Authentication

basicAuth

Delete return location corresponding to this location. Ensure all rules associated with this rule are deleted.

Responses

204 No Content
Update a return location
PUT /api/return_locations/:id

Authentication

basicAuth

Update an exisiting return location

Request body

Object
location
Object required

Location information

address1
string required

Address line 1

Example:
1211 Main Road
address2
string

Address line 2

Example:
Suite 44
city
string required

City

Example:
San Francisco
latitude
number required

Latitude

Example:
12.22
longitude
number required

Longitude

Example:
-24.33
phone
string required

Phone number for shipping ( E.164 format)

Example:
1-415-555-5555
state
string required

State of province

Example:
California
state_code
string required

ISO 3166-1 formatted state code without country code prefix

Example:
CA
zip
string required

Zip or postal code

Example:
94105
country_code
string required

ISO 3166-1 alpha-2 formatted country code

Example:
US
country
string required

Country

Example:
United States
accept_in_store_returns
boolean required

Is this an in-store location accepting returns

accept_mail_in_returns
boolean required

Is this a location that can be used to mail in returns

id
string required

ID of the return location to update

name
string required

Name of the location

Integrations