How CSV and API offer ingestion works on Kinetic Grid

Two integration paths

Every supplier has different technical capabilities and operational preferences. Some teams prefer to manage rate sheets in spreadsheets and submit updates on a regular cadence. Others need their pricing engine to push changes automatically as market conditions shift.

Kinetic Grid accommodates both workflows. The CSV path is ideal for suppliers with a small number of plans or infrequent updates. The API path is designed for suppliers who update rates daily or manage hundreds of plan variants across multiple utility territories.

• CSV batch upload: Email your rate sheet to a dedicated ingestion address or upload through the supplier portal. Files are validated and processed within minutes.
• OAuth2 API: Authenticate with client credentials and push offer updates in real time. The API supports create, update, and expire operations on individual plans.

CSV format and validation

The CSV format uses a flat structure with one row per plan variant. Required columns include supplier name, plan name, utility territory, commodity type, rate, term length, and effective date. Optional columns cover cancellation fees, renewable content percentage, and promotional terms.

When a file is submitted, the ingestion engine runs a multi-step validation pass before any offers go live. The validator checks for:

• Missing required fields: Any row missing a required column is flagged and excluded from processing. You receive a detailed error report identifying the exact rows and columns that need attention.
• Duplicate detection: If two rows describe the same plan for the same utility territory and term, the system flags the conflict rather than overwriting silently.
• Zone mismatches:The validator cross-references your utility territory values against the platform's canonical utility list. Misspellings or outdated territory names are caught before they create invisible offers.
• Rate sanity checks: Rates that fall outside expected bounds for a given commodity and market are flagged for manual review to catch decimal-point errors.

API sync for real-time updates

The Kinetic Grid API uses OAuth2 client credentials for authentication. After registering your application in the supplier portal, you receive a client ID and secret that you exchange for a bearer token. Tokens are valid for 60 minutes and can be refreshed programmatically.

The API exposes endpoints for creating new offers, updating existing ones, and marking offers as expired. Each offer is identified by a combination of supplier ID, plan name, and utility territory - the same natural key used in the CSV format.

Typical integration pattern

Most API-integrated suppliers run a sync job on a scheduled basis - hourly or daily - that compares their internal pricing database against the offers currently live on the platform. The job creates new offers, updates rates that have changed, and expires plans that are no longer available. This approach keeps your marketplace presence accurate without requiring manual intervention.

Offer lifecycle: draft to expired

Every offer on the platform moves through a defined lifecycle, regardless of how it was submitted:

• Draft: The offer has been received but has not yet passed validation. Draft offers are not visible to consumers.
• Validated: The offer has passed all validation checks and is ready to go live. Suppliers can review validated offers in the portal before publishing.
• Live: The offer is visible to consumers and appears in comparison results for matching utility territories and ZIP codes.
• Expired: The offer has been removed from consumer-facing results, either because its effective date range has passed or because the supplier explicitly expired it.

Utility and load-zone mapping

Kinetic Grid maintains a canonical database of utility territories, load zones, and service areas across all supported deregulated markets. When you submit offers, your utility territory values are mapped against this database to ensure accurate consumer matching.

If you serve customers across multiple utilities in a state, each utility territory requires its own set of offer rows or API records. This granularity ensures that consumers see only the plans available for their specific utility - not plans that happen to be in the same state but are served by a different distribution company.

Staging environment for testing

Before going live, every supplier has access to a staging environment that mirrors production. You can submit test CSV files or make API calls against staging endpoints to verify that your offers are validated correctly, displayed as expected, and mapped to the right utility territories.

The staging environment also supports test enrollments, so you can walk through the full lifecycle - from offer submission to customer enrollment - without affecting real customers or production data.