Internet Offers

Overview

Internet is a first-class service type on Offergrid. Rather than a free-form JSON blob, internet offers carry a single, structured internet object grouped into four sections — speed, data, term, and disclosures — including the FCC Broadband Consumer Label fields.

This page is the narrative guide. The field-by-field reference is published in the API Reference as the InternetContractWrite and InternetContract schema components.

Identifying an internet offer

Every offer response carries a top-level serviceType discriminator that mirrors category — check either field:

{
  "id": "…",
  "serviceType": "internet",
  "category": "internet",
  "name": "Gigabit Fiber",
  "status": "active",
  "internet": { /* the contract, see below */ }
}

Internet offers additionally include the grouped internet object. Other service types (electricity, other) get their own top-level key.

The `internet` contract

"internet": {
  "speed": {
    "minBandwidthMbps": 100,                // advertised plan range
    "maxBandwidthMbps": 1000,
    "connectionType": "fiber"               // fiber | cable | dsl | satellite | fixed_wireless | 5g_home
  },
  "data": {
    "capGb": 1024                           // omit for an unlimited plan
  },
  "term": {
    "length": "months_12",                  // no_contract | month_to_month | months_12 | months_24 | months_36
    "earlyTerminationFee": 150,             // dollars
    "earlyTerminationFeeNotes": "Prorated by months remaining"
  },
  "disclosures": {                          // FCC Broadband Consumer Label
    "broadbandLabel": {
      "url": "https://example.com/broadband-label.pdf",
      "typicalDownload": 940,               // Mbps
      "typicalUpload": 880,                 // Mbps
      "typicalLatency": 15,                 // ms
      "dataCapGb": 1024
    },
    "networkManagementUrl": "https://example.com/network-management"
  }
}

All four sections and all fields are optional on write, except the publish requirement. Send only what you have; unspecified fields are left untouched on update.

speed — advertised service level

minBandwidthMbps / maxBandwidthMbps — the marketed plan range, in Mbps.
connectionType — fiber, cable, dsl, satellite, fixed_wireless, or 5g_home.

The FCC “typical” speeds (what customers actually experience) live under disclosures.broadbandLabel.

data — allowance

capGb — monthly data cap in GB. Omit for an unlimited plan.

term — contract length and cancellation

length — no_contract, month_to_month, months_12, months_24, or months_36.
earlyTerminationFee — cancellation fee in dollars.
earlyTerminationFeeNotes — free-text detail, e.g. “Prorated by months remaining”.

disclosures — FCC Broadband Consumer Label

broadbandLabel — url, plus the label’s typical performance figures (typicalDownload, typicalUpload in Mbps, typicalLatency in ms) and dataCapGb.
networkManagementUrl — link to your network management practices disclosure.

Creating an internet offer

curl -X POST https://api.offergrid.io/provider/offers \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Gigabit Fiber",
    "category": "internet",
    "monthlyPrice": 79.99,
    "internet": {
      "speed": { "minBandwidthMbps": 100, "maxBandwidthMbps": 1000, "connectionType": "fiber" },
      "data": { "capGb": 1024 },
      "term": { "length": "months_12", "earlyTerminationFee": 150 },
      "disclosures": {
        "broadbandLabel": {
          "url": "https://example.com/broadband-label.pdf",
          "typicalDownload": 940,
          "typicalUpload": 880,
          "typicalLatency": 15
        },
        "networkManagementUrl": "https://example.com/network-management"
      }
    }
  }'

const response = await fetch('https://api.offergrid.io/provider/offers', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.OFFERGRID_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Gigabit Fiber',
    category: 'internet',
    monthlyPrice: 79.99,
    internet: {
      speed: { minBandwidthMbps: 100, maxBandwidthMbps: 1000, connectionType: 'fiber' },
      data: { capGb: 1024 },
      term: { length: 'months_12', earlyTerminationFee: 150 },
      disclosures: {
        broadbandLabel: {
          url: 'https://example.com/broadband-label.pdf',
          typicalDownload: 940,
          typicalUpload: 880,
          typicalLatency: 15,
        },
        networkManagementUrl: 'https://example.com/network-management',
      },
    },
  }),
});

const offer = await response.json();

The response is the created offer with serviceType: "internet", the projected internet object, and the standard offer fields. Unlike electricity, internet pricing is set directly via monthlyPrice — the contract does not derive it.

Updating an internet offer

Send only the sections you’re changing. The internet object is merged onto the stored offer, so unrelated data is preserved:

PATCH /provider/offers/{id}

{
  "internet": {
    "term": { "earlyTerminationFee": 0, "length": "no_contract" }
  }
}

This changes only the term; the existing speed, data, and disclosures are untouched.

The internet object is the only way to set an internet offer’s speed, data, term, and disclosures — there is no flat/free-form alternative field to fall back to.

Publishing requirements

POST /provider/offers/{id}/publish validates the offer. For internet, the contract-specific rule is:

speed must include minBandwidthMbps, maxBandwidthMbps, and a valid connectionType.

If any are missing, publish returns 400 with structured validationErrors pointing at the internetDetails bandwidth/connection fields. General offer requirements — name, SKU, description, at least one market, etc. — also apply.

Storage

Internet offer data lives in a dedicated typed relation — there is no free-form JSON blob involved. Read and write everything internet-related through .internet.

Quick reference

You want to…	Use
Detect an internet offer	top-level `serviceType === "internet"`
Read speed / connection	`internet.speed`
Read data allowance	`internet.data.capGb` (omitted = unlimited)
Read term / ETF	`internet.term`
Read FCC label	`internet.disclosures.broadbandLabel`
Set the offer	send `internet.speed` / `data` / `term` / `disclosures` on create/update
Publish	ensure `speed` has min/max bandwidth + connectionType, then `POST …/publish`

Next steps

Creating Offers

The general offer create/publish flow

Electricity Offers

The parallel structured contract for electricity

API Integration

Automate offer sync and order processing

API Reference

The InternetContract schema, field by field

Getting Started

Managing Offers

Order Fulfillment

Partner Management

Integration

Overview

Identifying an internet offer

The `internet` contract

Creating an internet offer

Updating an internet offer

Publishing requirements

Storage

Quick reference

Next steps

Creating Offers

Electricity Offers

API Integration

API Reference

​Overview

​Identifying an internet offer

​The internet contract

​Creating an internet offer

​Updating an internet offer

​Publishing requirements

​Storage

​Quick reference

​Next steps

Creating Offers

Electricity Offers

API Integration

API Reference

Overview

Identifying an internet offer

The `internet` contract

Creating an internet offer

Updating an internet offer

Publishing requirements

Storage

Quick reference

Next steps