Submit Return Event

This guide explains how to submit return and refund data to LoudCrowd so commissions are correctly adjusted when items are returned. These requests use the same single endpoint as order events and are selected by header.

• Endpoint: POST https://api.loudcrowd.com/event/ecomm
• Topic header: X-LC-TOPIC: ORDER_UPDATE
• Authentication and base payload: see Submit Order Event

Important Notes

Refund Line Item ID Management

The refund_line_item_id is critical for proper commission tracking:

• One stable ID per line item: Assign a refund_line_item_id that is unique within the ecommerce integration to each original line_item_id.
• Cumulative updates: Reuse that ID on later updates and send the current cumulative amount, tax, and quantity refunded for the line item.
• Different original line items: Use different refund IDs for different original line items. Do not issue a second refund ID for the same original line item.

Commission Adjustment Logic

When processing returns:

1. Full Refund: If the refund amount equals the line item amount, the entire line item is disqualified for commissions.
2. Partial Refund: If the refund amount is less than the line item amount, commissions are adjusted proportionally.
3. Multiple Refunds: Update the stable refund record for an original line item with cumulative values; use separate IDs only for different original line items.

Order Amount Updates

When submitting return events:

• Keep amount, tax, and shipping as the order's gross values before refunds. LoudCrowd subtracts the supplied refund amounts separately.
• Update platform_updated_at to the current timestamp.
• Include all original line_items plus the new refund_line_items.

Common Scenarios

The following examples are independent scenarios. For later updates to the same original line item, reuse its refund ID and send cumulative values.

Full Item Return

{
  "refund_line_item_id": "REFUND_001",
  "line_item_id": "1",
  "platform_refunded_at": "2021-01-03T10:00:00Z",
  "sku": "SKU1",
  "variant_sku": "VARIANT1",
  "amount": "100.00",
  "tax": "6.00",
  "quantity": "2"
}

Partial Item Return

{
  "refund_line_item_id": "REFUND_002",
  "line_item_id": "1",
  "platform_refunded_at": "2021-01-03T10:00:00Z",
  "sku": "SKU1",
  "variant_sku": "VARIANT1",
  "amount": "50.00",
  "tax": "3.00",
  "quantity": "1"
}