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 |
currency | The currency used in the refund |
provider_refund_id | The refund id used in the provider |
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"
}