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	Type	Description
topic	string	Webhook type (return)
trigger	string	Event that triggered the webhook (created, updated, closed)
shop_id	integer	The ID of the shop that created the webhook
id	string	Loop return ID
state	string	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 28 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	string	Date and time (ISO 8601 format) when the return was created in Loop
edited_at	string	Date and time (ISO 8601 format) when the return was last edited inside Loop, and null when the return has not been edited.
total	string	The total cost of the return
order_id	integer	Loop order ID
order_name	string	Shopify order name
provider_order_id	string	Shopify order ID
provider_order_external_id	string	External Shopify order ID
order_number	string	Shopify order number
provider_order_number	string	Shopify number
customer	string	Email address of Shopify customer
customer_detail	array of strings	Email, first name, middle name, and last name of Shopify customer
address	array of strings	The original customer's shipping address or the address that the customer inputs in the case of a gift return
currency	string	Currency of the store at the time of the order
return_product_total	string	Value of returned line items excluding order discounts and taxes
return_discount_total	string	Sum of all discounts on returned items
return_tax_total	string	Value of order taxes on returned line items
return_total	string	Return total after taxes and discounts
return_credit_total	string	Value of total return credit (product + honored discount + tax)
status_page_url	string	Link to the return status page
exchange_product_total	string	Value of exchange items before discounts and taxes
exchange_discount_total	string	Discount on exchange items
exchange_tax_total	string	Tax on exchange items
exchange_total	string	Exchange total after taxes and discounts
exchange_credit_total	string	Total exchange items value after discounts and taxes which is used by the customer
gift_card	string	Amount of store credit to be issued to the customer on a gift card
handling_fee	string	Handling fee amount set in Loop admin
refund	string	The total refund value of the return
upsell	string	Additional amount paid by customer when exchange credit total is greater than return credit total
is_gift_return	boolean	Whether or not the return is a gift return
refunds	array	The breakdown of refunds across payment gateways; see refunds
labels	array	Details on each label associated with the return; see labels
line_items	array	Details on items being sent to Loop as part of the return; see line_items
exchanges	array	Exchange information for the return; see exchanges
shipment_id	string	The Happy Returns shipment ID
carrier	string	The name of the carrier or N/A if the carrier has not yet been assigned
tracking_number	string	The tracking number provided by the carrier or N/A if the tracking number has not yet been assigned
label_status	string	Status of the shipment according to EasyPost: - no shipment status - pre_transit - in_transit - out_for_delivery - delivered - error - failureN/A if no label status has been provided yet.
label_updated_at	string	Date and time (ISO 8601 format) when the last status update occurred. N/A: label not yet updated
destination_id	string	Loop destination ID
return_method	array	Return method details; see return_method
package_reference	string	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.
type	string	Return type (e.g. standard, warranty)

refunds

The amount of credit to be issued to the customer as a refund.

Field	Type	Description
refunds	array
gateway	string	The payment gateway in which a refund was processed
amount	string	The refund amount issued to a gateway
currency	string	The currency used in the refund
provider_refund_id	string	The refund id used in the provider

labels

Details for each label associated with the return are included in an array.

Field	Type	Description
status	string	The status of the return shipping label.
updated_at	string	The date and time at which the label was last updated, using the ISO 8601 date format.
url	string	The link to the label details.
rate	string	The shipping rate paid for the label.
carrier	string	The carrier associated with the label.
tracking_number	string	The tracking number associated with the label.
line_items	array of integers	A list of line item IDs associated with the label.

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	integer \|\| 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
provider_location_id	integer	Shopify location ID for the line item
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")
taxes	array	Tax information for the line item

"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",
      "taxes": []
    }
],

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	Type	Description
exchange_id	string	Loop exchange ID
product_id	string	Shopify product ID
variant_id	string	Shopify variant ID
exchange_order_name	string	New Shopify exchange order name
exchange_order_id	integer	New Shopify exchange order ID
sku	string	Shopify variant SKU
type	string	The exchange type
title	string	Shopify product title
price	string	Price of exchange item before discounts and tax
discount	string	Discount on exchange item
tax	string	Tax on exchange item
total	string	Price of exchange item after discounts and tax
out_of_stock	boolean	Whether the item is out of stock
out_of_stock_resolution	string	The resolution if the item is out of stock

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

Response

{
    "topic": "return",
    "trigger": "return.updated",
    "shop_id": 3439,
    "id": "1673",
    "state": "closed",
    "created_at": "2024-11-20T19:31:40+00:00",
    "edited_at": "2024-11-30T18:15:12+00:00", // can also be null
    "total": "48.81",
    "order_id": "2871",
    "order_name": "#47727779",
    "provider_order_id": "58997314",
    "provider_order_external_id": "12354567890",
    "order_number": "7078",
    "provider_order_number": 8078,
    "customer": "[email protected]",
    "customer_detail": {
      "email": "[email protected]",
      "first_name": "Jean",
      "middle_name": "Francois",
      "last_name": "Launier"
    },
    "address": {
      "name": "Dr. Nya D'Amore MD",
      "company": null,
      "address1": "310 Bogisich Ranch Apt. 357",
      "address2": null,
      "city": "Lake Aubreyport",
      "state": "VT",
      "zip": "40772-0948",
      "country": "United States",
      "country_code": "US",
      "phone": "+1-458-534-1685"
    },
    "currency": "USD",
    "return_product_total": "5.87",
    "return_discount_total": "0.00",
    "return_tax_total": "0.00",
    "return_total": "5.87",
    "return_credit_total": "5.87",
    "status_page_url": "https://example.loopreturns.com/#/return/b3e4764e-7adf-4b8c-802a-553305b6db49",
    "exchange_product_total": "99.11",
    "exchange_discount_total": "0.00",
    "exchange_tax_total": "0.00",
    "exchange_total": "99.11",
    "exchange_credit_total": "99.11",
    "gift_card": "0.00",
    "handling_fee": "0.00",
    "refund": "0.00",
    "upsell": "0.00",
    "is_gift_return": false,
    "refunds": [
        {
          "gateway": "your gateway",
          "amount": "0.00"
        }
      ],
    "labels": [
        {
          "status": "new",
          "updated_at": "2024-02-02 21:19:04",
          "url": "https://partner.loopreturns.com/label/12345456",
          "rate": "1093",
          "carrier": "USPS",
          "tracking_number": "123456789101112",
          "line_items": [
            987654321
          ]
        }
      ],
    "line_items": [
      {
        "line_item_id": "2351",
        "provider_line_item_id": "45604886",
        "product_id": "67756501",
        "variant_id": "69122513",
        "sku": "vJGJ\"YIj",
        "barcode": "",
        "title": "Dr. Jonatan Batz - Prof. Arlie Hayes",
        "weight_in_grams": 0,
        "price": "5.87",
        "discount": "0.00",
        "tax": "0.00",
        "refund": "0.00",
        "returned_at": null,
        "exchange_variant": "",
        "return_reason": "N/A",
        "provider_restock_location_id": 1,
        "is_in_store_return": null,
        "provider_location_id": 67785432,
        "parent_return_reason": null,
        "return_comment": "N/A",
        "outcome": "default",
        "taxes": []
      }
    ],
    "exchanges": [
      {
        "exchange_id": "1417",
        "product_id": "69713389",
        "variant_id": "9502968",
        "exchange_order_name": "#EXC-5551-1",
        "exchange_order_id": "",
        "sku": "Ieey?9j@",
        "type": "exchange",
        "title": "T-Shirt - Large",
        "price": "99.11",
        "discount": "0.00",
        "tax": "0.00",
        "total": "99.11",
        "out_of_stock": true,
        "out_of_stock_resolution": "credited" // credited | refunded | null
      }
    ],
    "shipment_id": "N/A",
    "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"
    "destination_id": 2232,
    "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
    },
    "package_reference": null,
    "type": "standard"
  }