> ## Documentation Index
> Fetch the complete documentation index at: https://offergrid.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Internet Offers
> Publish internet plans with the structured .internet contract
## 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](https://www.fcc.gov/broadbandlabels) fields.
This page is the narrative guide. The field-by-field reference is published in
the [API Reference](/docs/api-reference/introduction) 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:
```jsonc theme={null}
{
"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
```jsonc theme={null}
"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](#publishing-requirements). Send only what you have; unspecified
fields are left untouched on update.
* **`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`.
* **`capGb`** — monthly data cap in GB. **Omit for an unlimited plan.**
* **`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".
* **`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
```bash cURL theme={null}
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"
}
}
}'
```
```typescript TypeScript theme={null}
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:
```jsonc PATCH /provider/offers/{id} theme={null}
{
"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
The general offer create/publish flow
The parallel structured contract for electricity
Automate offer sync and order processing
The `InternetContract` schema, field by field