Return Webhook

This notification is sent when the Return topic is requested. For those that subscribe to this topic for more than one trigger event, the "trigger" property is included in the payload for reference.

Response HeaderDescription
X-Loop-SignatureHashed Webhook Secret Key

The X-Loop-Signature is a base-64, HMAC hash of body payload using the Webhook Secret provided by Loop.

Note: Before attempting to create your hash of the POST request body, make sure slashes have been escaped & newlines have been removed from the JSON.

return

FieldDescription
topicWebhook type (return, label, restock)
triggerEvent that triggered the webhook (created, updated, requested)
return_idLoop return ID
stateLoop return status, possible values: open, closed, cancelled, expired. Closed means Loop has processed all the outcomes. Review means Loop wasn't able to process the outcomes automatically. Open means Loop has not fully processed all the outcomes.
created_atDate and time (ISO 8601 format) when the return was created in Loop
order_idLoop order ID
order_nameShopify order name
provider_order_idShopify order ID
order_numberShopify order number
customerEmail address of Shopify customer
currencyCurrency of the store at the time of the order
return_product_totalValue of returned line items excluding order discounts and taxes
return_discount_totalSum of all discounts on returned items
return_tax_totalValue of order taxes on returned line items
return_totalReturn total after taxes and discounts
return_credit_totalValue of total return credit (product + honored discount + tax)
exchange_product_totalValue of exchange items before discounts and taxes
exchange_discount_totalDiscount on exchange items
exchange_tax_totalTax on exchange items
exchange_totalExchange total after taxes and discounts
exchange_credit_totalTotal exchange items value after discounts and taxes which is used by the customer
gift_cardAmount of store credit to be issued to the customer on a gift card
handling_feeHandling fee amount set in Loop admin
upsellAdditional amount paid by customer when exchange credit total is greater than return credit total
carrierName of carrier or N/A: carrier not yet assigned
tracking_numberThe tracking number provided by the carrier or N/A: tracking number not yet assigned
label_statusStatus of the shipment according to EasyPost, N/A: no shipment status, pre_transit, in_transit, out_for_delivery, delivered, error, failure
label_updated_atDate and time ( ISO 8601 format) when the last status update occurred. N/A: label not yet updated

line_items

Line Item data reflects items being sent to Loop as part of the return

FieldDescription
line_item_idLoop line item ID
provider_line_item_idShopify order line item ID
product_idShopify product ID
variant_idShopify variant ID
skuShopify variant SKU
barcodeShopify barcode
titleShopify product title
pricePrice paid by customer before discounts and tax
discountDiscount on item
taxTax on item
refundAmount refunded to customer for this item
returned_atDate and time ( ISO 8601 format) when the return was created in Loop
exchange_variantShopify variant ID for replacement product (if exchange)
return_reasonReason for return as selected by the customer in Loop
parent_return_reasonParent reason for return as selected by the customer in Loop

exchanges

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

FieldDescription
exchange_idLoop exchange ID
product_idShopify product ID
variant_idShopify variant ID
exchange_order_nameNew Shopify exchange order name
exchange_order_idNew Shopify exchange order id
skuShopify variant SKU
titleShopify product title
pricePrice of exchange item before discounts and tax
discountDiscount on exchange item
taxTax on exchange item
totalPrice of exchange item after discounts and tax

carrier

refund

Amount of credit to be issued to the customer as a refund

FieldDescription
refundsThe breakdown of refunds across payment gateways
gatewayThe payment gateway in which a refund was processed
amountThe refund amount issued to a gateway

Response

{
    "topic": "return",
    "trigger": "return.created",
    "id": "12345",
    "shop_id": "9876",
    "state": "open",
    "created_at": "2019-04-01T12:00:00+00:00",
    "order_id": "1234567890",
    "order_name": "#1234",
    "provider_order_id": "1029384756",
    "order_number": "1234",
    "customer": "[email protected]",
    "currency": "USD",
    "return_product_total": "46.00",
    "return_discount_total": "0.00",
    "return_tax_total": "3.34",
    "return_total": "49.34",
    "return_credit_total": "49.34",
    "exchange_product_total": "84.00",
    "exchange_discount_total": "10.00",
    "exchange_tax_total": "5.37",
    "exchange_total": "79.37",
    "exchange_credit_total": "49.34",
    "gift_card": "0.00",
    "handling_fee": "0.00",
    "refund": "0.00",
    "refunds": [
        {
            "gateway": "your gateway",
            "amount": "0.00"
        }
    ],
    "upsell": "30.03",
    "address": {
      "name": "First Last",
      "company": "Company Name",
      "address1": "123 Road",
      "address2": "apt 1",
      "city": "Anywhere",
      "state": "California",
      "zip": "11111",
      "country": "United States",
      "country_code": "US",
      "phone": ""
    },
    "line_items": [
        {
            "line_item_id": "123456789",
            "provider_line_item_id": "3847568374653883",
            "product_id": "1624622563417",
            "variant_id": "14773475377241",
            "sku": "FD-RL-2",
            "barcode": "",
            "title": "Retro Laser - Big",
            "price": "46.00",
            "discount": "0.00",
            "tax": "3.34",
            "refund": "0.00",
            "returned_at": "2019-04-01T12:00:00+00:00",
            "exchange_variant": "",
            "return_reason": "Reason here",
            "parent_return_reason": "Parent reason here",
            "outcome": "Line item outcome('default', 'keep', 'donate', 'reject')"
            
        }
    ],
    "exchanges": [
        {
            "exchange_id": "54320",
            "product_id": "1624622563418",
            "variant_id": "14773475377242",
            "sku": "FD-NC-1",
            "exchange_order_name": "#1234",
            "exchange_order_id": "1234",
            "title": "Noisy Cricket - Small",
            "price": "46.00",
            "discount": "5.48",
            "tax": "2.94",
            "total": "43.46",
            "out_of_stock": true,  // true | false
            "out_of_stock_resolution": "credited" // credited | refunded | null
        },
        {
            "exchange_id": "54321",
            "product_id": "1624622563419",
            "variant_id": "14773475377243",
            "sku": "FD-RG-2",
            "exchange_order_name": "12345-1",
            "exchange_order_id": "13131313",
            "title": "Ray Gun - Medium",
            "price": "46.00",
            "discount": "5.48",
            "tax": "2.94",
            "total": "43.46",
            "out_of_stock": false,
            "out_of_stock_resolution": null          
        }
    ],
    "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": "2",
    "shipment_id": "fwe66545646"
}