Skip to main content

Overview

Best practices for polling API endpoints to track order status efficiently.

Basic Polling Pattern

async function pollStatus(checkFunction, options = {}) {
  const {
    maxAttempts = 60,
    interval = 5000,
    finalStates = ["FULFILLED", "REFUNDED"],
  } = options;

  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    const result = await checkFunction();

    if (finalStates.includes(result.status)) {
      return result;
    }

    if (attempt < maxAttempts) {
      await new Promise((resolve) => setTimeout(resolve, interval));
    }
  }

  throw new Error("Polling timeout");
}

// Usage
const result = await pollStatus(() => checkTopupStatus(topupId), {
  maxAttempts: 60,
  interval: 5000,
});

Service-Specific Polling

Mobile Top-Ups (5 minutes max)

async function pollMobileTopup(topupId) {
  return await pollStatus(() => checkMobileStatus(topupId), {
    maxAttempts: 60,
    interval: 5000,
    finalStates: ["FULFILLED", "REFUNDED", "UNKNOWN_ERROR"],
  });
}

Internet Top-Ups (5 minutes max)

async function pollInternetTopup(topupId) {
  return await pollStatus(() => checkInternetStatus(topupId), {
    maxAttempts: 60,
    interval: 5000,
    finalStates: ["FULFILLED", "REFUNDED", "QUEUED"],
  });
}

Gift Cards (10 minutes max)

async function pollGiftCardOrder(orderId) {
  return await pollStatus(() => checkGiftCardOrder(orderId), {
    maxAttempts: 120,
    interval: 5000,
    finalStates: ["FULFILLED", "PARTIALLY_FILLED", "REFUNDED"],
  });
}

Best Practices

Set Timeouts

Always set maximum polling duration

Handle Errors

Catch and handle polling timeouts

Log Progress

Track polling attempts for debugging

Final States

Define clear terminal states
ServiceIntervalMax DurationFinal States
Mobile5s5 minFULFILLED, REFUNDED, UNKNOWN_ERROR
Internet5s5 minFULFILLED, REFUNDED, QUEUED
Gift Cards5s10 minFULFILLED, PARTIALLY_FILLED, REFUNDED