Narvar Shopify RMA Spec

Narvar RMA Spec for Returns app on Shopify

Retailer Hosted Endpoint

https://shopifyzero.narvar.com
General

You can use webhook subscriptions to receive notifications about particular events on your product returns. Currently, Narvar webhooks must be configured by a Narvar support engineer, and cannot be enabled from within the Shopify Admin dashboard, currently. There are two endpoints here – one is the RMA webhook to receive updates from Narvar, and the other is Refund Approval endpoint for your warehouse to send updates to Narvar. These are decribed below.

RMA webhook

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 to have.

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

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 /retailer_provided_endpoint
POST /merchant/returns/approval
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.

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

Example:
5.99
destination_id
string

Location ID of the destination

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
policy
Object
refund_at
string

The event at which the refund should be issued

Example:
initiated
refund_automation_until
number

Number of days after inititation refund can be issued

Example:
20
mark_as_paid_at
string
mark_as_paid_automation_until
number

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

Example:
20
restock_at
string
restock_automation_until
string

Number of days after inititation restock automation can be done

Example:
20
reserve_inventory_at
string
reserve_automation_until
integer

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

Example:
20
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

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. If you want Narvar to issue a partial refund, you have to set the refund override amounts. By default, if an item is marked as not_received, then that item won’t be refunded.

Refund amount changes

If only a partial refund needs to be issued, you need to specify the refund_override amount for each of the item, as well as any order level refund_adjustment ( this would have been shipping and handling fees we would show end user), and the final total_refund_override amount. We will ensure that total of all the item level refunds amounts and the refund_adjustment amounts add up to total_refund_override amount.

Basic Auth with HMAC Verification

Narvar will provide you with an application_secret that will be used in the Basic Auth verification creation.

The basic auth username will be current timestamp in UTC as epoch seconds. For reference, Saturday, February 27, 2021 11:15:24 AM will be 1614424524.

The password is the signature generated using a hash-based message authentication code (HMAC) with SHA-256 and the application secret shared with you directly by your Narvar Implementation engineer i.e. HMAC.SHA256( application_secret, signed_payload) where signed_payload is created by concatenating the timestamp ( passed as username), the character ‘.’ and the actual JSON payload (i.e. the request body).

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

Pseudocode (Ruby) is given below.

user_name = Time.now.to_i
signed_payload = user_name + "." + body.to_json
password = OpenSSL::HMAC.hexdigest("SHA256", application_secret, signed_payload)
header = "#{user_name}:#{password}"
b64 = Base64.encode64(header)
{
    'Authorization' => "Basic " + b64,
    'Content-Type' => 'application/json'
}

Request parameters

rma_number
string optional

RMA Number previously created by Narvar

Example:
TP1233APQW
refund_adjustment_amount
number optional

Shipping / handling fees at the order level

refund_adjustment_currency
string optional

Currency for the shipping / handling fees

total_refund_override_amount
number optional

Total refund amount that will be issued to the customer ( needed if this is different from the original amount)

total_refund_override_currency
string optional

Currency for the above total refund amount.

items
array of object optional
Collection format: multi
process_refund
boolean optional

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

Default:
true
call_reference_id
string uuid required

Unique reference ID that indicates this transaction. We will ignore additional updates with the same reference_id if the first call was successful.