Narvar Shopify RMA Spec
Hostname
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.
Authentication
This API allows you to programatically create returns and exchanges on your shop
Request headers
Your shopify domain
Request body
Locale
Items being exchanged (if any)
Return Reason ( from Narvar Return Reasons page)
Return Reason ID ( from Narvar Return Reasons page)
Line item ID
Replacement product ID
Replacement product Variant ID
Replacement product Variant Info
Replacement product SKU
Replacement product Name
Replacement product Image
Replacement product amount
Currency
Number of items returned
Return Reason
Return Reason ID
Line Item ID returned
Order Number
Customer Email
Shipping Price
Shipping method
USPS
Fedex
UPS ( ask Narvar for additional carriers)
Keep the item
In-store return
Ship on your own
Selected Refund Method ( assuming available according to Narvar Refund Rules)
Refund in original form of payment
Refund as gift card
From Address is only required if there is an issue with the address in the order
Responses
Body
URL to Image
URL to Image
RMA Number
Error creating return
Authentication
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 to retrieve (required if Order Number and email are not present)
Order number (required if RMA number and email are not present)
Email address of the customer (required if Order Number and RMA number are not present)
Date-time in ISO 8601 format. Only one of created_since, created_max, updated_since or updated_max can be specified
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
Date-time in ISO 8601 format. Only one of created_since, created_max, updated_since or updated_max can be specified
Limit number of results
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
Your shopify domain name or retailer moniker
Responses
Authentication
Subscribe to this webhook to receive the status of the return, refunds and exchanges. This webhook is sent 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 URL 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
Your shopify domain name or retailer moniker
Request body
RMA details
This represents the status of the return during its journey to the distribution centre.
This field is populated right after a return is initiated.
This field is populated when we receive a first scan event from the carrier.
This field is populated when we receive a delivered scan event from the carrier.
This event is called when a return is approved by the retailer.
This event is called when a return is cancelled by the retailer.
This field is populated when an user chooses to cancel the return.
This event is called when a return is rejected by the retailer.
This event is called when Narvar encounters an error in processing the return.
This event is called when an exchange cannot be completed because an item is out of stock.
This event is called when a retailer decides to handle an exception manually.
When Narvar creates the RMA number it will be passed in this field
Original order number for the order
Date when a return was created on the Narvar platform
Retailer name as it is stored in the Narvar system
This object will contain details package containing the returned item/s
The carrier tracking number for the package
Carrier used to delivery the package
Class of service used for the package
Destination area of the return
Destination city for the return
Destination country for the return
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.
Location ID of the destination
(deprecated) - use shipping_fee
Method selected for the return. Only if MAIL is selected will a corresponding “package” object be sent
When customer ships the product via mail.
When the customer returns it in store.
When the customer returns on their own.
When customer choose the printerless option.
When customer gets the keep the item and the refund is issued without receiving items to the DC
Sent as “true” if the return was initiated by a gift recipient
Email associated with the return. When “gift” is “true” this will contain the gift recipient email collected by Narvar during the returns flow.
Locale that was used to initiate the return
Zip code of the return package origin
City of the return package origin
Country of the return package origin
Amount shown to the end user in the returns process as the estimated refund
Restocking fee shown to the end user during the returns process
Narvar will host the packing slip and label URL as a PDF. This is the URL to access that PDF
This is the refund method the user chose at the last step of the returns workflow.
If the user chose to receive the refund via Gift Card.
If the user chose to receive the refund in the original payment method.
Array of the items being returned
SKU of the item being returned
Unique identifier of the item being returned
Quantity being returned
Reason for the return selected by the end user
Reason code for the return selected by the end user
Comments entered by the end user during the return process. 300 character max
Unit price of the item being returned
Unit price * Quantity being returned
This denotes if the item is a return or exchange
If the item is a return
If the item is an exchange
Title of the exchange item
Variant ID of the exchange item.
Variant SKU
Exchange options chosen by the user.
Note: color and size are examples - fields may vary based on the Inventory API integration.
Name of the variant
Value
Product ID of the exchange item
Quantity of items exchanged
Indicates whether the item is kept
Child reason if any
Child reason code if any
Status of the item
Number of items in this status
epoch when event was recorded
Original price of a single quantity of an item prior to markdown in shop currency
Discount attached to product
Unit price of item after discounts
Tax and duties paid per unit of an item
unit_price_discounted added with tax calculated above.
Original price of a single quantity of an item prior to markdown in checkout currency
Discount attached to product in checkout currency
Discounted price of item after applying above discounts
Tax and duties paid per unit of an item paid in checkout currency
Final amount ( inc. tax and duties) paid py the consumer
This part of the RMA payload indicates what rules were configured for automating processing of returns.
The event at which the refund should be issued
Number of days after inititation refund can be issued
Timestamp indicating when refund automation succeeded. ISO8601 format with UTC offset.
The return status
when the exchange draft order was completed as a paid order.
Number of days after inititation draft order can be mark as paid ( in case of an exchange)
Timestamp indicating when the mark-as-paid automation succeeded. ISO8601 format with UTC offset.
The return status
when the returned item will be restocked.
Number of days after inititation restock automation can be done
Timestamp indicating when the restock automation succeeded. ISO8601 format with UTC offset.
The return status
when the inventory will be held for the new exchanged items.
Number of days after inititation inventory for an exchange will be held
Timestamp indicating when the reserve inventory automation succeeded. ISO8601 format with UTC offset.
List of all transactions that have happened
Unique ID of the transaction
Epoch at which this transaction occured
Source that originated this event
Autoamtion Rule inititated
An agent issued on our platform
From Shopify
Third party API
Amount that was refunded
Currency of transaction
Refund back to original payment
Issue a Shopify Gift Card
Issue an instant refund in good faith
Adjust an instant refund
ID of the gift card issued
Gateway that was used to issue refund
Authorization token if any
Currency conversion for presentment currency to shop currency
Universal order ID used to reference shopify orders ( usually part of the URL in Shopify)
In case of exchanges ( and subsequent exchanges), this holds the pointer to the original shopify order ID.
This is the currency in which the order was paid
The currency in which the Shop’s accounting is done
Reference to Stripe charge id if enabled on uour account
Unique ID denoting this transaction
Reserved for future use
Reserved for future use
A link to the tracking page for this package.
Error timestamp, in ISO8601 format
[{"fee":0.0,"currency":"USD","description":"Return Fee","tax_code":null,"display_with_return_method":true,"formatted_fee":"FREE"},{"fee":850.0,"currency":"USD","description":"Shipping Fee","tax_code":null,"display_with_return_method":true,"formatted_fee":"($8.50)"}]
Currency subunits, e.g. cents
Array of previous versions, representing retailer edits, or the result of automations such as out-of-stock refund conversion. Added 2024-05-22
When the return version record was created, ie. the time of edit
Subset of historical version properties. Fields are same as at top-level, plus item_versions
Version records
When the item version record was created, ie. the time of edit
Subset of historical item version properties. Fields same as at top-level.
Present if the RMA Edit was by a retailer, and RBAC is enabled.
Examples
Responses
SUCCESS
Body
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.
Authentication
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
Your shopify domain name.
Request body
RMA Number previously created by Narvar
Unique reference ID that indicates this transaction. We will ignore additional updates with the same ID.
Issue refund in Shopify. If set to false, no refund is issued.
Obsolete, ignored.
Obsolete, ignored.
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.
Currency for the above total refund amount, ISO 4217.
Line items in the return
Shopify Item ID of the item. This field is required if the item SKU is not provided.
Item SKU if required if the item ID is not specified.
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 of the received items.
Approved for refund and restock if restock automation is set.
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.
Not approved for refund or restock
Item was missing / not received
Needs manual intervention from retailer
Item was not part of the RMA
Return was processed but then determined to be invalid
Obsolete, ignored.
Obsolete, ignored.
Obsolete, ignored.
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.
Enable partial refund via total_refund_override_amount
Authentication
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 of the return for which you are setting the shipment status.
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
Merchant RMA text to append
Request headers
Your shopify domain name or retailer moniker
If management of return locations is enabled on your account, you can use this API to add return locations to your account.
Authentication
Add a new location available for returns.
Request body
Location information
Address line 1
Address line 2
City
Latitude
Longitude
Phone number for shipping ( E.164 format)
State of province
ISO 3166-1 alpha-2 formatted state code without country code prefix
Zip or postal code
ISO 3166-1 alpha-2 formatted country code
Country
Is this an in-store location accepting returns
Is this a location that can be used to mail in returns
Name of the location
Authentication
List all return locations live on your store
Responses
Body
Is this an in-store location accepting returns
Is this a location that can be used to mail in returns
Narvar ID of the location
Address of the location
Address line 1
Address line 2
City
Latitude
Longitude
Phone number in E.164 format
State or Province
State Code
Zip or postal code
2-digit country code
Country
Name of the location
Authentication
Get the specified return location
Responses
Body
Address of the location
Address line 1
Address line 2
City
Latitude
Longitude
Phone number ( E.164 format)
State
ISO code
Zip or postal code
ISO Country code
Country
Is this an in-store location accepting returns
Is this a location that can be used to mail in returns
ID of the return location
Name of the location
Authentication
Update an exisiting return location
Request body
Location information
Address line 1
Address line 2
City
Latitude
Longitude
Phone number for shipping ( E.164 format)
State of province
ISO 3166-1 formatted state code without country code prefix
Zip or postal code
ISO 3166-1 alpha-2 formatted country code
Country
Is this an in-store location accepting returns
Is this a location that can be used to mail in returns
ID of the return location to update
Name of the location