Return

{
  "topic": "<string>",
  "trigger": "<string>",
  "shop_id": 123,
  "id": "<string>",
  "state": "<string>",
  "created_at": "<string>",
  "edited_at": "<string>",
  "total": "<string>",
  "order_id": "<string>",
  "order_name": "<string>",
  "provider_order_id": "<string>",
  "order_number": "<string>",
  "provider_order_number": 123,
  "provider_order_external_id": "<string>",
  "provider_order_sales_channel": "<string>",
  "customer": "<string>",
  "customer_detail": {
    "email": "<string>",
    "first_name": "<string>",
    "last_name": "<string>"
  },
  "address": {
    "name": "<string>",
    "company": "<string>",
    "address1": "<string>",
    "address2": "<string>",
    "city": "<string>",
    "state": "<string>",
    "zip": "<string>",
    "country": "<string>",
    "country_code": "<string>",
    "phone": "<string>"
  },
  "currency": "<string>",
  "return_product_total": "<string>",
  "return_discount_total": "<string>",
  "return_tax_total": "<string>",
  "return_total": "<string>",
  "return_credit_total": "<string>",
  "status_page_url": "<string>",
  "exchange_product_total": "<string>",
  "exchange_discount_total": "<string>",
  "exchange_tax_total": "<string>",
  "exchange_total": "<string>",
  "exchange_credit_total": "<string>",
  "gift_card": "<string>",
  "handling_fee": "<string>",
  "refund": "<string>",
  "upsell": "<string>",
  "is_gift_return": true,
  "refunds": [
    {
      "gateway": "<string>",
      "amount": "<string>",
      "currency": "<string>",
      "provider_refund_id": "<string>"
    }
  ],
  "labels": [
    {
      "status": "<string>",
      "updated_at": "<string>",
      "url": "<string>",
      "rate": 123,
      "carrier": "<string>",
      "tracking_number": "<string>",
      "line_items": [
        123
      ]
    }
  ],
  "line_items": [
    {
      "line_item_id": "<string>",
      "provider_line_item_id": "<string>",
      "product_id": "<string>",
      "variant_id": "<string>",
      "sku": "<string>",
      "barcode": "<string>",
      "title": "<string>",
      "weight_in_grams": 123,
      "price": "<string>",
      "discount": "<string>",
      "tax": "<string>",
      "refund": "<string>",
      "returned_at": "<string>",
      "exchange_variant": "<string>",
      "return_reason": "<string>",
      "provider_restock_location_id": 123,
      "is_in_store_return": true,
      "provider_location_id": 123,
      "parent_return_reason": "<string>",
      "return_comment": "<string>",
      "outcome": "<string>",
      "taxes": "<array>"
    }
  ],
  "exchanges": [
    {
      "exchange_id": "<string>",
      "product_id": "<string>",
      "variant_id": "<string>",
      "exchange_order_name": "<string>",
      "exchange_order_id": "<string>",
      "sku": "<string>",
      "type": "<string>",
      "title": "<string>",
      "price": "<string>",
      "discount": "<string>",
      "tax": "<string>",
      "total": "<string>",
      "out_of_stock": true,
      "out_of_stock_resolution": "<string>"
    }
  ],
  "shipment_id": "<string>",
  "carrier": "<string>",
  "tracking_number": "<string>",
  "label_status": "<string>",
  "label_updated_at": "<string>",
  "destination_id": "<string>",
  "return_method": {
    "provider": "<string>",
    "return_method_type": "<string>",
    "scannable_id": "<string>",
    "address": "<array>",
    "state": "<string>",
    "rma_id": "<string>",
    "qr_code_url": "<string>",
    "scheduled_at": "<string>"
  },
  "package_reference": "<string>",
  "type": "<string>"
}

WEBHOOK

Return

{
  "topic": "<string>",
  "trigger": "<string>",
  "shop_id": 123,
  "id": "<string>",
  "state": "<string>",
  "created_at": "<string>",
  "edited_at": "<string>",
  "total": "<string>",
  "order_id": "<string>",
  "order_name": "<string>",
  "provider_order_id": "<string>",
  "order_number": "<string>",
  "provider_order_number": 123,
  "provider_order_external_id": "<string>",
  "provider_order_sales_channel": "<string>",
  "customer": "<string>",
  "customer_detail": {
    "email": "<string>",
    "first_name": "<string>",
    "last_name": "<string>"
  },
  "address": {
    "name": "<string>",
    "company": "<string>",
    "address1": "<string>",
    "address2": "<string>",
    "city": "<string>",
    "state": "<string>",
    "zip": "<string>",
    "country": "<string>",
    "country_code": "<string>",
    "phone": "<string>"
  },
  "currency": "<string>",
  "return_product_total": "<string>",
  "return_discount_total": "<string>",
  "return_tax_total": "<string>",
  "return_total": "<string>",
  "return_credit_total": "<string>",
  "status_page_url": "<string>",
  "exchange_product_total": "<string>",
  "exchange_discount_total": "<string>",
  "exchange_tax_total": "<string>",
  "exchange_total": "<string>",
  "exchange_credit_total": "<string>",
  "gift_card": "<string>",
  "handling_fee": "<string>",
  "refund": "<string>",
  "upsell": "<string>",
  "is_gift_return": true,
  "refunds": [
    {
      "gateway": "<string>",
      "amount": "<string>",
      "currency": "<string>",
      "provider_refund_id": "<string>"
    }
  ],
  "labels": [
    {
      "status": "<string>",
      "updated_at": "<string>",
      "url": "<string>",
      "rate": 123,
      "carrier": "<string>",
      "tracking_number": "<string>",
      "line_items": [
        123
      ]
    }
  ],
  "line_items": [
    {
      "line_item_id": "<string>",
      "provider_line_item_id": "<string>",
      "product_id": "<string>",
      "variant_id": "<string>",
      "sku": "<string>",
      "barcode": "<string>",
      "title": "<string>",
      "weight_in_grams": 123,
      "price": "<string>",
      "discount": "<string>",
      "tax": "<string>",
      "refund": "<string>",
      "returned_at": "<string>",
      "exchange_variant": "<string>",
      "return_reason": "<string>",
      "provider_restock_location_id": 123,
      "is_in_store_return": true,
      "provider_location_id": 123,
      "parent_return_reason": "<string>",
      "return_comment": "<string>",
      "outcome": "<string>",
      "taxes": "<array>"
    }
  ],
  "exchanges": [
    {
      "exchange_id": "<string>",
      "product_id": "<string>",
      "variant_id": "<string>",
      "exchange_order_name": "<string>",
      "exchange_order_id": "<string>",
      "sku": "<string>",
      "type": "<string>",
      "title": "<string>",
      "price": "<string>",
      "discount": "<string>",
      "tax": "<string>",
      "total": "<string>",
      "out_of_stock": true,
      "out_of_stock_resolution": "<string>"
    }
  ],
  "shipment_id": "<string>",
  "carrier": "<string>",
  "tracking_number": "<string>",
  "label_status": "<string>",
  "label_updated_at": "<string>",
  "destination_id": "<string>",
  "return_method": {
    "provider": "<string>",
    "return_method_type": "<string>",
    "scannable_id": "<string>",
    "address": "<array>",
    "state": "<string>",
    "rma_id": "<string>",
    "qr_code_url": "<string>",
    "scheduled_at": "<string>"
  },
  "package_reference": "<string>",
  "type": "<string>"
}

Body

application/json

topic

string

The webhook type.

Example:

"return"

trigger

string

The event that triggered the webhook.

Examples:

"return.created"

"return.updated"

"return.closed"

shop_id

integer

The ID of the shop that created the webhook.

Example:

12345

string

The Loop return ID.

Example:

"1673"

state

string

The state of the return.

Possible values:

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 the 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.
review: Refers to a return that has been flagged for review.

Examples:

"open"

"cancelled"

"closed"

"review"

created_at

string

The date and time (ISO 8601 format) when the return was created in Loop.

Example:

"2019-04-01T12:00:00+00:00"

edited_at

string

Date and time (ISO 8601 format) when the return was last edited inside Loop. null when the return has not been edited.

Examples:

"2019-04-01T12:00:00+00:00"

null

total

string

The total cost of the return.

Example:

"48.81"

order_id

string

The Loop order ID.

Example:

"2871"

order_name

string

The Shopify order name.

Example:

"#47727779"

provider_order_id

string

The Shopify order ID.

Example:

"58997314"

order_number

string

The Shopify order number.

Example:

"7078"

provider_order_number

The Shopify number.

Example:

8078

provider_order_external_id

string

The external Shopify order ID.

Example:

12354567890

provider_order_sales_channel

string

The name of the sales channel that the order was created in.

Example:

"Example Online Store"

customer

string

The email address of the Shopify customer.

Example:

"[email protected]"

customer_detail

object

The Shopify customer's email, first name, and last name.

Show child attributes

address

object

The original customer's shipping address or the address that the customer inputs in the case of a gift return.

Show child attributes

currency

string

The currency of the store at the time of the order.

Example:

"USD"

return_product_total

string

The value of returned line items, excluding order discounts and taxes.

Example:

"50.00"

return_discount_total

string

The sum of all discounts on returned items.

Example:

"5.00"

return_tax_total

string

The value of order taxes on returned line items.

Example:

"2.50"

return_total

string

The return total after taxes and discounts.

Example:

"47.50"

return_credit_total

string

The value of total return credit (product + honored discount + tax).

Example:

"47.50"

status_page_url

string

The link to the return status page.

Example:

"https://example.loopreturns.com/#/return/b3e4764e-7adf-4b8c-802a-553305b6db49"

exchange_product_total

string

The value of exchange items before discounts and taxes.

Example:

"60.00"

exchange_discount_total

string

The discount on exchange items.

Example:

"10.00"

exchange_tax_total

string

The tax on exchange items.

Example:

"3.00"

exchange_total

string

The exchange total after taxes and discounts.

Example:

"53.00"

exchange_credit_total

string

The total exchange items value after discounts and taxes, which is used by the customer.

Example:

"53.00"

gift_card

string

The amount of store credit to be issued to the customer on a gift card.

Example:

"25.00"

handling_fee

string

The handling fee amount set in Loop admin.

Example:

"5.00"

refund

string

The total refund value of the return.

Example:

"20.00"

upsell

string

The additional amount paid by customer when exchange credit total is greater than return credit total.

Example:

"10.00"

is_gift_return

boolean

Whether or not the return is a gift return.

Examples:

true

false

refunds

object[]

The breakdown of refunds across payment gateways.

Show child attributes

labels

object[]

Details on each label associated with the return.

Show child attributes

line_items

object[]

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

Show child attributes

exchanges

object[]

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

Show child attributes

shipment_id

string

The Happy Returns shipment ID.

Example:

"SHIP-001"

carrier

string

The name of the carrier or N/A if the carrier has not yet been assigned.

Examples:

"USPS"

"N/A"

tracking_number

string

The tracking number provided by the carrier or N/A if the carrier has not yet been assigned.

Examples:

"28735625627856237856287"

"N/A"

label_status

string

Status of the shipment according to EasyPost:

no shipment status
pre_transit
in_transit
out_for_delivery
delivered
error
failure

N/A if no label status has been provided yet.

Examples:

"pre_transit"

"delivered"

label_updated_at

string

The date and time (ISO 8601 format) when the last status update occurred.

N/A: label not yet updated.

Examples:

"2025-11-07T01:47:42+00:00"

"N/A"

destination_id

string

The Loop destination ID.

Example:

"2232"

return_method

object

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.

Show child attributes

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.

Example:

"PKG-12345"

type

string

The return type.

Examples:

"standard"

"warranty"

Response

200

Return a 200 status to indicate that the data was received successfully

Validate webhooks from Loop Label

⌘I

Webhook Reference

Webhook Payloads

Body

Response