Purpose
The following article outlines the API spec for posting order and returns data via LoudCrowd's Events API. This data is required for LoudCrowd to pay your creators. LoudCrowd uses this data to identify orders that are attributed to creators, and calculate commissions earned from each order.
Pre-requisite: LoudCrowd program setup & site installation
For order attribution to work on your ecommerce site, it is required that:
LoudCrowd SDK is installed on your site
LoudCrowd shoppable program has been set up (to generate affiliate links)
Posting Events
Post events to https://api.loudcrowd.com/event/ecomm
Request Headers
X-LC-SHOP-ID: this is the LoudCrowd internal id of the ecomm integration. You can find this in the LoudCrowd dashboard in Integrations
X-Signature: The sha256 hexdigest of the utf-8 encoded json payload
X-LC-TOPIC: either ORDER_CREATE, ORDER_UPDATE, or ORDER_CANCEL
Content-Type: application/json
Request Body
The body of the event data is a utf-8 encoded json object with the following properties.
platform_order_id: Your internal id of the order
platform_customer_id: Your internal id of the customer who purchased the order
email: email of the customer (either email or phone is required)
phone: phone number of the customer (either email or phone is required)
platform_ordered_at: the date+time the order was purchased in ISO 8601 in UTC
platform_updated_at: the date+time the order was most recently updated at in ISO 8601 format in UTC
platform_cancelled_at: the date+time the order was cancelled in UTC. Leave this null otherwise
amount: the total amount of the order incuding tax, shipping, and deductions such as discounts. Does not include refunds/returns.
tax: the total amount of tax paid on the order
shipping: the total amount of shipping paid on the order
currency_code: the currency code of the order in ISO 4217 format
discounts:
code: the code used to apply the discount
type: the type of the discount application. Only DISCOUNT_CODE is supported via events
value_type: Either FIXED_AMOUNT or PERCENTAGE
value: The value of the discount applies to the order.
line_items: The line items purchased in the order. Must have at least 1 line item.
line_item_id: the platform distinct id of the line item
sku: the id of the product purchased
variant_sku: the id of the product variant purchased
amount: the total amount paid for the line item including taxes and any deductions
tax: The total amount of tax paid on the line item
quantity: the number of products purchased
refund_line_items: The line items that have been returned/refunded
refund_line_item_id: the platform distinct id of the return. Note if an order has more than 1 returned line item, all of the refund_line_item_ids for the order should be different.
line_item_id: the platform id of the line item that was returned
platform_refunded_at: the date+time the line item was returned in UTC
sku: the id of the product that was returned
variant_sku: the id of the product variant that was returned
amount: the total amount of the refund incuding tax refunds. This should equal the corresponding line item amount to disqualify the entire line item for commissions
tax: the total amount of tax refunded
quantity: the number of product returned/refunded
lc_anon_id: the value of lc_anon_user_id in browser local storage. This is not required if LoudCrowd's order confirmation script is installed.
Providing lc_anon_id
You can skip this step if you have already configured the order confirmation script
The lc_anon_id is effectively the tracking id of the customer who purchased the order and it is required in order to attribute a creator storefront landing with a conversion event. In order to provide the lc_anon_id in the event data, you will have to use the LoudCrowd embed sdk to pull the value of the tracking id out of local storage when the order confirmation page renders.
Use the following snippet in your order confirmation page to get the tracking id
window.loudcrowd.identifyDevice()
Best Practices
Keep your pre-shared key secret
Anyone with access to the api pre-shared key can create orders and conversion events in LoudCrowd which could be used to report on revenue and assign commissions to creators.Never save your secret key in source code.
Hide your secret key from back-end logging.
Configure access control policies to ensure only authorized individuals can read pre-shared keys on a "need to know" basis.
Encrypt your keys when transfered out of storage. Never share your keys with anyone (including LoudCrowd)
Sending the order event
Look at the api response and the status code of the post request to ensure that LoudCrowd received the event. You should expect a 200 status code response if everything is working properly.Check for 200 status code response.
Handle 400+ status code exceptions.
Build internal logging around status code errors.
Send LoudCrowd an event as soon as an order is placed.
Consistency
To ensure 100% consistency, We recommend building a back-fill pipeline alongside the events API. See Sending order line item data to LoudCrowd for instructions on providing order data via SFTP.
Example Request
Use the following python snippet as an outline for posting order events to LoudCrowd
import json
from hashlib import sha256
import hmac
import requests
sample_order_data = {
"platform_order_id": "123456",
"platform_customer_id": "123456",
"email": "joe@loudcrowd.com",
"phone": "1234567890",
"platform_ordered_at": "2021-01-01T00:00:00Z",
"platform_updated_at": "2021-01-01T00:00:00Z",
"platform_cancelled_at": None,
"amount": "200.00",
"tax": "12.00",
"shipping": "10.00",
"currency_code": "USD",
"discounts": [
{
"code": "JOE15",
"type": "DISCOUNT_CODE",
"value": "15",
"value_type": "PERCENTAGE",
}
],
"line_items": [
{
"line_item_id": "1",
"sku": "SKU1",
"variant_sku": "VARIANT1",
"amount": "100.00",
"tax": "6.00",
"quantity": "2",
},
{
"line_item_id": "2",
"sku": "SKU2",
"variant_sku": "VARIANT2",
"amount": "100.00",
"tax": "6.00",
"quantity": "1",
},
],
"refund_line_items": [
{
"refund_line_item_id": "1",
"line_item_id": "1",
"platform_refunded_at": "2021-01-03T00:00:00Z",
"sku": "SKU1",
"variant_sku": "VARIANT1",
"amount": "100.00",
"tax": "6.00",
"quantity": "1",
},
],
"lc_anon_id": "a8723fbb-7a83-42a7-8198-bfba2be8f7a8",
}
secret_key = "your-secret-key"
payload = json.dumps(sample_order_data).encode("utf-8")
# This should be dc171fa8190193e4fc3653da0e24d5658dfde48d18f6f09cba1e66adbbf87444 for this example
digest = hmac.new(
secret_key.encode("utf-8"), payload, sha256
).hexdigest()
headers={
"X-LC-SHOP-ID": "your-shop-id",
"X-Signature": digest,
"X-LC-TOPIC": "ORDER_CREATE",
"Content-Type": "application/json",
}
response = requests.post(
"https://api.loudcrowd.com/event/ecomm",
headers=headers,
data=payload,
)
print(response.text)
FAQ
For selling regions using a gross taxation policy (ie, that have tax included in the price), how should we handle amount and tax fields?
For each line item:
Amount
Send LoudCrowd the Gross amount, ie item price with the tax included.
Tax
Send LoudCrowd an amount that represents the VAT paid.
If your amount field includes tax here is a formula to extract the tax amount from a gross taxation policy to send VAT to LoudCrowd
tax = round(amount - (amount / (1 + tax_rate)), 2)
Note: If the VAT is 20%, then the tax rate is 0.2 in the above formula
Alternative methods to send attribution data
There are other ways to enable LoudCrowd attribution. Complete these steps: