Build a Plan Comparison Widget

Show your users a table of electricity plans with prices, brands, and document links. This is the most common integration pattern.

1. Resolve the TDSP

Start by determining which TDSP territory the user is in. The easiest way is to resolve from their ZIP code:

JavaScript

const response = await fetch("https://pricing.api.comparepower.com/api/tdsps?zip_code=77001");
const tdsps = await response.json();
const tdspDuns = tdsps[0].duns_number; // "957877905" (CenterPoint)

You can also let the user select their TDSP from a dropdown. See the TDSP Reference for all 6 TDSP territories and their DUNS codes.

2. Fetch Plans with Prices

Pass the TDSP DUNS number and the usage levels you want prices at. The standard Texas comparison uses 500, 1000, and 2000 kWh:

JavaScript

const params = new URLSearchParams({
  tdsp_duns: tdspDuns,
});
// display_usage must use bracket syntax
params.append("display_usage[]", "500");
params.append("display_usage[]", "1000");
params.append("display_usage[]", "2000");

const response = await fetch(`https://pricing.api.comparepower.com/api/plans?${params}`);
const plans = await response.json();

The display_usage parameter uses bracket syntax: display_usage[]=500&display_usage[]=1000. Passing a comma-separated string will not work.

3. Display the Comparison Table

Each plan in the response includes expected_prices with the per-kWh price at each usage level you requested:

JavaScript

// Render a comparison table
plans.forEach(plan => {
  const prices = plan.expected_prices;
  console.log(plan.key);
  prices.forEach(p => {
    // p.price is cost per kWh (e.g., 0.136 = 13.6 cents/kWh)
    console.log(`  ${p.usage} kWh: ${(p.price * 100).toFixed(1)}¢/kWh`);
  });
});

4. Link to Disclosure Documents

Legal requirement

If you display plan information to Texas consumers, you must provide links to the EFL, YRAAC, and TOS documents. This is required by the Public Utility Commission of Texas (PUCT).

JavaScript

// Each plan has document_links
plan.document_links.forEach(doc => {
  // doc.type: "efl" | "yraac" | "tos"
  // doc.link: URL to the PDF
  console.log(`${doc.type.toUpperCase()}: ${doc.link}`);
});

Full Example

Complete Example

async function getPlansForZip(zipCode) {
  // Step 1: Resolve TDSP
  const tdspRes = await fetch(
    "https://pricing.api.comparepower.com/api/tdsps?zip_code=" + zipCode
  );
  const tdsps = await tdspRes.json();

  if (!tdsps.length) {
    throw new Error("No TDSP found for ZIP " + zipCode);
  }

  // Step 2: Fetch plans with prices
  const params = new URLSearchParams({
    tdsp_duns: tdsps[0].duns_number,
  });
  params.append("display_usage[]", "500");
  params.append("display_usage[]", "1000");
  params.append("display_usage[]", "2000");

  const plansRes = await fetch(
    "https://pricing.api.comparepower.com/api/plans?" + params
  );
  const plans = await plansRes.json();

  // Step 3: Return plans with prices and document links
  return plans.map(plan => ({
    id: plan._id,
    name: plan.key,
    prices: plan.expected_prices,
    documents: plan.document_links,
  }));
}

// Usage
const plans = await getPlansForZip("77001");
console.log(plans);

Want to earn commissions when users sign up through your integration? Apply as a partner — it's free and takes about 5 minutes.