Introduction
Purpose: Use this endpoint when a customer completes a purchase.
Context: For brands and developers who want to integrate their e-commerce platform with SocialLadder’s referral attribution system.
⚠️ Note: This requires technical setup. Involve your IT/development team.
Endpoint
POST /api/v2/conversion
Query Parameters
Parameter | Required | Description |
apiKey | Yes | Your API key |
conversionCookieGUID | Optional | Used for cookie-based attribution. You'll learn how to retrieve this information in a separate section at the end of the article. |
Example Request Body
JSON
{
"TransId": "ORDER-12345",
"ShopCode": "YOUR_SHOP_CODE",
"PromoCode": "AMB-SARAH-10",
"EmailAddress": "customer@example.com",
"TransAmount": 150.00,
"TransUnits": 3,
"Action": "SALE",
"CustomerID": "CUST-789",
"CustomerFirstName": "John",
"CustomerLastName": "Doe",
"SaleDate": "2025-01-15T14:30:00Z",
"IsResidual": false,
"ProductList": [
{
"ExternalID": "PROD-001",
"ExternalLineNumber": 1,
"SKU": "SHIRT-BLU-M",
"Value": 49.99,
"Units": 1,
"Currency": "USD",
"ProductName": "Blue Cotton Shirt",
"ProductTitle": "Cotton Shirt",
"VariantTitle": "Blue / Medium",
"TagList": [
"t-shirts"
],
"TagListString": "t-shirts",
}
]
}
Request Body – Field Reference
Field | Type | Required | Description |
TransId | string | Yes | Your unique order/transaction ID. Must be idempotent (do not reuse across different orders). |
ShopCode | string | Yes | Provided by your SocialLadder representative, it should be unique per campaign. |
PromoCode | string | Yes* | Promo/discount code used at checkout. Used for primary attribution when present. *Required if you are using promo-code-based attribution. |
EmailAddress | string | No | Customer email address. Used for email-based attribution when promo/cookie aren’t available. |
TransAmount | decimal | Yes* | Total transaction amount. *If ProductList is provided, this can be auto-calculated from line items. |
TransUnits | int | Yes* | Total number of units in the order. *Also auto-calculated when ProductList is provided. |
Action | string | Yes | Transaction type must be "SALE”. |
CustomerID | string | No | Your internal customer identifier (e.g., CRM or e-commerce customer ID). Useful for reconciliation and lifecycle tracking. |
CustomerFirstName | string | No | Customer first name. Optional but recommended for better reporting. |
CustomerLastName | string | No | Customer last name. Optional but recommended. |
SaleDate | string | No | Date/time of the sale. If omitted, SocialLadder uses the current server time. Format example: 2025-01-15T14:30:00Z. |
IsResidual | bool | No | Set to true for recurring/subscription payments related to an original order. Set to false (or omit) for the first transaction. |
OriginalOrderId | string | No | When IsResidual = true, this should reference the original TransId of the first order so residual commissions are linked correctly. |
OverridePointValue | int | No | Optional override for the default points calculation. When provided, SocialLadder uses this value instead of campaign rules. |
ProductList | array | No | List of product/line-item objects. Strongly recommended for product-level attribution, SKU-based rules, and detailed reporting. See table below. |
UDF9 – UDF14 | string | No | User-defined fields for passing custom metadata (e.g., sales channel, region, coupon stack, internal flags). These are stored and can be surfaced in reporting or exports. |
ProductList – Field Reference
You can place this right after the ProductList example JSON.
Each entry in ProductList represents a single line item in the order.
Field | Type | Required | Description |
ExternalID | string | No | Your internal line item or product row ID. Helpful for reconciliation with your order system. |
ExternalLineNumber | int | No | Line number in the order (e.g., 1, 2, 3). Useful for consistent ordering in reports. |
SKU | string | Yes (recommended) | Product SKU. Important if you want to use SKU-based rules or reporting in SocialLadder. |
Value | decimal | Yes | Monetary value of this line item (typically unit price × quantity, including or excluding tax depending on your configuration). |
Units | int | Yes | Quantity of this product in this order. |
Currency | string | Yes | 3-letter currency code (e.g., USD, EUR). |
ProductName | string | No | Descriptive product name (e.g., “Blue Cotton Shirt”). |
ProductTitle | string | No | Shorter marketing or catalog title, if different. |
VariantTitle | string | No | Variant information (e.g., size/color: “Blue / Medium”). |
TagList | array | No | A list of tags present in this item. Tags can be used by compensation rules, like paying extra commission for certain product lines. |
TagListString | string | No | A comma-separated string that represents the list of tags of this item. |
UDF1 – UDF8 | string | No | User-defined fields for passing custom metadata (e.g., product line, material, internal flags). These are stored and can be surfaced in reporting or exports. |
Successful Response
JSON
{
"Result": 1,
"ResultMessage": "Conversion successfully recorded and attributed"
}
Common Error Responses
JSON
{
"Result": 0,
"ResultMessage": "Unable to attribute conversion - no matching ambassador found"
}
{
"Result": 0,
"ResultMessage": "Invalid ApiKey for Shop Code"
}
Updating an Existing Conversion (Refunds & Modifications)
Use the Update endpoint when an order already sent to SocialLadder changes — for example, when issuing a refund, canceling an item, or modifying order totals.
The Update request accepts the same full schema as the Insert (POST) request, with one additional optional field: Reason.
When updating an order, you must send the new final state of the order — not the difference or refund amount.
Endpoint
PUT /api/v2/conversion
Example Request
JSON
{
"TransId": "ORDER-12345",
"ShopCode": "YOUR_SHOP_CODE",
--All fields, representing the final state you want for the sale
"Reason": "Partial refund - 1 item returned"
}
Important Notes
Always send the new final values, not deltas.
SocialLadder recalculates ambassador payouts automatically.
Successful Response
JSON
{
"Result": 1,
"ResultMessage": "Conversion updated successfully. Compensation adjusted."
}
Retrieving Conversion History
Use this endpoint for reconciliation, reporting, or syncing with your system.
Endpoint
GET /api/v2/conversion
Query Parameters
Parameter | Description |
beforeID | For pagination |
orderId | Return only a specific order |
trackingKey | Filter by referral tracking key |
showDeletedProducts | Include returned items |
minUpdateDate | Only conversions updated after this timestamp |
Example Request
GET /api/v2/conversion?apiKey=YOUR_API_KEY&showDeletedProducts=true&minUpdateDate=2025-01-01T00:00:00Z
Pagination
Up to 200 conversions per request
Use the PreviousPageURL field to continue fetching additional pages
How to retrieve a conversion cookie
Before moving on, it’s important to understand why retrieving the conversion cookie matters in the manual API flow.
When your site uses our tracking scripts—such as in pixel-based setups or native integrations like Shopify—SocialLadder automatically handles cookie creation and retrieval in the background. However, when you submit purchases directly to our APIs, you’re responsible for capturing this cookie at checkout and including it in your request.
This cookie contains the unique identifier that allows us to tie a sale back to the ambassador whose referral link initiated the session. Without it, we cannot attribute the conversion correctly. Now that you’ve added the tracking script and know how to read the cookie, the next step is ensuring this value is passed to our API whenever a purchase is completed.
Step 1: Add the SocialLadder Tracking Script
Make sure the following script is embedded on all public-facing pages, especially on landing pages and product pages:
HTML
<script src="https://socialladder.rkiapps.com/ecom/socialladder-ecom.js" type="text/javascript"></script>
This script sets a cookie named:
sl-track-purchase
Step 2: Read the Cookie in Your Frontend Code
In your frontend JavaScript (when preparing the checkout or order payload), read the value of the cookie using the function below:
JavaScript
function getSocialLadderCookie() {
const name = 'sl-track-purchase';
const cookies = decodeURIComponent(document.cookie).split(';');
for (let c of cookies) {
c = c.trim();
if (c.startsWith(name)) {
return c.substring(name.length);
}
}
return null;
}
Now, when you’re trying to add or update an order through the endpoint /api/v2/conversion, you'll have to pass the value of this cookie in the parameter conversionCookieGUID.
Best Practices
✓ Always send product-level data
Improves reporting for you and for ambassadors, and enables product-based commission rules.
✓ Use unique transaction IDs
TransId must be unique for every order.
✓ Implement retry logic
Network interruptions happen—use exponential backoff.
✓ Log every API request & response
Essential for debugging and reconciliation.
✓ Reconcile regularly
Use the GET endpoint daily to verify no orders were missed.
Testing Checklist
Before going live:
Submit a test order with a valid promo code
Submit a test order without a promo code
Test refunds
Test duplicate TransId handling
Verify product list ingestion
Test pagination
Test large orders
Test special characters
Verify attribution in dashboard
Conclusion
The SocialLadder Conversion API provides a flexible, accurate way to track sales, attribute referrals, and calculate ambassador compensation. By following the recommendations in this guide—especially around unique transaction IDs, product-level data, and proper error handling—you’ll ensure a reliable and scalable integration.
If you have any questions, your SocialLadder representative is always there to help.