> ## 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. # Create a new offer > Create a new service offering as a provider. The offer will be associated with your team. ## OpenAPI ````yaml /openapi/openapi-provider.json post /provider/offers openapi: 3.0.0 info: title: OfferGrid API description: >- **Provider API** - Create and manage service offerings, fulfill orders from resellers. As a provider, you can: - Create and publish service offerings (internet, electricity) - Control which resellers can access your offers (all, preferred, or selected) - View and manage orders from resellers - Update order fulfillment status and schedule installations - Track order lifecycle from pending to completion version: '1.0' contact: {} servers: - url: https://api.offergrid.io description: Production - url: http://localhost:3000 description: Local development security: [] tags: - name: provider-offers description: 'Provider: Manage your service offerings' - name: provider-orders description: 'Provider: Fulfill orders from resellers' paths: /provider/offers: post: tags: - provider-offers summary: Create a new offer description: >- Create a new service offering as a provider. The offer will be associated with your team. operationId: ProviderOffersController_create parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateOfferDto' responses: '201': description: Offer successfully created content: application/json: schema: $ref: '#/components/schemas/OfferResponse' '403': description: Forbidden - Provider role required '409': description: An offer with the same SKU already exists (SKUs are unique) security: - api-key: [] components: schemas: CreateOfferDto: type: object properties: name: type: string description: Public-facing name of the offer example: High-Speed Internet 1000 Mbps internalName: type: string description: Internal name for tracking (not shown to customers) example: HSI-1000-Q4-2024 category: type: string description: Service category enum: - internet - electricity - other example: internet status: type: string description: Current status of the offer enum: - draft - active - inactive - archived example: draft default: draft sku: type: string description: Stock Keeping Unit (SKU) - must be unique example: INT-1000-001 externalId: type: string description: External system identifier example: ext-12345 externalProductKey: type: string description: >- Identifier of this offer's product in the provider's serviceability source. When the source returns several products for an address, this selects the one whose price/plan is shown for this offer; offers sharing a market can therefore each surface their own address-level pricing. Leave unset to use the source's default (payload-level) projection. example: FIBER-500 metadata: type: object description: Custom metadata as JSON object example: tags: - fiber - residential priority: 1 description: type: string description: Detailed description of the offer example: Blazing fast fiber internet with unlimited data internalDescription: type: string description: Internal notes and description example: Q4 promotional offer for new markets marketingHeadline: type: string description: Marketing headline example: Get Lightning-Fast Internet Today! marketingDescription: type: string description: Marketing description example: Experience the future of connectivity with our fiber-optic network keyFeatures: description: Array of key features example: - 1000 Mbps download - Unlimited data - No contract type: array items: type: string imageUrl: type: string description: URL to offer image example: https://cdn.example.com/offers/internet-1000.jpg overview: type: string description: Detailed overview of the offer example: This package includes installation, router, and 24/7 support brandId: type: string description: >- Id of one of your team brands (see /provider/brands) to display the offer under. Takes precedence over brandName. Send null on update to clear the brand and fall back to the provider team identity. example: a3f1c9c2-7f42-4b6e-9a8e-2f0d5c6b1e77 brandName: type: string description: >- Brand display name. When set, buyer-facing surfaces show this brand's name/logo instead of the owning provider team — used to load offers under another company's identity. If your team has no brand with this name it is created; matching is case/space-insensitive within your team. Falls back to the provider team name when omitted. Ignored when brandId is set. example: Direct Energy brandImageUrl: type: string description: >- Brand logo URL. Only used to set the image when the brand is first created (or when an existing brand has no image); it never overwrites an existing brand logo. example: https://logo.clearbit.com/directenergy.com submissionUrl: type: string description: URL for order submission example: https://provider.example.com/api/orders submissionConfig: type: object description: Submission configuration including form fields example: formFields: - name: address type: text required: true - name: phone type: tel required: true metadata: [] electricity: allOf: - $ref: '#/components/schemas/ElectricityContractWrite' description: >- Structured electricity contract — the only way to set an electricity offer’s pricing, term, plan and disclosures. Folded into storage server-side. Grouped as rate / term / plan / disclosures. internet: allOf: - $ref: '#/components/schemas/InternetContractWrite' description: >- Structured internet contract — the only way to set an internet offer’s speed, data allowance, term and disclosures. Folded into storage server-side. Grouped as speed / data / term / disclosures. pricingType: type: string description: Pricing type enum: - fixed - variable - tiered - custom example: fixed monthlyPrice: type: number description: Monthly recurring price example: 59.99 minimum: 0 marketNames: description: >- Scope the offer to one or more existing markets by NAME. Each name must match an existing market on your team (create markets separately via the markets API). Mirrors the CSV bulk-upload `marketNames` column so a JSON integration and the CSV path use the same identifier. Use `marketIds` if you already have market IDs. Cannot be combined with `marketIds`. example: - Texas — Oncor - Texas — CenterPoint type: array items: type: string marketIds: description: >- Scope the offer to one or more existing markets by ID. Each id must belong to a market on your team. Prefer `marketNames` when you have the market name (matches the CSV column and is easier to author). Cannot be combined with `marketNames`. example: - b1c8d1e2-... type: array items: type: string required: - name title: Create Offer Request OfferResponse: type: object title: Offer description: >- An offer. Always includes a top-level `serviceType` discriminator ("electricity", "internet", …); electricity offers additionally include a grouped `electricity` object and internet offers a grouped `internet` object. The underlying offer fields (name, status, markets, marketing, pricing, …) are also present. additionalProperties: true properties: serviceType: type: string nullable: true description: >- Flat service-type discriminator derived from category. Check this instead of `category` directly. example: internet electricity: allOf: - $ref: '#/components/schemas/ElectricityContract' description: Present only on electricity offers. internet: allOf: - $ref: '#/components/schemas/InternetContract' description: Present only on internet offers. ElectricityContractWrite: type: object properties: rate: type: object properties: type: type: string enum: - fixed - variable - indexed charges: type: array items: $ref: '#/components/schemas/ElectricityCharge' avgPriceAt1000Kwh: type: number minimum: 0 additionalProperties: false term: type: object properties: length: type: string enum: - no_contract - month_to_month - months_12 - months_24 - months_36 earlyTerminationFee: nullable: true type: number minimum: 0 earlyTerminationFeeNotes: nullable: true type: string additionalProperties: false plan: type: object properties: renewablePercentage: type: number minimum: 0 maximum: 100 freeNightsWeekends: type: boolean noDeposit: type: boolean additionalProperties: false disclosures: type: object properties: electricityFactsLabel: type: object properties: url: anyOf: - type: string format: uri - type: string enum: - '' versionId: type: string avgPrice500kwh: type: number minimum: 0 avgPrice1000kwh: type: number minimum: 0 avgPrice2000kwh: type: number minimum: 0 renewablePercent: type: number minimum: 0 maximum: 100 additionalProperties: false puctCertNumber: type: string puctCertifiedName: type: string termsOfServiceUrl: anyOf: - type: string format: uri - type: string enum: - '' yourRightsUrl: anyOf: - type: string format: uri - type: string enum: - '' additionalProperties: false additionalProperties: false title: Electricity Contract (write) description: >- The electricity offer payload accepted on create/update. When present it is authoritative for pricing/term/plan/disclosures and is folded into storage server-side. Grouped as rate / term / plan / disclosures. InternetContractWrite: type: object properties: speed: type: object properties: minBandwidthMbps: type: number minimum: 0 maxBandwidthMbps: type: number minimum: 0 connectionType: type: string enum: - fiber - cable - dsl - satellite - fixed_wireless - 5g_home additionalProperties: false data: type: object properties: capGb: type: number minimum: 0 additionalProperties: false term: type: object properties: length: type: string enum: - no_contract - month_to_month - months_12 - months_24 - months_36 earlyTerminationFee: nullable: true type: number minimum: 0 earlyTerminationFeeNotes: nullable: true type: string additionalProperties: false disclosures: type: object properties: broadbandLabel: type: object properties: url: anyOf: - type: string format: uri - type: string enum: - '' typicalDownload: type: number minimum: 0 typicalUpload: type: number minimum: 0 typicalLatency: type: number minimum: 0 dataCapGb: nullable: true type: number minimum: 0 additionalProperties: false networkManagementUrl: anyOf: - type: string format: uri - type: string enum: - '' additionalProperties: false additionalProperties: false title: Internet Contract (write) description: >- The internet offer payload accepted on create/update. When present it is authoritative for speed/data/term/disclosures and is folded into storage server-side. Grouped as speed / data / term / disclosures. ElectricityContract: type: object properties: rate: type: object properties: type: type: string enum: - fixed - variable - indexed charges: type: array items: $ref: '#/components/schemas/ElectricityCharge' avgPriceAt1000Kwh: type: number minimum: 0 estimatedMonthlyAt1000Kwh: nullable: true type: number minimum: 0 readOnly: true additionalProperties: false term: type: object properties: length: type: string enum: - no_contract - month_to_month - months_12 - months_24 - months_36 earlyTerminationFee: nullable: true type: number minimum: 0 earlyTerminationFeeNotes: nullable: true type: string additionalProperties: false plan: type: object properties: renewablePercentage: type: number minimum: 0 maximum: 100 freeNightsWeekends: type: boolean noDeposit: type: boolean additionalProperties: false disclosures: type: object properties: electricityFactsLabel: type: object properties: url: anyOf: - type: string format: uri - type: string enum: - '' versionId: type: string avgPrice500kwh: type: number minimum: 0 avgPrice1000kwh: type: number minimum: 0 avgPrice2000kwh: type: number minimum: 0 renewablePercent: type: number minimum: 0 maximum: 100 additionalProperties: false puctCertNumber: type: string puctCertifiedName: type: string termsOfServiceUrl: anyOf: - type: string format: uri - type: string enum: - '' yourRightsUrl: anyOf: - type: string format: uri - type: string enum: - '' additionalProperties: false additionalProperties: false title: Electricity Contract description: >- The electricity offer payload returned on read. Same shape as the write contract plus the derived, read-only `rate.estimatedMonthlyAt1000Kwh` headline. InternetContract: type: object properties: speed: type: object properties: minBandwidthMbps: type: number minimum: 0 maxBandwidthMbps: type: number minimum: 0 connectionType: type: string enum: - fiber - cable - dsl - satellite - fixed_wireless - 5g_home additionalProperties: false data: type: object properties: capGb: type: number minimum: 0 additionalProperties: false term: type: object properties: length: type: string enum: - no_contract - month_to_month - months_12 - months_24 - months_36 earlyTerminationFee: nullable: true type: number minimum: 0 earlyTerminationFeeNotes: nullable: true type: string additionalProperties: false disclosures: type: object properties: broadbandLabel: type: object properties: url: anyOf: - type: string format: uri - type: string enum: - '' typicalDownload: type: number minimum: 0 typicalUpload: type: number minimum: 0 typicalLatency: type: number minimum: 0 dataCapGb: nullable: true type: number minimum: 0 additionalProperties: false networkManagementUrl: anyOf: - type: string format: uri - type: string enum: - '' additionalProperties: false additionalProperties: false title: Internet Contract description: >- The internet offer payload returned on read — the grouped speed / data / term / disclosures view of an internet offer. ElectricityCharge: oneOf: - type: object properties: type: type: string enum: - perKwh centsPerKwh: type: number minimum: 0 owner: type: string enum: - provider - utility label: type: string minLength: 1 minUsageKwh: type: number minimum: 0 maxUsageKwh: type: number minimum: 0 required: - type - centsPerKwh - owner - label additionalProperties: false - type: object properties: type: type: string enum: - fixed amountDollars: type: number minimum: 0 owner: type: string enum: - provider - utility label: type: string minLength: 1 minUsageKwh: type: number minimum: 0 maxUsageKwh: type: number minimum: 0 required: - type - amountDollars - owner - label additionalProperties: false - type: object properties: type: type: string enum: - credit amountDollars: type: number minimum: 0 owner: type: string enum: - provider - utility label: type: string minLength: 1 minUsageKwh: type: number minimum: 0 maxUsageKwh: type: number minimum: 0 required: - type - amountDollars - owner - label additionalProperties: false title: Electricity Charge description: >- A single provider (REP) or utility delivery (TDU) charge line. perKwh lines bill per kWh in an optional usage band; fixed/credit lines apply a flat dollar amount (credits entered positive, subtracted). securitySchemes: api-key: type: apiKey in: header name: x-api-key description: >- Team API key for authentication. Your team role (provider/reseller/hybrid) determines which endpoints you can access. ````