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 Header	Description
X-Loop-Signature	Hashed 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

Field	Description
topic	Webhook type (return, label, restock)
trigger	Event that triggered the webhook (created, updated, requested, closed)
id	Loop return ID
state	Loop return states (state of the return) Possible values: open, cancelled, closed, expired, needs review. - "Open" requests have yet to be processed (Loop has not fully processed all the outcomes). - "Cancelled" refers to any return requests that have been cancelled in Loop admin. - "Closed" typically refers to any return request/outcome that has been processed or closed manually. No further action is required for these returns. - "Expired" means any return or exchange that has not been sent back, according to the shipping label status provided. Labels must be in a new or pre-transit state for this process to start. All labels expire after 2 days. - "Needs Review" requests have a block in processing, and Loop cannot proceed with normal processing until the merchant approves. Review requests can also include Out of Stock items or Insufficient Funds.
created_at	Date and time (ISO 8601 format) when the return was created in Loop
edited_at	Date and time (ISO 8601 format) when the return was last edited inside Loop, and null when the return has not been edited.
order_id	Loop order ID
order_name	Shopify order name
provider_order_id	Shopify order ID
order_number	Shopify order number
provider_order_number	Shopify number
customer	Email address of Shopify customer
customer_detail	Email, first name, middle name, and last name of Shopify customer
address	The original customer's shipping address or the address that the customer inputs in the case of a gift return
currency	Currency of the store at the time of the order
return_product_total	Value of returned line items excluding order discounts and taxes
return_discount_total	Sum of all discounts on returned items
return_tax_total	Value of order taxes on returned line items
return_total	Return total after taxes and discounts
return_credit_total	Value of total return credit (product + honored discount + tax)
exchange_product_total	Value of exchange items before discounts and taxes
exchange_discount_total	Discount on exchange items
exchange_tax_total	Tax on exchange items
exchange_total	Exchange total after taxes and discounts
exchange_credit_total	Total exchange items value after discounts and taxes which is used by the customer
gift_card	Amount of store credit to be issued to the customer on a gift card
handling_fee	Handling fee amount set in Loop admin
upsell	Additional amount paid by customer when exchange credit total is greater than return credit total
carrier	Name of carrier or N/A: carrier not yet assigned
tracking_number	The tracking number provided by the carrier or N/A: tracking number not yet assigned
package_reference	The value that identifies the physical package that the return is in regardless if it was returned via box & ship or a different return method.
label_status	Status of the shipment according to EasyPost, N/A: no shipment status, pre_transit, in_transit, out_for_delivery, delivered, error, failure
label_updated_at	Date and time ( ISO 8601 format) when the last status update occurred. N/A: label not yet updated
status_page_url	Url to the return status page
destination_id	Loop Destination ID
type	Return type (e.g. standard, warranty)

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.

Field	Type	Description
line_item_id	integer	Loop line item ID (for example, "123456789")
provider_line_item_id	integer	Shopify order line item ID (for example, "3847568374653883")
product_id	integer	Shopify product ID (for example, "1624622563417")
variant_id	integer	Shopify variant ID (for example, "14773475377241")
sku	string \|\| null	Shopify variant SKU (for example, "FD-RL-2")
barcode	string \|\| null	Shopify barcode
title	string	Shopify product title (for example, "Retro Laser - Big")
weight_in_grams	integer \|\| null	Weight of the line item (for example, "226")
price	integer	Price paid by customer before discounts and tax (for example, "46.00")
discount	integer	Discount on item (for example, "0.00")
tax	integer	Tax on item (for example, "3.34")
refund	integer	Amount refunded to customer for this item (for example, "0.00")
returned_at	string	Date and time (ISO 8601 format) when the return was created in Loop (for example, "2019-04-01T12:00:00+00:00")
exchange_variant	int \|\| null	Shopify variant ID for replacement product, if exchange
return_reason	string	Reason for return as selected by the customer in Loop
provider_restock_location_id	integer \|\| null	Shopify location ID for line item restocking
is_in_store_return	boolean	True if the return is made in-store through the Loop Point of Sale application. False if return is made online through the returns portal
parent_return_reason	string \|\| null	Parent reason for return as selected by the customer in Loop
return_comment	string	Return reason comment
outcome	string	Return outcomes (for example, "default", "keep", "donate", "reject")

"line_items": [
    {
      "line_item_id": "123456789",
      "provider_line_item_id": "12149029339269",
      "product_id": "5107813056645",
      "variant_id": "34404555554949",
      "sku": "new-sku",
      "barcode": "barcode1234",
      "title": "A mug",
      "weight_in_grams": 5,
      "price": "35.38",
      "discount": "0.00",
      "tax": "2.65",
      "refund": "38.03",
      "returned_at": "2024-01-11 22:47:02",
      "exchange_variant": "",
      "return_reason": "I didn't like how the item looked",
      "provider_restock_location_id": null,
      "is_in_store_return": false,
      "parent_return_reason": "I didn't like the item",
      "return_comment": "N/A",
      "outcome": "default",

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.

Field	Description
exchange_id	Loop exchange ID
product_id	Shopify product ID
variant_id	Shopify variant ID
exchange_order_name	New Shopify exchange order name
exchange_order_id	New Shopify exchange order id
sku	Shopify variant SKU
title	Shopify product title
price	Price of exchange item before discounts and tax
discount	Discount on exchange item
tax	Tax on exchange item
total	Price of exchange item after discounts and tax

carrier

refund

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

Field	Description
refunds	The breakdown of refunds across payment gateways
gateway	The payment gateway in which a refund was processed
amount	The 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.

Field	Description
provider	The provider of the return method (e.g. happy-returns)
return_method_type	pick-up or drop-off
address	If the return method is a drop-off, this is the destination where it can be dropped off at
state	The state of the return method at the current time, similar to label status (in_transit, new, etc)
rma_id	The ID of the return record in the related system
qr_code_url	If the return method has a QR code, this is the link, otherwise null
scheduled_at	If this return method needs to be scheduled for pick up or drop off otherwise null
scannable_id	The identifier that can be scanned at the warehouse to connect to the return data

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",
  "provider_order_number": "1234",
  "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",
  "package_reference": "28735625627856237856287",
  "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",
    "scannable_id": null,
    "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",
  "type": "standard"
}