Return Webhook

This notification is sent when the Return topic is requested. For those that subscribe to this topic for more than one trigger event, the "trigger" property is included in the payload for reference.

Response HeaderDescription
X-Loop-SignatureHashed Webhook Secret Key

The X-Loop-Signature is a base-64, HMAC hash of body payload using the Webhook Secret provided by Loop.

Note: Before attempting to create your hash of the POST request body, make sure slashes have been escaped & newlines have been removed from the JSON.

return

FieldDescription
topicWebhook type (return, label, restock)
triggerEvent that triggered the webhook (created, updated, requested)
idLoop return ID
stateLoop return state
Possible values: open, closed, cancelled, expired, review.

- "Open" means Loop has not fully processed all the outcomes.
- "Closed" means there is no further action required for this return. Typically, this means all outcomes have processed.
- "Review" means Loop cannot proceed with normal processing until merchant approval.
created_atDate and time (ISO 8601 format) when the return was created in Loop
edited_atDate and time (ISO 8601 format) when the return was last edited inside Loop, and null when the return has not been edited.
order_idLoop order ID
order_nameShopify order name
provider_order_idShopify order ID
order_numberShopify order number
customerEmail address of Shopify customer
customer_detailEmail, first name, middle name, and last name of Shopify customer
currencyCurrency of the store at the time of the order
return_product_totalValue of returned line items excluding order discounts and taxes
return_discount_totalSum of all discounts on returned items
return_tax_totalValue of order taxes on returned line items
return_totalReturn total after taxes and discounts
return_credit_totalValue of total return credit (product + honored discount + tax)
exchange_product_totalValue of exchange items before discounts and taxes
exchange_discount_totalDiscount on exchange items
exchange_tax_totalTax on exchange items
exchange_totalExchange total after taxes and discounts
exchange_credit_totalTotal exchange items value after discounts and taxes which is used by the customer
gift_cardAmount of store credit to be issued to the customer on a gift card
handling_feeHandling fee amount set in Loop admin
upsellAdditional amount paid by customer when exchange credit total is greater than return credit total
carrierName of carrier or N/A: carrier not yet assigned
tracking_numberThe tracking number provided by the carrier or N/A: tracking number not yet assigned
label_statusStatus of the shipment according to EasyPost, N/A: no shipment status, pre_transit, in_transit, out_for_delivery, delivered, error, failure
label_updated_atDate and time ( ISO 8601 format) when the last status update occurred. N/A: label not yet updated
status_page_urlUrl to the return status page
destination_idLoop Destination ID

line_items

Line Item data reflects items being sent to Loop as part of the return.

Line items are provided in the return webhook in an array, if you need to know the quantity of items being returned you must iterate through the array and count the items.

FieldDescription
line_item_idLoop line item ID
provider_line_item_idShopify order line item ID
product_idShopify product ID
variant_idShopify variant ID
skuShopify variant SKU
barcodeShopify barcode
titleShopify product title
pricePrice paid by customer before discounts and tax
discountDiscount on item
taxTax on item
refundAmount refunded to customer for this item
returned_atDate and time ( ISO 8601 format) when the return was created in Loop
exchange_variantShopify variant ID for replacement product (if exchange)
return_reasonReason for return as selected by the customer in Loop
parent_return_reasonParent reason for return as selected by the customer in Loop

Exchanges

Exchanges data reflects product(s) being sent to a customer. This can be a result of an even exchange, replacements for returned items, or new purchases made through the app.

Exchanges are provided in the return webhook in an array, if you need to know the quantity of items being exchanged you must iterate through the array and count the items.

FieldDescription
exchange_idLoop exchange ID
product_idShopify product ID
variant_idShopify variant ID
exchange_order_nameNew Shopify exchange order name
exchange_order_idNew Shopify exchange order id
skuShopify variant SKU
titleShopify product title
pricePrice of exchange item before discounts and tax
discountDiscount on exchange item
taxTax on exchange item
totalPrice of exchange item after discounts and tax

carrier

refund

Amount of credit to be issued to the customer as a refund

FieldDescription
refundsThe breakdown of refunds across payment gateways
gatewayThe payment gateway in which a refund was processed
amountThe refund amount issued to a gateway

return_method

If the return is not being sent back through boxing and shipping, this field describes the way in which the item is being returned. These are usually pick-up or drop-off options.

FieldDescription
providerThe provider of the return method (e.g. happy-returns)
return_method_typepick-up or drop-off
addressIf the return method is a drop-off, this is the destination where it can be dropped off at
stateThe state of the return method at the current time, similar to label status (in_transit, new, etc)
rma_idThe ID of the return record in the related system
qr_code_urlIf the return method has a QR code, this is the link, otherwise null
scheduled_atIf this return method needs to be scheduled for pick up or drop off otherwise null

Response

{
  "topic": "return",
  "trigger": "return.updated",
  "id": "12345",
  "shop_id": "9876",
  "state": "open",
  "created_at": "2019-04-01T12:00:00+00:00",
  "edited_at": "2019-04-01T12:00:00+00:00", // can also be null
  "order_id": "1234567890",
  "order_name": "#1234",
  "provider_order_id": "1029384756",
  "order_number": "234",
  "customer": "[email protected]",
  "customer_detail": [
    "email": "[email protected]",
    "first_name": "Mary",
    "middle_name": "Todd",
    "last_name": "Lincoln",
  ],
  "currency": "USD",
  "return_product_total": "46.00",
  "return_discount_total": "0.00",
  "return_tax_total": "3.34",
  "return_total": "49.34",
  "return_credit_total": "49.34",
  "exchange_product_total": "84.00",
  "exchange_discount_total": "10.00",
  "exchange_tax_total": "5.37",
  "exchange_total": "79.37",
  "exchange_credit_total": "49.34",
  "gift_card": "0.00",
  "handling_fee": "0.00",
  "refund": "0.00",
  "refunds": [
    {
      "gateway": "your gateway",
      "amount": "0.00"
    }
  ],
  "upsell": "30.03",
  "address": {
    "name": "First Last",
    "company": "Company Name",
    "address1": "123 Road",
    "address2": "apt 1",
    "city": "Anywhere",
    "state": "California",
    "zip": "11111",
    "country": "United States",
    "country_code": "US",
    "phone": ""
  },
  "line_items": [
    {
      "line_item_id": "123456789",
      "provider_line_item_id": "3847568374653883",
      "product_id": "1624622563417",
      "variant_id": "14773475377241",
      "sku": "FD-RL-2",
      "barcode": "",
      "title": "Retro Laser - Big",
      "price": "46.00",
      "discount": "0.00",
      "tax": "3.34",
      "refund": "0.00",
      "returned_at": "2019-04-01T12:00:00+00:00",
      "exchange_variant": "",
      "return_reason": "Reason here",
      "parent_return_reason": "Parent reason here",
      "outcome": "Line item outcome('default', 'keep', 'donate', 'reject')"
    }
  ],
  "exchanges": [
    {
      "exchange_id": "54320",
      "product_id": "1624622563418",
      "variant_id": "14773475377242",
      "sku": "FD-NC-1",
      "exchange_order_name": "#1234",
      "exchange_order_id": "1234",
      "title": "Noisy Cricket - Small",
      "price": "46.00",
      "discount": "5.48",
      "tax": "2.94",
      "total": "43.46",
      "out_of_stock": true, // true | false
      "out_of_stock_resolution": "credited" // credited | refunded | null
    },
    {
      "exchange_id": "54321",
      "product_id": "1624622563419",
      "variant_id": "14773475377243",
      "sku": "FD-RG-2",
      "exchange_order_name": "12345-1",
      "exchange_order_id": "13131313",
      "title": "Ray Gun - Medium",
      "price": "46.00",
      "discount": "5.48",
      "tax": "2.94",
      "total": "43.46",
      "out_of_stock": false,
      "out_of_stock_resolution": null
    }
  ],
  "carrier": "USPS", // If no label exists, we pass "N/A"
  "tracking_number": "28735625627856237856287", // If no label exists, we pass "N/A"
  "label_status": "in_transit", // If no label exists, we pass "N/A"
  "label_updated_at": "2019-04-01T12:00:00+00:00", // If no label exists, we pass "N/A"
  "status_page_url": "https://partner.loopreturns.com/#/return/12345456",
  "destination_id": "2",
  "return_method": {  // If no return method exists, we pass null
    "provider": "happy-returns",
    "return_method_type": "drop-off",
    "address": {
      "name": "Staples 0152",
      "company": null,
      "address1": "7881 Edinger Ave.Ste.130",
      "address2": "Bella Terra Mall",
      "city": "Huntington Beach",
      "state": "CA",
      "zip": "92647",
      "country": "United States of America",
      "country_code": "US",
      "phone": "",
      "latitude": 33.7313927,
      "longitude": -117.9910687
    },
    "state": "new",
    "rma_id": "HRABC123",
    "qr_code_url": "https://partner.happyreturns.com/barcode/qr?code=HRABC123",
    "scheduled_at": null
  },
  "shipment_id": "fwe66545646"
}