{"info":{"_postman_id":"ad453d01-9db9-4978-b230-1671823d2120","name":"ReturnsDirect by LiquiDonate (Beta)","description":"

ReturnsDirect by LiquiDonate Integration API

This collection covers the two sides of the ReturnsDirect by LiquiDonate integration for non-Shopify retailers:

1. Inbound — Retailer → ReturnsDirect by LiquiDonate

You push order data to us whenever an order is created or updated. We cache it so the customer-facing return portal can look up order details without calling your API at return time.

Endpoint: POST https://returns-sandbox.liquidonate.com/webhooks/external-order

2. Outbound — ReturnsDirect by LiquiDonate → Retailer

We POST return and refund status events to the webhook URL you register with us. You use these to update your own order management system.

Order Lookup — Zero-Config Option

If you also want ReturnsDirect by LiquiDonate to be able to fetch orders on-demand from your API (for backlog orders that predate your integration), your order search endpoint can return data in the canonical ReturnsDirect by LiquiDonate format — the same camelCase field names used in the Push Order request body.

When your API speaks this format, no custom mapping code is needed on our side. We will use the built-in default mapper automatically.

You only need a custom mapper if your API uses different field names or a different structure.

Authentication

Both directions use HMAC-SHA256 with a shared secret that Liquid provisions for your shop.

Signing a request (you → us)

signature = HMAC-SHA256(secret, rawRequestBody)\nX-Signature: <signature as lowercase hex>\nX-Shop-Domain: <your shop identifier>\n\n

Verifying a request (us → you)

We send the same headers. To verify:

expected = HMAC-SHA256(secret, rawRequestBody)\ntimingSafeEqual(expected, X-Signature header)\n\n

Environment Variables

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Variable	Description
`base_url`	ReturnsDirect by LiquiDonate base URL, e.g. `https://returns-sandbox.liquidonate.com`
`shop_domain`	Your shop identifier, e.g. `acme.com`
`webhook_secret`	Shared HMAC secret provisioned by Liquid
`retailer_webhook_url`	Your endpoint URL that receives outbound events

","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"ReturnsDirect by LiquiDonate Integration API","slug":"returnsdirect-by-liquidonate-integration-api"}],"owner":"28612413","collectionId":"ad453d01-9db9-4978-b230-1671823d2120","publishedId":"2sBXierZMP","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"publishDate":"2026-03-11T05:39:42.000Z"},"item":[{"name":"Inbound — Retailer → ReturnsDirect by LiquiDonate","item":[{"name":"Push Order","event":[{"listen":"prerequest","script":{"id":"f851bbff-cdad-406c-9490-d41cc346d607","exec":["// Auto-sign the request body with HMAC-SHA256.","// Requires the 'webhook_secret' collection variable to be set.","const secret = pm.variables.get('webhook_secret');","const body = pm.request.body.raw;","","if (!secret || secret === 'your_shared_secret_here') {"," console.warn('webhook_secret is not set — request will fail signature validation');","}","","const signature = CryptoJS.HmacSHA256(body, secret).toString(CryptoJS.enc.Hex);","pm.variables.set('X_Signature', signature);","console.log('X-Signature:', signature);"],"type":"text/javascript","packages":{},"requests":{}}},{"listen":"test","script":{"id":"5b692e20-2b34-48c2-8d50-d4d39b3e4d3d","exec":["pm.test('Status is 200', () => pm.response.to.have.status(200));","pm.test('Response has success:true', () => {"," const body = pm.response.json();"," pm.expect(body.success).to.be.true;"," pm.expect(body.id).to.be.a('number');","});"],"type":"text/javascript","packages":{},"requests":{}}}],"id":"47e52f49-d93c-433e-981d-73e6e17982c7","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"X-Shop-Domain","value":"acme.com","description":"

Your shop identifier

\n"},{"key":"X-Signature","value":"{{X_Signature}}","description":"

HMAC-SHA256 of the raw request body, set by the pre-request script

\n"}],"body":{"mode":"raw","raw":"{\n \"externalId\": \"order_99001\",\n \"orderNumber\": \"#1001\",\n \"confirmationNumber\": \"CONF-99001\",\n \"orderDate\": \"2026-03-01T10:00:00Z\",\n \"customerName\": \"Jane Smith\",\n \"customerEmail\": \"jane@example.com\",\n \"customerPhone\": \"+1-555-0100\",\n \"shippingAddress1\": \"123 Main St\",\n \"shippingAddress2\": \"Apt 4B\",\n \"shippingCity\": \"Austin\",\n \"shippingState\": \"TX\",\n \"shippingZip\": \"78701\",\n \"shippingCountry\": \"US\",\n \"shippingPhone\": \"+1-555-0100\",\n \"shippingLatitude\": 30.2672,\n \"shippingLongitude\": -97.7431,\n \"originalShippingFee\": 9.99,\n \"shippingTaxAmount\": 0.82,\n \"tags\": [\"vip\", \"spring-promo\"],\n \"transactions\": [\n {\n \"id\": \"txn_abc123\",\n \"kind\": \"sale\",\n \"status\": \"success\",\n \"amount\": 149.97,\n \"currency\": \"USD\",\n \"paymentMethod\": \"visa\",\n \"createdAt\": \"2026-03-01T10:01:00Z\"\n }\n ],\n\n \"lineItems\": [\n {\n \"externalLineItemId\": \"li_001\",\n \"externalFulfillmentLineItemId\": \"fli_001\",\n \"externalVariantId\": \"var_blue_md\",\n \"title\": \"Classic T-Shirt\",\n \"description\": \"100% cotton crew neck\",\n \"sku\": \"TSHIRT-BLUE-MD\",\n \"imageUrl\": \"https://cdn.acme.com/products/tshirt-blue.jpg\",\n \"quantity\": 2,\n \"pricePerUnit\": 49.99,\n \"discountAmountPerUnit\": 5.00,\n \"total\": 89.98,\n \"weight\": 0.3,\n \"weightUnit\": \"KILOGRAMS\",\n \"collectionIds\": [\"col_apparel\", \"col_summer\"],\n \"categoryTypes\": [\"clothing\"],\n \"tags\": [\"final-sale\"]\n },\n {\n \"externalLineItemId\": \"li_002\",\n \"externalFulfillmentLineItemId\": \"fli_002\",\n \"externalVariantId\": \"var_sneaker_10\",\n \"title\": \"Runner Sneakers\",\n \"description\": \"Lightweight mesh upper\",\n \"sku\": \"SNEAKER-WHT-10\",\n \"imageUrl\": \"https://cdn.acme.com/products/sneaker-white.jpg\",\n \"quantity\": 1,\n \"pricePerUnit\": 59.99,\n \"discountAmountPerUnit\": 0,\n \"total\": 59.99,\n \"weight\": 0.6,\n \"weightUnit\": \"KILOGRAMS\",\n \"collectionIds\": [\"col_footwear\"],\n \"categoryTypes\": [\"clothing\"],\n \"tags\": []\n }\n ]\n}","options":{"raw":{"language":"json"}}},"url":"https://returns-sandbox.liquidonate.com/webhooks/external-order","description":"

Push a single order into the ReturnsDirect by LiquiDonate cache. Call this whenever an order is fulfilled or updated.

When to call this

After an order is fulfilled (items shipped)
\n
If shipping address or customer info changes
\n
On re-push of backlog orders when first installing Liquid
\n

Idempotency

Safe to call multiple times for the same order. Each call fully replaces the stored line items, so always send the complete order — not a diff.

Required fields

externalId — your internal order ID (unique per shop)
\n
orderNumber — human-readable reference shown in the return portal
\n
orderDate — ISO 8601 timestamp
\n
lineItems — at least one item
\n

Response

{ \"success\": true, \"id\": 42 }\n\n

Error responses

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Status	Meaning
400	Missing required fields or invalid JSON
401	Invalid HMAC signature
500	Internal error storing the order

Weight units

Accepted values for weightUnit: GRAMS, KILOGRAMS, OUNCES, POUNDS

Category Types

Accepted values for categoryType:

\"packaged_food_and_snacks\"
\"masculine\"
\"sports\"
\"personal_hygiene\"
\"non_fiction_books\"
\"cats\"
\"pillows\"
\"packaged_foods_and_snacks\"
\"electronics\"
\"health_products\"
\"pain_relief\"
\"rugs__blankets\"
\"electronic_accessories\"
\"living_room\"
\"feminine\"
\"kids\"
\"school_supplies\"
\"furniture\"
\"textbooks\"
\"other_electronics\"
\"office_supplies\"
\"office_furniture\"
\"prepared_meals\"
\"all\"
\"other_pets\"
\"outdoor_gear_other\"
\"beauty_products\"
\"arts__crafts\"
\"personal_care\"
\"office_goods\"
\"shelf_stable_milk\"
\"outdoor_gear\"
\"books\"
\"clothing\"
\"fiction_books\"
\"home_goods\"
\"home_furniture\"
\"perishable\"
\"food\"
\"laptops_and_computers\"
\"first_aid\"
\"mobile_phones\"
\"pharmacy\"
\"adaptiveassistive_equipment__ppe\"
\"pet_supplies\"
\"camping\"
\"outdoor_furniture\"
\"beverages\"
\"non_perishable\"
\"glasses__eyewear\"
\"canned_foods\"
\"dogs\"
\"laptops__desktop_computers\"
\"monitors\"
\"audio_equipment\"
\"cell_phones\"
\"televisions\"
\"bathroom_organization\"
\"storage__organization\"
\"bathroom_accessories\"
\"sexual_wellness\"
\"seasonal_home_decor\"
\"decor\"
\"family\"
\"packing__shipping\"
\"masculine_shoes\"
\"kids_socks__underwear\"
\"masculine_clothing\"
\"masculine_formal_wear\"
\"masculine_costumes\"
\"supplements\"
\"kids_outerwear\"
\"masculine_outerwear\"
\"diapers__baby_wipes\"
\"kids_shoes\"
\"kids_clothing\"
\"masculine_jewelry__accessories\"
\"feminine_jewelry__accessories\"
\"feminine_shoes\"
\"masculine_socks__underwear\"
\"feminine_socks__underwear\"
\"feminine_formal_wear\"
\"makeup\"
\"baby_supplies\"
\"strollers__car_seats\"
\"baby_formula__food\"
\"hair_care\"
\"skin_care\"
\"audiovideo\"
\"bedding\"
\"raw_materials\"
\"games__activities\"
\"small_appliances\"
\"book_bags\"
\"cookware\"
\"towels_rugs_mats\"
\"shower_curtains\"
\"classroom_supplies\"
\"toys__games\"
\"holiday__seasonal\"
\"lunch_bags\"
\"bedmattress\"
\"lamps__lighting\"
\"desks\"
\"media_players\"
\"seating\"
\"appliances\"
\"office_organization\"
\"office_storage__organization\"
\"feeding\"
\"equipment\"
\"gaming_consoles\"
\"tablets\"
\"backpacking\"
\"tents\"
\"winter_sports\"
\"cycling\"
\"nursery\"
\"toys__activities\"
\"storage__hard_drives\"
\"videophoto_cameras\"
\"exercise__fitness\"
\"accessories\"
\"water_sports\"
\"playsets\"
\"cleaning\"
\"sleeping_bags\"
\"miscellaneous_gear\"
\"camp_cooking\"
\"tools\"
\"holiday_decorations\"
\"maintenance_equipment\"
\"home_storage__organization\"
\"metals\"
\"other_raw_materials\"
\"tables\"
\"kitchen\"
\"bedroom\"
\"bathroom\"
\"cat_food\"
\"cat_health_and_general_supplies\"
\"dog_food\"
\"dog_toys\"
\"other_pet_food\"
\"other_pet_toys\"
\"liquids\"
\"wood_supplies\"
\"stoneceramics\"
\"glass\"
\"textiles\"
\"cat_toys\"
\"tableware\"
\"paper_products\"
\"other_pet_health_and_general_supplies\"
\"dog_health_and_general_supplies\"
\"adaptiveassistive\"
\"writingdrawing\"
\"feminine_costumes\"
\"children\"
\"home_seating\"
\"infant\"
\"kids_costumes\"
\"kids_accessories\"
\"feminine_clothing\"
\"window_accessories\"
\"masculine__swimwear\"
\"feminine__swimwear\"
\"kids__swimwear\"
\"feminine_outerwear\"
\"party_supplies\"

Tags

tags on the order and on each line item are used by the return policy engine to apply exceptions (e.g. items tagged final-sale may be ineligible for return).

\n","urlObject":{"path":["webhooks","external-order"],"host":["https://returns-sandbox.liquidonate.com"],"query":[],"variable":[]}},"response":[{"id":"2c465bcb-38e7-48d6-9835-418115d6194c","name":"200 – Order stored","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"X-Shop-Domain","value":"acme.com","description":"Your shop identifier"},{"key":"X-Signature","value":"{{X_Signature}}","description":"HMAC-SHA256 of the raw request body, set by the pre-request script"}],"body":{"mode":"raw","raw":"{\n \"externalId\": \"order_99001\",\n \"orderNumber\": \"#1001\",\n \"confirmationNumber\": \"CONF-99001\",\n \"orderDate\": \"2026-03-01T10:00:00Z\",\n \"customerName\": \"Jane Smith\",\n \"customerEmail\": \"jane@example.com\",\n \"customerPhone\": \"+1-555-0100\",\n \"shippingAddress1\": \"123 Main St\",\n \"shippingAddress2\": \"Apt 4B\",\n \"shippingCity\": \"Austin\",\n \"shippingState\": \"TX\",\n \"shippingZip\": \"78701\",\n \"shippingCountry\": \"US\",\n \"shippingPhone\": \"+1-555-0100\",\n \"shippingLatitude\": 30.2672,\n \"shippingLongitude\": -97.7431,\n \"originalShippingFee\": 9.99,\n \"shippingTaxAmount\": 0.82,\n \"tags\": [\"vip\", \"spring-promo\"],\n \"transactions\": [\n {\n \"id\": \"txn_abc123\",\n \"kind\": \"sale\",\n \"status\": \"success\",\n \"amount\": 149.97,\n \"currency\": \"USD\",\n \"paymentMethod\": \"visa\",\n \"createdAt\": \"2026-03-01T10:01:00Z\"\n }\n ],\n\n \"lineItems\": [\n {\n \"externalLineItemId\": \"li_001\",\n \"externalFulfillmentLineItemId\": \"fli_001\",\n \"externalVariantId\": \"var_blue_md\",\n \"title\": \"Classic T-Shirt\",\n \"description\": \"100% cotton crew neck\",\n \"sku\": \"TSHIRT-BLUE-MD\",\n \"imageUrl\": \"https://cdn.acme.com/products/tshirt-blue.jpg\",\n \"quantity\": 2,\n \"pricePerUnit\": 49.99,\n \"discountAmountPerUnit\": 5.00,\n \"total\": 89.98,\n \"weight\": 0.3,\n \"weightUnit\": \"KILOGRAMS\",\n \"collectionIds\": [\"col_apparel\", \"col_summer\"],\n \"categoryTypes\": [\"clothing\"],\n \"tags\": [\"final-sale\"]\n },\n {\n \"externalLineItemId\": \"li_002\",\n \"externalFulfillmentLineItemId\": \"fli_002\",\n \"externalVariantId\": \"var_sneaker_10\",\n \"title\": \"Runner Sneakers\",\n \"description\": \"Lightweight mesh upper\",\n \"sku\": \"SNEAKER-WHT-10\",\n \"imageUrl\": \"https://cdn.acme.com/products/sneaker-white.jpg\",\n \"quantity\": 1,\n \"pricePerUnit\": 59.99,\n \"discountAmountPerUnit\": 0,\n \"total\": 59.99,\n \"weight\": 0.6,\n \"weightUnit\": \"KILOGRAMS\",\n \"collectionIds\": [\"col_footwear\"],\n \"categoryTypes\": [\"clothing\"],\n \"tags\": []\n }\n ]\n}","options":{"raw":{"language":"json"}}},"url":"https://returns-sandbox.liquidonate.com/webhooks/external-order","description":"Push a single order into the ReturnsDirect by LiquiDonate cache. Call this whenever an order is fulfilled or updated.\n\n### When to call this\n\n- After an order is fulfilled (items shipped)\n \n- If shipping address or customer info changes\n \n- On re-push of backlog orders when first installing Liquid\n \n\n### Idempotency\n\nSafe to call multiple times for the same order. Each call fully replaces the stored line items, so always send the complete order — not a diff.\n\n### Required fields\n\n- `externalId` — your internal order ID (unique per shop)\n \n- `orderNumber` — human-readable reference shown in the return portal\n \n- `orderDate` — ISO 8601 timestamp\n \n- `lineItems` — at least one item\n \n\n### Response\n\n``` json\n{ \"success\": true, \"id\": 42 }\n\n ```\n\n### Error responses\n\n| Status | Meaning |\n| --- | --- |\n| 400 | Missing required fields or invalid JSON |\n| 401 | Invalid HMAC signature |\n| 500 | Internal error storing the order |\n\n### Weight units\n\nAccepted values for `weightUnit`: `GRAMS`, `KILOGRAMS`, `OUNCES`, `POUNDS`\n\n### Category Types\n\nAccepted values for **`categoryType`**:\n\n\"packaged_food_and_snacks\" \n\"masculine\" \n\"sports\" \n\"personal_hygiene\" \n\"non_fiction_books\" \n\"cats\" \n\"pillows\" \n\"packaged_foods_and_snacks\" \n\"electronics\" \n\"health_products\" \n\"pain_relief\" \n\"rugs__blankets\" \n\"electronic_accessories\" \n\"living_room\" \n\"feminine\" \n\"kids\" \n\"school_supplies\" \n\"furniture\" \n\"textbooks\" \n\"other_electronics\" \n\"office_supplies\" \n\"office_furniture\" \n\"prepared_meals\" \n\"all\" \n\"other_pets\" \n\"outdoor_gear_other\" \n\"beauty_products\" \n\"arts__crafts\" \n\"personal_care\" \n\"office_goods\" \n\"shelf_stable_milk\" \n\"outdoor_gear\" \n\"books\" \n\"clothing\" \n\"fiction_books\" \n\"home_goods\" \n\"home_furniture\" \n\"perishable\" \n\"food\" \n\"laptops_and_computers\" \n\"first_aid\" \n\"mobile_phones\" \n\"pharmacy\" \n\"adaptiveassistive_equipment__ppe\" \n\"pet_supplies\" \n\"camping\" \n\"outdoor_furniture\" \n\"beverages\" \n\"non_perishable\" \n\"glasses__eyewear\" \n\"canned_foods\" \n\"dogs\" \n\"laptops__desktop_computers\" \n\"monitors\" \n\"audio_equipment\" \n\"cell_phones\" \n\"televisions\" \n\"bathroom_organization\" \n\"storage__organization\" \n\"bathroom_accessories\" \n\"sexual_wellness\" \n\"seasonal_home_decor\" \n\"decor\" \n\"family\" \n\"packing__shipping\" \n\"masculine_shoes\" \n\"kids_socks__underwear\" \n\"masculine_clothing\" \n\"masculine_formal_wear\" \n\"masculine_costumes\" \n\"supplements\" \n\"kids_outerwear\" \n\"masculine_outerwear\" \n\"diapers__baby_wipes\" \n\"kids_shoes\" \n\"kids_clothing\" \n\"masculine_jewelry__accessories\" \n\"feminine_jewelry__accessories\" \n\"feminine_shoes\" \n\"masculine_socks__underwear\" \n\"feminine_socks__underwear\" \n\"feminine_formal_wear\" \n\"makeup\" \n\"baby_supplies\" \n\"strollers__car_seats\" \n\"baby_formula__food\" \n\"hair_care\" \n\"skin_care\" \n\"audiovideo\" \n\"bedding\" \n\"raw_materials\" \n\"games__activities\" \n\"small_appliances\" \n\"book_bags\" \n\"cookware\" \n\"towels_rugs_mats\" \n\"shower_curtains\" \n\"classroom_supplies\" \n\"toys__games\" \n\"holiday__seasonal\" \n\"lunch_bags\" \n\"bedmattress\" \n\"lamps__lighting\" \n\"desks\" \n\"media_players\" \n\"seating\" \n\"appliances\" \n\"office_organization\" \n\"office_storage__organization\" \n\"feeding\" \n\"equipment\" \n\"gaming_consoles\" \n\"tablets\" \n\"backpacking\" \n\"tents\" \n\"winter_sports\" \n\"cycling\" \n\"nursery\" \n\"toys__activities\" \n\"storage__hard_drives\" \n\"videophoto_cameras\" \n\"exercise__fitness\" \n\"accessories\" \n\"water_sports\" \n\"playsets\" \n\"cleaning\" \n\"sleeping_bags\" \n\"miscellaneous_gear\" \n\"camp_cooking\" \n\"tools\" \n\"holiday_decorations\" \n\"maintenance_equipment\" \n\"home_storage__organization\" \n\"metals\" \n\"other_raw_materials\" \n\"tables\" \n\"kitchen\" \n\"bedroom\" \n\"bathroom\" \n\"cat_food\" \n\"cat_health_and_general_supplies\" \n\"dog_food\" \n\"dog_toys\" \n\"other_pet_food\" \n\"other_pet_toys\" \n\"liquids\" \n\"wood_supplies\" \n\"stoneceramics\" \n\"glass\" \n\"textiles\" \n\"cat_toys\" \n\"tableware\" \n\"paper_products\" \n\"other_pet_health_and_general_supplies\" \n\"dog_health_and_general_supplies\" \n\"adaptiveassistive\" \n\"writingdrawing\" \n\"feminine_costumes\" \n\"children\" \n\"home_seating\" \n\"infant\" \n\"kids_costumes\" \n\"kids_accessories\" \n\"feminine_clothing\" \n\"window_accessories\" \n\"masculine__swimwear\" \n\"feminine__swimwear\" \n\"kids__swimwear\" \n\"feminine_outerwear\" \n\"party_supplies\"\n\n### Tags\n\n`tags` on the order and on each line item are used by the return policy engine to apply exceptions (e.g. items tagged `final-sale` may be ineligible for return)."},"status":"OK","code":200,"_postman_previewlanguage":"Text","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"success\": true,\n \"id\": 42\n}"},{"id":"6851bfc8-7810-4016-912e-40b7e920cf19","name":"400 – Missing required fields","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"X-Shop-Domain","value":"acme.com","description":"Your shop identifier"},{"key":"X-Signature","value":"{{X_Signature}}","description":"HMAC-SHA256 of the raw request body, set by the pre-request script"}],"body":{"mode":"raw","raw":"{\n \"externalId\": \"order_99001\",\n \"orderNumber\": \"#1001\",\n \"confirmationNumber\": \"CONF-99001\",\n \"orderDate\": \"2026-03-01T10:00:00Z\",\n \"customerName\": \"Jane Smith\",\n \"customerEmail\": \"jane@example.com\",\n \"customerPhone\": \"+1-555-0100\",\n \"shippingAddress1\": \"123 Main St\",\n \"shippingAddress2\": \"Apt 4B\",\n \"shippingCity\": \"Austin\",\n \"shippingState\": \"TX\",\n \"shippingZip\": \"78701\",\n \"shippingCountry\": \"US\",\n \"shippingPhone\": \"+1-555-0100\",\n \"shippingLatitude\": 30.2672,\n \"shippingLongitude\": -97.7431,\n \"originalShippingFee\": 9.99,\n \"shippingTaxAmount\": 0.82,\n \"tags\": [\"vip\", \"spring-promo\"],\n \"transactions\": [\n {\n \"id\": \"txn_abc123\",\n \"kind\": \"sale\",\n \"status\": \"success\",\n \"amount\": 149.97,\n \"currency\": \"USD\",\n \"paymentMethod\": \"visa\",\n \"createdAt\": \"2026-03-01T10:01:00Z\"\n }\n ],\n\n \"lineItems\": [\n {\n \"externalLineItemId\": \"li_001\",\n \"externalFulfillmentLineItemId\": \"fli_001\",\n \"externalVariantId\": \"var_blue_md\",\n \"title\": \"Classic T-Shirt\",\n \"description\": \"100% cotton crew neck\",\n \"sku\": \"TSHIRT-BLUE-MD\",\n \"imageUrl\": \"https://cdn.acme.com/products/tshirt-blue.jpg\",\n \"quantity\": 2,\n \"pricePerUnit\": 49.99,\n \"discountAmountPerUnit\": 5.00,\n \"total\": 89.98,\n \"weight\": 0.3,\n \"weightUnit\": \"KILOGRAMS\",\n \"collectionIds\": [\"col_apparel\", \"col_summer\"],\n \"categoryTypes\": [\"clothing\"],\n \"tags\": [\"final-sale\"]\n },\n {\n \"externalLineItemId\": \"li_002\",\n \"externalFulfillmentLineItemId\": \"fli_002\",\n \"externalVariantId\": \"var_sneaker_10\",\n \"title\": \"Runner Sneakers\",\n \"description\": \"Lightweight mesh upper\",\n \"sku\": \"SNEAKER-WHT-10\",\n \"imageUrl\": \"https://cdn.acme.com/products/sneaker-white.jpg\",\n \"quantity\": 1,\n \"pricePerUnit\": 59.99,\n \"discountAmountPerUnit\": 0,\n \"total\": 59.99,\n \"weight\": 0.6,\n \"weightUnit\": \"KILOGRAMS\",\n \"collectionIds\": [\"col_footwear\"],\n \"categoryTypes\": [\"clothing\"],\n \"tags\": []\n }\n ]\n}","options":{"raw":{"language":"json"}}},"url":"https://returns-sandbox.liquidonate.com/webhooks/external-order","description":"Push a single order into the ReturnsDirect by LiquiDonate cache. Call this whenever an order is fulfilled or updated.\n\n### When to call this\n\n- After an order is fulfilled (items shipped)\n \n- If shipping address or customer info changes\n \n- On re-push of backlog orders when first installing Liquid\n \n\n### Idempotency\n\nSafe to call multiple times for the same order. Each call fully replaces the stored line items, so always send the complete order — not a diff.\n\n### Required fields\n\n- `externalId` — your internal order ID (unique per shop)\n \n- `orderNumber` — human-readable reference shown in the return portal\n \n- `orderDate` — ISO 8601 timestamp\n \n- `lineItems` — at least one item\n \n\n### Response\n\n``` json\n{ \"success\": true, \"id\": 42 }\n\n ```\n\n### Error responses\n\n| Status | Meaning |\n| --- | --- |\n| 400 | Missing required fields or invalid JSON |\n| 401 | Invalid HMAC signature |\n| 500 | Internal error storing the order |\n\n### Weight units\n\nAccepted values for `weightUnit`: `GRAMS`, `KILOGRAMS`, `OUNCES`, `POUNDS`\n\n### Category Types\n\nAccepted values for **`categoryType`**:\n\n\"packaged_food_and_snacks\" \n\"masculine\" \n\"sports\" \n\"personal_hygiene\" \n\"non_fiction_books\" \n\"cats\" \n\"pillows\" \n\"packaged_foods_and_snacks\" \n\"electronics\" \n\"health_products\" \n\"pain_relief\" \n\"rugs__blankets\" \n\"electronic_accessories\" \n\"living_room\" \n\"feminine\" \n\"kids\" \n\"school_supplies\" \n\"furniture\" \n\"textbooks\" \n\"other_electronics\" \n\"office_supplies\" \n\"office_furniture\" \n\"prepared_meals\" \n\"all\" \n\"other_pets\" \n\"outdoor_gear_other\" \n\"beauty_products\" \n\"arts__crafts\" \n\"personal_care\" \n\"office_goods\" \n\"shelf_stable_milk\" \n\"outdoor_gear\" \n\"books\" \n\"clothing\" \n\"fiction_books\" \n\"home_goods\" \n\"home_furniture\" \n\"perishable\" \n\"food\" \n\"laptops_and_computers\" \n\"first_aid\" \n\"mobile_phones\" \n\"pharmacy\" \n\"adaptiveassistive_equipment__ppe\" \n\"pet_supplies\" \n\"camping\" \n\"outdoor_furniture\" \n\"beverages\" \n\"non_perishable\" \n\"glasses__eyewear\" \n\"canned_foods\" \n\"dogs\" \n\"laptops__desktop_computers\" \n\"monitors\" \n\"audio_equipment\" \n\"cell_phones\" \n\"televisions\" \n\"bathroom_organization\" \n\"storage__organization\" \n\"bathroom_accessories\" \n\"sexual_wellness\" \n\"seasonal_home_decor\" \n\"decor\" \n\"family\" \n\"packing__shipping\" \n\"masculine_shoes\" \n\"kids_socks__underwear\" \n\"masculine_clothing\" \n\"masculine_formal_wear\" \n\"masculine_costumes\" \n\"supplements\" \n\"kids_outerwear\" \n\"masculine_outerwear\" \n\"diapers__baby_wipes\" \n\"kids_shoes\" \n\"kids_clothing\" \n\"masculine_jewelry__accessories\" \n\"feminine_jewelry__accessories\" \n\"feminine_shoes\" \n\"masculine_socks__underwear\" \n\"feminine_socks__underwear\" \n\"feminine_formal_wear\" \n\"makeup\" \n\"baby_supplies\" \n\"strollers__car_seats\" \n\"baby_formula__food\" \n\"hair_care\" \n\"skin_care\" \n\"audiovideo\" \n\"bedding\" \n\"raw_materials\" \n\"games__activities\" \n\"small_appliances\" \n\"book_bags\" \n\"cookware\" \n\"towels_rugs_mats\" \n\"shower_curtains\" \n\"classroom_supplies\" \n\"toys__games\" \n\"holiday__seasonal\" \n\"lunch_bags\" \n\"bedmattress\" \n\"lamps__lighting\" \n\"desks\" \n\"media_players\" \n\"seating\" \n\"appliances\" \n\"office_organization\" \n\"office_storage__organization\" \n\"feeding\" \n\"equipment\" \n\"gaming_consoles\" \n\"tablets\" \n\"backpacking\" \n\"tents\" \n\"winter_sports\" \n\"cycling\" \n\"nursery\" \n\"toys__activities\" \n\"storage__hard_drives\" \n\"videophoto_cameras\" \n\"exercise__fitness\" \n\"accessories\" \n\"water_sports\" \n\"playsets\" \n\"cleaning\" \n\"sleeping_bags\" \n\"miscellaneous_gear\" \n\"camp_cooking\" \n\"tools\" \n\"holiday_decorations\" \n\"maintenance_equipment\" \n\"home_storage__organization\" \n\"metals\" \n\"other_raw_materials\" \n\"tables\" \n\"kitchen\" \n\"bedroom\" \n\"bathroom\" \n\"cat_food\" \n\"cat_health_and_general_supplies\" \n\"dog_food\" \n\"dog_toys\" \n\"other_pet_food\" \n\"other_pet_toys\" \n\"liquids\" \n\"wood_supplies\" \n\"stoneceramics\" \n\"glass\" \n\"textiles\" \n\"cat_toys\" \n\"tableware\" \n\"paper_products\" \n\"other_pet_health_and_general_supplies\" \n\"dog_health_and_general_supplies\" \n\"adaptiveassistive\" \n\"writingdrawing\" \n\"feminine_costumes\" \n\"children\" \n\"home_seating\" \n\"infant\" \n\"kids_costumes\" \n\"kids_accessories\" \n\"feminine_clothing\" \n\"window_accessories\" \n\"masculine__swimwear\" \n\"feminine__swimwear\" \n\"kids__swimwear\" \n\"feminine_outerwear\" \n\"party_supplies\"\n\n### Tags\n\n`tags` on the order and on each line item are used by the return policy engine to apply exceptions (e.g. items tagged `final-sale` may be ineligible for return)."},"status":"Bad Request","code":400,"_postman_previewlanguage":"Text","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"error\": \"Missing required fields: externalId, orderNumber\"\n}"},{"id":"d743b306-f944-45c7-a2ce-186fb594a8fe","name":"401 – Invalid signature","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"X-Shop-Domain","value":"acme.com","description":"Your shop identifier"},{"key":"X-Signature","value":"{{X_Signature}}","description":"HMAC-SHA256 of the raw request body, set by the pre-request script"}],"body":{"mode":"raw","raw":"{\n \"externalId\": \"order_99001\",\n \"orderNumber\": \"#1001\",\n \"confirmationNumber\": \"CONF-99001\",\n \"orderDate\": \"2026-03-01T10:00:00Z\",\n \"customerName\": \"Jane Smith\",\n \"customerEmail\": \"jane@example.com\",\n \"customerPhone\": \"+1-555-0100\",\n \"shippingAddress1\": \"123 Main St\",\n \"shippingAddress2\": \"Apt 4B\",\n \"shippingCity\": \"Austin\",\n \"shippingState\": \"TX\",\n \"shippingZip\": \"78701\",\n \"shippingCountry\": \"US\",\n \"shippingPhone\": \"+1-555-0100\",\n \"shippingLatitude\": 30.2672,\n \"shippingLongitude\": -97.7431,\n \"originalShippingFee\": 9.99,\n \"shippingTaxAmount\": 0.82,\n \"tags\": [\"vip\", \"spring-promo\"],\n \"transactions\": [\n {\n \"id\": \"txn_abc123\",\n \"kind\": \"sale\",\n \"status\": \"success\",\n \"amount\": 149.97,\n \"currency\": \"USD\",\n \"paymentMethod\": \"visa\",\n \"createdAt\": \"2026-03-01T10:01:00Z\"\n }\n ],\n\n \"lineItems\": [\n {\n \"externalLineItemId\": \"li_001\",\n \"externalFulfillmentLineItemId\": \"fli_001\",\n \"externalVariantId\": \"var_blue_md\",\n \"title\": \"Classic T-Shirt\",\n \"description\": \"100% cotton crew neck\",\n \"sku\": \"TSHIRT-BLUE-MD\",\n \"imageUrl\": \"https://cdn.acme.com/products/tshirt-blue.jpg\",\n \"quantity\": 2,\n \"pricePerUnit\": 49.99,\n \"discountAmountPerUnit\": 5.00,\n \"total\": 89.98,\n \"weight\": 0.3,\n \"weightUnit\": \"KILOGRAMS\",\n \"collectionIds\": [\"col_apparel\", \"col_summer\"],\n \"categoryTypes\": [\"clothing\"],\n \"tags\": [\"final-sale\"]\n },\n {\n \"externalLineItemId\": \"li_002\",\n \"externalFulfillmentLineItemId\": \"fli_002\",\n \"externalVariantId\": \"var_sneaker_10\",\n \"title\": \"Runner Sneakers\",\n \"description\": \"Lightweight mesh upper\",\n \"sku\": \"SNEAKER-WHT-10\",\n \"imageUrl\": \"https://cdn.acme.com/products/sneaker-white.jpg\",\n \"quantity\": 1,\n \"pricePerUnit\": 59.99,\n \"discountAmountPerUnit\": 0,\n \"total\": 59.99,\n \"weight\": 0.6,\n \"weightUnit\": \"KILOGRAMS\",\n \"collectionIds\": [\"col_footwear\"],\n \"categoryTypes\": [\"clothing\"],\n \"tags\": []\n }\n ]\n}","options":{"raw":{"language":"json"}}},"url":"https://returns-sandbox.liquidonate.com/webhooks/external-order","description":"Push a single order into the ReturnsDirect by LiquiDonate cache. Call this whenever an order is fulfilled or updated.\n\n### When to call this\n\n- After an order is fulfilled (items shipped)\n \n- If shipping address or customer info changes\n \n- On re-push of backlog orders when first installing Liquid\n \n\n### Idempotency\n\nSafe to call multiple times for the same order. Each call fully replaces the stored line items, so always send the complete order — not a diff.\n\n### Required fields\n\n- `externalId` — your internal order ID (unique per shop)\n \n- `orderNumber` — human-readable reference shown in the return portal\n \n- `orderDate` — ISO 8601 timestamp\n \n- `lineItems` — at least one item\n \n\n### Response\n\n``` json\n{ \"success\": true, \"id\": 42 }\n\n ```\n\n### Error responses\n\n| Status | Meaning |\n| --- | --- |\n| 400 | Missing required fields or invalid JSON |\n| 401 | Invalid HMAC signature |\n| 500 | Internal error storing the order |\n\n### Weight units\n\nAccepted values for `weightUnit`: `GRAMS`, `KILOGRAMS`, `OUNCES`, `POUNDS`\n\n### Category Types\n\nAccepted values for **`categoryType`**:\n\n\"packaged_food_and_snacks\" \n\"masculine\" \n\"sports\" \n\"personal_hygiene\" \n\"non_fiction_books\" \n\"cats\" \n\"pillows\" \n\"packaged_foods_and_snacks\" \n\"electronics\" \n\"health_products\" \n\"pain_relief\" \n\"rugs__blankets\" \n\"electronic_accessories\" \n\"living_room\" \n\"feminine\" \n\"kids\" \n\"school_supplies\" \n\"furniture\" \n\"textbooks\" \n\"other_electronics\" \n\"office_supplies\" \n\"office_furniture\" \n\"prepared_meals\" \n\"all\" \n\"other_pets\" \n\"outdoor_gear_other\" \n\"beauty_products\" \n\"arts__crafts\" \n\"personal_care\" \n\"office_goods\" \n\"shelf_stable_milk\" \n\"outdoor_gear\" \n\"books\" \n\"clothing\" \n\"fiction_books\" \n\"home_goods\" \n\"home_furniture\" \n\"perishable\" \n\"food\" \n\"laptops_and_computers\" \n\"first_aid\" \n\"mobile_phones\" \n\"pharmacy\" \n\"adaptiveassistive_equipment__ppe\" \n\"pet_supplies\" \n\"camping\" \n\"outdoor_furniture\" \n\"beverages\" \n\"non_perishable\" \n\"glasses__eyewear\" \n\"canned_foods\" \n\"dogs\" \n\"laptops__desktop_computers\" \n\"monitors\" \n\"audio_equipment\" \n\"cell_phones\" \n\"televisions\" \n\"bathroom_organization\" \n\"storage__organization\" \n\"bathroom_accessories\" \n\"sexual_wellness\" \n\"seasonal_home_decor\" \n\"decor\" \n\"family\" \n\"packing__shipping\" \n\"masculine_shoes\" \n\"kids_socks__underwear\" \n\"masculine_clothing\" \n\"masculine_formal_wear\" \n\"masculine_costumes\" \n\"supplements\" \n\"kids_outerwear\" \n\"masculine_outerwear\" \n\"diapers__baby_wipes\" \n\"kids_shoes\" \n\"kids_clothing\" \n\"masculine_jewelry__accessories\" \n\"feminine_jewelry__accessories\" \n\"feminine_shoes\" \n\"masculine_socks__underwear\" \n\"feminine_socks__underwear\" \n\"feminine_formal_wear\" \n\"makeup\" \n\"baby_supplies\" \n\"strollers__car_seats\" \n\"baby_formula__food\" \n\"hair_care\" \n\"skin_care\" \n\"audiovideo\" \n\"bedding\" \n\"raw_materials\" \n\"games__activities\" \n\"small_appliances\" \n\"book_bags\" \n\"cookware\" \n\"towels_rugs_mats\" \n\"shower_curtains\" \n\"classroom_supplies\" \n\"toys__games\" \n\"holiday__seasonal\" \n\"lunch_bags\" \n\"bedmattress\" \n\"lamps__lighting\" \n\"desks\" \n\"media_players\" \n\"seating\" \n\"appliances\" \n\"office_organization\" \n\"office_storage__organization\" \n\"feeding\" \n\"equipment\" \n\"gaming_consoles\" \n\"tablets\" \n\"backpacking\" \n\"tents\" \n\"winter_sports\" \n\"cycling\" \n\"nursery\" \n\"toys__activities\" \n\"storage__hard_drives\" \n\"videophoto_cameras\" \n\"exercise__fitness\" \n\"accessories\" \n\"water_sports\" \n\"playsets\" \n\"cleaning\" \n\"sleeping_bags\" \n\"miscellaneous_gear\" \n\"camp_cooking\" \n\"tools\" \n\"holiday_decorations\" \n\"maintenance_equipment\" \n\"home_storage__organization\" \n\"metals\" \n\"other_raw_materials\" \n\"tables\" \n\"kitchen\" \n\"bedroom\" \n\"bathroom\" \n\"cat_food\" \n\"cat_health_and_general_supplies\" \n\"dog_food\" \n\"dog_toys\" \n\"other_pet_food\" \n\"other_pet_toys\" \n\"liquids\" \n\"wood_supplies\" \n\"stoneceramics\" \n\"glass\" \n\"textiles\" \n\"cat_toys\" \n\"tableware\" \n\"paper_products\" \n\"other_pet_health_and_general_supplies\" \n\"dog_health_and_general_supplies\" \n\"adaptiveassistive\" \n\"writingdrawing\" \n\"feminine_costumes\" \n\"children\" \n\"home_seating\" \n\"infant\" \n\"kids_costumes\" \n\"kids_accessories\" \n\"feminine_clothing\" \n\"window_accessories\" \n\"masculine__swimwear\" \n\"feminine__swimwear\" \n\"kids__swimwear\" \n\"feminine_outerwear\" \n\"party_supplies\"\n\n### Tags\n\n`tags` on the order and on each line item are used by the return policy engine to apply exceptions (e.g. items tagged `final-sale` may be ineligible for return)."},"status":"Unauthorized","code":401,"_postman_previewlanguage":"Text","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"error\": \"Invalid signature\"\n}"}],"_postman_id":"47e52f49-d93c-433e-981d-73e6e17982c7"}],"id":"590b226c-4415-4f54-9bbc-ed6a6d5b7c9a","description":"

Requests you send to ReturnsDirect by LiquiDonate to push order data into the return portal cache.

\n","_postman_id":"590b226c-4415-4f54-9bbc-ed6a6d5b7c9a"},{"name":"Outbound — ReturnsDirect by LiquiDonate → Retailer","item":[{"name":"return.pending","id":"aa8f5468-9c60-4f19-b2d6-5ffc0e51ed9e","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"X-Shop-Domain","value":"acme.com"},{"key":"X-Signature","value":""}],"body":{"mode":"raw","raw":"{\n \"event\": \"return.pending\",\n \"shop\": \"acme.com\",\n \"parcelId\": 101,\n \"rmaId\": \"1001\",\n \"externalOrderId\": \"order_99001\",\n \"orderNumber\": \"#1001\",\n \"status\": \"pending\",\n \"refundStatus\": \"pending\",\n \"refundAmount\": null,\n \"refundMethod\": \"cash\",\n \"updatedAt\": \"2026-03-07T09:00:00.000Z\"\n}","options":{"raw":{"language":"json"}}},"url":"https://your-system.com/webhooks/returnsdirect-rms","description":"

Fired when a customer submits a return request. The return is queued for workflow matching.

\n","urlObject":{"host":["https://your-system.com/webhooks/returnsdirect-rms"],"query":[],"variable":[]}},"response":[],"_postman_id":"aa8f5468-9c60-4f19-b2d6-5ffc0e51ed9e"},{"name":"return.pending_approval","id":"f38618fd-fbab-40a0-9e23-e6625bb66711","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"X-Shop-Domain","value":"acme.com"},{"key":"X-Signature","value":""}],"body":{"mode":"raw","raw":"{\n \"event\": \"return.pending_approval\",\n \"shop\": \"acme.com\",\n \"parcelId\": 101,\n \"rmaId\": \"1001\",\n \"externalOrderId\": \"order_99001\",\n \"orderNumber\": \"#1001\",\n \"status\": \"pending_approval\",\n \"refundStatus\": \"pending\",\n \"refundAmount\": null,\n \"refundMethod\": \"cash\",\n \"updatedAt\": \"2026-03-07T09:01:00.000Z\"\n}","options":{"raw":{"language":"json"}}},"url":"https://your-system.com/webhooks/returnsdirect-rms","description":"

Fired when the return has been matched to a workflow and is waiting for merchant approval.

\n","urlObject":{"host":["https://your-system.com/webhooks/returnsdirect-rms"],"query":[],"variable":[]}},"response":[],"_postman_id":"f38618fd-fbab-40a0-9e23-e6625bb66711"},{"name":"return.approved","id":"9dbcdbf8-0d03-456a-ad74-4c644082efc5","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"X-Shop-Domain","value":"acme.com"},{"key":"X-Signature","value":""}],"body":{"mode":"raw","raw":"{\n \"event\": \"return.approved\",\n \"shop\": \"acme.com\",\n \"parcelId\": 101,\n \"rmaId\": \"1001\",\n \"externalOrderId\": \"order_99001\",\n \"orderNumber\": \"#1001\",\n \"status\": \"approved\",\n \"refundStatus\": \"pending\",\n \"refundAmount\": null,\n \"refundMethod\": \"cash\",\n \"updatedAt\": \"2026-03-07T09:05:00.000Z\"\n}","options":{"raw":{"language":"json"}}},"url":"https://your-system.com/webhooks/returnsdirect-rms","description":"

Fired when the return is approved. A return shipping label may be issued at this point.

\n","urlObject":{"host":["https://your-system.com/webhooks/returnsdirect-rms"],"query":[],"variable":[]}},"response":[],"_postman_id":"9dbcdbf8-0d03-456a-ad74-4c644082efc5"},{"name":"return.rejected","id":"dbd25e12-ed67-4200-af33-4ac8c32a4755","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"X-Shop-Domain","value":"acme.com"},{"key":"X-Signature","value":""}],"body":{"mode":"raw","raw":"{\n \"event\": \"return.rejected\",\n \"shop\": \"acme.com\",\n \"parcelId\": 101,\n \"rmaId\": \"1001\",\n \"externalOrderId\": \"order_99001\",\n \"orderNumber\": \"#1001\",\n \"status\": \"rejected\",\n \"refundStatus\": \"pending\",\n \"refundAmount\": null,\n \"refundMethod\": \"cash\",\n \"updatedAt\": \"2026-03-07T09:10:00.000Z\"\n}","options":{"raw":{"language":"json"}}},"url":"https://your-system.com/webhooks/returnsdirect-rms","description":"

Fired when the return is declined by the merchant.

\n","urlObject":{"host":["https://your-system.com/webhooks/returnsdirect-rms"],"query":[],"variable":[]}},"response":[],"_postman_id":"dbd25e12-ed67-4200-af33-4ac8c32a4755"},{"name":"return.cancelled","id":"4fbe4542-ae18-47fe-8b81-4ae4f92d76fe","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"X-Shop-Domain","value":"acme.com"},{"key":"X-Signature","value":""}],"body":{"mode":"raw","raw":"{\n \"event\": \"return.cancelled\",\n \"shop\": \"acme.com\",\n \"parcelId\": 101,\n \"rmaId\": \"1001\",\n \"externalOrderId\": \"order_99001\",\n \"orderNumber\": \"#1001\",\n \"status\": \"cancelled\",\n \"refundStatus\": \"pending\",\n \"refundAmount\": null,\n \"refundMethod\": \"cash\",\n \"updatedAt\": \"2026-03-07T09:12:00.000Z\"\n}","options":{"raw":{"language":"json"}}},"url":"https://your-system.com/webhooks/returnsdirect-rms","description":"

Fired when the return is cancelled (either by the customer or the merchant).

\n","urlObject":{"host":["https://your-system.com/webhooks/returnsdirect-rms"],"query":[],"variable":[]}},"response":[],"_postman_id":"4fbe4542-ae18-47fe-8b81-4ae4f92d76fe"},{"name":"refund.completed","id":"4206131c-4fde-4a8b-8cae-633e435b29f4","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"X-Shop-Domain","value":"acme.com"},{"key":"X-Signature","value":""}],"body":{"mode":"raw","raw":"{\n \"event\": \"refund.completed\",\n \"shop\": \"acme.com\",\n \"parcelId\": 101,\n \"rmaId\": \"1001\",\n \"externalOrderId\": \"order_99001\",\n \"orderNumber\": \"#1001\",\n \"status\": \"approved\",\n \"refundStatus\": \"completed\",\n \"refundAmount\": 89.98,\n \"refundMethod\": \"cash\",\n \"updatedAt\": \"2026-03-07T10:30:00.000Z\"\n}","options":{"raw":{"language":"json"}}},"url":"https://your-system.com/webhooks/returnsdirect-rms","description":"

Fired when the refund has been successfully issued.

refundAmount is the net amount refunded to the customer (after deductions). refundMethod indicates whether it was returned to the original payment method (cash), issued as store credit, or fulfilled as an exchange.

\n","urlObject":{"host":["https://your-system.com/webhooks/returnsdirect-rms"],"query":[],"variable":[]}},"response":[],"_postman_id":"4206131c-4fde-4a8b-8cae-633e435b29f4"},{"name":"refund.flagged","id":"b9953838-44fb-42e3-b037-401476fe27d5","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"X-Shop-Domain","value":"acme.com"},{"key":"X-Signature","value":""}],"body":{"mode":"raw","raw":"{\n \"event\": \"refund.flagged\",\n \"shop\": \"acme.com\",\n \"parcelId\": 101,\n \"rmaId\": \"1001\",\n \"externalOrderId\": \"order_99001\",\n \"orderNumber\": \"#1001\",\n \"status\": \"approved\",\n \"refundStatus\": \"flagged\",\n \"refundAmount\": 89.98,\n \"refundMethod\": \"cash\",\n \"updatedAt\": \"2026-03-07T10:35:00.000Z\"\n}","options":{"raw":{"language":"json"}}},"url":"https://your-system.com/webhooks/returnsdirect-rms","description":"

Fired when a refund is flagged for manual review by Liquid (e.g. refund amount looks anomalous). The refund has not been issued yet. A refund.completed event will follow once resolved.

\n","urlObject":{"host":["https://your-system.com/webhooks/returnsdirect-rms"],"query":[],"variable":[]}},"response":[],"_postman_id":"b9953838-44fb-42e3-b037-401476fe27d5"}],"id":"e4f71880-b0f0-41eb-b881-e84a244bd77a","description":"

Events that ReturnsDirect by LiquiDonate posts to your webhook URL when a return or refund changes status.

Your endpoint must:

Accept POST requests with Content-Type: application/json
Verify the X-Signature header using HMAC-SHA256 with your shared secret
Return HTTP 200 to acknowledge receipt

Verification example (Node.js)

const crypto = require('crypto');\n\nfunction verifySignature(secret, rawBody, signatureHeader) {\n  const expected = crypto\n    .createHmac('sha256', secret)\n    .update(rawBody)\n    .digest('hex');\n  const a = Buffer.from(expected, 'hex');\n  const b = Buffer.from(signatureHeader, 'hex');\n  if (a.length !== b.length) return false;\n  return crypto.timingSafeEqual(a, b);\n}\n

Status reference

status values

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Value	Meaning
`pending`	Return request submitted, awaiting review
`pending_approval`	Matched to a workflow, awaiting approval
`approved`	Return approved, label may be issued
`rejected`	Return declined
`cancelled`	Return cancelled
`externally_processed`	Handled outside ReturnsDirect by LiquiDonate
`closed`	Return forcibly closed

refundStatus values

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Value	Meaning
`pending`	Refund not yet issued
`completed`	Refund processed
`flagged`	Refund flagged for manual review

refundMethod values\ncash, store_credit, exchange

\n","_postman_id":"e4f71880-b0f0-41eb-b881-e84a244bd77a"},{"name":"Custom Adapter — Retailer API Endpoints","item":[{"name":"GET Order","id":"927a66fc-ba15-4300-8bb1-ff9291ae4356","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Accept","value":"application/json"},{"key":"Authorization","value":"Bearer {{retailer_api_token}}","description":"

Or whichever auth type is configured

\n"}],"url":"{{retailer_base_url}}/orders/{{order_id}}","description":"

ReturnsDirect calls this when it needs to fetch a single order by ID.

Mapped from endpointGetOrder with {id} replaced by the order ID.

Expected response shape

Return data in the canonical ReturnsDirect by LiquiDonate format (same camelCase fields as the Push Order body) for zero-config mapping, or a custom structure if you have a mapper configured.

\n","urlObject":{"path":["orders","{{order_id}}"],"host":["{{retailer_base_url}}"],"query":[],"variable":[]}},"response":[{"id":"6687deca-1be8-4115-a765-337641e001ad","name":"200 – Order found","originalRequest":{"method":"GET","header":[{"key":"Accept","value":"application/json"},{"key":"Authorization","value":"Bearer {{retailer_api_token}}","description":"Or whichever auth type is configured"}],"url":"{{retailer_base_url}}/orders/{{order_id}}","description":"ReturnsDirect calls this when it needs to fetch a single order by ID.\n\nMapped from `endpointGetOrder` with `{id}` replaced by the order ID.\n\n### Expected response shape\n\nReturn data in the canonical ReturnsDirect by LiquiDonate format (same camelCase fields as the Push Order body) for zero-config mapping, or a custom structure if you have a mapper configured."},"status":"OK","code":200,"_postman_previewlanguage":"Text","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"externalId\": \"order_99001\",\n \"orderNumber\": \"#1001\",\n \"orderDate\": \"2026-03-01T10:00:00Z\",\n \"customerName\": \"Jane Smith\",\n \"customerEmail\": \"jane@example.com\",\n \"lineItems\": [\n {\n \"externalLineItemId\": \"li_001\",\n \"externalFulfillmentLineItemId\": \"fli_001\",\n \"title\": \"Classic T-Shirt\",\n \"sku\": \"TSHIRT-BLUE-MD\",\n \"quantity\": 2,\n \"pricePerUnit\": 49.99\n }\n ]\n}"},{"id":"bc53baf9-37f8-4cab-a950-52c6998950dd","name":"404 – Order not found","originalRequest":{"method":"GET","header":[{"key":"Accept","value":"application/json"},{"key":"Authorization","value":"Bearer {{retailer_api_token}}","description":"Or whichever auth type is configured"}],"url":"{{retailer_base_url}}/orders/{{order_id}}","description":"ReturnsDirect calls this when it needs to fetch a single order by ID.\n\nMapped from `endpointGetOrder` with `{id}` replaced by the order ID.\n\n### Expected response shape\n\nReturn data in the canonical ReturnsDirect by LiquiDonate format (same camelCase fields as the Push Order body) for zero-config mapping, or a custom structure if you have a mapper configured."},"status":"Not Found","code":404,"_postman_previewlanguage":"Text","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"error\": \"Order not found\"\n}"}],"_postman_id":"927a66fc-ba15-4300-8bb1-ff9291ae4356"},{"name":"Search Orders","id":"5c4ffde7-2f50-4fd3-8d8b-61e82b02f207","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Accept","value":"application/json"},{"key":"Authorization","value":"Bearer {{retailer_api_token}}"}],"url":"{{retailer_base_url}}/orders?q={{query}}","description":"

ReturnsDirect calls this when searching for orders (e.g. by order number or customer email).

Mapped from endpointSearchOrders with {query} replaced by the search term.

Expected response shape

An array of orders in the canonical ReturnsDirect by LiquiDonate format, or a custom structure if you have a mapper configured.

\n","urlObject":{"path":["orders"],"host":["{{retailer_base_url}}"],"query":[{"key":"q","value":"{{query}}"}],"variable":[]}},"response":[{"id":"86f833b3-b439-4be7-a2ba-e88e48ee6655","name":"200 – Results","originalRequest":{"method":"GET","header":[{"key":"Accept","value":"application/json"},{"key":"Authorization","value":"Bearer {{retailer_api_token}}"}],"url":{"raw":"{{retailer_base_url}}/orders?q={{query}}","host":["{{retailer_base_url}}"],"path":["orders"],"query":[{"key":"q","value":"{{query}}"}]},"description":"ReturnsDirect calls this when searching for orders (e.g. by order number or customer email).\n\nMapped from `endpointSearchOrders` with `{query}` replaced by the search term.\n\n### Expected response shape\n\nAn array of orders in the canonical ReturnsDirect by LiquiDonate format, or a custom structure if you have a mapper configured."},"status":"OK","code":200,"_postman_previewlanguage":"Text","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"[\n {\n \"externalId\": \"order_99001\",\n \"orderNumber\": \"#1001\",\n \"orderDate\": \"2026-03-01T10:00:00Z\",\n \"customerEmail\": \"jane@example.com\"\n }\n]"}],"_postman_id":"5c4ffde7-2f50-4fd3-8d8b-61e82b02f207"},{"name":"Process Return","id":"3ad89277-3b71-4a34-acf1-ce878ba688dd","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"},{"key":"Authorization","value":"Bearer {{retailer_api_token}}"}],"body":{"mode":"raw","raw":"{\n \"input\": {\n \"returnId\": \"gid://shopify/Return/123\",\n \"returnLineItems\": [\n {\n \"id\": \"fli_001\",\n \"quantity\": 1\n }\n ],\n \"financialTransfer\": {\n \"issueRefund\": {\n \"orderTransactions\": [\n {\n \"transactionId\": \"txn_abc123\",\n \"amount\": \"49.99\"\n }\n ]\n }\n },\n \"notifyCustomer\": true\n }\n}","options":{"raw":{"language":"json"}}},"url":"{{retailer_base_url}}/returns/process","description":"

ReturnsDirect calls this to complete (process) a return — issuing the refund and closing the return in your system.

Mapped from endpointProcessReturn. The request body is posted as-is from the internal processReturn input.

Key fields

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Field	Description
`input.returnId`	ReturnsDirect's internal return identifier
`input.returnLineItems`	Line items being returned, each with `id` (fulfillment line item ID) and `quantity`
`input.financialTransfer.issueRefund.orderTransactions`	Transactions to refund against, with `transactionId` and `amount`
`input.notifyCustomer`	Whether to send a customer notification

Expected response

Return any JSON body — ReturnsDirect passes it through as AdapterResult.data. Return a non-2xx status to signal failure.

Error responses

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Status	Meaning
400	Invalid input (missing fields, bad return ID, etc.)
401	Unauthorized
422	Return cannot be processed (e.g. already processed, ineligible items)
500	Internal error in your system

","urlObject":{"path":["returns","process"],"host":["{{retailer_base_url}}"],"query":[],"variable":[]}},"response":[{"id":"d6711539-2233-458d-b063-c74e04470058","name":"200 – Return processed","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"},{"key":"Authorization","value":"Bearer {{retailer_api_token}}"}],"body":{"mode":"raw","raw":"{\n \"input\": {\n \"returnId\": \"gid://shopify/Return/123\",\n \"returnLineItems\": [\n {\n \"id\": \"fli_001\",\n \"quantity\": 1\n }\n ],\n \"financialTransfer\": {\n \"issueRefund\": {\n \"orderTransactions\": [\n {\n \"transactionId\": \"txn_abc123\",\n \"amount\": \"49.99\"\n }\n ]\n }\n },\n \"notifyCustomer\": true\n }\n}","options":{"raw":{"language":"json"}}},"url":"{{retailer_base_url}}/returns/process","description":"ReturnsDirect calls this to complete (process) a return — issuing the refund and closing the return in your system.\n\nMapped from `endpointProcessReturn`. The request body is posted as-is from the internal `processReturn` input.\n\n### Key fields\n\n| Field | Description |\n| --- | --- |\n| `input.returnId` | ReturnsDirect's internal return identifier |\n| `input.returnLineItems` | Line items being returned, each with `id` (fulfillment line item ID) and `quantity` |\n| `input.financialTransfer.issueRefund.orderTransactions` | Transactions to refund against, with `transactionId` and `amount` |\n| `input.notifyCustomer` | Whether to send a customer notification |\n\n### Expected response\n\nReturn any JSON body — ReturnsDirect passes it through as `AdapterResult.data`. Return a non-2xx status to signal failure.\n\n### Error responses\n\n| Status | Meaning |\n| --- | --- |\n| 400 | Invalid input (missing fields, bad return ID, etc.) |\n| 401 | Unauthorized |\n| 422 | Return cannot be processed (e.g. already processed, ineligible items) |\n| 500 | Internal error in your system |"},"status":"OK","code":200,"_postman_previewlanguage":"Text","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"success\": true,\n \"returnId\": \"gid://shopify/Return/123\",\n \"refundAmount\": 49.99\n}"},{"id":"4807ffe1-f25a-4cf2-9412-2fa882604fb0","name":"422 – Already processed","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"},{"key":"Authorization","value":"Bearer {{retailer_api_token}}"}],"body":{"mode":"raw","raw":"{\n \"input\": {\n \"returnId\": \"gid://shopify/Return/123\",\n \"returnLineItems\": [\n {\n \"id\": \"fli_001\",\n \"quantity\": 1\n }\n ],\n \"financialTransfer\": {\n \"issueRefund\": {\n \"orderTransactions\": [\n {\n \"transactionId\": \"txn_abc123\",\n \"amount\": \"49.99\"\n }\n ]\n }\n },\n \"notifyCustomer\": true\n }\n}","options":{"raw":{"language":"json"}}},"url":"{{retailer_base_url}}/returns/process","description":"ReturnsDirect calls this to complete (process) a return — issuing the refund and closing the return in your system.\n\nMapped from `endpointProcessReturn`. The request body is posted as-is from the internal `processReturn` input.\n\n### Key fields\n\n| Field | Description |\n| --- | --- |\n| `input.returnId` | ReturnsDirect's internal return identifier |\n| `input.returnLineItems` | Line items being returned, each with `id` (fulfillment line item ID) and `quantity` |\n| `input.financialTransfer.issueRefund.orderTransactions` | Transactions to refund against, with `transactionId` and `amount` |\n| `input.notifyCustomer` | Whether to send a customer notification |\n\n### Expected response\n\nReturn any JSON body — ReturnsDirect passes it through as `AdapterResult.data`. Return a non-2xx status to signal failure.\n\n### Error responses\n\n| Status | Meaning |\n| --- | --- |\n| 400 | Invalid input (missing fields, bad return ID, etc.) |\n| 401 | Unauthorized |\n| 422 | Return cannot be processed (e.g. already processed, ineligible items) |\n| 500 | Internal error in your system |"},"status":"Unprocessable Entity","code":422,"_postman_previewlanguage":"Text","header":[{"key":"Content-Type","value":"application/json"}],"cookie":[],"responseTime":null,"body":"{\n \"error\": \"Return has already been processed\"\n}"}],"_postman_id":"3ad89277-3b71-4a34-acf1-ce878ba688dd"}],"id":"95a6ec34-c3e3-4714-bf07-716bb84f9e7c","description":"

Endpoints that your API must expose when using the Custom Adapter (non-Shopify retailers).

ReturnsDirect by LiquiDonate calls these endpoints directly during return processing. Configure each endpoint path in the admin under Retailer Adapter → Custom API Config.

Endpoint configuration fields

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Field	Description
`baseUrl`	Root URL of your API, e.g. `https://api.acme.com/v1`
`endpointGetOrder`	Path template to fetch a single order, e.g. `/orders/{id}`
`endpointSearchOrders`	Path template to search orders, e.g. `/orders?q={query}`
`endpointGetProducts`	Path template to fetch products by IDs, e.g. `/products?ids={ids}`
`endpointSearchProducts`	Path template to search products, e.g. `/products?q={query}`
`endpointProcessReturn`	Path to process (complete) a return, e.g. `/returns/process`

Authentication

All outbound requests from Liquid to your API include an auth header configured per-retailer (bearer, api_key, basic, or none).

\n","_postman_id":"95a6ec34-c3e3-4714-bf07-716bb84f9e7c"}],"event":[{"listen":"prerequest","script":{"id":"9947ea76-a5d9-4593-b1fc-d1662970eb98","type":"text/javascript","packages":{},"requests":{},"exec":[""]}},{"listen":"test","script":{"id":"a226e881-b6b9-427a-bce4-15a134cb8736","type":"text/javascript","packages":{},"requests":{},"exec":[""]}}],"variable":[{"key":"base_url","value":"https://returns-sandbox.liquidonate.com","description":"ReturnsDirect by LiquiDonate base URL"},{"key":"shop_domain","value":"acme.com","description":"Your shop identifier — must match the value Liquid has on file"},{"key":"webhook_secret","value":"your_shared_secret_here","description":"Shared HMAC-SHA256 secret provisioned by Liquid for your shop"},{"key":"retailer_webhook_url","value":"https://your-system.com/webhooks/returnsdirect-rms","description":"Your endpoint that receives outbound events from ReturnsDirect by LiquiDonate"}]}