How do I use the Giveaway Ninja API?

https://api.giveaway.ninja

{ "status": "TooManyRequests", "retryAfterSeconds": 23 }

# cURL
curl -A "MyStore-Integration/1.0" ...

# Node.js (fetch or axios)
headers: { 'Content-Type': 'application/json', 'User-Agent': 'MyStore-Integration/1.0' }

# Python (requests)
requests.post(url, json=payload, headers={'User-Agent': 'MyStore-Integration/1.0'})

# PHP (cURL)
curl_setopt($ch, CURLOPT_USERAGENT, 'MyStore-Integration/1.0');

curl -X POST "https://api.giveaway.ninja/api/server/addUserEntries" \
  -A "MyStore-Integration/1.0" \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "your_private_api_key",
    "giveawayId": "your_giveaway_id",
    "email": "user@example.com",
    "entries": 10,
    "description": "Bonus entries for VIP customer"
  }'

{
  "status": "Success",
  "data": {
    "totalEntries": 135,
    "saleValue": 487.50,
    "emailConfirmed": "true",
    "referralId": "XYZ1234",
    "referralCount": 8
  }
}

curl -X POST "https://api.giveaway.ninja/api/server/addUserEntriesBatch" \
  -A "MyStore-Integration/1.0" \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "your_private_api_key",
    "giveawayId": "your_giveaway_id",
    "users": [
      { "email": "anna@example.com", "entries": 140, "description": "FX correction order #1001 (CAD)" },
      { "email": "ben@example.com", "entries": -20, "description": "FX correction order #1002 (GBP)" },
      { "email": "nobody@example.com", "entries": 5 }
    ]
  }'

{
  "status": "Success",
  "data": {
    "processed": 3,
    "succeeded": 2,
    "failed": 1,
    "entriesApplied": 120,
    "results": [
      { "email": "anna@example.com", "status": "Success", "entries": 140, "totalEntries": 640 },
      { "email": "ben@example.com", "status": "Success", "entries": -20, "totalEntries": 80 },
      { "email": "nobody@example.com", "status": "GiveawayOrUserNotFound" }
    ]
  }
}

curl -X POST "https://api.giveaway.ninja/api/server/getUserInfo" \
  -A "MyStore-Integration/1.0" \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "your_private_api_key",
    "giveawayId": "your_giveaway_id",
    "email": "user@example.com"
  }'

{
  "status": "Success",
  "data": {
    "email": "user@example.com",
    "totalEntries": 640,
    "saleValue": 487.50,
    "saleCurrency": "USD",
    "emailConfirmed": "true",
    "referralId": "XYZ1234",
    "referralCount": 8,
    "orders": [
      {
        "orderId": "5001",
        "orderPoints": "360",
        "validation": "{\"OrderId\":\"5001\",\"OrderSource\":\"shopify\",\"OrderPoints\":360,\"TotalPoints\":360,\"AttributionMethod\":\"subtotal\", ...}",
        "date": "2026-11-12T14:03:22.1234567Z"
      }
    ],
    "apiEntries": [
      { "entries": 140, "description": "FX correction order #5001 (CAD)", "date": "2026-11-12T14:15:02.0000000Z" }
    ]
  }
}

curl -X POST "https://api.giveaway.ninja/api/server/listOrders" \
  -A "MyStore-Integration/1.0" \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "your_private_api_key",
    "giveawayId": "your_giveaway_id",
    "since": "2026-11-30T00:00:00Z",
    "limit": 200
  }'

{
  "status": "Success",
  "data": {
    "count": 2,
    "hasMore": true,
    "nextCursor": "639012345678901234-672a1b2c3d4e5f6a7b8c9d0e",
    "orders": [
      {
        "id": "672a1b2c3d4e5f6a7b8c9d0d",
        "orderId": "5001",
        "date": "2026-11-30T08:12:41.0000000Z",
        "status": "entries",
        "email": "anna@example.com",
        "giveawayId": "your_giveaway_id",
        "entries": 360,
        "vipSignupBonusEntries": 0,
        "orderTotal": 72.00,
        "currency": "USD",
        "source": "web",
        "giftCardAmount": 0,
        "validation": "{\"OrderId\":\"5001\",\"OrderPoints\":360,\"TotalPoints\":360,\"AttributionMethod\":\"subtotal\", ...}"
      },
      {
        "id": "672a1b2c3d4e5f6a7b8c9d0e",
        "orderId": "5002",
        "date": "2026-11-30T08:14:02.0000000Z",
        "status": "no-user",
        "email": "guest@example.com",
        "giveawayId": "",
        "entries": 0,
        "vipSignupBonusEntries": 0,
        "orderTotal": 40.00,
        "currency": "USD",
        "source": "web",
        "giftCardAmount": 0,
        "validation": "No matching giveaway user found"
      }
    ]
  }
}

async function listOrdersSince(since) {
  const all = [];
  let cursor = '';
  do {
    const res = await fetch('https://api.giveaway.ninja/api/server/listOrders', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json', 'User-Agent': 'MyStore-Integration/1.0' },
      body: JSON.stringify({ apiKey: process.env.GN_PRIVATE_KEY, giveawayId: 'YOUR_GIVEAWAY_ID', since, limit: 500, cursor })
    });
    const body = await res.json();
    if (body.status === 'TooManyRequests') {
      await new Promise(r => setTimeout(r, (body.retryAfterSeconds || 60) * 1000));
      continue;
    }
    if (body.status !== 'Success') throw new Error('listOrders: ' + body.status);
    all.push(...body.data.orders);
    cursor = body.data.hasMore ? body.data.nextCursor : '';
  } while (cursor);
  return all;
}

{
  "status": "Success",
  "data": {
    "totalEntries": 125,
    "saleValue": 487.50,
    "emailConfirmed": "true",
    "referralId": "XYZ1234",
    "referralCount": 8,
    "orders": [
      {
        "orderId": "5001",
        "orderPoints": "50",
        "validation": "{\"OrderId\":\"5001\",\"OrderSource\":\"shopify\",\"OrderSourceResult\":{\"Description\":\"Valid order\",\"IsValid\":true},\"OrderPoints\":50,\"OrderPointsDescription\":\"Entries per currency spent: 1 points per 3 USD (subtotal)\",\"BundleRulePoints\":0,\"BundleRuleResults\":[],\"PurchaseRulePoints\":10,\"TotalPoints\":60,\"PurchasePeriodResult\":null,\"AovBoosterResult\":null,\"OrderDateRangeResult\":{\"Description\":\"Order within valid date range\",\"IsValid\":true},\"MinimumOrderValueResult\":{\"Description\":\"Minimum order value reached\",\"IsValid\":true},\"AttributionMethod\":\"subtotal\",\"PurchaseRuleResults\":[\"Product X matched: +10 points\"],\"GiftCardAmount\":null,\"GiftCardInfo\":null}"
      }
    ]
  }
}

fetch('https://api.giveaway.ninja/api/client/getUserInfo', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    giveawayId: 'YOUR_GIVEAWAY_ID',
    apiKey: 'YOUR_PUBLIC_API_KEY',
    email: 'customer@example.com'
  })
})
.then(response => response.json())
.then(data => {
  if (data.status === 'Success') {
    console.log('Total entries:', data.data.totalEntries);
    console.log('Referral code:', data.data.referralId);
    console.log('Orders:', data.data.orders);
  } else {
    console.error('API error:', data.status);
  }
})
.catch(error => console.error('Request failed:', error));

<div id="giveaway-info">
  <p>Loading...</p>
</div>

<script>
(function() {
  var container = document.getElementById('giveaway-info');

  fetch('https://api.giveaway.ninja/api/client/getUserInfo', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      giveawayId: 'YOUR_GIVEAWAY_ID',
      apiKey: 'YOUR_PUBLIC_API_KEY',
      email: '{{ customer.email }}'  // Shopify Liquid variable
    })
  })
  .then(function(r) { return r.json(); })
  .then(function(data) {
    if (data.status === 'Success') {
      var d = data.data;
      container.innerHTML =
        '<p><strong>Total Entries:</strong> ' + d.totalEntries + '</p>' +
        '<p><strong>Sale Value:</strong> $' + d.saleValue.toFixed(2) + '</p>' +
        '<p><strong>Referral Code:</strong> ' + d.referralId + '</p>' +
        '<p><strong>Referrals:</strong> ' + d.referralCount + '</p>';
    } else if (data.status === 'GiveawayOrUserNotFound') {
      container.innerHTML = '<p>No giveaway data found for this user.</p>';
    } else {
      container.innerHTML = '<p>Error: ' + data.status + '</p>';
    }
  })
  .catch(function(err) {
    container.innerHTML = '<p>Could not load giveaway data.</p>';
  });
})();
</script>

{
  "status": "Success",
  "data": {
    "totalEntries": 15,
    "ruleType": "quantity",
    "ruleEntries": 5,
    "ruleQuantity": 1,
    "ruleAmount": 0,
    "multiplier": 2,
    "orderRuleEntries": 10,
    "orderRuleAmount": 1,
    "hasOrderRule": true,
    "rewardAmountSpent": 1,
    "isExpired": false,
    "bonusOrderEntries": 50,
    "bonusOrderEntriesOver": 100.00,
    "aovMultiplier": 1,
    "isAovBooster": false,
    "aovExcludeFromOrderTotal": false
  }
}

// Calculate entries for a single product
// price = unit price in cents (Shopify format: $50.00 = 5000)
fetch('https://api.giveaway.ninja/api/client/calculateEntries', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    giveawayId: 'YOUR_GIVEAWAY_ID',
    apiKey: 'YOUR_PUBLIC_API_KEY',
    productId: '7654321',
    variantId: '43210987',
    quantity: 1,
    price: 5000  // $50.00 in cents
  })
})
.then(response => response.json())
.then(data => {
  if (data.status === 'Success') {
    console.log('Entries for this product:', data.data.totalEntries);
    console.log('Rule type:', data.data.ruleType);
    console.log('Time multiplier:', data.data.multiplier + 'x');

    if (data.data.isExpired) {
      console.log('Giveaway has ended');
    }
  } else {
    console.error('API error:', data.status);
  }
})
.catch(error => console.error('Request failed:', error));

<div id="entries-badge" style="display:none; padding:10px; background:#f0fff0; border:1px solid #ccc; border-radius:6px;">
  <span id="entries-count"></span> entries with this product
</div>

<script>
(function() {
  // Replace with your actual values or use Shopify Liquid variables
  var productId = '{{ product.id }}';
  var variantId = '{{ product.selected_or_first_available_variant.id }}';
  var price = {{ product.selected_or_first_available_variant.price }};  // Already in cents in Liquid

  fetch('https://api.giveaway.ninja/api/client/calculateEntries', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      giveawayId: 'YOUR_GIVEAWAY_ID',
      apiKey: 'YOUR_PUBLIC_API_KEY',
      productId: productId,
      variantId: variantId,
      quantity: 1,
      price: price
    })
  })
  .then(function(r) { return r.json(); })
  .then(function(data) {
    if (data.status === 'Success' && data.data.totalEntries > 0) {
      document.getElementById('entries-count').textContent = data.data.totalEntries;
      document.getElementById('entries-badge').style.display = 'block';
    }
  })
  .catch(function(err) {
    console.error('Failed to load entries:', err);
  });
})();
</script>

{
  "status": "Success",
  "data": [
    {
      "productId": "7654321",
      "variantId": "43210987",
      "status": "Success",
      "totalEntries": 15,
      "ruleType": "quantity",
      "ruleEntries": 5,
      "ruleQuantity": 1,
      "ruleAmount": 0,
      "multiplier": 2,
      "orderRuleEntries": 10,
      "orderRuleAmount": 1,
      "hasOrderRule": true,
      "rewardAmountSpent": 1,
      "isExpired": false,
      "bonusOrderEntries": 50,
      "bonusOrderEntriesOver": 100.00,
      "aovMultiplier": 1,
      "isAovBooster": false,
      "aovExcludeFromOrderTotal": false
    }
  ]
}

// Calculate entries for multiple products in one request
// Ideal for collection pages to avoid multiple API calls
fetch('https://api.giveaway.ninja/api/client/calculateEntriesBatch', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    giveawayId: 'YOUR_GIVEAWAY_ID',
    apiKey: 'YOUR_PUBLIC_API_KEY',
    products: [
      { productId: '111', variantId: '222', quantity: 1, price: 2500 },
      { productId: '333', variantId: '444', quantity: 1, price: 4900 },
      { productId: '555', variantId: '666', quantity: 1, price: 7500 }
    ]
  })
})
.then(response => response.json())
.then(data => {
  if (data.status === 'Success') {
    data.data.forEach(function(product) {
      console.log('Product ' + product.productId + ': ' +
        product.totalEntries + ' entries (' + product.status + ')');
    });
  }
})
.catch(error => console.error('Request failed:', error));

<!-- Place badges inside your product grid items -->
<div class="product-grid">
  <div class="product-card" data-product-id="111" data-variant-id="222" data-price="2500">
    <p>Product A - $25.00</p>
    <span class="entry-badge" style="display:none;"></span>
  </div>
  <div class="product-card" data-product-id="333" data-variant-id="444" data-price="4900">
    <p>Product B - $49.00</p>
    <span class="entry-badge" style="display:none;"></span>
  </div>
</div>

<script>
(function() {
  var cards = document.querySelectorAll('.product-card');
  var products = [];

  cards.forEach(function(card) {
    products.push({
      productId: card.dataset.productId,
      variantId: card.dataset.variantId,
      quantity: 1,
      price: parseInt(card.dataset.price)
    });
  });

  fetch('https://api.giveaway.ninja/api/client/calculateEntriesBatch', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      giveawayId: 'YOUR_GIVEAWAY_ID',
      apiKey: 'YOUR_PUBLIC_API_KEY',
      products: products
    })
  })
  .then(function(r) { return r.json(); })
  .then(function(data) {
    if (data.status === 'Success') {
      data.data.forEach(function(result, i) {
        if (result.status === 'Success' && result.totalEntries > 0) {
          var badge = cards[i].querySelector('.entry-badge');
          badge.textContent = result.totalEntries + ' entries';
          badge.style.display = 'inline-block';
        }
      });
    }
  })
  .catch(function(err) { console.error('Batch request failed:', err); });
})();
</script>

{
  "status": "Success",
  "data": {
    "totalEntries": 45,
    "orderPoints": 20,
    "bundleRulePoints": 10,
    "purchaseRulePoints": 15,
    "multiplier": 1,
    "aovMultiplier": 1,
    "calculationBase": 120.00,
    "attributionMode": "subtotal",
    "isExpired": false,
    "hasMinimumOrder": true,
    "minimumOrderValue": 50.00,
    "minimumOrderReached": true
  }
}

// Calculate total order entries from Shopify cart data
// Fetch the current cart, then call the API
fetch('/cart.js')
  .then(response => response.json())
  .then(cart => {
    var cartData = {
      items: cart.items.map(item => ({
        productId: String(item.product_id),
        variantId: String(item.variant_id),
        quantity: item.quantity,
        price: item.final_line_price  // Line total in cents
      })),
      subtotal: cart.items_subtotal_price,
      total: cart.total_price,
      currency: cart.currency
    };

    return fetch('https://api.giveaway.ninja/api/client/calculateOrderEntries', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        giveawayId: 'YOUR_GIVEAWAY_ID',
        apiKey: 'YOUR_PUBLIC_API_KEY',
        cartData: cartData
      })
    });
  })
  .then(response => response.json())
  .then(data => {
    if (data.status === 'Success') {
      console.log('Total entries for this order:', data.data.totalEntries);
      console.log('Order points:', data.data.orderPoints);
      console.log('Bundle points:', data.data.bundleRulePoints);
      console.log('Purchase rule points:', data.data.purchaseRulePoints);

      if (data.data.hasMinimumOrder && !data.data.minimumOrderReached) {
        console.log('Minimum order of $' +
          data.data.minimumOrderValue.toFixed(2) + ' not reached');
      }
    }
  })
  .catch(error => console.error('Request failed:', error));

<div id="order-entries-banner" style="display:none; padding:12px; background:#e8f5e8; border:1px solid #c3e6c3; border-radius:6px; margin:10px 0;">
  <span id="order-entries-text"></span>
</div>

<script>
(function() {
  var banner = document.getElementById('order-entries-banner');
  var text = document.getElementById('order-entries-text');

  // Fetch the Shopify cart
  fetch('/cart.js')
    .then(function(r) { return r.json(); })
    .then(function(cart) {
      if (!cart.items || cart.items.length === 0) return;

      var cartData = {
        items: cart.items.map(function(item) {
          return {
            productId: String(item.product_id),
            variantId: String(item.variant_id),
            quantity: item.quantity,
            price: item.final_line_price
          };
        }),
        subtotal: cart.items_subtotal_price,
        total: cart.total_price,
        currency: cart.currency
      };

      return fetch('https://api.giveaway.ninja/api/client/calculateOrderEntries', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          giveawayId: 'YOUR_GIVEAWAY_ID',
          apiKey: 'YOUR_PUBLIC_API_KEY',
          cartData: cartData
        })
      });
    })
    .then(function(r) { return r ? r.json() : null; })
    .then(function(data) {
      if (!data || data.status !== 'Success') return;
      var d = data.data;

      if (d.hasMinimumOrder && !d.minimumOrderReached) {
        text.textContent = 'Add $' +
          (d.minimumOrderValue - d.calculationBase).toFixed(2) +
          ' more to earn giveaway entries!';
        banner.style.background = '#fff8e1';
        banner.style.borderColor = '#ffe082';
        banner.style.display = 'block';
      } else if (d.totalEntries > 0) {
        var label = d.totalEntries === 1 ? ' entry' : ' entries';
        text.textContent = d.totalEntries + label + ' with this order!';
        banner.style.display = 'block';
      }
    })
    .catch(function(err) {
      console.error('Order entries error:', err);
    });
})();
</script>