Order Tracking via API (Server Side)

Why Choose API Integration?
Authentication
Creating and Updating Orders
Order Parameters
Examples

When integrating manually, you have two options: the order tracking script or server-side integration via our API. The script offers a faster setup, but we strongly recommend using server side for a more secure, flexible, and reliable solution.

Why Choose Server Side Integration?

Using our server side API provides significant advantages over the script/pixel approach:

• Robust: Unlike client-side scripts, server-side API calls cannot be blocked or fail to load, ensuring that no order data is lost.

• Flexible: The API can be integrated with greater versatility across different systems, making it suitable for a wide range of eCommerce setups.

• Secure: The order confirmation script could theoretically be discovered and manipulated by a user. API communication happens server-to-server, making it much more secure.

• Updatable: The API allows you to send order updates, such as when an order is partially refunded or cancelled, keeping your data accurate and current.

Authentication

All API requests require basic authentication. You can create API user credentials in the dashboard under Settings > API Users (https://app.duel.me/app/settings/open-api)

Creating and Updating Orders

Orders are created and updated via our Open API:
https://developers.duel.tech/open-api/ 

For new integrations, we recommend using the PUT upsert endpoint. It handles both creation and updates in a single call, removing the need to track whether an order already exists in Duel.

Recommended: Create or Update an Order

PUT to https://api.duel.me/v1/orders/{order_id}

Send this whenever an order event occurs, regardless of whether the order has already been sent to Duel. The endpoint creates the order if it doesn't exist, or updates it if it does.

The response returns:

• 201 Created if the order was new
• 200 OK if an existing order was updated
• A change_status field in the response body indicating which action was taken

Legacy endpoints: Create an Order

POST to https://api.duel.me/v1/orders

Legacy endpoints: Update an Order

POST to https://api.duel.me/v1/orders/{order_id} with the same parameters and the updated total amount.

• The email and promo parameters are not required for updates, as they were captured at order creation.
• Sending a total of 0 will cancel the order.

Retrieving an Order

GET to https://api.duel.me/v1/orders/{order_id}

Use this endpoint to retrieve a single order by its external order ID. It is useful for verifying that an order reached Duel, checking attribution status, or troubleshooting an integration without contacting support.

The response includes the full order object, including referral, redemption, loyalty, and commission data. Returns a 404 if no order matching that ID exists for your brand.

Required Order Parameters

• order - Order ID
• total - The final order amount, which can be net if the brand chooses to exclude taxes shipping etc
• currency - Order currency
• email - Email of customer placing order. Plain text and hashed emails are both supported. For full hashed email via API information refer to our Hashed Email via API documentation.
• promo - Include if a promo code was applied to the order. If multiple promo codes were used, pass them as an array.
• affiliate - Include if the order came via an affiliate link. Pass the advocate's username or affiliate parameter to mark it accordingly.

Recommended Parameters

• date - Using the ISO 8601 format. If no date is provided, the current date at the time of the request will be used.
• customer_id - ID of customer placing order, used to track life time value
• new_customer - If customer placing order is a new customer pass a value of y or true (boolean)
• total_gross - The order amount before any deductions, including discounts, shipping, and other fees

Optional Parameters

• instore - Mark order as in-store by passing a value of y or true (boolean) 
• points -  can be sent when you want to allocate additional points for a specific order (i.e. when an order is placed by a new customer)
• commission -  can be sent when you want to allocate specific commission for an order (i.e. when an order is placed by a new customer)
• commission_currency - should be sent along with the commission figure above

Examples 

Below are example implementations. If your backend uses a different language, or if there are any problems, please contact us.

.NET

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Threading.Tasks;

static readonly HttpClient client = new HttpClient();

static async Task Main(string[] args)
{
    var values = new Dictionary<string, string>
    {
        // ... Order parameters
    };

    try
    {
        client.BaseAddress = new Uri("https://api.duel.me/");

                var response = client.PostAsync("v1/orders", new StringContent(
                values.ToString(),
                Encoding.UTF8,
                "application/json"));

        var jsonString = await response.Content.ReadAsStringAsync();
    }
    catch (Exception e)
    {
        // Handle exception
    }
}

Node.js

const https = require('https');

const data = JSON.stringify({
  // ... Order parameters
});

const options = {
  hostname: 'api.duel.me',
  path: '/v1/orders',
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Content-Length': Buffer.byteLength(data)
  }
};

const req = https.request(options, (res) => {
  let data = '';

  res.on('data', (chunk) => {
    data += chunk;
  });

  res.on('end', () => {
    const { status, result } = JSON.parse(data);
    // use reponse data for further processing
  });
}).on('error', (err) => {
  // handle error
});

req.write(data);
req.end();

PHP

<?php

$body = json_encode(array(
  // ... Order parameters
));

$curl = curl_init('https://api.duel.me/v1/orders');

curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $body);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));

$result = curl_exec($curl);

?>