Skip to main content

Key concepts

The Light API revolves around several key entities that work together to enable seamless management of electricity services for consumers.

Entities​

Apps​

Each App corresponds to a single application or integration built on the Light platform. Apps have their own set of accounts, data, and configuration. You can create your own Sandbox Apps in the Light dashboard. Once you have an App, you can configure it, download an App Token, and configure webhooks.

info

Currently, Light assists with the creation of Live Apps. When you are ready to go live, we will work with you to help create a Live App and ensure it is ready to launch.

Accounts​

An Account represents a prospective or active electricity consumer. Creating an Account requires minimal information such as an email address and name. Once an Account is created, it can be used to enroll or manage the consumer's electricity service for a service location.

Location​

A Location is attached to an Account and corresponds to a physical service address where an electricity consumer resides with an electricity meter. The process of creating or attaching the Location to an Account is called "Enrollment." This process includes verifying eligibility, retrieving available plans, and accepting an offered Plan.

Multiple Locations

If users in your system only have one location or property, then you can have one Account per user. However, if users in your system may have multiple locations, then you will likely want to create an Account per location.

Plan groups​

A Plan Group represents a type of electricity plan available to consumers. Plan groups include feature details such as name, base fees, solar buyback programs, and commission.

The Plan Group does not include specific rates, as those will vary depending on the location of the customer and the fluctuations in the market pricing day-to-day.

Plans​

A Plan represents an individual instance of a plan group with specific rates and terms at that point in time. The Plan is dependent on location of the customer, and the time being requested. Until accepted by a customer, Plans will expire as market rates change.

Plans include the specific rates that would show on an Electricity Facts Label (EFL), as well as the Terms of Service (TOS) and Your Rights as a Customer (YRAC).

Custom rates

You can also generate custom rates per Account, overriding some components like term length and commission. This can be useful for offering the same overall Plan in different term lengths or prices depending on your business needs.

Invoices and billing​

An Invoice represents the billing statement for electricity consumption over a specific period. Invoices ensure regulatory compliance and provide detailed billing information to consumers. The Light API offers endpoints to access itemized invoice details and download invoice documents.

API structure​

Light API organizes endpoints into groups to make it easier to interact with these entities. These groups include the following:

  • /app endpoints: Used for managing and interacting with Apps, including creating and managing accounts, generating tokens, and retrieving app-specific data. These all use AppToken authentication.

    • /app/accounts/enroll endpoints: Used for privileged enrollment operations with AppToken authentication, including address search, eligibility checks, requesting plans with custom rates, and accessing plan benchmarks.

  • /account endpoints: Used for managing individual consumer Accounts. Endpoints use AccountToken authentication.

    • /account/enroll endpoints: Used for the enrollment process with AccountToken authentication, including address search, identity verification, credit checks, and plan acceptance.
    • /account/billing endpoints: Used for billing-related tasks, such as creating payment sessions, retrieving invoices, updating payment methods, and managing billing addresses.
    • /account/locations/{location_uuid} endpoints: Used for managing locations, including retrieving plan details, accessing service documents, viewing usage data (meter reads, monthly, daily, and interval usage), and managing service cancellation.
    • /account/sandbox endpoints: Used for testing and simulating account states in the sandbox environment.