Skip to main content
POST
/
provider
/
offers
Create a new offer
curl --request POST \
  --url https://api.offergrid.io/provider/offers \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "name": "High-Speed Internet 1000 Mbps",
  "internalName": "HSI-1000-Q4-2024",
  "category": "internet",
  "status": "draft",
  "sku": "INT-1000-001",
  "externalId": "ext-12345",
  "metadata": {
    "tags": [
      "fiber",
      "residential"
    ],
    "priority": 1
  },
  "description": "Blazing fast fiber internet with unlimited data",
  "internalDescription": "Q4 promotional offer for new markets",
  "marketingHeadline": "Get Lightning-Fast Internet Today!",
  "marketingDescription": "Experience the future of connectivity with our fiber-optic network",
  "keyFeatures": [
    "1000 Mbps download",
    "Unlimited data",
    "No contract"
  ],
  "imageUrl": "https://cdn.example.com/offers/internet-1000.jpg",
  "overview": "This package includes installation, router, and 24/7 support",
  "submissionUrl": "https://provider.example.com/api/orders",
  "submissionConfig": {
    "formFields": [
      {
        "name": "address",
        "type": "text",
        "required": true
      },
      {
        "name": "phone",
        "type": "tel",
        "required": true
      }
    ],
    "metadata": []
  },
  "serviceSpecificData": {
    "minBandwidth": 100,
    "maxBandwidth": 1000,
    "connectionType": "fiber",
    "dataCap": null
  },
  "pricingType": "fixed",
  "monthlyPrice": 59.99,
  "complianceData": {
    "broadbandLabel": {
      "url": "https://provider.com/broadband-label.pdf",
      "typicalDownload": 940,
      "typicalUpload": 880,
      "typicalLatency": 15,
      "dataCapGb": null
    },
    "networkManagementUrl": "https://provider.com/network-management"
  },
  "complianceStatus": "unknown",
  "complianceNotes": "Waiting for updated EFL from legal team"
}
'

Authorizations

​
x-api-key
string
header
required

Team API key for authentication. Your team role (provider/reseller/hybrid) determines which endpoints you can access.

Body

application/json
​
name
string
required

Public-facing name of the offer

Example:

"High-Speed Internet 1000 Mbps"

​
internalName
string

Internal name for tracking (not shown to customers)

Example:

"HSI-1000-Q4-2024"

​
category
enum<string>

Service category

Available options:
internet,
television,
security,
energy,
insurance,
other
Example:

"internet"

​
status
enum<string>
default:draft

Current status of the offer

Available options:
draft,
active,
inactive,
archived
Example:

"draft"

​
sku
string

Stock Keeping Unit (SKU) - must be unique

Example:

"INT-1000-001"

​
externalId
string

External system identifier

Example:

"ext-12345"

​
metadata
object

Custom metadata as JSON object

Example:
{
  "tags": ["fiber", "residential"],
  "priority": 1
}
​
description
string

Detailed description of the offer

Example:

"Blazing fast fiber internet with unlimited data"

​
internalDescription
string

Internal notes and description

Example:

"Q4 promotional offer for new markets"

​
marketingHeadline
string

Marketing headline

Example:

"Get Lightning-Fast Internet Today!"

​
marketingDescription
string

Marketing description

Example:

"Experience the future of connectivity with our fiber-optic network"

​
keyFeatures
string[]

Array of key features

Example:
[
  "1000 Mbps download",
  "Unlimited data",
  "No contract"
]
​
imageUrl
string

URL to offer image

Example:

"https://cdn.example.com/offers/internet-1000.jpg"

​
overview
string

Detailed overview of the offer

Example:

"This package includes installation, router, and 24/7 support"

​
submissionUrl
string

URL for order submission

Example:

"https://provider.example.com/api/orders"

​
submissionConfig
object

Submission configuration including form fields

Example:
{
  "formFields": [
    {
      "name": "address",
      "type": "text",
      "required": true
    },
    {
      "name": "phone",
      "type": "tel",
      "required": true
    }
  ],
  "metadata": []
}
​
serviceSpecificData
Internet Service Details · object

Service-specific data varies by category:

Internet (InternetServiceDataDto):

  • minBandwidth (required): Minimum bandwidth in Mbps
  • maxBandwidth (required): Maximum bandwidth in Mbps
  • connectionType (required): fiber | cable | dsl | satellite | fixed_wireless | 5g_home
  • dataCap (optional): Data cap in GB

Security (SecurityServiceDataDto):

  • monitoringType (required): professional_monitoring | self_monitoring | hybrid
  • installationType (required): professional | diy
  • equipmentIncluded (required): Description of equipment

Television (TelevisionServiceDataDto):

  • channelCount (optional): Number of channels
  • includesStreaming (optional): Boolean
  • hd (optional): Boolean
  • dvr (optional): Boolean

Energy (EnergyServiceDataDto):

  • energyType (optional): electricity | gas | solar
  • contractLengthMonths (optional): Contract length in months
  • renewablePercentage (optional): Percentage of renewable energy

Insurance (InsuranceServiceDataDto):

  • insuranceType (optional): Type of insurance
  • coverageAmount (optional): Coverage amount in dollars
  • deductible (optional): Deductible in dollars
Example:
{
  "minBandwidth": 100,
  "maxBandwidth": 1000,
  "connectionType": "fiber",
  "dataCap": null
}
​
pricingType
enum<string>

Pricing type

Available options:
fixed,
variable,
tiered,
custom
Example:

"fixed"

​
monthlyPrice
number

Monthly recurring price

Required range: x >= 0
Example:

59.99

​
complianceData
Internet Compliance (FCC Broadband Label) · object

Compliance data varies by category:

Internet (InternetComplianceDataDto) - FCC Broadband Facts Label:

  • broadbandLabel: { url, typicalDownload, typicalUpload, typicalLatency, dataCapGb }
  • networkManagementUrl: URL to network management policy

Energy (EnergyComplianceDataDto) - Texas PUCT Electricity Facts Label:

  • electricityFactsLabel: { url, versionId, avgPrice500kwh, avgPrice1000kwh, avgPrice2000kwh, renewablePercent }
  • puctCertNumber: PUCT REP certificate number
  • termsOfServiceUrl: URL to terms of service
  • yourRightsUrl: URL to YRAC document

Security (SecurityComplianceDataDto) - State Licensing:

  • licensesText: State licenses in text format
  • bondAmount: Surety bond amount
  • insuranceCertUrl: URL to insurance certificate
  • qualifyingAgentName: Name of qualifying agent

Television (TelevisionComplianceDataDto) - FCC Cable/TV:

  • allInMonthlyPrice: Total monthly cost including all fees
  • franchiseFees, regulatoryFees, equipmentFees: Fee breakdown
  • privacyPolicyUrl: URL to privacy policy

Insurance (InsuranceComplianceDataDto) - State Licensing:

  • agentLicensesText: Agent/agency licenses
  • producerDisclosureUrl: URL to producer disclosure
  • naicCode: NAIC identifier
Example:
{
  "broadbandLabel": {
    "url": "https://provider.com/broadband-label.pdf",
    "typicalDownload": 940,
    "typicalUpload": 880,
    "typicalLatency": 15,
    "dataCapGb": null
  },
  "networkManagementUrl": "https://provider.com/network-management"
}
​
complianceStatus
enum<string>
default:unknown

Overall compliance status

Available options:
unknown,
compliant,
incomplete,
non_compliant,
exempt
Example:

"unknown"

​
complianceNotes
string

Internal notes about compliance status

Example:

"Waiting for updated EFL from legal team"

Response

Offer successfully created