This endpoint allows you to send order data to LoudCrowd so that orders can be properly attributed to creators and commissions can be calculated. LoudCrowd uses this data to identify which orders are attributed to creators and calculate the commissions earned from each order.

Note: The Events API is a single endpoint (POST https://api.loudcrowd.com/event/ecomm). Behavior is selected via the X-LC-TOPIC header (ORDER_CREATE, ORDER_UPDATE, ORDER_CANCEL). For refunds/returns specifics, see the Submit Return Event guide.

Prerequisites

Before using this endpoint, ensure that:

• LoudCrowd SDK is installed on your ecommerce site
• LoudCrowd shoppable program has been set up to generate affiliate links

Authentication

The API uses HMAC-SHA256 signature authentication. Each request must include:

• X-LC-SHOP-ID: The Shop ID of the ecommerce integration that owns the order, shown on the LoudCrowd Integrations page. This is not an Account ID or API token.
• X-Signature: Lowercase hexadecimal HMAC-SHA256 of the exact raw request-body bytes, using an API token with the Write orders scope as the HMAC secret
• X-LC-TOPIC: Event type (ORDER_CREATE, ORDER_UPDATE, or ORDER_CANCEL)
• Content-Type: application/json

Sign the exact bytes sent on the wire. Reformatting JSON after calculating the signature changes those bytes and causes authentication to fail. Send the hexadecimal digest directly, without a sha256= prefix.

import hashlib
import hmac
from pathlib import Path

api_token = "YOUR_API_TOKEN"
body = Path("order.json").read_bytes()
signature = hmac.new(api_token.encode("utf-8"), body, hashlib.sha256).hexdigest()

Send order.json unchanged as the request body and use signature as the X-Signature header value.

Topic behavior

Send the complete order payload for every topic. For ORDER_CANCEL, set platform_cancelled_at to the cancellation time and set platform_updated_at to a value later than the preceding event. The topic alone does not mark the order as cancelled.

A 200 response with the body success means the event was authenticated and accepted for asynchronous processing. It does not confirm persistence, attribution, or commission calculation.

Important Notes

Refund Line Item IDs

The refund_line_item_id is crucial for LoudCrowd to distinguish between new refunds and updates. These IDs must be:

• Unique within the ecommerce integration and stable for each original line_item_id
• Reused on later updates to that line item, with cumulative current amount, tax, and quantity
• Different for different original line items

Providing lc_anon_id

If you haven't configured the order confirmation script, you can get the tracking ID using:

window.loudcrowd.identifyDevice();

Gross Taxation Policy

For regions using gross taxation (tax included in price):

• Amount: Send the gross amount (item price with tax included)
• Tax: Send the VAT amount

Use this formula to extract tax from gross amounts:

tax = round(amount - (amount / (1 + tax_rate)), 2)

Where tax_rate is the decimal representation (e.g., 0.2 for 20% VAT).

Best Practices

1. Security: Keep your API token secret and never store it in source code
2. Success verification: Verify every request returns status 200 with the body success
3. Error handling: Log and investigate any other status or body
4. Timing: Send events as soon as orders are placed
5. Consistency: Build a back-fill pipeline alongside the events API
6. Validation: Ensure all required fields are present and properly formatted