Return

{
  "topic": "return",
  "trigger": "return.created",
  "shop_id": 12345,
  "id": "1673",
  "state": "open",
  "refund_before_inspection": false,
  "created_at": "2019-04-01T12:00:00+00:00",
  "edited_at": "2019-04-01T12:00:00+00:00",
  "total": "48.81",
  "order_id": "2871",
  "order_name": "#47727779",
  "taxes_included": false,
  "provider_order_id": "58997314",
  "order_number": "7078",
  "provider_order_number": 8078,
  "provider_order_external_id": "12354567890",
  "provider_order_sales_channel": "Example Online Store",
  "customer": "me@myself.com",
  "customer_detail": {
    "email": "jf@example.com",
    "first_name": "Jean",
    "last_name": "Launier"
  },
  "address": {
    "name": "J.F. Launier",
    "company": "Universal Exports",
    "address1": "1234 Example Street",
    "address2": "Unit 19",
    "city": "Townsville",
    "state": "Louisiana",
    "zip": "90210",
    "country": "United States",
    "country_code": "US",
    "phone": "+1-678-999-8212"
  },
  "currency": "USD",
  "return_product_total": "50.00",
  "return_discount_total": "5.00",
  "return_tax_total": "2.50",
  "return_total": "47.50",
  "return_credit_total": "47.50",
  "status_page_url": "https://example.loopreturns.com/#/return/b3e4764e-7adf-4b8c-802a-553305b6db49",
  "exchange_product_total": "60.00",
  "exchange_discount_total": "10.00",
  "exchange_tax_total": "3.00",
  "exchange_total": "53.00",
  "exchange_credit_total": "53.00",
  "gift_card": "25.00",
  "handling_fee": "5.00",
  "refund": "20.00",
  "upsell": "10.00",
  "is_gift_return": true,
  "refunds": [
    {
      "gateway": "Stripe",
      "amount": "20.00",
      "currency": "USD",
      "provider_refund_id": "987654321",
      "provider": "stripe"
    }
  ],
  "labels": [
    {
      "status": "new",
      "updated_at": "2024-02-02T21:19:04.000Z",
      "url": "https://partner.loopreturns.com/label/12345456",
      "rate": 1093,
      "carrier": "USPS",
      "tracking_number": "123456789101112",
      "line_items": [
        987654321
      ]
    }
  ],
  "line_items": [
    {
      "line_item_id": "123456789",
      "provider_line_item_id": "12149029339269",
      "product_id": "5107813056645",
      "variant_id": "34404555554949",
      "sku": "new-sku",
      "barcode": "barcode1234",
      "title": "Retro Laser - Big",
      "weight_in_grams": 226,
      "price": "35.38",
      "discount": "0.00",
      "tax": "2.65",
      "refund": "38.03",
      "returned_at": "2024-01-11T22:47:02+00:00",
      "exchange_variant": "23141001",
      "return_reason": "I didn't like how the item looked",
      "provider_restock_location_id": 6543,
      "is_in_store_return": false,
      "provider_location_id": 1456,
      "parent_return_reason": "I didn't like the item",
      "return_comment": "N/A",
      "outcome": "default",
      "taxes": [
        {
          "title": "State Tax",
          "amount": 265,
          "rate": 0.0625
        }
      ],
      "fulfillment_sku": "FULFIL-SKU-123"
    }
  ],
  "exchanges": [
    {
      "exchange_id": "1417",
      "product_id": "69713389",
      "variant_id": "9502968",
      "exchange_order_name": "#EXC-5551-1",
      "exchange_order_id": "459765194",
      "sku": "example-sku-123",
      "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"
    }
  ],
  "shipment_id": "SHIP-001",
  "carrier": "USPS",
  "tracking_number": "28735625627856237856287",
  "label_status": "pre_transit",
  "label_updated_at": "2025-11-07T01:47:42+00:00",
  "destination_id": 2232,
  "destination_provider_location_id": 987654321,
  "return_method": {
    "provider": "happy-returns",
    "return_method_type": "drop-off",
    "scannable_id": "23124100124923",
    "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",
    "updated_at": "2024-02-02 21:19:04",
    "scheduled_at": null
  },
  "package_reference": "PKG-12345",
  "type": "standard"
}

WEBHOOK

Return

{
  "topic": "return",
  "trigger": "return.created",
  "shop_id": 12345,
  "id": "1673",
  "state": "open",
  "refund_before_inspection": false,
  "created_at": "2019-04-01T12:00:00+00:00",
  "edited_at": "2019-04-01T12:00:00+00:00",
  "total": "48.81",
  "order_id": "2871",
  "order_name": "#47727779",
  "taxes_included": false,
  "provider_order_id": "58997314",
  "order_number": "7078",
  "provider_order_number": 8078,
  "provider_order_external_id": "12354567890",
  "provider_order_sales_channel": "Example Online Store",
  "customer": "me@myself.com",
  "customer_detail": {
    "email": "jf@example.com",
    "first_name": "Jean",
    "last_name": "Launier"
  },
  "address": {
    "name": "J.F. Launier",
    "company": "Universal Exports",
    "address1": "1234 Example Street",
    "address2": "Unit 19",
    "city": "Townsville",
    "state": "Louisiana",
    "zip": "90210",
    "country": "United States",
    "country_code": "US",
    "phone": "+1-678-999-8212"
  },
  "currency": "USD",
  "return_product_total": "50.00",
  "return_discount_total": "5.00",
  "return_tax_total": "2.50",
  "return_total": "47.50",
  "return_credit_total": "47.50",
  "status_page_url": "https://example.loopreturns.com/#/return/b3e4764e-7adf-4b8c-802a-553305b6db49",
  "exchange_product_total": "60.00",
  "exchange_discount_total": "10.00",
  "exchange_tax_total": "3.00",
  "exchange_total": "53.00",
  "exchange_credit_total": "53.00",
  "gift_card": "25.00",
  "handling_fee": "5.00",
  "refund": "20.00",
  "upsell": "10.00",
  "is_gift_return": true,
  "refunds": [
    {
      "gateway": "Stripe",
      "amount": "20.00",
      "currency": "USD",
      "provider_refund_id": "987654321",
      "provider": "stripe"
    }
  ],
  "labels": [
    {
      "status": "new",
      "updated_at": "2024-02-02T21:19:04.000Z",
      "url": "https://partner.loopreturns.com/label/12345456",
      "rate": 1093,
      "carrier": "USPS",
      "tracking_number": "123456789101112",
      "line_items": [
        987654321
      ]
    }
  ],
  "line_items": [
    {
      "line_item_id": "123456789",
      "provider_line_item_id": "12149029339269",
      "product_id": "5107813056645",
      "variant_id": "34404555554949",
      "sku": "new-sku",
      "barcode": "barcode1234",
      "title": "Retro Laser - Big",
      "weight_in_grams": 226,
      "price": "35.38",
      "discount": "0.00",
      "tax": "2.65",
      "refund": "38.03",
      "returned_at": "2024-01-11T22:47:02+00:00",
      "exchange_variant": "23141001",
      "return_reason": "I didn't like how the item looked",
      "provider_restock_location_id": 6543,
      "is_in_store_return": false,
      "provider_location_id": 1456,
      "parent_return_reason": "I didn't like the item",
      "return_comment": "N/A",
      "outcome": "default",
      "taxes": [
        {
          "title": "State Tax",
          "amount": 265,
          "rate": 0.0625
        }
      ],
      "fulfillment_sku": "FULFIL-SKU-123"
    }
  ],
  "exchanges": [
    {
      "exchange_id": "1417",
      "product_id": "69713389",
      "variant_id": "9502968",
      "exchange_order_name": "#EXC-5551-1",
      "exchange_order_id": "459765194",
      "sku": "example-sku-123",
      "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"
    }
  ],
  "shipment_id": "SHIP-001",
  "carrier": "USPS",
  "tracking_number": "28735625627856237856287",
  "label_status": "pre_transit",
  "label_updated_at": "2025-11-07T01:47:42+00:00",
  "destination_id": 2232,
  "destination_provider_location_id": 987654321,
  "return_method": {
    "provider": "happy-returns",
    "return_method_type": "drop-off",
    "scannable_id": "23124100124923",
    "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",
    "updated_at": "2024-02-02 21:19:04",
    "scheduled_at": null
  },
  "package_reference": "PKG-12345",
  "type": "standard"
}

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 the return belongs to.

Example:

12345

string

The Loop return ID.

Example:

"1673"

state

enum<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.
expired: The return did not complete before the shop return window ended. A return.updated webhook fires for this state change.

Available options:

open,

cancelled,

closed,

review,

expired

Examples:

"open"

"cancelled"

"closed"

"review"

"expired"

refund_before_inspection

boolean

Whether the return is configured to refund before the items are inspected.

Example:

false

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 | null

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 order name from the commerce provider (e.g. Shopify).

Example:

"#47727779"

taxes_included

boolean

Whether taxes are included in the order's prices. Defaults to false.

Example:

false

provider_order_id

string

The order ID from the commerce provider (e.g. Shopify).

Example:

"58997314"

order_number

string

The order number from the commerce provider (e.g. Shopify).

Example:

"7078"

provider_order_number

The order number from the commerce provider (e.g. Shopify).

Example:

8078

provider_order_external_id

string | null

The external order ID from the commerce provider (e.g. Shopify). null when the order has no external identifier.

Examples:

"12354567890"

null

provider_order_sales_channel

string | null

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

Examples:

"Example Online Store"

null

customer

string

The email address of the customer.

Example:

"me@myself.com"

customer_detail

object

The 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

integer | null

The Loop destination ID. null when the return has no destination.

Examples:

2232

null

destination_provider_location_id

integer | null

The commerce platform's numeric location ID for the return shipping destination (the same destination as destination_id), when that destination has a linked Loop location. null when no location is linked or when the return has no destination. This is separate from line_items[].provider_location_id, which describes fulfillment/origin context per line item.

Examples:

987654321

null

return_method

object | null

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 | null

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

Webhook Reference

Webhook Payloads

Body

Response