Overview
This guide explains how non-Shopify customers and Shopify customers that have not connected their store to Aspire can integrate with Aspire's API to send order details for link-based conversions.
This integration is required to:
Use Products or Collections as conditions when creating commission payout rules (learn more here).
Enable automatic currency conversions for non-USD orders.
Note: You must also implement one of Aspire's conversion tracking methods and pass the order ID using the parameter adv_unique1 for each conversion.
For Non-Shopify Brands
Follow the steps below to integrate with Aspire's API.
Request a Secret Key. Contact Aspire's Support team to request your secret key, which is used for API authentication.
Send Order Data via POST Request. Ask your web development or engineering team to configure a POST request to Aspire's API and send the order payload in the following structure:
orderDetails = {
"orderId": string,
"data": {
"orderValue": number,
"currency": string,
"productDetails": [
{
"id": string,
"name": string,
"price": number,
"collectionId": string
}
]
}
}
Example: If a customer places an order for Jeans ($100 USD) and a Shirt ($50 USD) through your website, you would send the order details in the following format:
orderDetails = {
"orderId"!: 012345,
"data": {
"orderValue": 150,
"currency": "USD",
"productDetails"!: [
{
"id"!: 09876,
"name": "Jeans",
"price": 100,
"collectionId": number | null
},
{
"id"!: 064643,
"name": "Shirt",
"price": 50
}
]
}
}
Below is an example script for non-Shopify customers.
async function recordConversionInAspire() {
try {
const response = await fetch(`https://services.aspireiq.com/v1/sales_tracking/order/details/webhook`, {
method: "POST",
headers: {
"Content-Type": "application/json",
"x-client-secret": "XXXXXXXX", // Add the secret key provided by Aspire
"Origin": window.location.origin, // Add the origin header
},
body: JSON.stringify({
orderId: "ORD_21213",
data: {
orderSubtotal: 1349.50,
currency: "USD",
productDetails: [{
id: "gid-123",
name: "Laptop",
subtotal: 300,
quantity: 2,
collections: [
{id: 123, name: "Collection-One"},
{id: 123, name: "Collection-Two"}
]
},
{
id: "gid-123",
name: "Laptop",
subtotal: 300,
quantity: 2,
collections: [
{id: 123, name: "Collection-One"},
{id: 123, name: "Collection-Two"}
]
}
]
}
}),
});
if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}
const data = await response.json();
console.log("Conversion recorded in Aspire", data);
return data;
} catch (error) {
console.error("Error when recording conversion in Aspire", error);
throw error; // Re-throw the error for proper error handling
}
}
Important: The currency field must follow standard ISO 4217 codes (e.g., "EUR", not "EUROS").
For Shopify Brands
If your Shopify store is not connected to Aspire, and you don’t plan to connect it, you must integrate with Aspire's API to send order details for link-based conversions in order to:
Use Products or Collections as conditions for commission payout rules.
Enable automatic currency conversions for non-USD orders.
Follow the steps below to integrate with Aspire's API.
Request a Secret Key. Contact Aspire's Support team to request your secret key, which is used for API authentication.
Create a Custom Pixel in Shopify*
From your Shopify admin, go to Settings > Customer Events.
Click Add Custom Pixel.
Enter a name, such as "Aspire API", then click Add Pixel.
In the Code area, remove the placeholder text and enter the code below.
Click Save in the banner, then Connect the pixel.
*Note: If you have already created a custom pixel in Shopify to install Aspire's Javascript tracking, you can modify your existing pixel to include both scripts. See here.
async function recordConversionInAspire() {
try {
const response = await fetch(`{{ASPIRE_API_URL}}/v1/sales_tracking/order/details/webhook`, {
method: "POST",
headers: {
"Content-Type": "application/json",
"ngrok-skip-browser-warning": true,
"Authorization": "XXXXXXXXXXXXX", // Enter the secret key provided by Aspire
"Origin": window.location.origin, // Add the origin header
},
mode: "cors", // Explicitly set CORS mode
body: JSON.stringify({
orderId: event.data.checkout.order.id,
data: {
orderValue: event.data.checkout.subtotalPrice.amount,
currency: event.data.checkout.subtotalPrice.currencyCode,
productDetails: event.data.checkout.lineItems.map((item) => ({
id: item.variant.product.id,
name: item.variant.product.title,
price: item.variant.price.amount,
quantity: item.quantity,
})),
}
}),
});
if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}
const data = await response.json();
console.log("Conversion recorded in Aspire", data);
return data;
} catch (error) {
console.error("Error when recording conversion in Aspire", error);
throw error; // Re-throw the error for proper error handling
}
}Custom Pixel with Javascript Code + Aspire's API Script
Replace the code in your current Custom Pixel with the one below.
!function(){
var o = window.tdl = window.tdl || [];
if (o.invoked) window.console && console.error && console.error("Tune snippet has been included more than once.");
else {
o.invoked = !0;
o.methods = ["init", "identify", "convert"];
o.factory = function(n){
return function(){
var e = Array.prototype.slice.call(arguments);
e.unshift(n), o.push(e), o
}
};
for(var e = 0; e < o.methods.length; e++){
var n = o.methods[e];
o[n] = o.factory(n)
}
o.init = function(e){
var n = document.createElement("script");
n.type = "text/javascript", n.async = !0;
n.src = "https://js.go2sdk.com/v2/tune.js";
var t = document.getElementsByTagName("script")[0];
t.parentNode.insertBefore(n, t), o.domain = e
}
}
}();
tdl.init("https://aspireiq.go2cloud.org")
analytics.subscribe('checkout_completed', (event) => {
async function recordConversion(){
const cartSubtotalCurrencyCode = event.data.checkout.subtotalPrice.currencyCode;
let cartSubtotal = event.data.checkout.subtotalPrice.amount;
let cartSubtotalUSD = cartSubtotal;
console.log({cartSubtotalUSD, eventCheckout: event.data.checkout.subtotalPrice.amount, cartSubtotalCurrencyCode, event: event.data.checkout});
tdl.convert({
'amount': cartSubtotalUSD,
'adv_unique1': event.data.checkout.order.id,
});
}
async function recordConversionInAspire() {
try {
const response = await fetch(`https://services.aspireiq.com/v1/sales_tracking/order/details/webhook`, {
method: "POST",
headers: {
"Content-Type": "application/json",
"x-client-secret": "XXXXXXX",
"Origin": window.location.origin, // Add the origin header
},
body: JSON.stringify({
orderId: event.data.checkout.order.id,
data: {
orderSubtotal: event.data.checkout.subtotalPrice.amount,
currency: event.data.checkout.subtotalPrice.currencyCode,
productDetails: event.data.checkout.lineItems.map((item) => ({
id: item.variant.product.id,
name: item.variant.product.title,
subtotal: item.variant.price.amount,
quantity: item.quantity,
collections: item.variant.product?.collections?.map((collection) => {
return {
id: collection.id,
name: collection.title,
}
}),
})),
}
}),
});
if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}
const data = await response.json();
console.log("Conversion recorded in Aspire", data);
return data;
} catch (error) {
console.error("Error when recording conversion in Aspire", error);
throw error; // Re-throw the error for proper error handling
}
}
recordConversion()
recordConversionInAspire()
});