WEBHOOK
Return
{
  "topic": "return",
  "trigger": "return.created",
  "shop_id": 12345,
  "id": "1673",
  "state": "open",
  "created_at": "2023-05-01T12:00:00Z",
  "edited_at": "2023-05-02T15:00:00Z",
  "total": "48.81",
  "order_id": 2871,
  "order_name": "#47727779",
  "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",
    "middle_name": "Francois",
    "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,
      "currency": "USD",
      "provider_refund_id": 987654321
    }
  ],
  "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,
      "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": []
    }
  ],
  "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": "2023-05-03T16:00:00Z",
  "destination_id": "2232",
  "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",
    "scheduled_at": null
  },
  "package_reference": "PKG-12345",
  "type": "standard"
}

Body

application/json
topic
string

The webhook type.

Examples:

"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.

Examples:

12345

id
string

The Loop return ID.

Examples:

"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.

Examples:

"2023-05-01T12:00:00Z"

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:

"2023-05-02T15:00:00Z"

null

total
string

The total cost of the return.

Examples:

"48.81"

order_id
string

The Loop order ID.

Examples:

2871

order_name
string

The Shopify order name.

Examples:

"#47727779"

provider_order_id
string

The Shopify order ID.

Examples:

"58997314"

order_number
string

The Shopify order number.

Examples:

"7078"

provider_order_number
string

The Shopify number.

Examples:

8078

provider_order_external_id
string

The external Shopify order ID.

Examples:

12354567890

provider_order_sales_channel
string

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

Examples:

"Example Online Store"

customer
string

The email address of the Shopify customer.

Examples:

"me@myself.com"

customer_detail
object

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

address
object

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

currency
string

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

Examples:

"USD"

return_product_total
string

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

Examples:

"50.00"

return_discount_total
string

The sum of all discounts on returned items.

Examples:

"5.00"

return_tax_total
string

The value of order taxes on returned line items.

Examples:

"2.50"

return_total
string

The return total after taxes and discounts.

Examples:

"47.50"

return_credit_total
string

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

Examples:

"47.50"

status_page_url
string

The link to the return status page.

Examples:

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

exchange_product_total
string

The value of exchange items before discounts and taxes.

Examples:

"60.00"

exchange_discount_total
string

The discount on exchange items.

Examples:

"10.00"

exchange_tax_total
string

The tax on exchange items.

Examples:

"3.00"

exchange_total
string

The exchange total after taxes and discounts.

Examples:

"53.00"

exchange_credit_total
string

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

Examples:

"53.00"

gift_card
string

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

Examples:

"25.00"

handling_fee
string

The handling fee amount set in Loop admin.

Examples:

"5.00"

refund
string

The total refund value of the return.

Examples:

"20.00"

upsell
string

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

Examples:

"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.

labels
object[]

Details on each label associated with the return.

line_items
object[]

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

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.

shipment_id
string

The Happy Returns shipment ID.

Examples:

"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:

"2023-05-03T16:00:00Z"

"N/A"

destination_id
string

The Loop destination ID.

Examples:

"2232"

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.

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.

Examples:

"PKG-12345"

type
string

The return type.

Examples:

"standard"

"warranty"

Response

200

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