Return

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",
  "provider_order_external_id": 12354567890,
  "order_number": "7078",
  "provider_order_number": 8078,
  "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

Webhook type

Example:

"return"

trigger

string

Event that triggered the webhook (created, updated, closed)

Example:

"return.created"

shop_id

integer

The ID of the shop that created the webhook

Example:

12345

string

Loop return ID

Example:

"1673"

state

string

Loop return states (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 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.

Example:

"open"

created_at

string

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

Example:

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

Example:

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

total

string

The total cost of the return

Example:

"48.81"

order_id

string

Loop order ID

Example:

2871

order_name

string

Shopify order name

Example:

"#47727779"

provider_order_id

string

Shopify order ID

Example:

"58997314"

provider_order_external_id

string

External Shopify order ID

Example:

12354567890

order_number

string

Shopify order number

Example:

"7078"

provider_order_number

string

Shopify number

Example:

8078

customer

string

Email address of Shopify customer

Example:

"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

Currency of the store at the time of the order

Example:

"USD"

return_product_total

string

Value of returned line items excluding order discounts and taxes

Example:

"50.00"

return_discount_total

string

Sum of all discounts on returned items

Example:

"5.00"

return_tax_total

string

Value of order taxes on returned line items

Example:

"2.50"

return_total

string

Return total after taxes and discounts

Example:

"47.50"

return_credit_total

string

Value of total return credit (product + honored discount + tax)

Example:

"47.50"

status_page_url

string

Link to the return status page

Example:

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

exchange_product_total

string

Value of exchange items before discounts and taxes

Example:

"60.00"

exchange_discount_total

string

Discount on exchange items

Example:

"10.00"

exchange_tax_total

string

Tax on exchange items

Example:

"3.00"

exchange_total

string

Exchange total after taxes and discounts

Example:

"53.00"

exchange_credit_total

string

Total exchange items value after discounts and taxes which is used by the customer

Example:

"53.00"

gift_card

string

Amount of store credit to be issued to the customer on a gift card

Example:

"25.00"

handling_fee

string

Handling fee amount set in Loop admin

Example:

"5.00"

refund

string

The total refund value of the return

Example:

"20.00"

upsell

string

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

Example:

true

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.

line_items.line_item_id

string

Loop line item ID

Example:

123456789

line_items.provider_line_item_id

string

Shopify order line item ID

Example:

12149029339269

line_items.product_id

string

Shopify product ID

Example:

5107813056645

line_items.variant_id

string

Shopify variant ID

Example:

34404555554949

line_items.sku

string | null

Shopify variant SKU

Example:

"new-sku"

line_items.barcode

string | null

Shopify barcode

Example:

"barcode1234"

line_items.title

string

Shopify product title

Example:

"Retro Laser - Big"

line_items.weight_in_grams

integer | null

Weight of the line item in grams

Example:

226

line_items.price

string

Price paid by customer before discounts and tax

Example:

35.38

line_items.discount

string

Discount on item

Example:

0

line_items.tax

string

Tax on item

Example:

"2.65"

line_items.refund

string

Amount refunded to customer for this item

Example:

"38.03"

line_items.returned_at

string

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

Example:

"2024-01-11T22:47:02+00:00"

line_items.exchange_variant

string | null

Shopify variant ID for replacement product, if exchange

Example:

23141001

line_items.return_reason

string

Reason for return as selected by the customer in Loop

Example:

"I didn't like how the item looked"

line_items.provider_restock_location_id

integer | null

Shopify location ID for line item restocking

Example:

6543

line_items.is_in_store_return

boolean

True if the return is made in-store through the Loop Point of Sale application; false if made online through the returns portal

Example:

false

line_items.provider_location_id

integer

Shopify location ID for the line item

Example:

1456

line_items.parent_return_reason

string | null

Parent reason for return as selected by the customer in Loop

Example:

"I didn't like the item"

line_items.return_comment

string

Return reason comment

Example:

"N/A"

line_items.outcome

string

Return outcomes

Example:

"default"

line_items.taxes

any[]

Tax information for the line item

Example:

[]

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

Example:

"SHIP-001"

carrier

string

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

Example:

"USPS"

tracking_number

string

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

Example:

"28735625627856237856287"

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.

Example:

"pre_transit"

label_updated_at

string

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

N/A:label not yet updated

Example:

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

destination_id

string

Loop destination ID

Example:

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

return_method.provider

string

The provider of the return method (e.g. happy-returns)

Example:

"happy-returns"

return_method.return_method_type

string

pick-up or drop-off

Example:

"drop-off"

return_method.scannable_id

string

The identifier that can be scanned at the warehouse to connect to the return data

Example:

23124100124923

return_method.address

any[]

If the return method is a drop-off, this is the destination where it can be dropped off at

Example:

{
  "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
}

return_method.state

string

The state of the return method at the current time, similar to label status (in_transit, new, etc)

Example:

"new"

return_method.rma_id

string

The ID of the return record in the related system

Example:

"HRABC123"

return_method.qr_code_url

string

If the return method has a QR code, this is the link, otherwise null

Example:

"https://partner.happyreturns.com/barcode/qr?code=HRABC123"

return_method.scheduled_at

string | null

If this return method needs to be scheduled for pick up or drop off, otherwise null

Example:

null

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

Return type

Example:

"standard"

Response

200

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

Validate webhooks from Loop Label

{
  "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",
  "provider_order_external_id": 12354567890,
  "order_number": "7078",
  "provider_order_number": 8078,
  "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"
}

Webhook Reference

Webhook Payloads

Body

Response