# Offergrid Docs

- [Welcome to Offergrid](https://offergrid.io/docs/index.md): The B2B marketplace connecting service providers with reseller partners
- [Quick Start](https://offergrid.io/docs/quickstart.md): Get started with Offergrid in minutes
- [How It Works](https://offergrid.io/docs/how-it-works.md): Understand how Offergrid connects service providers with reseller partners
- [Authentication](https://offergrid.io/docs/authentication.md): Learn how to authenticate with the Offergrid API
- [Agent briefing](https://offergrid.io/docs/agents.md): Everything an AI agent or code generator needs to call the Offergrid API correctly
- [Provider Documentation](https://offergrid.io/docs/provider-documentation.md): Complete guide for service providers using Offergrid
- [Reseller Documentation](https://offergrid.io/docs/reseller-documentation.md): Complete guide for reseller partners using Offergrid
- [API Documentation](https://offergrid.io/docs/api-documentation.md): Complete API reference and integration guides for engineering teams
- [Provider Overview](https://offergrid.io/docs/providers/index.md): Start distributing your services through the Offergrid marketplace
- [Provider Business Case](https://offergrid.io/docs/providers/business-case.md): How Offergrid reduces fulfillment costs by enabling direct API orders from PMS partners
- [Provider Quick Start](https://offergrid.io/docs/providers/quickstart.md): Get up and running as a service provider in minutes
- [Creating Offers](https://offergrid.io/docs/providers/creating-offers.md): Learn how to create and publish service offerings
- [Service Categories](https://offergrid.io/docs/providers/offer-categories.md): Understanding service categories and category-specific requirements
- [Internet Offers](https://offergrid.io/docs/providers/internet-offers.md): Publish internet plans with the structured .internet contract
- [Electricity Offers](https://offergrid.io/docs/providers/electricity-offers.md): Publish deregulated retail electricity plans with the structured .electricity contract
- [Pricing Strategies](https://offergrid.io/docs/providers/pricing-strategies.md): Understanding different pricing models and how to set them up
- [Offer Visibility & Access Control](https://offergrid.io/docs/providers/offer-visibility.md): Control which resellers can see and order your services
- [Receiving Orders](https://offergrid.io/docs/providers/receiving-orders.md): Understanding incoming orders from resellers
- [Order Lifecycle & Status Updates](https://offergrid.io/docs/providers/order-workflow.md): Understanding order status progression and when to update
- [Fulfillment Best Practices](https://offergrid.io/docs/providers/fulfillment-best-practices.md): Tips and strategies for smooth order fulfillment
- [Managing Reseller Relationships](https://offergrid.io/docs/providers/reseller-relationships.md): Building and maintaining partnerships with resellers
- [Preferred Reseller Programs](https://offergrid.io/docs/providers/preferred-resellers.md): Setting up and managing preferred partner lists
- [API Integration Guide](https://offergrid.io/docs/providers/api-integration.md): Integrate Offergrid with your existing systems
- [Serviceability Integration](https://offergrid.io/docs/providers/serviceability-integration.md): Expose one endpoint and Offergrid shows address-level availability and live pricing for your offers
- [Webhooks](https://offergrid.io/docs/providers/webhooks.md): Receive signed, real-time notifications about orders and order items
- [Reseller Overview](https://offergrid.io/docs/resellers/index.md): Start selling essential services through the Offergrid marketplace
- [Reseller Quick Start](https://offergrid.io/docs/resellers/quickstart.md): Get up and running as a reseller in minutes
- [Browsing the Catalog](https://offergrid.io/docs/resellers/browsing-catalog.md): Search and filter available service offerings
- [Understanding Service Categories](https://offergrid.io/docs/resellers/service-categories.md): Learn about different service types available on Offergrid
- [Comparing Offers](https://offergrid.io/docs/resellers/comparing-offers.md): How to evaluate and compare service offerings
- [Checking Availability](https://offergrid.io/docs/resellers/checking-availability.md): Verify service availability before placing orders
- [Creating Orders](https://offergrid.io/docs/resellers/creating-orders.md): How to place orders for your customers
- [Customer Information Requirements](https://offergrid.io/docs/resellers/customer-information.md): What customer details you need to collect
- [Order Submission Process](https://offergrid.io/docs/resellers/order-submission.md): What happens after you submit an order
- [Tracking Orders](https://offergrid.io/docs/resellers/tracking-orders.md): Monitor order status and communicate with customers
- [Order Lifecycle](https://offergrid.io/docs/resellers/order-lifecycle.md): Understanding how orders progress from submission to completion
- [Canceling Orders](https://offergrid.io/docs/resellers/cancellations.md): How to cancel orders when needed
- [API Integration Guide](https://offergrid.io/docs/resellers/api-integration.md): Integrate Offergrid into your existing systems
- [Webhooks](https://offergrid.io/docs/resellers/webhooks.md): Receive signed, real-time events for the orders your team placed
- [Introduction](https://offergrid.io/docs/api-reference/introduction.md): Base URL, authentication, roles, and where to go next in the Offergrid API
- [API Authentication](https://offergrid.io/docs/api-reference/authentication.md): Detailed guide to authenticating with the Offergrid API
- [Agent briefing](https://offergrid.io/docs/agents.md): Everything an AI agent or code generator needs to call the Offergrid API correctly
- [API conventions](https://offergrid.io/docs/api-reference/conventions.md): List responses, identifiers, timestamps, money, and filtering — the rules every endpoint follows
- [Errors](https://offergrid.io/docs/api-reference/errors.md): Every error the Offergrid API returns, what causes it, and how to recover
- [Rate limits](https://offergrid.io/docs/api-reference/rate-limits.md): What is rate limited on the Offergrid API today, and what to build for
- [Versioning](https://offergrid.io/docs/api-reference/versioning.md): How the Offergrid API changes, what we promise not to break, and how deprecations work
- [Changelog](https://offergrid.io/docs/api-reference/changelog.md): Dated record of changes to the Offergrid API
- [Provider API Reference](https://offergrid.io/docs/api-reference/provider.md): Every provider endpoint — offers, orders, markets, webhooks, brands, and customers
- [List all your offers](https://offergrid.io/docs/provider-api-reference/provider-offers/list-all-your-offers.md): Retrieve all offers created by your provider team.
- [Create a new offer](https://offergrid.io/docs/provider-api-reference/provider-offers/create-a-new-offer.md): Create a new service offering as a provider. The offer will be associated with your team.
- [Get a specific offer](https://offergrid.io/docs/provider-api-reference/provider-offers/get-a-specific-offer.md): Retrieve details of a specific offer you created.
- [Delete an offer](https://offergrid.io/docs/provider-api-reference/provider-offers/delete-an-offer.md): Permanently delete an offer. You can only delete your own offers.
- [Update an offer](https://offergrid.io/docs/provider-api-reference/provider-offers/update-an-offer.md): Update an existing offer. You can only update your own offers.
- [Where this offer is distributed](https://offergrid.io/docs/provider-api-reference/provider-offers/where-this-offer-is-distributed.md): Resolve the three independent gates that decide whether an offer reaches anyone — active status, active-market coverage, and each distribution channel (consumer /shop and reseller B2B). An offer can be active with a valid service area and still reach no one; `visibleNowhere` flags exactly that, and…
- [Publish an offer](https://offergrid.io/docs/provider-api-reference/provider-offers/publish-an-offer.md): Validate an offer against the publish-readiness rules and, if it passes, set its status to active. Returns 400 with structured validationErrors when the offer is not ready to publish.
- [Duplicate an offer](https://offergrid.io/docs/provider-api-reference/provider-offers/duplicate-an-offer.md): Create a new draft offer pre-filled from an existing one. The copy gets a "(Copy)" name, resets to draft status, omits the unique SKU, and strips known sample pricing entries.
- [Download CSV template for bulk offer upload](https://offergrid.io/docs/provider-api-reference/provider-offers/download-csv-template-for-bulk-offer-upload.md): Download a CSV template file with headers and an example row. Use this template to bulk upload offers.
- [Bulk upload offers from CSV](https://offergrid.io/docs/provider-api-reference/provider-offers/bulk-upload-offers-from-csv.md): Upload a CSV file to create multiple offers at once. Download the template first using GET /bulk-upload/template. The CSV supports linking offers to markets using the "marketNames" column (comma-separated market names). Markets must already exist before uploading - create them first via the markets…
- [Validate CSV file without creating offers](https://offergrid.io/docs/provider-api-reference/provider-offers/validate-csv-file-without-creating-offers.md): Upload a CSV file to validate its structure and data without actually creating offers. This is useful for checking your CSV before performing the actual bulk upload.
- [Bulk update offers from CSV](https://offergrid.io/docs/provider-api-reference/provider-offers/bulk-update-offers-from-csv.md): Upload a CSV file to update multiple existing offers at once, using the same template as bulk upload (GET /bulk-upload/template). Each row is matched to an existing offer by its "sku" column (scoped to your team), so "sku" is required on every row. Blank cells leave the existing value unchanged — on…
- [Validate a bulk-update CSV without updating offers](https://offergrid.io/docs/provider-api-reference/provider-offers/validate-a-bulk-update-csv-without-updating-offers.md): Upload a CSV file to validate it against the bulk-update rules without writing anything. Checks that every row has a "sku" matching one of your offers and that any non-blank enum, numeric, and market values are valid.
- [List order items to fulfill](https://offergrid.io/docs/provider-api-reference/provider-orders/list-order-items-to-fulfill.md): Retrieve all order items for your offers that need fulfillment. Each item represents a single offer ordered by a reseller.
- [Get order item details](https://offergrid.io/docs/provider-api-reference/provider-orders/get-order-item-details.md): Retrieve detailed information about a specific order item for fulfillment.
- [Update order item status](https://offergrid.io/docs/provider-api-reference/provider-orders/update-order-item-status.md): Update the fulfillment status of an order item (e.g., accept, reject, schedule, complete). Use this to manage the order workflow from acceptance to completion.
- [List all markets for your team](https://offergrid.io/docs/provider-api-reference/provider-markets/list-all-markets-for-your-team.md)
- [Create a market](https://offergrid.io/docs/provider-api-reference/provider-markets/create-a-market.md)
- [Get a market by id](https://offergrid.io/docs/provider-api-reference/provider-markets/get-a-market-by-id.md)
- [Delete a market](https://offergrid.io/docs/provider-api-reference/provider-markets/delete-a-market.md)
- [Update a market](https://offergrid.io/docs/provider-api-reference/provider-markets/update-a-market.md)
- [Add a geographic area to a market](https://offergrid.io/docs/provider-api-reference/provider-markets/add-a-geographic-area-to-a-market.md): Areas compose a market. Supply the `type` field and the matching fields: postalCodes (postal), admin* fields (admin), geometry (polygon), h3Cells (h3), or sourceRef (serviceability — must name an active serviceability integration source owned by your team). Use operation=exclude to carve a hole out…
- [Remove an area from a market](https://offergrid.io/docs/provider-api-reference/provider-markets/remove-an-area-from-a-market.md)
- [List customers](https://offergrid.io/docs/provider-api-reference/provider-customers/list-customers.md): Customers are people who have placed an order for one of your offers. This list does not include reseller-side leads.
- [Get customer detail](https://offergrid.io/docs/provider-api-reference/provider-customers/get-customer-detail.md): Detail view of a customer including the order items they have placed for your offers.
- [Record a consent revocation you received](https://offergrid.io/docs/provider-api-reference/provider-customers/record-a-consent-revocation-you-received.md): Call this when a customer or lead tells you to stop (a STOP text, a verbal do-not-call request). Every consent record naming your team is marked revoked, the customer is flagged `unsubscribed` for your team, and an `order.consent_revoked` event is emitted. Keeps the shared record truthful — consent…
- [List your registered webhooks](https://offergrid.io/docs/provider-api-reference/provider-webhooks/list-your-registered-webhooks.md): Secrets are masked — the full value is only ever returned at creation.
- [Register a webhook](https://offergrid.io/docs/provider-api-reference/provider-webhooks/register-a-webhook.md): Register an HTTPS endpoint to receive signed order-event deliveries. The response includes the signing secret — it is shown only this once.
- [Get a webhook by id](https://offergrid.io/docs/provider-api-reference/provider-webhooks/get-a-webhook-by-id.md)
- [Delete a webhook](https://offergrid.io/docs/provider-api-reference/provider-webhooks/delete-a-webhook.md)
- [Update a webhook (url, subscribed events, or active state)](https://offergrid.io/docs/provider-api-reference/provider-webhooks/update-a-webhook-url-subscribed-events-or-active-state.md)
- [List recent delivery attempts for a webhook](https://offergrid.io/docs/provider-api-reference/provider-webhooks/list-recent-delivery-attempts-for-a-webhook.md)
- [List all brands for your team](https://offergrid.io/docs/provider-api-reference/provider-brands/list-all-brands-for-your-team.md)
- [Create a brand](https://offergrid.io/docs/provider-api-reference/provider-brands/create-a-brand.md): Brands are the visual identity offers display under instead of your team name. Each team manages its own brands; names are matched case-insensitively within the team.
- [Get a brand by id](https://offergrid.io/docs/provider-api-reference/provider-brands/get-a-brand-by-id.md)
- [Delete an unused brand](https://offergrid.io/docs/provider-api-reference/provider-brands/delete-an-unused-brand.md): Only brands no offer references can be deleted.
- [Update a brand](https://offergrid.io/docs/provider-api-reference/provider-brands/update-a-brand.md): Renaming or re-logoing a brand changes it for every offer displaying it. Sending an empty imageUrl clears the logo.
- [Reseller API Reference](https://offergrid.io/docs/api-reference/reseller.md): Every reseller endpoint — catalog, availability, orders, links, and customers
- [Browse available offers](https://offergrid.io/docs/reseller-api-reference/reseller-catalog/browse-available-offers.md): Browse all service offers available to your reseller team. Visibility is based on provider settings (all resellers, preferred resellers, or selected resellers). Supports filtering by category, price range, ZIP code, and search terms. Results are sorted by relevance!
- [Get offer details](https://offergrid.io/docs/reseller-api-reference/reseller-catalog/get-offer-details.md): Retrieve detailed information about a specific offer in the catalog. You can only view offers that are available to your reseller team.
- [Find available offers for an address](https://offergrid.io/docs/reseller-api-reference/reseller-availability/find-available-offers-for-an-address.md): Given a service address, returns every offer your reseller team can sell at that location. Coverage is evaluated against each offer’s availability rules — postal codes and active market areas (including state-wide and city-level coverage) — and provider visibility settings (all resellers, preferred…
- [List your orders](https://offergrid.io/docs/reseller-api-reference/reseller-orders/list-your-orders.md): Retrieve all orders placed by your reseller team. Includes order items and their fulfillment status.
- [Place a new order](https://offergrid.io/docs/reseller-api-reference/reseller-orders/place-a-new-order.md): Create a new order for one or more service offers. Each offer will be sent to its respective provider for fulfillment. You can only order offers that are available to your reseller team.
- [Get order details](https://offergrid.io/docs/reseller-api-reference/reseller-orders/get-order-details.md): Retrieve detailed information about a specific order, including all items and their fulfillment status.
- [Cancel an order](https://offergrid.io/docs/reseller-api-reference/reseller-orders/cancel-an-order.md): Cancel a pending or submitted order. Orders can only be cancelled if they have not been accepted by providers.
- [List all shareable links](https://offergrid.io/docs/reseller-api-reference/reseller-links/list-all-shareable-links.md): Retrieve all shareable links created by your reseller team. Includes view and order counts for analytics.
- [Create a shareable link](https://offergrid.io/docs/reseller-api-reference/reseller-links/create-a-shareable-link.md): Generate a shareable link for tenants to order services at a specific address. The link can be shared via email or SMS. Tenants can use the link to browse available offers and place orders without needing to create an account.
- [Get link details](https://offergrid.io/docs/reseller-api-reference/reseller-links/get-link-details.md): Retrieve detailed information about a specific link, including recent orders placed via the link.
- [Delete a link](https://offergrid.io/docs/reseller-api-reference/reseller-links/delete-a-link.md): Permanently delete a shareable link. Orders placed via this link will be preserved.
- [Update a link](https://offergrid.io/docs/reseller-api-reference/reseller-links/update-a-link.md): Update link properties such as property name, move-in date, or status. Set status to "inactive" to disable a link without deleting it.
- [List customers and leads](https://offergrid.io/docs/reseller-api-reference/reseller-customers/list-customers-and-leads.md): Returns this reseller team's customers (people who have placed an order) and leads (people added manually, by API import, or by event). Filter via the kind query param.
- [Add a customer or lead manually](https://offergrid.io/docs/reseller-api-reference/reseller-customers/add-a-customer-or-lead-manually.md): Create a new lead or customer record. Resellers use this to track contacts from off-platform sources before they place an order.
- [Get customer detail (with this reseller's orders)](https://offergrid.io/docs/reseller-api-reference/reseller-customers/get-customer-detail-with-this-resellers-orders.md)
- [Remove customer from this reseller's list](https://offergrid.io/docs/reseller-api-reference/reseller-customers/remove-customer-from-this-resellers-list.md): Removes the link between this reseller and the customer. The shared Customer record itself is preserved so other teams' views are unaffected.
- [Update customer notes / tags / status / kind](https://offergrid.io/docs/reseller-api-reference/reseller-customers/update-customer-notes-tags-status-kind.md): Update reseller-private fields. To update the underlying contact info (name, email, address) the contact themselves must place a new order, since those fields are shared across all teams that know this person.
- [List your registered webhooks](https://offergrid.io/docs/reseller-api-reference/reseller-webhooks/list-your-registered-webhooks.md): Secrets are masked — the full value is only ever returned at creation.
- [Register a webhook](https://offergrid.io/docs/reseller-api-reference/reseller-webhooks/register-a-webhook.md): Register an HTTPS endpoint to receive signed order-event deliveries for orders your team placed. The response includes the signing secret — it is shown only this once.
- [Get a webhook by id](https://offergrid.io/docs/reseller-api-reference/reseller-webhooks/get-a-webhook-by-id.md)
- [Delete a webhook](https://offergrid.io/docs/reseller-api-reference/reseller-webhooks/delete-a-webhook.md)
- [Update a webhook (url, subscribed events, or active state)](https://offergrid.io/docs/reseller-api-reference/reseller-webhooks/update-a-webhook-url-subscribed-events-or-active-state.md)
- [List recent delivery attempts for a webhook](https://offergrid.io/docs/reseller-api-reference/reseller-webhooks/list-recent-delivery-attempts-for-a-webhook.md): The 50 most recent attempts, newest first. Every attempt is logged whether it succeeded or failed — start here when a delivery appears to be missing.
- [Public API Reference](https://offergrid.io/docs/api-reference/public.md): Unauthenticated endpoints powering shareable reseller links and the /shop storefront
- [Get link details](https://offergrid.io/docs/public-api-reference/public/get-link-details.md): Retrieve public information about a shareable link, including the service address and property name. This endpoint does not require authentication.
- [Get available offers for a link](https://offergrid.io/docs/public-api-reference/public/get-available-offers-for-a-link.md): Retrieve all service offers available for the address associated with this link. Offers are grouped by category (internet, electricity, other). This endpoint does not require authentication.
- [Submit an order via a shareable link](https://offergrid.io/docs/public-api-reference/public/submit-an-order-via-a-shareable-link.md): Create a new order for the selected service offers. The order will be associated with the reseller who created the link. This endpoint does not require authentication.
- [Browse consumer-enabled offers](https://offergrid.io/docs/public-api-reference/public/browse-consumer-enabled-offers.md): Returns active, consumer-enabled offers, optionally filtered by ZIP/city/state (coverage-checked through the offer's markets) and category. Unauthenticated — backs the public /shop storefront.
- [Get a consumer offer by its id](https://offergrid.io/docs/public-api-reference/public/get-a-consumer-offer-by-its-id.md): Full pricing/compliance detail for one consumer-enabled offer. Pass `zip` to re-check coverage for that ZIP. Unauthenticated.
- [Check address-level serviceability for on-screen offers](https://offergrid.io/docs/public-api-reference/public/check-address-level-serviceability-for-on-screen-offers.md): Given a full street address, returns per-offer serviceability + exact price for offers whose markets reference an external serviceability source. Layered on top of ZIP coverage (not a gate) — offers without a source are simply absent from the result map. Unauthenticated.
- [Place a checkout-mode shop order](https://offergrid.io/docs/public-api-reference/public/place-a-checkout-mode-shop-order.md): Creates an order through the canonical transactional path (idempotent, snapshotted, outbox-emitting), attributed to the house reseller team. Re-checks coverage against the submitted address; unauthenticated.
- [Record an outbound shop click](https://offergrid.io/docs/public-api-reference/public/record-an-outbound-shop-click.md): Logs a click for a consumer offer — a lead_gen click returns a redirectUrl (the provider URL with Offergrid attribution merged on); a checkout-mode click is fire-and-forget funnel logging with no redirect. Unauthenticated, lightly rate-limited per IP.
- [Withdraw consent to be contacted](https://offergrid.io/docs/public-api-reference/public/withdraw-consent-to-be-contacted.md): Backs offergrid.io/opt-out. Marks every consent granted for this phone/email as revoked, unsubscribes the person with every team that knows them, and notifies the providers who were named. Always returns 200 — the response never reveals whether a number or address was known. Unauthenticated, rate-li…

## OpenAPI Specs

- [openapi-provider](/docs/openapi/openapi-provider.json)
- [openapi-public](/docs/openapi/openapi-public.json)
- [openapi-reseller](/docs/openapi/openapi-reseller.json)
- [openapi](/docs/openapi/openapi.json)

## Optional

- [Dashboard](https://offergrid.io)
- [Support](mailto:support@offergrid.io)