API conventions

Conventions that hold across the whole API. Individual endpoints document what is specific to them; everything here is assumed.

Requests


Base URL	`https://api.offergrid.io`
Protocol	HTTPS only
Auth header	`x-api-key: YOUR_TEAM_API_KEY` on every authenticated request — see Authentication
Request bodies	JSON. Send `Content-Type: application/json`.
Partial updates	`PATCH` with only the fields you want changed. Omitted fields are left alone.

Unknown fields are rejected, not ignored. Sending a property the endpoint does not define returns 400 with "property <name> should not exist". This turns a typo into an immediate error instead of a silently dropped value — but it also means you cannot round-trip a response object straight back into a PATCH. Send only the fields you intend to change.

List responses

Every list endpoint is unpaginated by default and paginated on request. Send neither limit nor cursor and you get the complete JSON array these endpoints have always returned:

[
  { "id": "1a2b3c4d-...", "name": "High-Speed Internet 1000 Mbps" },
  { "id": "5e6f7a8b-...", "name": "Fiber 500" }
]

Send either one and the response becomes an envelope:

curl -G https://api.offergrid.io/reseller/orders \
  -H "x-api-key: YOUR_TEAM_API_KEY" \
  --data-urlencode "limit=25"

{
  "data": [
    { "id": "3c9d8b7a-...", "status": "in_progress" }
  ],
  "hasMore": true,
  "nextCursor": "3c9d8b7a-1e2f-4a5b-8c7d-6e5f4a3b2c1d"
}

Field	Description
`data`	The records for this page.
`hasMore`	Whether another page exists.
`nextCursor`	Pass as `cursor` to fetch the next page. `null` on the last page.

Parameters

Parameter	Description
`limit`	Records per page, 1–100. Defaults to 50 when only `cursor` is sent.
`cursor`	The `nextCursor` from the previous page. Returns records strictly after it.

Walking a list

Stop when hasMore is false. Do not stop on a short page — a page can come back shorter than limit and still have more behind it.

async function* allOrders() {
  let cursor: string | undefined;

  do {
    const params = new URLSearchParams({ limit: '100' });
    if (cursor) params.set('cursor', cursor);

    const response = await fetch(`https://api.offergrid.io/reseller/orders?${params}`, {
      headers: { 'x-api-key': process.env.OFFERGRID_API_KEY! },
    });
    const page = await response.json();

    yield* page.data;
    cursor = page.hasMore ? page.nextCursor : undefined;
  } while (cursor);
}

Why cursors and not page numbers. These lists are ordered newest-first, so a record created while you are paging lands on page 1 and shifts every subsequent offset by one — an offset client silently re-reads or skips records. A cursor anchors to a record rather than a position, so concurrent writes cannot corrupt a walk. The trade-off is no page numbers and no jumping to an arbitrary page.

Treat nextCursor as opaque and pass it back unmodified. A cursor whose record no longer exists ends the walk rather than restarting it.

Choosing a page size

Filtering server-side beats paging through everything. GET /reseller/catalog accepts category, minPrice, maxPrice, zipCode, and search; narrowing there is far cheaper than fetching every page and filtering locally. If you do not paginate, do not assume a bounded response size in your client — no fixed buffers, no hard-coded array-length expectations.

Filtering

Filters are query parameters, and they combine with AND. An unknown query parameter is rejected with 400, the same as an unknown body field.

curl -G https://api.offergrid.io/reseller/catalog \
  -H "x-api-key: YOUR_TEAM_API_KEY" \
  --data-urlencode "category=internet" \
  --data-urlencode "zipCode=94102" \
  --data-urlencode "maxPrice=100" \
  --data-urlencode "search=fiber"

Identifiers

Every resource id is a UUID v4 string.

1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d

Treat them as opaque: do not parse them, infer type or ordering from them, or assume any length other than 36 characters. Ids are stable for the life of the resource. The one exception is a shareable link’s slug, which appears in public URLs and is a short human-shareable token rather than a UUID.

Timestamps

All timestamps are ISO 8601 in UTC, with milliseconds and a trailing Z.

{ "createdAt": "2026-08-28T12:00:00.000Z" }

Send them in the same format. Date-only fields — a move-in date, an installation date — are calendar dates with no time component and no timezone; do not convert them through a local timezone or they can shift by a day.

Money

Monetary values are returned as strings, not numbers.

{
  "monthlyPrice": "79.99",
  "promoMonthlyPrice": "49.99",
  "totalMonthly": "129.98"
}

Parse money with a decimal library, not parseFloat. These are exact decimal values; binary floating point cannot represent them exactly, and rounding drift on prices and totals shows up in customer-visible numbers. Strings are used precisely so no precision is lost in transport.

All amounts are in USD, monthly, and before taxes and fees unless the offer states otherwise. Prices on an order are snapshotted at order time — an offer whose price changes later does not retroactively change existing orders.

Nulls and optional fields

A field that does not apply is null rather than absent, so response shapes stay stable. Two exceptions are genuinely conditional and absent when they do not apply:

electricity — present only on electricity offers
internet — present only on internet offers

Every offer carries a top-level serviceType discriminator ("electricity", "internet", …), so branch on that rather than probing for the grouped object.

Responses are additive over time. New fields can appear in any response without notice, so parse permissively and ignore what you do not recognize — a strict parser that rejects unknown response fields will break on a routine release. See Versioning.

Idempotency

There is no Idempotency-Key header today. POST /reseller/orders is not idempotent: two identical requests create two orders. If a write times out without a response, reconcile before retrying — GET /reseller/orders will tell you whether the first attempt landed. See Handling errors. Reads, PATCH, and DELETE are naturally idempotent and safe to retry.

Next steps

Errors

Every status code and a retry-safe client

Rate limits

What is limited, and what is not

Versioning

What we promise not to break

Authentication

Keys, headers, roles, and rotation

Getting Started

Core Concepts

Provider API

Reseller API

Public API

Requests

List responses

Parameters

Walking a list

Choosing a page size

Filtering

Identifiers

Timestamps

Money

Nulls and optional fields

Idempotency

Next steps

Errors

Rate limits

Versioning

Authentication

​Requests

​List responses

​Parameters

​Walking a list

​Choosing a page size

​Filtering

​Identifiers

​Timestamps

​Money

​Nulls and optional fields

​Idempotency

​Next steps

Errors

Rate limits

Versioning

Authentication

Requests

List responses

Parameters

Walking a list

Choosing a page size

Filtering

Identifiers

Timestamps

Money

Nulls and optional fields

Idempotency

Next steps