Return

Return Event Properties

topic

string

A webhook configured with the return topic will always have the value return

trigger

enum<string>

Event that triggered the webhook.

shop_id

integer

The Loop ID of the shop that created the webhook

integer

Unique Loop return ID

state

enum<string>

Loop return states (state of the return)

Options: open, cancelled, closed, expired, needs review

created_at

string

Date and time (ISO 8601 format) when the return was created in Loop

edited_at

string | null

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

Total cost of the return

order_id

integer

Loop order ID

order_name

string

Shopify order name

provider_order_id

integer

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

object

Details of the Shopify customer

address

object

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

upsell

string

Additional amount paid by customer when exchange credit total is greater than return credit total

is_gift_return

boolean

true if the return is a gift return, false otherwise

refunds

array<object>

The breakdown of refunds across payment gateways; see refunds

labels

array<object>

Details on each label associated with the return; see labels

line_items

array<object>

Details on items being sent to Loop as part of the return

exchanges

array<object

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

enum<string>

Status of the shipment according to EasyPost

Options: pre_transit, in_transit, out_for_delivery, delivered, failure, error, N/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

object | null

Return method description

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

enum<string>

Return type

Options: standard, warranty

Example payload

{
    "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",
    "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": "me@myself.com",
    "customer_detail": {
      "email": "me@myself.com",
      "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"
  }

Webhook Reference

Webhook Payloads

Return Event Properties

Example payload

Webhook Reference

Webhook Payloads

​Return Event Properties

​Example payload

Return Event Properties

Example payload