# Submit Order Event Submit order data to LoudCrowd for attribution and commission calculation. 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](./submit_return_event.md). ## 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**: Your LoudCrowd internal shop ID (found in the LoudCrowd dashboard) - **X-Signature**: SHA256 hexdigest of the UTF-8 encoded JSON payload - **X-LC-TOPIC**: Event type (`ORDER_CREATE`, `ORDER_UPDATE`, or `ORDER_CANCEL`) - **Content-Type**: `application/json` ## Important Notes ### Refund Line Item IDs The `refund_line_item_id` is crucial for LoudCrowd to distinguish between new refunds and existing ones. These IDs must be: - Unique for each line item returned in the order - Consistent between multiple order update events - Different for each refund entity in a single order ### Providing lc_anon_id If you haven't configured the order confirmation script, you can get the tracking ID using: ```javascript 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 pre-shared key secret and never store it in source code 2. **Error Handling**: Always check for 200 status code responses and handle 400+ errors 3. **Logging**: Build internal logging around status code errors 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 # OpenAPI definition ```json { "info": { "title": "LoudCrowd API", "version": "0.0.0", "description": "This API provides access to LoudCrowd's Creator Storefronts and Attribution Events functionality. The Creator Storefronts API is used in place of the creator storefront web-components, and the Attribution Events API enables submission of order and return data for commission calculation.\n", "license": { "name": "MIT", "url": "https://opensource.org/licenses/MIT" } }, "openapi": "3.0.0", "servers": [ { "url": "https://store-api.loudcrowd.com/api", "description": "LoudCrowd Creator Storefronts API" }, { "url": "https://api.loudcrowd.com", "description": "LoudCrowd Attribution Events API" } ], "x-readme": { "explorer-enabled": false }, "paths": { "/event/ecomm": { "post": { "summary": "Submit Order Event", "description": "Submit order data to LoudCrowd for attribution and commission calculation. This endpoint handles order creation, updates, and cancellations.", "operationId": "submit_order_event", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "A unique key to safely retry requests. Requests with the same key and payload within 24 hours are treated as a single operation.", "schema": { "type": "string", "maxLength": 255 } }, { "in": "header", "name": "X-LC-SHOP-ID", "description": "Your LoudCrowd internal shop identifier", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "X-Signature", "description": "The SHA-256 hexadecimal digest of the UTF-8 encoded JSON payload", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "X-LC-TOPIC", "description": "Specifies the event type", "required": true, "schema": { "type": "string", "enum": [ "ORDER_CREATE", "ORDER_UPDATE", "ORDER_CANCEL" ] } }, { "in": "header", "name": "Content-Type", "description": "Content type of the request", "required": true, "schema": { "type": "string", "default": "application/json" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "platform_order_id", "platform_customer_id", "platform_ordered_at", "platform_updated_at", "amount", "currency_code", "line_items" ], "properties": { "platform_order_id": { "type": "string", "description": "Your internal identifier for the order" }, "platform_customer_id": { "type": "string", "description": "Your internal identifier for the customer who placed the order" }, "email": { "type": "string", "format": "email", "description": "Customer's email address. Either email or phone is required." }, "phone": { "type": "string", "description": "Customer's phone number. Either email or phone is required." }, "platform_ordered_at": { "type": "string", "format": "date-time", "description": "The date and time when the order was placed, in ISO 8601 format (UTC)" }, "platform_updated_at": { "type": "string", "format": "date-time", "description": "The date and time when the order was last updated, in ISO 8601 format (UTC)" }, "platform_cancelled_at": { "type": "string", "format": "date-time", "nullable": true, "description": "The date and time when the order was cancelled, in ISO 8601 format (UTC). Set to null if not applicable." }, "amount": { "type": "number", "description": "Total amount of the order, including tax, shipping, and discounts. Excludes refunds/returns." }, "tax": { "type": "number", "description": "Total tax amount for the order" }, "shipping": { "type": "number", "description": "Total shipping cost for the order" }, "currency_code": { "type": "string", "description": "Currency code of the order, in ISO 4217 format" }, "discounts": { "type": "array", "description": "Array of discount objects applied to the order", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Discount code used" }, "type": { "type": "string", "enum": [ "DISCOUNT_CODE" ], "description": "Type of discount application" }, "value_type": { "type": "string", "enum": [ "FIXED_AMOUNT", "PERCENTAGE" ], "description": "Type of discount value" }, "value": { "type": "number", "description": "Value of the discount applied" } }, "required": [ "code", "type", "value_type", "value" ] } }, "line_items": { "type": "array", "description": "Array of line item objects representing products purchased in the order", "items": { "type": "object", "required": [ "line_item_id", "sku", "amount", "quantity" ], "properties": { "line_item_id": { "type": "string", "description": "Platform-specific identifier for the line item" }, "sku": { "type": "string", "description": "SKU of the product purchased" }, "variant_sku": { "type": "string", "description": "SKU of the product variant purchased" }, "amount": { "type": "number", "description": "Total amount paid for the line item, including taxes and deductions" }, "tax": { "type": "number", "description": "Total tax amount for the line item" }, "quantity": { "type": "integer", "description": "Number of units purchased for this line item" } } } }, "refund_line_items": { "type": "array", "description": "Array of refund line item objects representing returned or refunded products", "items": { "type": "object", "required": [ "refund_line_item_id", "line_item_id", "platform_refunded_at", "sku", "amount", "quantity" ], "properties": { "refund_line_item_id": { "type": "string", "description": "Platform-specific identifier for the refund line item. Each refund line item ID must be unique within the order." }, "line_item_id": { "type": "string", "description": "Identifier of the original line item that was refunded" }, "platform_refunded_at": { "type": "string", "format": "date-time", "description": "Date and time when the line item was refunded, in ISO 8601 format (UTC)" }, "sku": { "type": "string", "description": "SKU of the product refunded" }, "variant_sku": { "type": "string", "description": "SKU of the product variant refunded" }, "amount": { "type": "number", "description": "Total amount refunded for the line item, including tax refunds" }, "tax": { "type": "number", "description": "Total tax amount refunded for the line item" }, "quantity": { "type": "integer", "description": "Number of units refunded for this line item" } } } }, "lc_anon_id": { "type": "string", "description": "Value of lc_anon_user_id from browser local storage. This is optional if LoudCrowd's order confirmation script is installed." } } } } } }, "responses": { "200": { "description": "Event submitted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Event submitted successfully" } } } } } }, "400": { "description": "Bad request - Invalid data provided", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Invalid request data" } } } } } }, "401": { "description": "Unauthorized - Invalid authentication", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Invalid authentication" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Internal server error" } } } } } } } } } }, "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Authorization header using the Bearer scheme. Example: \"Authorization: Bearer {token}\"" } } } } ```