Narvar Shopify RMA Spec

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.

Rate Limiting in HTTP header responses

Some operations are rate-limited. All rate limited operations return information in HTTP response headers as specified in the IETF definition for Rate Limit Headers. Rate limiting headers describe the limit, quota, and refresh window in the following header properties (all values provided as examples only):

X-Rate-Limit-Limit: 300
X-Rate-Limit-Remaining: 150
X-Rate-Limit-Reset: 45

• X-Rate-Limit-Limit: The maximum number of requests that can be made before the rate limit is reached
• X-Rate-Limit-Remaining: The number of requests remaining before the rate limit is reached
• X-Rate-Limit-Reset: The number of seconds remaining before the rate limit is reset

All rate limiting values are subject to change, and should be derived from values within the header fields themselves rather than relying on static values.

When Rate Limits are Exceeded

If the rate limit is exceeded for an operation, the HTTP response code will change to 429 and the following message returned in the JSON response:

{
  "status": "Too Many Requests"
}