Skip to main content

Introduction #

Base URL
https://api.light.dev

Light's API delivers grid electricity to your customers' homes. It covers the full lifecycle — enrollment, billing, documents, usage, service changes, and renewal — so you don't need to run the operational backend yourself.

Endpoints are split across two authentication contexts. The App API is authenticated with a long-lived AppToken and handles server-side, app-scoped actions. The Account API is authenticated with a short-lived AccountToken minted per customer and handles anything a customer does on their own account. See Authentication for the full flow and Key concepts for the entity model behind both.

Not building a UI from scratch? Light also ships three prebuilt experiences you can drop in instead: Embedded Flow runs scoped flows inside your own app or website, Light-Hosted Flow opens one on a standalone Light page, and Light-Hosted Application serves the full customer dashboard on a Light subdomain or your own custom domain.

Ready to make your first call? Follow the Quickstart. Backward-compatible changes ship within v1; breaking changes get a new version. See Versioning for the full policy.

Record an enrollment funnel event#

Record an enrollment funnel event.

Use this for steps Light's APIs do not already capture, such as when plans are presented to a customer or when they decline to continue enrollment. Call from your backend using your app token. Do not expose your app token in a browser. No account token is required because these events usually happen before an account is created in Light. Server-side API actions (for example plan requests) are recorded automatically by Light.

Supported events (event field):

ValueWhen to call
plans_viewedPlans are presented to the customer, not when fetching or caching plan data
enrollment_opt_outCustomer declines to continue; fetch survey options from GET /accounts/enroll/opt-out/reasons

Errors:

  • 400: Request validation failed (for example unknown account_uuid, occurred_at in the future, invalid field types, or unknown event value)

Request

Body (event = plans_viewed)

prospectoptional, EventProspectIdentity
Optional prospect identifiers. Omit or set to null when the partner does not yet have identifying data for this customer.
Example: {"email":"customer@example.com"}
account_uuidoptional, string
Light account UUID, if the partner has already created one for this prospect.
Example: "a14b20c3-809a-483f-98dc-3d35911eec42"
occurred_atoptional, string
When the event occurred on the partner's side (ISO 8601 with timezone). Defaults to the server receive time if omitted.
Example: "2026-03-15T14:30:00Z"
plan_uuidsoptional, array of string
UUIDs of plans shown to the customer, from the plans/request response.
Example: ["db94f2a7-84ab-4081-9896-4de2bdde984e"]
propertiesoptional, object
Optional partner-defined key-value data attached to the event in analytics. When the customer has not yet created a Light account, include esi_id and service_address if you have them. Any additional keys are allowed, up to 50 keys.
Example: {"esi_id":"55512345671234567","service_address":"123 Main St, Dallas, TX 75201"}
eventstring
Record when plans are rendered in your UI.
Example: "plans_viewed"

Body (event = enrollment_opt_out)

prospectoptional, EventProspectIdentity
Optional prospect identifiers. Omit or set to null when the partner does not yet have identifying data for this customer.
Example: {"email":"customer@example.com"}
account_uuidoptional, string
Light account UUID, if the partner has already created one for this prospect.
Example: "a14b20c3-809a-483f-98dc-3d35911eec42"
occurred_atoptional, string
When the event occurred on the partner's side (ISO 8601 with timezone). Defaults to the server receive time if omitted.
Example: "2026-03-15T14:30:00Z"
plan_uuidsoptional, array of string
UUIDs of plans shown to the customer, from the plans/request response.
Example: ["db94f2a7-84ab-4081-9896-4de2bdde984e"]
propertiesoptional, object
Optional partner-defined key-value data attached to the event in analytics. When the customer has not yet created a Light account, include esi_id and service_address if you have them. Any additional keys are allowed, up to 50 keys.
Example: {"esi_id":"55512345671234567","service_address":"123 Main St, Dallas, TX 75201"}
eventstring
Record when a customer declines to continue enrollment.
Example: "enrollment_opt_out"
reasonoptional, string
Machine-readable reason code from GET /accounts/enroll/opt-out/reasons, other, or a partner-defined code.
Example: "found_cheaper_rate"
labeloptional, string
Human-readable reason text shown to the customer.
Example: "I don't want to switch right now"
flowoptional, string
Which enrollment flow the customer opted out of. One of enrollment_switch, enrollment_move_in, or renewal.
Possible values: enrollment_switch, enrollment_move_in, renewal
Example: "enrollment_switch"
detailoptional, string
Free-text follow-up the customer provided after selecting a reason (e.g. which competitor plan, what question they had). Corresponds to the follow_up_placeholder on the selected reason.
Example: "Acme Energy 12-month plan"

Response

EnrollmentEventResponse

Generate account token#

Generate a new account token for a specific account.

This endpoint creates a new AccountToken that can be used to make authorized API requests on behalf of the account.

Request

Path parameters

account_uuidstring
UUID of the account.

Response

AccountTokenResponse

Generate flow login#

Generate a pre-authenticated login link for a specific account.

Send your user this link (for example by email, SMS, or in your app) to log them into a prebuilt UI experience without requiring a password. The link is single-use and expires after a short period. Once used, the user can access the experience until their session or token expires.

Use the behavior field to choose which prebuilt delivery option to use. See Choosing an integration approach for when to use each option.

Request

Path parameters

account_uuidstring
UUID of the account.

Body

scopestring
Scope of the session. enrollment opens the enrollment flow, update-payment-method the payment method update flow, documents the documents flow, billing the invoices flow, renewal the renewal flow for the active service location, and connect-battery the battery connection flow.
Possible values: enrollment, update-payment-method, documents, billing, renewal, connect-battery
Example: "enrollment"
behavioroptional, string
How the pre-authenticated link is delivered. "embedded" launches Embedded Flow, a link opened inside your app as an iframe or webview, so customers stay in your product. "hosted" launches Light Hosted Flow, a branded standalone page hosted by Light, typically sent by email or SMS, for out-of-band flows like renewals or battery connection. Both behaviors support all scopes.
Possible values: embedded, hosted
Example: "embedded"
attributionoptional, string
Optional partner-defined attribution tag recorded with the session.
Example: "marketing-page"
plan_groupoptional, string
UUID of the plan group to preselect for the session.
Example: "bb7d3c4d-3402-4291-b3a4-e537a8b3225d"

Response

FlowLoginResponse

Generate app-login link#

Generate a pre-authenticated login link for Light Hosted Application.

Send your user this link to log them into your white-labeled customer web app on a dedicated Light-hosted domain without requiring a password. Links expire 14 days after they are generated and can be reused during that period.

Only available when Light Hosted Application is configured for your organization. The link uses your configured standalone domain, including any custom domain you have set up.

Request

Path parameters

account_uuidstring
UUID of the account.

Body

routeoptional, string
Where to send the user after login in Light Hosted Application.
Possible values: home, enroll, billing, documents, update_payment_method
Example: "billing"
plan_groupoptional, string
UUID of the plan group to preselect in the hosted application.
Example: "bb7d3c4d-3402-4291-b3a4-e537a8b3225d"

Response

AppLoginResponse

List accounts#

Retrieve a list of all accounts associated with your app.

This endpoint returns a paginated list of accounts, including key details for each account. To get the total count of accounts (with the same filters applied), use the /count endpoint.

For details on status and status_reason, see Account Statuses.

Request

Query parameters

filteroptional, array of string
Account lifecycle states to filter by. Repeat to match any of several states, e.g. ?filter=active&filter=cancelled. created: no consumer attached yet. applying: consumer attached but prerequisites not yet met. reviewing: enrollment is being reviewed. needs_attention: something needs to be fixed. scheduled: all of Light's checks have cleared, waiting to send the switch to the utility. activating: the switch was sent to the utility, waiting for service to start. active: service is active. cancelled: service or account is cancelled.
Example: "enrolled"
searchoptional, string
Case-insensitive search across email, first name, last name, external_id, and account number. Names and email match on a partial; external_id and account number have to match in full. Every word has to match something, so a full name narrows the results instead of widening them (Ryan Schwab returns the Ryan named Schwab, not every Ryan and every Schwab). Only the first four words are used. A search made up only of digits and phone punctuation is also matched against the phone number in any format, and a full account UUID returns that account exactly.
Example: "john"
emailoptional, string
Filters to accounts with this exact email address (case-insensitive).
Example: "john@example.com"
plan_group_uuidoptional, array of string
Filters to accounts on these plans. Repeat to match any of several plans. Matches the plan exactly; see include_fallback_plans to also match accounts that rolled onto a plan's fallback.
Example: "bb7d3c4d-3402-4291-b3a4-e537a8b3225d"
external_idoptional, string
Filters to the account with this partner-assigned external ID.
Example: "external-id-456"
plan_typeoptional, string
Filters to accounts on plans of this type.
Possible values: TERM, MONTH_TO_MONTH, FALLBACK
Example: "FALLBACK"
include_fallback_plansoptional, boolean
Whether plan_group_uuid also matches accounts on the plan's fallback plan. Useful because a fallback plan cannot be filtered on its own.
device_typeoptional, array of string
Narrows device_status and missing_program_device to these device types. On its own it narrows both, so it returns accounts whose device is of these types as well as accounts on a program expecting one with nothing enrolled.
Example: "BATTERY"
device_statusoptional, array of string
Only accounts whose device is in one of these statuses. inactive matches a device that was unenrolled or decommissioned, which is narrower than missing_program_device — that also covers accounts which never connected one.
Example: "needs_attention"
missing_program_deviceoptional, boolean
Only accounts on a device program with no device currently enrolled. Combines with device_status as a union, and with device_type by the types the program expects.
expiring_in_daysoptional, integer
Only accounts whose active term contract ends within this many days and whose consumer has not accepted a renewal offer yet. Contracts already ended, or cut short because the location is leaving service, are excluded. Also orders the list by soonest end date first.
Example: 90
limitoptional, integer
Maximum number of results to return per page.
offsetoptional, integer
Number of results to skip before the returned page.

Response

PagedAppAccountResponse

Create account#

Create a new account for a consumer.

This endpoint allows you to create a new account with minimal information such as the consumer's first name, last name, and email address. Note that phone_number is required before service can be activated, but can be provided later.

Request

Body

first_namestring
Customer's first name.
Example: "John"
last_namestring
Customer's last name.
Example: "Doe"
emailstring
Customer's email address.
Example: "john@example.com"
phone_numberoptional, string
Customer's phone number, used for customer support. Required before service can be activated.
Example: "5551234567"
birth_dateoptional, string
Customer's date of birth in ISO 8601 (YYYY-MM-DD) format. Required before service can be activated.
Example: "1983-04-17"
service_start_dateoptional, string
Requested date for service to start.
Example: "2026-08-20"
preliminary_addressoptional, PreliminaryAddressInput
Preliminary service address for the account.
Example: 
{
  "address_1": "123 Main St",
  "address_2": "Apt 1",
  "city": "Dallas",
  "postal_code": "75201",
  "state": "TX"
}
location_metadataoptional, AccountLocationMetadata
Additional metadata about the service location, such as solar and battery details.
Example: 
{
  "battery_capacity_kwh": "13.5",
  "solar_estimated_annual_kwh": 12000,
  "solar_system_size_watts": 9000
}
account_linksoptional, AccountLinks
Custom billing and renewal URLs for the account.
Example: 
{
  "billing_url": "https://example.com/billing",
  "renewals_url": "https://example.com/renewals"
}
external_idoptional, string
Partner-assigned identifier for the account. You can also set or change it later with the update account endpoint.
Example: "external-id-456"
metadataoptional, object
Freeform partner-supplied string metadata. Fields are shallow-merged into the stored object: a value adds or overwrites that key, null removes it, and omitted keys are left unchanged. At most 50 keys, and each key together with its value may be at most 100 characters.
Example: 
{
  "building_name": "Maple Court",
  "move_in_date": "2026-08-20",
  "move_out_date": "2027-08-19"
}
term_month_optionsoptional, array of integer
Contract terms in months the customer may choose from during enrollment. Overrides the plan's default term options. Omit to use the plan's default options. Only applies to term plans.
Example: [12,24,36]
planoptional, string
UUID of the plan to preselect for the account.
Example: "bb7d3c4d-3402-4291-b3a4-e537a8b3225d"
broker_terms_agreedoptional, boolean
Whether the customer has been shown, and agreed to, the broker terms of service. Pass true only if the customer has already agreed.

Response

AccountCreateResponse

Get accounts count#

Get the total count of accounts.

This endpoint allows you to get the total count of accounts without fetching all the data, which is useful for performance and UI purposes (like showing "X of Y records").

This endpoint supports the same query parameters as the List accounts endpoint. See that endpoint for more details on the supported filters.

Request

Query parameters

filteroptional, array of string
Account lifecycle states to filter by. Repeat to match any of several states, e.g. ?filter=active&filter=cancelled. created: no consumer attached yet. applying: consumer attached but prerequisites not yet met. reviewing: enrollment is being reviewed. needs_attention: something needs to be fixed. scheduled: all of Light's checks have cleared, waiting to send the switch to the utility. activating: the switch was sent to the utility, waiting for service to start. active: service is active. cancelled: service or account is cancelled.
Example: "enrolled"
searchoptional, string
Case-insensitive search across email, first name, last name, external_id, and account number. Names and email match on a partial; external_id and account number have to match in full. Every word has to match something, so a full name narrows the results instead of widening them (Ryan Schwab returns the Ryan named Schwab, not every Ryan and every Schwab). Only the first four words are used. A search made up only of digits and phone punctuation is also matched against the phone number in any format, and a full account UUID returns that account exactly.
Example: "john"
emailoptional, string
Filters to accounts with this exact email address (case-insensitive).
Example: "john@example.com"
plan_group_uuidoptional, array of string
Filters to accounts on these plans. Repeat to match any of several plans. Matches the plan exactly; see include_fallback_plans to also match accounts that rolled onto a plan's fallback.
Example: "bb7d3c4d-3402-4291-b3a4-e537a8b3225d"
external_idoptional, string
Filters to the account with this partner-assigned external ID.
Example: "external-id-456"
plan_typeoptional, string
Filters to accounts on plans of this type.
Possible values: TERM, MONTH_TO_MONTH, FALLBACK
Example: "FALLBACK"
include_fallback_plansoptional, boolean
Whether plan_group_uuid also matches accounts on the plan's fallback plan. Useful because a fallback plan cannot be filtered on its own.
device_typeoptional, array of string
Narrows device_status and missing_program_device to these device types. On its own it narrows both, so it returns accounts whose device is of these types as well as accounts on a program expecting one with nothing enrolled.
Example: "BATTERY"
device_statusoptional, array of string
Only accounts whose device is in one of these statuses. inactive matches a device that was unenrolled or decommissioned, which is narrower than missing_program_device — that also covers accounts which never connected one.
Example: "needs_attention"
missing_program_deviceoptional, boolean
Only accounts on a device program with no device currently enrolled. Combines with device_status as a union, and with device_type by the types the program expects.
expiring_in_daysoptional, integer
Only accounts whose active term contract ends within this many days and whose consumer has not accepted a renewal offer yet. Contracts already ended, or cut short because the location is leaving service, are excluded. Also orders the list by soonest end date first.
Example: 90

Response

AccountsCountResponse

Get account#

Retrieve detailed information about a specific account associated with your app.

This endpoint provides information about any Account of an App using an AppToken.

For details on status and status_reason, see Account Statuses.

Request

Path parameters

account_uuidstring
UUID of the account.

Response

AppAccountResponse

Update account#

Update the details of an existing account.

This endpoint allows you to update the first name, last name, and email address of an account.

It must be called with an AppToken from the server side, since editing an account requires app-level permissions. Make sure that you have validated these updates through your own server before updating Light. For example, verify that a new email address is owned by the account holder.

Request

Path parameters

account_uuidstring
UUID of the account.

Body

first_nameoptional, string
Customer's first name.
Example: "John"
last_nameoptional, string
Customer's last name.
Example: "Doe"
emailoptional, string
Customer's email address.
Example: "john@example.com"
phone_numberoptional, string
Customer's phone number, used for customer support. Required before service can be activated.
Example: "5551234567"
service_start_dateoptional, string
Requested date for service to start.
Example: "2026-08-20"
preliminary_addressoptional, PreliminaryAddressInput
Preliminary service address for the account.
Example: 
{
  "address_1": "123 Main St",
  "address_2": "Apt 1",
  "city": "Dallas",
  "postal_code": "75201",
  "state": "TX"
}
location_metadataoptional, AccountLocationMetadata
Additional metadata about the service location, such as solar and battery details.
Example: 
{
  "battery_capacity_kwh": "13.5",
  "solar_estimated_annual_kwh": 12000,
  "solar_system_size_watts": 9000
}
account_linksoptional, AccountLinks
Custom billing and renewal URLs for the account.
Example: 
{
  "billing_url": "https://example.com/billing",
  "renewals_url": "https://example.com/renewals"
}
external_idoptional, string
Partner-assigned identifier for the account. Omit to leave unchanged, send null to clear, or send a string to set.
Example: "external-id-456"
metadataoptional, object
Freeform partner-supplied string metadata. Fields are shallow-merged into the stored object: a value adds or overwrites that key, null removes it, and omitted keys are left unchanged. At most 50 keys, and each key together with its value may be at most 100 characters.
Example: 
{
  "building_name": "Maple Court",
  "move_in_date": "2026-08-20",
  "move_out_date": "2027-08-19"
}
term_month_optionsoptional, array of integer
Contract terms in months the customer may choose from during enrollment. Omit to leave unchanged, send null to revert to the plan's default options, or send a list to set. Only applies to term plans.
Example: [12,24,36]
planoptional, string
UUID of the plan to preselect for the account.
Example: "bb7d3c4d-3402-4291-b3a4-e537a8b3225d"
broker_terms_agreedoptional, boolean
Whether the customer has been shown, and agreed to, the broker terms of service. Pass true only if the customer has already agreed. An agreement can't be revoked, so false is ignored.

Response

AppAccountResponse

Get enrollment evidence#

Retrieve a link to the enrollment evidence PDF for an account's finalized enrollment.

The PDF contains evidence documents based on where the account is enrolled. In Texas, the document is the PUCT §25.474 evidence package documenting the customer's enrollment. The returned URL is a signed link that expires one week after it is generated.

Returns 422 if the account's enrollment has not been finalized yet.

Request

Path parameters

account_uuidstring
UUID of the account.

Response

EnrollmentEvidenceResponse

Cancel pre-activation enrollment#

Cancel an enrollment before service starts.

Partners use this when a project is cancelled before activation. The endpoint cancels the enrollment when service has not started, including after submission to the utility. When the enrollment was submitted, this endpoint also sends a cancel request to the utility. Active service, ended service, and closed accounts are rejected.

Response: The updated account, including status and status_reason. On success, status is cancelled and status_reason is cancelled_pre_start.

Returns 404 if the account is not found. Returns 409 if the scheduled start date is today or earlier, service has started, service has ended, or the account is closed. Returns 400 if reason is missing.

Request

Path parameters

account_uuidstring
UUID of the account.

Body

reasonstring
Reason the partner is cancelling the enrollment.
Example: "Project cancelled before PTO"

Response

AppAccountResponse

Record client agent enrollment#

Record that a client agent is authorized to enroll on the customer's behalf.

A valid client agent record is required to accept a plan with accepted_by: "partner". Calling this endpoint again updates the existing record.

It must be called with an AppToken from the server side.

Request

Path parameters

account_uuidstring
UUID of the account.

Body

client_agent_accepted_atoptional, string
When the customer accepted the power-of-attorney agreement. Defaults to the current time. Cannot be in the future or more than one year in the past.
Example: "2026-03-01T14:30:00Z"
agreement_pdfoptional, string
Base64-encoded PDF of the power of attorney agreement, at most 10MB. A new document replaces the previous one.
Example: "JVBERi0xLjQ="

Response

AppAccountResponse

Create battery#

Provision a battery for an Account with a preliminary capacity. Light will use the identifier to automatically validate authorization and battery details with the manufacturer. Implementation of this endpoint is typically only required where the partner owns the battery and there is no consumer OAuth flow. The battery should only be created after the system activation/PTO (permission to operate) date.

Request

Path parameters

account_uuidstring
UUID of the account.

Body

manufacturerstring
The device manufacturer name.
Possible values: tesla, solaredge, enphase, sigenergy, franklin, ecoflow, duracell, foxess, sonnen, generac, epcube
Example: "tesla"
identifierstring
Manufacturer-specific identifier. For Tesla: energy_site_id. For SolarEdge: siteId. For Enphase: system_id. For EP Cube: the EP Cube device ID. For Generac: the PWRcell 2 gateway serial number. For FoxESS: stationID, or the inverter or hub serial number. For Sonnen: the battery serial number.
Example: "429124"
preliminary_capacity_kwhnumber | string
The total kWh capacity for all batteries at this location. Send a number or a decimal string. This value is only used as a placeholder until Light has an authorized connection to the battery.
Example: 13.5

Response

AppAccountDevice

Create charger#

Provision a charger (EVSE) for an Account. Light will use the identifier to automatically validate authorization and device details with the manufacturer. Implementation of this endpoint is typically only required where the partner owns the charger and there is no consumer OAuth flow. The charger should only be created after it has been installed.

Request

Path parameters

account_uuidstring
UUID of the account.

Body

manufacturerstring
The EVSE manufacturer name.
Example: "emporia"
identifierstring
Manufacturer-specific charger identifier.
Example: "charger-001"

Response

AppAccountDevice

Create vehicle#

Provision a vehicle for an Account. Light will use the identifier to automatically validate authorization and device details with the manufacturer. Implementation of this endpoint is typically only required where the partner owns the vehicle and there is no consumer OAuth flow.

Request

Path parameters

account_uuidstring
UUID of the account.

Body

manufacturerstring
The vehicle manufacturer name.
Possible values: hyundai, volvo, rivian, genesis
Example: "hyundai"
identifierstring
VIN or manufacturer-specific vehicle unique identifier.
Example: "KM8KRDDF3RU000001"

Response

AppAccountDevice

Search by address#

Search for service addresses by partial address query.

This endpoint allows you to search for service addresses using a partial address query. It is best used as a typeahead search for the user to select from. If you want to search for a full address, then consider using the full-address-search endpoint instead which does more of an exact match.

The API contains all possible addresses that could be enrolled for service. If a user is unable to find their address with this endpoint, they could try inputting an ESI ID directly into the ESI ID search endpoint. Both endpoints are searching over the same information.

Request

Body

querystring
Free-text address search query.
Example: "123 Main St"
postal_codeoptional, string
Optional postal code to narrow the search.
Example: "75201"

Response

array of AddressSearchResponse

Search full address by components#

Search for service addresses by full address.

This endpoint allows you to search for service addresses using a full address components. It is best used if you already have the full address components and want to search for a specific address. It operates similarly to the preliminary address search, but doesn't require a preliminary address to be set on the account.

The search will mostly look for exact matches, although it does some transformations to is try and match to addresses in the utility database which are often formatted differently than other sources like Google Maps. For example, it will try to match "123 Main St" to "123 Main Street".

Request

Body

address_1string
First line of the street address.
Example: "123 Main St"
address_2optional, string
Second line of the street address, such as a unit or apartment.
Example: "Apt 1"
citystring
City of the address.
Example: "Dallas"
statestring
State of the address.
Example: "TX"
postal_codestring
Postal code of the address.
Example: "75201"

Response

array of AddressSearchResponse

Check eligibility#

Check if a user is likely eligible to enroll in a plan.

This endpoint requires at least a postal code, but it is recommended to provide as much information as possible to increase the accuracy of the eligibility check.

Request

Body

postal_codestring
Postal code of the service location.
Example: "75201"
address_1optional, string
First line of the street address.
Example: "123 Main St"
address_2optional, string
Second line of the street address, such as a unit or apartment.
Example: "Apt 1"
cityoptional, string
City of the address.
Example: "Dallas"
stateoptional, string
Two-letter state code of the address.
Example: "TX"
utility_numberoptional, string
Utility meter identifier (ESI ID) for the location.
Example: "55512345671234567"

Response

EligibilityResponse

Get plan benchmarks#

Get estimated benchmarks for comparing against market rates.

This endpoint requires at least a postal code, but it is recommended to provide as much information as available to increase accuracy.

The response includes a list of example rate plans that the user could likely enroll in along with one or more benchmarked plans similar to that plan. The benchmarked plans represent an average of similar plans on the market that the user could enroll in. These benchmarks are useful for showing potential cost savings by comparing your plans against typical market alternatives.

Request

Body

postal_codestring
Postal code of the service location.
Example: "75201"
address_1optional, string
First line of the street address.
Example: "123 Main St"
address_2optional, string
Second line of the street address, such as a unit or apartment.
Example: "Apt 1"
cityoptional, string
City of the address.
Example: "Dallas"
stateoptional, string
Two-letter state code of the address.
Example: "TX"
utility_numberoptional, string
Utility meter identifier (ESI ID) for the location.
Example: "55512345671234567"

Response

BenchmarksResponse

Request available plans#

Request customized electricity plans with adjustable pricing and terms.

This App-level API (requiring AppToken authentication) extends the standard plan request functionality by allowing partners to customize margin, rate, and term length parameters.

If you are showing the rate to the user, make sure that you show the returned energy_rate_cents_per_kwh and not the energy_rate_cents_per_kwh that you pass in. The returned one may be rounded to the nearest 2 decimal places.

You can provide either the esi_id or the postal_code and utility together.

Request

Body

esi_idoptional, string
ESI ID (meter identifier) for the service location.
Example: "55512345671234567"
postal_codeoptional, string
Postal code of the service location.
Example: "77098"
utilityoptional, string
Identifier of the utility (TDSP) serving the location.
Example: "CENTERPOINT"
plan_groupoptional, string
UUID of the plan group to request a rate for.
Example: "bb7d3c4d-3402-4291-b3a4-e537a8b3225d"
term_monthsoptional, integer
Contract term length in months being requested.
Example: 12
energy_rate_cents_per_kwhoptional, number | string | null
Energy rate in cents per kWh. Will be rounded to nearest 2 decimal places.
Example: "10.0"
partner_commission_per_month_dollarsoptional, number | string | null
Partner commission per month in dollars. Will be rounded to nearest 2 decimal places.
Example: "10.0"

Response

array of CustomPlanResponse

List enrollment opt-out reasons#

Return the suggested opt-out reasons to present in an enrollment opt-out survey.

Partners can fetch this list instead of hardcoding reason codes and labels. Use the returned reason value in POST /accounts/events with event: enrollment_opt_out and pass the text shown to the customer in label when needed (for example when reason is other or the customer enters free-form text).

filter values:

ValueWhen to use
enrollment_switchCustomer is switching providers at an existing address
enrollment_move_inCustomer is moving in and starting new service
renewalCustomer is declining to renew their current plan

Examples

GET /accounts/enroll/opt-out/reasons?filter=enrollment_switch
GET /accounts/enroll/opt-out/reasons?filter=renewal

Mounted at GET /accounts/enroll/opt-out/reasons.

Request

Query parameters

filteroptional, string
Survey filter. Returns a curated list of reasons for that flow. One of enrollment_switch, enrollment_move_in, or renewal. Omit to return every defined reason.
Possible values: enrollment_switch, enrollment_move_in, renewal
Example: "enrollment_switch"

Response

array of OptOutReasonOption

Get disallowed service start dates#

Get a list of dates that are not allowed for service start.

This endpoint returns all weekends and holidays for the upcoming year (365 days) that cannot be selected as service start dates. If a non-business day is submitted as a service start date, it will be automatically adjusted to the next business day.

Example Use Case: Use this endpoint to populate a date picker in your UI, disabling dates that are not available for service start. This ensures users can only select valid business days for their service start date.

Request

No request parameters.

Response

DisallowedDatesResponse

List contracts#

List contracts for the authenticated app

This API lists out contracts for the authenticated app including plan details specific to each contract

Request

Query parameters

stateoptional, string
Filters to contracts in this state. active: the contract is currently active. ended: the customer ended the contract early by moving out or switching service. expired: the contract expired. queued: the contract is scheduled to activate in the future.
Possible values: active, ended, expired, queued
Example: "active"
account_uuidoptional, string
Filters to contracts for this account.
Example: "a14b20c3-809a-483f-98dc-3d35911eec42"
location_uuidoptional, string
Filters to contracts for this service location.
Example: "440e8400-e29b-41d4-a716-446655440000"
plan_group_uuidoptional, string
Filters to contracts on this plan.
Example: "bb7d3c4d-3402-4291-b3a4-e537a8b3225d"
limitoptional, integer
Maximum number of results to return per page.
offsetoptional, integer
Number of results to skip before the returned page.

Response

PagedContractResponse

List devices#

List the devices of all Accounts in your app. Each device includes the account_uuid of the Account that owns it. Devices are in the order that they were created. To find the Accounts that have no device in their device program, use GET /v1/app/accounts with missing_program_device=true.

Request

Query parameters

account_idsoptional, array of string
Only the devices of these Accounts. You can send a maximum of 25 Account UUIDs.
limitoptional, integer
Maximum number of results to return per page.
offsetoptional, integer
Number of results to skip before the returned page.

Response

PagedAppAccountDevice

Upload usage profile#

Upload interval usage data for asynchronous processing. Once processed successfully, you will be able to request custom pricing for this location.

Data Requirements:

  • At least 1 year of interval data is required
  • Data must be from a reputable source such as Smart Meter Texas or AMS in ERCOT

Interval Data Format:

  • Each day should typically have 96 intervals (24 hours x 4 intervals/hour)
  • DST spring forward days have 92 intervals (skipped hour)
  • DST fall back days have 100 intervals (repeated hour)
  • Import values are required, export values are optional
  • All values are in kWh

Returns 202 Accepted with the usage profile UUID that can be used to check status.

Note: This feature requires enablement. Contact support to enable usage profiles for your app.

Webhooks:

  • usage_profile.completed — sent when the profile is successfully processed
  • usage_profile.failed — sent when processing fails

Webhook payloads include uuid, status, utility_account_number, start_date, end_date, and error_message.

Usage Profile Behavior:

  • Plans for this utility account must be requested using utility_account_number (not postal_code/utility)
  • The profile will automatically be applied to customize rates

Request

Body

dataarray of UsageProfileDayData
Array of daily interval data. At least 1 year of data required. Each day must have 92-100 intervals (typically 96 for non-DST days).
Example: [{"date":"2023-12-14","export":[0,0],"import":[0.768,1.622]}]
utility_account_numberstring
ESI ID / utility account number associated with the usage profile.
Example: "10123456789012345678"
timezoneoptional, string
Timezone for interval data. Currently only America/Chicago is supported.
Example: "America/Chicago"
interval_minutesoptional, integer
Minutes per interval. Currently only 15 is supported.
Example: 15

Response

UsageProfile

Fetch usage profile from SMT#

Trigger an SMT data fetch to create a usage profile from a comparison invoice.

The invoice does not need to be fully processed — if it is still pending, the SMT agreement will be created automatically once processing completes. The usage data is fetched and processed asynchronously. Use the GET endpoint to poll for status, or configure webhooks to be notified.

Returns 202 Accepted with the usage profile UUID that can be used to check status.

Sandbox vs Live:

  • Sandbox apps will use synthetic data instead of real SMT data.
  • Live apps require proper customer authorization with explicit language that the customer is authorizing the use of their Smart Meter Texas data.

Webhooks:

  • usage_profile.completed — sent when the profile is successfully processed
  • usage_profile.failed — sent when processing fails

Webhook payloads include uuid, status, utility_account_number, start_date, end_date, and error_message.

Usage Profile Behavior:

  • Once completed, the usage profile will automatically be applied to customize rates when requesting plans for the associated utility_account_number.

Note: This feature may require enablement for your account. Contact support to enable usage profiles for your app.

Request

Body

comparison_invoice_uuidstring
UUID of the comparison invoice to fetch usage data for.
Example: "f1a2b3c4-d5e6-4f7a-8b9c-0d1e2f3a4b5c"
user_authorizes_usage_fetchboolean
Whether the user has authorized the usage fetch. In Texas, this is using Smart Meter Texas to fetch usage data.

Response

UsageProfile

Get usage profile#

Get the current status and metadata of a usage profile.

Status values:

  • pending: Profile received, queued for processing
  • completed: Successfully processed
  • failed: Processing failed (see error_message)

When completed, the usage profile will automatically be applied to customize rates when requesting plans for the associated utility account using utility_account_number.

Request

Path parameters

usage_profile_uuidstring
UUID of the usage profile.

Response

UsageProfile

Get account details#

Get the currently authenticated Account.

This API gives information on the current state of this account, including the consumer's overall account status, enrollment status, service locations, and billing information.

For details on status and status_reason, see Account Statuses.

For most apps and accounts there will only be one location once the consumer has enrolled. Multiple locations are possible if you intend to support multiple service addresses for the same user on your system.

Request

No request parameters.

Response

AppAccountResponse

Update account#

Update user information on the authenticated account. Note that phone_number and birth_date must be provided before service can be activated.

Request

Body

first_nameoptional, string
Customer's first name.
Example: "John"
last_nameoptional, string
Customer's last name.
Example: "Doe"
emailoptional, string
Customer's email address.
Example: "john@example.com"
phone_numberoptional, string
Customer's phone number, used for customer support. Required before service can be activated.
Example: "5551234567"
birth_dateoptional, string
Customer's date of birth in ISO 8601 (YYYY-MM-DD) format. Required before service can be activated.
Example: "1983-04-17"

Response

AppAccountResponse

Create payment session#

Create a payment session for setting up a payment method.

This endpoint is used to create a session with a payment provider (e.g., Stripe) to securely collect and save payment information for the consumer's account.

Request

No request parameters.

Response

CreatePaymentSessionResponse

Ensure payment method added#

Ensure a payment method has been added to the consumer's account.

This endpoint verifies that the provided payment method is associated with the consumer's account and updates the account with this payment method if it is not already set as the default.

Request

Body

payment_method_idoptional, string
Identifier of the payment method to add.
Example: "pm_1J2k3L4M5N6O7P8Q9R0"

Response

empty object

Get payment method#

Retrieve the current default payment method for the consumer's account.

This endpoint returns the details of the default payment method associated with the consumer's account.

Request

No request parameters.

Response

PaymentMethodResponse

Get billing address#

Retrieve the billing address associated with the consumer's account.

This endpoint returns the billing address details if it has been confirmed by the consumer.

Request

No request parameters.

Response

BillingAddressResponse

Updating billing address#

Update the billing address for the consumer's account.

This endpoint allows the consumer to set or update their billing address.

Request

Body

same_as_service_addressoptional, boolean
Whether the billing address is the same as the service address.
addressoptional, Address
Billing address, required when it differs from the service address.

Response

empty object

List invoices#

Retrieve a list of invoices for the consumer's account.

This endpoint returns a paginated list of invoices, including key details for each invoice.

Request

Query parameters

limitoptional, integer
Maximum number of results to return per page.
offsetoptional, integer
Number of results to skip before the returned page.

Response

PagedInvoiceResponse

Get invoice details#

Retrieve detailed information about a specific invoice.

This endpoint provides a comprehensive breakdown of an invoice, including itemized charges and usage details.

Request

Path parameters

invoice_numberstring
Invoice number.

Response

InvoiceDetailResponse

Pay an invoice#

Make a payment for the given invoice

This endpoint allows a customer to pay an invoice manually. Generally, this will allow them to make a payment before an invoice is due. It will also allow them to make a payment after updating their payment method if their previous payment method failed.

Response: 204: The invoice was successfully paid. 404: No payable invoice was found for the given invoice number. The invoice may not exist, or may not be in a payable state. 422: The payment could not be processed at this time. This can occur if the invoice is not yet payable before its due date, the payment method is invalid, or another issue prevents charging.

Request

Path parameters

invoice_numberstring
Invoice number.

Body

allow_payment_before_due_dateoptional, boolean
Whether to allow paying the invoice before its due date. Must be true to pay an invoice that is not yet due.

Response

Get comparison invoice#

Get the comparison invoice for a user.

Request

No request parameters.

Response

ComparisonInvoiceResponse

Upload a comparison invoice#

Upload a user's invoice from their current energy provider to compare costs.

This endpoint accepts a PDF invoice and extracts usage and cost data for comparison purposes. The parsed data can be used to show potential savings by comparing the customer's current costs against available plans. Use the simple-compare endpoint after uploading to get comparison results.

Request

No request parameters.

Response

ComparisonInvoiceResponse

Simple compare#

Get a simple comparison between an uploaded invoice and a plan.

This endpoint provides a comparison between a previously uploaded invoice and a plan, showing the estimated cost difference between what the customer paid and what they would have likely paid on the plan for the same usage. The comparison is off an "all-in" cost of an invoice for this usage, including a typical tax rate, etc.

Example usage


// get the response of this API
data = response.json()

// check if there was an error
if (data.processing_error) {
    console.error(data.processing_error)
    return
}

// get the parsed invoice data
const invoiceData = data.parsed_invoice_data

// if the plan is month-to-month
if (!invoiceData.contract_end_date) {
    console.log("The customer is on a month-to-month plan")

    // see if there would have been savings on this usage
    const savings = invoiceData.total_dollars - planComparison.total_dollars
    if (savings > 0) {
        console.log(`The customer would have saved ${savings} dollars this invoice`)
    } else {
        console.log("The customer would not have saved any money on this usage")
    }
    return
} else {
  // Otherwise there is a contract in place, which may indicate an early-termination fee if
  // they were to switch now. If savings is high enough
}

Request

Query parameters

plan_groupoptional, string
Identifier of the plan to compare against the customer's current plan. The app's default plan is used when omitted.
Example: "solar-buyback"
uuidoptional, string
UUID of a specific comparison invoice to use; the most recent is used when omitted.
Example: "f1a2b3c4-d5e6-4f7a-8b9c-0d1e2f3a4b5c"

Response

ComparisonInvoiceSimpleCompareResponse

Annual compare#

Get a full-year (Jan-Dec) cost projection comparing the customer's current plan against your offered plan.

Unlike simple-compare, which replays a single invoice period to show what that exact usage would have cost on Light's plan, annual-compare projects costs across all 12 calendar months. Because monthly usage is estimated from historical data (not tied to a specific meter reading period), annual totals may not exactly match any single invoice — this endpoint is designed to give a broader picture of expected annual savings in a typical year.

How monthly usage is determined

The endpoint uses a cascade to build a 12-month usage profile:

  1. Usage profile available (preferred): If the customer has a completed usage profile with interval analysis, actual historical meter data is averaged into monthly totals. The analysis may span more than one year of data, in which case daily usage is averaged across years before scaling to full months. This produces the most accurate month-by-month projection.

  2. No usage profile, but invoice date available (fallback): A default Texas residential load shape is scaled to match the invoice's kWh for its billing month.

Current plan simulation

The customer's current plan is classified from the parsed invoice into one of several types:

  • SIMPLE: Standard energy rate + TDU charges + base charges. Most common.
  • FREE_PERIOD: Plans with a portion of usage at no energy charge (e.g., free nights/weekends). TDU charges still apply to all usage.
  • AVERAGE_BILLING: Level-pay / budget billing — the invoice total is treated as a flat monthly cost.

These classifications may evolve as we encounter new plan structures and improve accuracy. This endpoint is not meant to provide a perfect prediction or guarantee, but to help illustrate the potential savings for most customers.

In cases where the simulation seems to be significantly off from the actual bill, we will adjust slightly or fall back to using the invoice's overall effective rate (total bill / total kWh).

Request

Query parameters

plan_groupoptional, string
Identifier of the plan to compare against the customer's current plan. The app's default plan is used when omitted.
Example: "solar-buyback"
uuidoptional, string
UUID of a specific comparison invoice to use; the most recent is used when omitted.
Example: "f1a2b3c4-d5e6-4f7a-8b9c-0d1e2f3a4b5c"

Response

AnnualCompareResponse

Search by address#

Search for service addresses by partial address query.

This endpoint allows you to search for service addresses using a partial address query. It is best used as a typeahead search for the user to select from. If you want to search for a full address, then consider using the full-address-search endpoint instead which does more of an exact match.

The API contains all possible addresses that could be enrolled for service. If a user is unable to find their address with this endpoint, they could try inputting an ESI ID directly into the ESI ID search endpoint. Both endpoints are searching over the same information.

Request

Body

querystring
Free-text address search query.
Example: "123 Main St"
postal_codeoptional, string
Optional postal code to narrow the search.
Example: "75201"

Response

array of AddressSearchResponse

Search by stored preliminary address#

Search for service addresses based on the account's preliminary address if set.

This search returns higher confidence addresses since it is matching against a complete address suggested for the account. However you will still want to have the user confirm the address before enrolling, and optionally fall back to other search endpoints if the user can't find their address with this one.

Request

No request parameters.

Response

array of AddressSearchResponse

Search by ESI ID#

Search for a service address by its ESI ID.

This endpoint allows you to search for a service address using its Electric Service Identifier (ESI ID). If the user can't find their ESID with this endpoint or the address search endpoint, they may not be in a deregulated area or may need to contact support for further help in enrollment.

Request

Body

esi_idstring
ESI ID (meter identifier) to look up.
Example: "55512345671234567"

Response

AddressSearchResponse

Identity#

Update a user's identity.

This endpoint collects information from a user for identity verification purposes. At least one of the fields needs to be given for a successful response.

Request

Body

ssn_last4optional, string
Last four digits of the customer's Social Security number.
Example: "1234"
mothers_maiden_nameoptional, string
Customer's mother's maiden name, used for identity verification.
Example: "Smith"
birth_cityoptional, string
City where the customer was born, used for identity verification.
Example: "Dallas"
birth_dateoptional, string
Customer's date of birth in ISO 8601 (YYYY-MM-DD) format. Required before service can be activated.
Example: "1983-04-17"
drivers_license_numberoptional, string
Customer's driver's license number.
Example: "1234567890"

Response

empty object

Submit credit check request#

Submit a credit check request for a user.

This endpoint allows you to submit a credit check request for a user as part of the enrollment process. The request must include the user's SSN (in the format 123-45-6789) and confirmation that they agree to the terms of the credit check. Please contact us for the required disclosure language.

Response: A response of 200 will be given on success.

Request

Body

ssnstring
Customer's full Social Security number, formatted as 123-45-6789.
Example: "123-45-6789"
agree_to_termsboolean
Whether the customer agreed to the credit-check terms. Must be true.

Response

empty object

Get plan groups#

Retrieve a list of available electricity plan groups.

A plan group indicates features and core details about a plan that will be available if a user continues the enrollment process. The full plan rate and pricing will vary depending on other factors like the service address, but the plan group will indicate the core features of the plan up front.

Some of the fields in the plan group are nullable. If a field like plan_monthly_cost_dollars is null then it means that the plan monthly cost may change depending on the service address and other factors. However if the field is not null then it means that the plan monthly cost is fixed across all attached plans and can be advertised ahead of receiving the full plan details.

Note that the plan groups are intended to be useful for advertising rates early in the enrollment process but are not intended to be used for contract acceptance like a full plan with EFL, TOS, and YRAC.

Request

No request parameters.

Response

array of PlanGroupResponse

Request available plans#

Request available electricity plans for a specific service address.

This endpoint returns a list of electricity rate plans available for the given address.

The plans are intended to be fetched when a user is viewing them and not cached for long periods of time as they can expire or change periodically when one of the variables in the plan changes. If a plan were to expire before being accepted, you will get an expiration error from the accept plan endpoint and need to fetch the plans again.

You can provide either the esi_id or the postal_code and utility together.

Request

Body

esi_idoptional, string
ESI ID (meter identifier) for the service location.
Example: "55512345671234567"
postal_codeoptional, string
Postal code of the service location.
Example: "77098"
utilityoptional, string
Identifier of the utility (TDSP) serving the location.
Example: "CENTERPOINT"
plan_groupoptional, string
UUID of the plan group to request a rate for.
Example: "bb7d3c4d-3402-4291-b3a4-e537a8b3225d"
term_monthsoptional, integer
Contract term length in months being requested.
Example: 12

Response

array of PlanResponse

Accept plan#

Accept an electricity rate plan for a specific service address.

This endpoint finalizes the selection of a rate plan and attaches it to the consumer's account.

Response: 200: The plan was successfully accepted. 422: The plan could not be accepted due to an error. - detail (string): The error message. Possible values include: - expired — the plan is no longer available - Account does not have a client agent record — accepted_by was "partner" but the account has no client agent on file - Client agent authorization has expired — accepted_by was "partner" but the client agent record is older than 12 months

Request

Body

plan_uuidstring
UUID of the plan to accept.
Example: "db94f2a7-84ab-4081-9896-4de2bdde984e"
esi_idstring
ESI ID (meter identifier) for the service location.
Example: "55512345671234567"
service_start_datestring
Date service should start.
Example: "2026-08-20"
service_eventoptional, string
Type of service event for the enrollment.
Possible values: switch, move_in
Example: "switch"
terms_acceptedboolean
Whether the customer accepted the plan terms. Must be true to accept the plan.
accepted_byoptional, string
Who accepted the plan. Case-insensitive. When partner, the account must have a client agent record accepted within the last 12 months, and a Letter of Authorization is generated at finalization.
Possible values: customer, partner
Example: "customer"

Response

empty object

Get a specific plan#

Fetch a single, previously-quoted plan by its uuid.

Returns the exact plan as it was priced when originally requested, without re-pricing. The uuid is the one returned by the request-plans endpoint. The plan is returned even if it has since expired or been deactivated; acceptance eligibility is only enforced when accepting the plan.

Request

Path parameters

plan_uuidstring
UUID of the plan.

Response

PlanResponse

Finalize enrollment#

Finalize the pending enrollment for this account.

This endpoint completes the enrollment process for the account. It should be called after the user has accepted a plan and provided all necessary information, including billing address confirmation, payment information, and identity verification.

You can determine whether or not this API will succeed by checking the can_finalize_enrollment field in Account's enrollment section.

Until this endpoint is called successfully, the user's enrollment will remain in a pending state and not be finalized, and they will not be able to receive service from the selected provider.

Request

No request parameters.

Response

empty object

Reset enrollment state#

Reset the enrollment state for an account.

This endpoint is meant to be used for an account that previously had a finalized enrollment, but wants to go through the process again. The primary supported use-case here currently is for a user that was an active customer that dropped/switched service and wants to re-enroll again. Calling this API for an account in that state will reset the account's enrollment states:

  • is_enrollment_finalized will become False
  • The account will be able to accept a new plan for the same esid as their previous plan.

Request

No request parameters.

Response

empty object

Check eligibility#

There is another version of this endpoint in the App Enrollment APIs depending on if you prefer to use it without an account created.

Check if a user is likely eligible to enroll in a plan.

This endpoint requires at least a postal code, but it is recommended to provide as much information as possible to increase the accuracy of the eligibility check.

Request

Body

postal_codestring
Postal code of the service location.
Example: "75201"
address_1optional, string
First line of the street address.
Example: "123 Main St"
address_2optional, string
Second line of the street address, such as a unit or apartment.
Example: "Apt 1"
cityoptional, string
City of the address.
Example: "Dallas"
stateoptional, string
Two-letter state code of the address.
Example: "TX"
utility_numberoptional, string
Utility meter identifier (ESI ID) for the location.
Example: "55512345671234567"

Response

EligibilityResponse

Get plan benchmarks#

There is another version of this endpoint in the App Enrollment APIs depending on if you prefer to use it without an account created.

Get estimated benchmarks for comparing against market rates.

This endpoint requires at least a postal code, but it is recommended to provide as much information as available to increase accuracy.

The response includes a list of example rate plans that the user could likely enroll in along with one or more benchmarked plans similar to that plan. The benchmarked plans represent an average of similar plans on the market that the user could enroll in. These benchmarks are useful for showing potential cost savings by comparing your plans against typical market alternatives.

Request

Body

postal_codestring
Postal code of the service location.
Example: "75201"
address_1optional, string
First line of the street address.
Example: "123 Main St"
address_2optional, string
Second line of the street address, such as a unit or apartment.
Example: "Apt 1"
cityoptional, string
City of the address.
Example: "Dallas"
stateoptional, string
Two-letter state code of the address.
Example: "TX"
utility_numberoptional, string
Utility meter identifier (ESI ID) for the location.
Example: "55512345671234567"

Response

BenchmarksResponse

Get disallowed service start dates#

Get a list of dates that are not allowed for service start.

This endpoint returns all weekends and holidays for the upcoming year (365 days) that cannot be selected as service start dates. If a non-business day is submitted as a service start date, it will be automatically adjusted to the next business day.

Example Use Case: Use this endpoint to populate a date picker in your UI, disabling dates that are not available for service start. This ensures users can only select valid business days for their service start date.

Request

No request parameters.

Response

DisallowedDatesResponse

Get location plan#

Retrieve the latest currently active rate plan for a specific service location.

This endpoint returns the currently active rate plan for the service location, including the plan's details and links to important documents.

Request

Path parameters

location_uuidstring
UUID of the service location.

Response

LocationPlan

Get all location plans#

Get all plans for a location

Request

Path parameters

location_uuidstring
UUID of the service location.

Query parameters

limitoptional, integer
Maximum number of results to return per page.
offsetoptional, integer
Number of results to skip before the returned page.

Response

PagedLocationPlan

Get active location documents#

Retrieve latest active documents related to a specific service location for the currently active contract.

This endpoint returns links to the latest important documents associated with the service location, including the Electricity Facts Label (EFL), Terms of Service (TOS), and Your Rights as a Customer (YRAC).

Request

Path parameters

location_uuidstring
UUID of the service location.

Response

DocumentsResponse

Get all location documents#

Retrieve a list of sets of documents, including historical documents, related to a specific service location.

This endpoint returns a list of document sets, each containing links to important documents associated with the service location, including the Electricity Facts Label (EFL), Terms of Service (TOS), and Your Rights as a Customer (YRAC).

Request

Path parameters

location_uuidstring
UUID of the service location.

Query parameters

limitoptional, integer
Maximum number of results to return per page.
offsetoptional, integer
Number of results to skip before the returned page.

Response

PagedDocumentsResponse

Get location support info#

Retrieve support and outage information for a specific service location.

This endpoint provides contact information for your app's customer support team as well as the Transmission and Distribution Utility (TDU) responsible for the service location.

Request

Path parameters

location_uuidstring
UUID of the service location.

Response

SupportInfoResponse

List location meter reads#

Retrieve meter reads and usage data for a specific service location.

This endpoint returns a list of meter reads, providing detailed information about electricity consumption over specified periods. These reads are typically ~30 days apart, but will fluctuate based on the utility's schedule. They can also be less than 30 days when a new meter is installed or service is started/switched.

Request

Path parameters

location_uuidstring
UUID of the service location.

Response

array of UsagePeriodResponse

Get monthly usage#

Retrieve the monthly usage for a specific location for the current year or the given year.

This endpoint returns an entire year of usage - both import and export - separated by month. In addition, it provides links to the previous and next year of usage if applicable.

Depending on the customer's utility provider, we may or may not have up to two years of historical data for a single customer prior to enrollment, and we do not receive a day's data until 2-5 days after that day.

This usage data falls on a month boundary and cannot be used to exactly calculate the usage represented by a meter reading, which happens at some point during the day of the meter read. It's for informational purposes only to show usage over time and is not used for billing.

Request

Path parameters

location_uuidstring
UUID of the service location.

Query parameters

yearoptional, integer
Calendar year to return usage for. Defaults to the current year.
Example: 2024

Response

MonthlyUsageDataResponse

Get daily usage#

Retrieve the daily usage for a specific location for the current month or the given month.

This endpoint returns an entire month of usage - both import and export - separated by day. In addition, it provides links to the previous and next month of usage if applicable.

Depending on the customer's utility provider, we may or may not have up to two years of historical data for a single customer prior to enrollment, and we do not receive a day's data until 2-5 days after that day.

This usage data falls on a day boundary and cannot be used to exactly calculate the usage represented by a meter reading, which happens at some point during the day of the meter read. It's for informational purposes only to show usage over time and is not used for billing.

Request

Path parameters

location_uuidstring
UUID of the service location.

Query parameters

monthoptional, integer
Calendar month (1-12) to return usage for. Defaults to the current month.
Example: 1
yearoptional, integer
Calendar year to return usage for. Defaults to the current year.
Example: 2024

Response

DailyUsageDataResponse

Get 15-minute interval usage#

Retrieve the 15-minute interval usage, organized by day, for a specific location for the current month or the given month.

This endpoint returns an entire month of usage - both import and export - separated by day. In addition, it provides links to the previous and next month of usage if applicable.

Depending on the customer's utility provider, we may or may not have up to two years of historical data for a single customer prior to enrollment, and we do not receive a day's data until 2-5 days after that day.

This usage data falls on a 15-minute interval boundary and cannot be used to exactly calculate the usage represented by a meter reading. It's for informational purposes only to show usage over time and is not used for billing.

Most days have 96 intervals (four 15-minute intervals per hour for a 24 hour day). However, for locations participating in daylight savings time, this could be 92 intervals (spring forward) or 100 intervals (fall back).

We receive this data one day at a time, so there will never be a partial day represented.

Request

Path parameters

location_uuidstring
UUID of the service location.

Query parameters

monthoptional, integer
Calendar month (1-12) to return usage for. Defaults to the current month.
Example: 1
yearoptional, integer
Calendar year to return usage for. Defaults to the current year.
Example: 2024

Response

IntervalUsageDataResponse

Request available renewal plans#

Request available renewal electricity plans for an active service location.

This endpoint returns a list of electricity rate plans available for renewal for the given service location. Unlike the general plan request API, this endpoint is intended for customers who already have an active service location and are eligible to renew their contract.

For typical "append" renewals, the earliest_start_date and latest_start_date will be the same date (the date after the current contract ends). This is the date that needs to be passed to the accept renewal plan endpoint after having the user confirm their acceptance of the terms and start date.

Notes:

  • This endpoint requires the service location to be active and not already have a queued renewal plan.
  • If the location has a queued renewal plan, a 422 will be returned.
  • If no renewable rate is found for the location, an empty list will be returned.

Request

Path parameters

location_uuidstring
UUID of the service location.

Response

array of RenewalPlanResponse

Accept renewal plan#

Accept a renewal electricity rate plan for an active service location.

This endpoint finalizes the selection of a renewal rate plan and schedules it to begin on the specified date.

Response: 201: The renewal plan was successfully accepted and scheduled. 404: No renewable rate found for the location. 409: The selected plan is not available for renewal. 422: The location already has a new contract scheduled.

Notes:

  • This endpoint requires the service location to be active and not already have a queued renewal plan.

Request

Path parameters

location_uuidstring
UUID of the service location.

Body

plan_uuidstring
UUID of the renewal plan to accept.
Example: "db94f2a7-84ab-4081-9896-4de2bdde984e"
service_start_datestring
Date the renewal should start. Usually the earliest_start_date from the request renewal plans endpoint.
Example: "2026-08-20"
terms_acceptedboolean
Whether the customer accepted the renewal terms. Must be true to accept the plan.

Response

empty object

[SANDBOX-ONLY] Seed demo data#

[SANDBOX-ONLY] Seed your account with demo data

This endpoint allows accounts added to a sandbox app to seed their account with demo data in order to test production functionality without needing to actually enroll any customers.

Request

No request parameters.

Response

empty object

[SANDBOX-ONLY] Simulate service drop#

[SANDBOX-ONLY] Simulate service drop

This endpoint allows accounts added to a sandbox app to simulate a service drop for their account. This is what would happen if a customer were to switch to another provider and we receive a drop request from the utility.

The final_service_date will be set to today, and cancellation webhooks and emails will be sent.

Request

No request parameters.

Response

empty object

[SANDBOX-ONLY] Delete demo data#

[SANDBOX-ONLY] Delete seeded demo data

This endpoint allows accounts added to a sandbox app to delete their pre-seeded demo data.

Request

No request parameters.

Response

empty object

[SANDBOX-ONLY] Delete enrollment#

[SANDBOX-ONLY] Delete enrollment

This endpoint allows accounts added to a sandbox app to delete their enrollment so that they can go through the enrollment flow again. This will also delete any seeded demo data, so there's no need to call the "Delete seeded demo data" API.

Request

No request parameters.

Response

empty object

[SANDBOX-ONLY] Simulate credit check failure#

[SANDBOX-ONLY] Simulate a credit check failure

Marks the credit check enrollment check as failed (declined) for the current account. All other verification checks are bypassed. This puts the account into the "needs attention - credit declined" state so you can test the credit remediation flow without running a real credit check.

The account must have a finalized enrollment (consumer + service location + enrollment finalized) to use this endpoint.

Request

No request parameters.

Response

empty object

[SANDBOX-ONLY] Simulate enrollment submitted to utility#

[SANDBOX-ONLY] Simulate enrollment submitted to utility

Advances the current account's enrollment from the pending/service-pending state to "utility submitted" (SYNCED) without actually contacting the utility. This lets you test the post-submission phase of the enrollment flow.

The account must have a pending enrollment (verified) to use this endpoint.

Request

No request parameters.

Response

empty object

[SANDBOX-ONLY] Simulate service starting#

[SANDBOX-ONLY] Simulate service starting

Advances the current account's enrollment to the active-service state by marking service as started. The service start date is moved to today so that the transition is immediate.

The account must have been verified (all checks passed or bypassed) before calling this endpoint.

Request

No request parameters.

Response

empty object

Models

AcceptPlanRequest #

plan_uuidstring
UUID of the plan to accept.
Example: "db94f2a7-84ab-4081-9896-4de2bdde984e"
esi_idstring
ESI ID (meter identifier) for the service location.
Example: "55512345671234567"
service_start_datestring
Date service should start.
Example: "2026-08-20"
service_eventoptional, string
Type of service event for the enrollment.
Possible values: switch, move_in
Example: "switch"
terms_acceptedboolean
Whether the customer accepted the plan terms. Must be true to accept the plan.
accepted_byoptional, string
Who accepted the plan. Case-insensitive. When partner, the account must have a client agent record accepted within the last 12 months, and a Letter of Authorization is generated at finalization.
Possible values: customer, partner
Example: "customer"

AcceptRenewalPlanRequest #

plan_uuidstring
UUID of the renewal plan to accept.
Example: "db94f2a7-84ab-4081-9896-4de2bdde984e"
service_start_datestring
Date the renewal should start. Usually the earliest_start_date from the request renewal plans endpoint.
Example: "2026-08-20"
terms_acceptedboolean
Whether the customer accepted the renewal terms. Must be true to accept the plan.

AccountApp #

uuidstring
Unique identifier of the app.
Example: "c8e5d2f1-3a4b-4c5d-8e9f-0a1b2c3d4e5f"
namestring
Display name of the app.
Example: "Prod"
stripe_public_keyoptional, string
Stripe publishable key for the app's payment environment. Pass it to Stripe Elements to securely collect payment information.
Example: "pk_live_51ABCDEFexampleKey"
is_sandboxboolean
Whether the app is in sandbox mode.
organization_uuidstring
Unique identifier of the organization that owns the app.
Example: "b25c31d4-920b-494f-89ed-4e46022ffdf2"
organization_namestring
Name of the organization that owns the app.
Example: "Acme Energy"

AccountCreateResponse #

uuidstring
Unique identifier of the account.
Example: "a14b20c3-809a-483f-98dc-3d35911eec42"
external_idoptional, string
Partner-assigned identifier for the account.
Example: "external-id-456"
account_numberoptional, string
Light account number for the account.
Example: "LT-1234567890"
statusstring
Current high-level status of the account.
Possible values: created, applying, reviewing, needs_attention, scheduled, activating, active, cancelled
Example: "active"
status_reasonstring
Detailed status reason for the account.
Possible values: unresolved, missing_address, plan_not_accepted, missing_identity, missing_payment_method, enrollment_not_finalized, verification_pending, credit_check_pending, credit_not_found, credit_declined, credit_check_frozen, credit_check_error, enrollment_blocked_switch_hold, enrollment_blocked_verification_hold, enrollment_blocked_deactivated, utility_blocked, enrollment_pending_client_agent, enrollment_pending_deferred, service_pending, utility_submitted, active, cancelled_pre_start, expire_pre_active, cancelled_post_start, duplicate_enrollment
Example: "unresolved"
created_atstring
When the account was created.
Example: "2026-08-20T14:30:00Z"
first_namestring
Customer's first name.
Example: "John"
last_namestring
Customer's last name.
Example: "Doe"
emailstring
Customer's email address.
Example: "john@example.com"
phone_numberoptional, string
Customer's phone number.
Example: "5551234567"
enrollmentoptional, AccountEnrollment
Enrollment progress for the account.
has_client_agentoptional, boolean
Whether a power-of-attorney client agent is on file for the account.
preliminary_addressoptional, PreliminaryAddress
Preliminary service address provided for the account, before it is verified.
Example: 
{
  "address_1": "123 Main St",
  "address_2": "Apt 1",
  "city": "Dallas",
  "postal_code": "75201",
  "state": "TX"
}
partner_payment_method_on_fileoptional, null
Deprecated; always null.
Example: null
location_metadataoptional, AccountLocationMetadata
Additional metadata about the account's service location, such as solar and battery details.
Example: 
{
  "battery_capacity_kwh": "13.5",
  "solar_estimated_annual_kwh": 12000,
  "solar_system_size_watts": 9000
}
account_linksoptional, AccountLinks
Custom billing and renewal URLs configured for the account.
Example: 
{
  "billing_url": "https://example.com/billing",
  "renewals_url": "https://example.com/renewals"
}
opt_outoptional, AccountOptOut
Information about a customer opting out of an offer.
Example: 
{
  "detail": "Acme Energy 12-month plan",
  "opted_out_at": "2026-08-20T14:30:00Z",
  "plan_uuids": [
    "db94f2a7-84ab-4081-9896-4de2bdde984e"
  ],
  "reason": "found_cheaper_rate",
  "stage": "enrollment"
}
term_month_optionsoptional, array of integer
Contract terms (months) the customer may choose, resolved for the account's currently selected plan. Request one of these via /plans/request for that same plan; requesting a different plan may reject the term.
Example: [12,24,36]
was_createdoptional, boolean
Whether this request created a new account, rather than returning an existing one.

AccountEnrollment #

has_accepted_planoptional, boolean
Whether the customer has accepted a plan.
has_payment_methodoptional, boolean
Whether the customer has a payment method on file.
is_billing_address_confirmedoptional, boolean
Whether the customer confirmed their billing address.
is_identity_verifiedoptional, boolean
Whether the customer's identity is verified.
are_vehicles_enrolledoptional, boolean
Whether the customer has at least one vehicle enrolled.
can_finalize_enrollmentoptional, boolean
Whether enrollment can now be finalized.
is_enrollment_finalizedoptional, boolean
Whether enrollment is finalized.
finalized_atoptional, string
When enrollment was finalized.
Example: "2026-08-20T14:30:00Z"
is_service_activeoptional, boolean
Whether service is active at any of the account's locations.
has_usage_historyoptional, boolean
Whether usage history is available for any of the account's locations. This typically comes shortly after service is activated.
requires_credit_verificationoptional, boolean
Whether the customer must complete credit verification.

AccountLinks #

billing_urloptional, string
Custom billing URL for the account.
Example: "https://example.com/billing"
renewals_urloptional, string
Custom renewal URL for the account.
Example: "https://example.com/renewals"

AccountLocationMetadata #

solar_system_size_wattsoptional, integer
Rated solar system size in watts.
Example: 9000
solar_estimated_annual_kwhoptional, integer
Estimated annual solar production in kWh.
Example: 12000
battery_capacity_kwhoptional, string
Total energy storage capacity of all batteries at the service location, in kWh.
Example: "13.5"

AccountOptOut #

stagestring
What the customer opted out of.
Possible values: enrollment, renewal
Example: "enrollment"
reasonstring
Reason code the customer selected (unspecified when the customer did not select a reason).
Example: "found_cheaper_rate"
detailoptional, string
Free-text follow-up the customer gave for the reason.
Example: "Acme Energy 12-month plan"
plan_uuidsoptional, array of string
UUIDs of the plans shown to the customer before they opted out.
Example: ["db94f2a7-84ab-4081-9896-4de2bdde984e"]
opted_out_atstring
When the customer opted out.
Example: "2026-08-20T14:30:00Z"

AccountTokenResponse #

tokenstring
Short-lived client access token for the account.
Example: "lt_client_a14b20c3.example809ae483f68dc3d35911eec"
expires_atstring
When the token expires, 1 hour after it is created.
Example: "2026-08-20T14:30:00Z"

AccountUpdateRequest #

first_nameoptional, string
Customer's first name.
Example: "John"
last_nameoptional, string
Customer's last name.
Example: "Doe"
emailoptional, string
Customer's email address.
Example: "john@example.com"
phone_numberoptional, string
Customer's phone number, used for customer support. Required before service can be activated.
Example: "5551234567"
birth_dateoptional, string
Customer's date of birth in ISO 8601 (YYYY-MM-DD) format. Required before service can be activated.
Example: "1983-04-17"

AccountsCountResponse #

countinteger
Number of accounts matching the query.
Example: 42

Address #

address_1string
First line of the street address.
Example: "123 Main St"
address_2optional, string
Second line of the street address, such as a unit or apartment.
Example: "Apt 1"
citystring
City of the address.
Example: "Dallas"
statestring
Two-letter state code of the address.
Example: "TX"
postal_codestring
Five-digit postal code of the address.
Example: "75201"

AddressSearchRequest #

querystring
Free-text address search query.
Example: "123 Main St"
postal_codeoptional, string
Optional postal code to narrow the search.
Example: "75201"

AddressSearchResponse #

address_1string
First line of the street address.
Example: "123 Main St"
address_2optional, string
Second line of the street address, such as a unit or apartment.
Example: "Apt 1"
citystring
City of the address.
Example: "Dallas"
statestring
Two-letter state code of the address.
Example: "TX"
postal_codestring
Five-digit postal code of the address.
Example: "75201"
esi_idstring
ESI ID (meter identifier) for this address. Use it to accept a plan.
Example: "55512345671234567"
aliasoptional, string
Mailing-address form of this address when it differs from the utility service address.
Example: "123 Main St"
utilityoptional, string
The unique identifier for the utility serving this meter.
Example: "ONCOR"

AnnualCompareAnnualTotals #

annual_import_kwhstring
Projected annual energy imported from the grid, in kWh.
Example: "14000.00"
annual_current_plan_dollarsstring
Estimated annual cost on the current plan, in dollars.
Example: "1800.00"
annual_offered_plan_dollarsstring
Estimated annual cost on Light's offered plan, in dollars.
Example: "1440.00"

AnnualCompareMonthResponse #

monthinteger
Month number (1=Jan, 12=Dec).
Example: 1
import_kwhstring
Projected import kWh for this month.
Example: "1200.50"
current_plan_dollarsstring
Estimated cost on current plan.
Example: "150.00"
offered_plan_dollarsstring
Estimated cost on Light's plan.
Example: "120.00"

AnnualCompareResponse #

processing_erroroptional, string
Error message when the comparison could not be computed, null otherwise. When present, the other fields are null or empty.
Example: null
monthsoptional, array of AnnualCompareMonthResponse
Monthly breakdown (12 entries, Jan-Dec), each with projected kWh and estimated cost on both plans.
Example: 
[
  {
    "current_plan_dollars": "120.50",
    "import_kwh": "950.00",
    "month": 1,
    "offered_plan_dollars": "96.40"
  },
  {
    "current_plan_dollars": "111.00",
    "import_kwh": "875.00",
    "month": 2,
    "offered_plan_dollars": "88.80"
  },
  {
    "current_plan_dollars": "101.50",
    "import_kwh": "800.00",
    "month": 3,
    "offered_plan_dollars": "81.20"
  },
  {
    "current_plan_dollars": "114.00",
    "import_kwh": "900.00",
    "month": 4,
    "offered_plan_dollars": "91.20"
  },
  {
    "current_plan_dollars": "139.50",
    "import_kwh": "1100.00",
    "month": 5,
    "offered_plan_dollars": "111.60"
  },
  {
    "current_plan_dollars": "190.00",
    "import_kwh": "1500.00",
    "month": 6,
    "offered_plan_dollars": "152.00"
  },
  {
    "current_plan_dollars": "228.00",
    "import_kwh": "1800.00",
    "month": 7,
    "offered_plan_dollars": "182.40"
  },
  {
    "current_plan_dollars": "234.50",
    "import_kwh": "1850.00",
    "month": 8,
    "offered_plan_dollars": "187.60"
  },
  {
    "current_plan_dollars": "177.50",
    "import_kwh": "1400.00",
    "month": 9,
    "offered_plan_dollars": "142.00"
  },
  {
    "current_plan_dollars": "133.00",
    "import_kwh": "1050.00",
    "month": 10,
    "offered_plan_dollars": "106.40"
  },
  {
    "current_plan_dollars": "114.00",
    "import_kwh": "900.00",
    "month": 11,
    "offered_plan_dollars": "91.20"
  },
  {
    "current_plan_dollars": "111.00",
    "import_kwh": "875.00",
    "month": 12,
    "offered_plan_dollars": "88.80"
  }
]
annual_totalsoptional, AnnualCompareAnnualTotals
Annual totals for kWh and cost on both plans.
parsed_invoice_dataoptional, ComparisonInvoiceParsedInvoiceData
The parsed data from the comparison invoice.
Example: 
{
  "avg_cents_per_kwh": "14.50",
  "billing_period_end": "2023-06-30",
  "billing_period_start": "2023-06-01",
  "contract_end_date": "2024-01-01",
  "energy_charge_cents_per_kwh": "10.50",
  "invoice_date": "2023-06-15",
  "is_average_billing": null,
  "plan_name": "Saver Deluxe 24",
  "provider_display_name": "TXU Energy",
  "total_dollars": "100.00",
  "total_kwh": "1000.0"
}
plan_comparisonoptional, ComparisonInvoiceComparedWithPlan
Summary plan comparison (annual totals).
Example: 
{
  "energy_charge_cents_per_kwh": "10.50",
  "group_uuid": "bb7d3c4d-3402-4291-b3a4-e537a8b3225d",
  "name": "Clean Energy",
  "total_dollars": "100.00",
  "usage_profile_uuid": null
}

AppAccountDevice #

uuidstring
The device's unique identifier.
Example: "7c6d5e4f-3a2b-4c1d-9e8f-0a1b2c3d4e5f"
device_typestring
The type of device.
Possible values: BATTERY, EVSE, VEHICLE
Example: "BATTERY"
statusstring
The device's partner-facing status.
Possible values: active, needs_attention, inactive
Example: "active"
battery_detailsoptional, BatteryState
The battery's state and details, present when the device is a battery.
Example: 
{
  "can_export": true,
  "can_import": true,
  "capacity_kwh": "13.50",
  "identifier": "429124",
  "is_reachable": true,
  "last_synced_at": "2026-08-20T14:30:00Z",
  "manufacturer": "tesla",
  "model": "Powerwall 3",
  "reserve_soc": 20
}
charger_detailsoptional, EVSEDetails
The EVSE's details, present when the device is an EVSE.
vehicle_detailsoptional, VehicleDetails
The vehicle's details, present when the device is a vehicle.
programoptional, DeviceProgram
Device program enrollment and compliance status.
disconnected_atoptional, string
When the connection to the customer's manufacturer account stopped working. The customer must reconnect the device. Null while the connection works.
Example: "2026-10-01T14:30:00Z"
account_uuidstring
The unique identifier of the account that owns this device.
Example: "a14b20c3-809a-483f-98dc-3d35911eec42"

AppAccountResponse #

uuidstring
Unique identifier of the account.
Example: "a14b20c3-809a-483f-98dc-3d35911eec42"
external_idoptional, string
Partner-assigned identifier for the account.
Example: "external-id-456"
account_numberoptional, string
Light account number for the account.
Example: "LT-1234567890"
statusstring
Current high-level status of the account.
Possible values: created, applying, reviewing, needs_attention, scheduled, activating, active, cancelled
Example: "active"
status_reasonstring
Detailed status reason for the account.
Possible values: unresolved, missing_address, plan_not_accepted, missing_identity, missing_payment_method, enrollment_not_finalized, verification_pending, credit_check_pending, credit_not_found, credit_declined, credit_check_frozen, credit_check_error, enrollment_blocked_switch_hold, enrollment_blocked_verification_hold, enrollment_blocked_deactivated, utility_blocked, enrollment_pending_client_agent, enrollment_pending_deferred, service_pending, utility_submitted, active, cancelled_pre_start, expire_pre_active, cancelled_post_start, duplicate_enrollment
Example: "unresolved"
created_atstring
When the account was created.
Example: "2026-08-20T14:30:00Z"
first_namestring
Customer's first name.
Example: "John"
last_namestring
Customer's last name.
Example: "Doe"
emailstring
Customer's email address.
Example: "john@example.com"
phone_numberoptional, string
Customer's phone number.
Example: "5551234567"
enrollmentoptional, AccountEnrollment
Enrollment progress for the account.
has_client_agentoptional, boolean
Whether a power-of-attorney client agent is on file for the account.
preliminary_addressoptional, PreliminaryAddress
Preliminary service address provided for the account, before it is verified.
Example: 
{
  "address_1": "123 Main St",
  "address_2": "Apt 1",
  "city": "Dallas",
  "postal_code": "75201",
  "state": "TX"
}
partner_payment_method_on_fileoptional, null
Deprecated; always null.
Example: null
location_metadataoptional, AccountLocationMetadata
Additional metadata about the account's service location, such as solar and battery details.
Example: 
{
  "battery_capacity_kwh": "13.5",
  "solar_estimated_annual_kwh": 12000,
  "solar_system_size_watts": 9000
}
account_linksoptional, AccountLinks
Custom billing and renewal URLs configured for the account.
Example: 
{
  "billing_url": "https://example.com/billing",
  "renewals_url": "https://example.com/renewals"
}
opt_outoptional, AccountOptOut
Information about a customer opting out of an offer.
Example: 
{
  "detail": "Acme Energy 12-month plan",
  "opted_out_at": "2026-08-20T14:30:00Z",
  "plan_uuids": [
    "db94f2a7-84ab-4081-9896-4de2bdde984e"
  ],
  "reason": "found_cheaper_rate",
  "stage": "enrollment"
}
term_month_optionsoptional, array of integer
Contract terms (months) the customer may choose, resolved for the account's currently selected plan. Request one of these via /plans/request for that same plan; requesting a different plan may reject the term.
Example: [12,24,36]
appAccountApp
The app the account belongs to.
locationsarray of Location
Service locations associated with the account.
Example: 
[
  {
    "address_1": "123 Main St",
    "address_2": "Apt 1",
    "city": "Dallas",
    "contract_end": null,
    "estimated_next_reading_date": "2022-02-01",
    "fallback_parent_name": null,
    "fallback_parent_uuid": null,
    "final_service_date": null,
    "has_usage_history": true,
    "is_service_active": true,
    "plan_name": null,
    "plan_type": null,
    "plan_uuid": null,
    "postal_code": "75201",
    "service_start_date": "2022-01-01",
    "state": "TX",
    "tdsp_id": "ONCOR",
    "tdsp_name": "Oncor Electric Delivery",
    "tdsp_outage_url": "https://stormcenter.oncor.com",
    "tdsp_phone": "888-313-4747",
    "tdsp_shortname": "ONCOR",
    "utility_number": "55512345671234567",
    "uuid": "440e8400-e29b-41d4-a716-446655440000"
  }
]

AppLoginResponse #

login_linkstring
Pre-authenticated URL that logs the customer into the hosted application.
Example: "https://app.light.dev/login/token?token=6277d9fb7b76832d1fc7545d4ed649d7"
routestring
Destination the customer lands on after login.
Possible values: home, enroll, billing, documents, update_payment_method
Example: "billing"
expires_atstring
When the login link expires, 14 days after it is created.
Example: "2026-08-20T14:30:00Z"

BatteryDetails #

minimum_capacity_kwhoptional, string
Minimum battery capacity, in kWh, required for the storage credit to apply.
Example: "10.00"
monthly_credit_dollarsoptional, string
Flat monthly credit for enrolled battery storage, in dollars.
Example: "40.00"
monthly_credit_per_kwh_dollarsoptional, string
Per-kWh monthly credit for enrolled battery storage capacity, in dollars.
Example: "4.00"

BatteryState #

identifierstring
The battery's unique identifier.
Example: "429124"
manufacturerstring
The battery's manufacturer.
Example: "tesla"
modelstring
The battery's model name.
Example: "Powerwall 3"
capacity_kwhoptional, string
The battery's total energy storage capacity, in kWh.
Example: "13.50"
is_reachableoptional, boolean
Whether the battery is currently online and reachable.
reserve_socoptional, integer
The battery's configured backup reserve state of charge, as a percentage.
Example: 20
can_importoptional, boolean
Whether the battery is permitted to charge from the grid.
can_exportoptional, boolean
Whether the battery is permitted to export energy to the grid.
last_synced_atoptional, string
The UTC timestamp when the battery's state was last synced from the manufacturer.
Example: "2026-08-20T14:30:00Z"

BenchmarkPlanItem #

planPendingPlan
The plan being benchmarked.
benchmarksarray of PlanBenchmark
Savings benchmarks for the plan at different usage levels.

BenchmarksRequest #

postal_codestring
Postal code of the service location.
Example: "75201"
address_1optional, string
First line of the street address.
Example: "123 Main St"
address_2optional, string
Second line of the street address, such as a unit or apartment.
Example: "Apt 1"
cityoptional, string
City of the address.
Example: "Dallas"
stateoptional, string
Two-letter state code of the address.
Example: "TX"
utility_numberoptional, string
Utility meter identifier (ESI ID) for the location.
Example: "55512345671234567"

BenchmarksResponse #

available_plansarray of BenchmarkPlanItem
Plans available for the address, each with savings benchmarks.
Example: 
[
  {
    "benchmarks": [
      {
        "assumed_export_kwh": 0,
        "assumed_storage_kwh": "10",
        "assumed_unlimited_kwh_usage": 0,
        "avg_cents_per_kwh_1000": "15.0",
        "avg_cents_per_kwh_2000": "14.0",
        "avg_cents_per_kwh_500": "16.0",
        "default_term_month_options": [
          12,
          24
        ],
        "device_terms": [],
        "early_termination_fee_dollars": "100.0",
        "energy_rate_cents": "10.0",
        "ev_charge_hour_end": null,
        "ev_charge_hour_start": null,
        "ev_monthly_cost_dollars": null,
        "export_rate_cents": "5.0",
        "export_rate_type": "fixed",
        "has_solar_buyback": false,
        "monthly_dollar_savings_1000_kwh": "50.15",
        "monthly_dollar_savings_2000_kwh": "105.20",
        "monthly_dollar_savings_500_kwh": "20.50",
        "plan_monthly_cost_dollars": "40.0",
        "renewable_percent": 100,
        "solar_preactivation_credit_percent": 20,
        "storage_monthly_credit_dollars": "30.0",
        "storage_monthly_credit_per_kwh_dollars": "0.01",
        "tdsp_base_dollars": "5.0",
        "tdsp_name": "Oncor Electric Delivery",
        "tdsp_rate_cents": "5.0",
        "tdsp_shortname": "ONCOR",
        "term_months": 12
      }
    ],
    "plan": {
      "assumed_export_kwh": 0,
      "assumed_storage_kwh": "10",
      "assumed_unlimited_kwh_usage": 0,
      "avg_cents_per_kwh_1000": "15.0",
      "avg_cents_per_kwh_2000": "14.0",
      "avg_cents_per_kwh_500": "16.0",
      "default_term_month_options": [
        12,
        24
      ],
      "device_terms": [],
      "earliest_start_date": "2022-01-01",
      "early_termination_fee_dollars": "100.0",
      "energy_rate_cents": "10.0",
      "ev_charge_hour_end": null,
      "ev_charge_hour_start": null,
      "ev_monthly_cost_dollars": null,
      "export_rate_cents": "5.0",
      "export_rate_type": "fixed",
      "has_solar_buyback": false,
      "latest_start_date": "2022-02-01",
      "plan_monthly_cost_dollars": "40.0",
      "renewable_percent": 100,
      "solar_preactivation_credit_percent": 20,
      "storage_monthly_credit_dollars": "30.0",
      "storage_monthly_credit_per_kwh_dollars": "0.01",
      "tdsp_base_dollars": "5.0",
      "tdsp_name": "Oncor Electric Delivery",
      "tdsp_rate_cents": "5.0",
      "tdsp_shortname": "ONCOR",
      "term_months": 12
    }
  }
]

BillingAddressResponse #

address_1string
First line of the street address.
Example: "123 Main St"
address_2optional, string
Second line of the street address, such as a unit or apartment.
Example: "Apt 1"
citystring
City of the address.
Example: "Dallas"
statestring
Two-letter state code of the address.
Example: "TX"
postal_codestring
Five-digit postal code of the address.
Example: "75201"
same_as_service_addressboolean
Whether the billing address is the same as the service address.

CancelEnrollmentRequest #

reasonstring
Reason the partner is cancelling the enrollment.
Example: "Project cancelled before PTO"

ComparisonInvoiceComparedWithPlan #

group_uuidstring
The UUID of the plan group being compared against.
Example: "bb7d3c4d-3402-4291-b3a4-e537a8b3225d"
namestring
The name of the plan being compared against.
Example: "Clean Energy"
total_dollarsstring
The estimated total amount that the same usage would cost on this plan.
Example: "100.00"
usage_profile_uuidoptional, string
UUID of the most recent completed usage profile for this ESI ID (if available within the past 30 days).
Example: "e5f6a7b8-c9d0-4e1f-8a3b-4c5d6e7f8a9b"
energy_charge_cents_per_kwhoptional, string
The base energy charge in cents per kWh for this plan. This is only the energy component and does not include TDU delivery charges, base fees, usage credits, time-of-use variations, taxes, or other surcharges that factor into the total plan cost. Not recommended for plan comparison as it is just one component of pricing.
Example: "10.50"

ComparisonInvoiceParsedInvoiceData #

total_dollarsstring
The total amount of the comparison invoice uploaded.
Example: "100.00"
total_kwhstring
The total kWh of the comparison invoice uploaded.
Example: "1000.0"
contract_end_dateoptional, string
The end date of the contract. If None, then the customer is likely on a month-to-month plan.
Example: "2024-01-01"
invoice_dateoptional, string
The date of the invoice. If None, then the invoice date is not known.
Example: "2024-01-01"
provider_display_nameoptional, string
The name of the Retail Electric Provider (REP) from the comparison invoice. If None, then the provider name is not known.
Example: "TXU Energy"
is_average_billingoptional, boolean
Whether the customer is enrolled in an average or budget billing program. If None, then it is not known.
energy_charge_cents_per_kwhoptional, string
The energy charge in cents per kWh parsed from the customer's invoice. This is only the energy component of the rate and does not include TDU delivery charges, base fees, usage credits, taxes, or other surcharges. Not recommended for plan comparison as it is just one component of pricing.
Example: "10.50"
plan_nameoptional, string
The name of the electricity plan from the customer's invoice. Some invoices do not include a plan name.
Example: "Saver Deluxe 24"
billing_period_startoptional, string
The start date of the billing period on the invoice.
Example: "2024-01-01"
billing_period_endoptional, string
The end date of the billing period on the invoice.
Example: "2024-02-01"
avg_cents_per_kwhoptional, string
The average price per kWh as printed on the customer's invoice. This is the literal value from the invoice (e.g., 'the average price you paid for electricity service'), not a calculated value.
Example: "14.50"

ComparisonInvoiceResponse #

uuidstring
Unique identifier of the uploaded comparison invoice.
Example: "f1a2b3c4-d5e6-4f7a-8b9c-0d1e2f3a4b5c"
created_atstring
When the comparison invoice was uploaded.
Example: "2026-08-20T14:30:00Z"
filestring
URL to the uploaded invoice PDF.
Example: "https://example.com/invoice.pdf"
processing_erroroptional, string
Error message when processing failed, null otherwise.
Example: null
processed_atoptional, string
When the invoice finished processing.
Example: "2026-08-20T14:30:00Z"

ComparisonInvoiceSimpleCompareResponse #

processing_erroroptional, string
Error message when processing failed, null otherwise.
Example: null
parsed_invoice_dataoptional, ComparisonInvoiceParsedInvoiceData
The parsed data from the comparison invoice. If the invoice is not parsed successfully, this will be None.
Example: 
{
  "avg_cents_per_kwh": "14.50",
  "billing_period_end": "2023-06-30",
  "billing_period_start": "2023-06-01",
  "contract_end_date": "2024-01-01",
  "energy_charge_cents_per_kwh": "10.50",
  "invoice_date": "2023-06-15",
  "is_average_billing": null,
  "plan_name": "Saver Deluxe 24",
  "provider_display_name": "TXU Energy",
  "total_dollars": "100.00",
  "total_kwh": "1000.0"
}
plan_comparisonoptional, ComparisonInvoiceComparedWithPlan
The plan comparison data. If the invoice is not parsed successfully, this will be None.
Example: 
{
  "energy_charge_cents_per_kwh": "10.50",
  "group_uuid": "bb7d3c4d-3402-4291-b3a4-e537a8b3225d",
  "name": "Clean Energy",
  "total_dollars": "100.00",
  "usage_profile_uuid": null
}

ComplianceItem #

Single item in a program compliance checklist.

fieldstring
The compliance requirement being evaluated.
Possible values: reserve_soc, can_import, can_export, is_reachable
labeloptional, string
The human-readable label for the compliance requirement.
Example: "Backup Reserve"
expectedboolean | integer | number | string | null
The value required for this compliance item to be satisfied.
Example: true
actualboolean | integer | number | string | null
The value most recently observed for this compliance item.
Example: true

ContractResponse #

term_monthsinteger
Contract term length in months.
Example: 12
default_term_month_optionsarray of integer
The term lengths offered by default for this plan: its term_months plus any additional options, deduplicated. Not exhaustive — any term within the plan's range can also be quoted on request.
Example: [12,24]
avg_cents_per_kwh_500string
Average all-in rate in cents per kWh at 500 kWh of monthly usage.
Example: "16.0"
avg_cents_per_kwh_1000string
Average all-in rate in cents per kWh at 1,000 kWh of monthly usage.
Example: "15.0"
avg_cents_per_kwh_2000string
Average all-in rate in cents per kWh at 2,000 kWh of monthly usage.
Example: "14.0"
energy_rate_cents_per_kwhstring
Energy charge in cents per kWh.
Example: "10.0"
tdu_namestring
Full name of the utility (TDSP) delivering power.
Example: "Oncor Electric Delivery"
tdu_shortnamestring
Short name of the utility (TDSP) delivering power.
Example: "ONCOR"
delivery_rate_cents_per_kwhstring
Utility (TDSP) delivery charge in cents per kWh.
Example: "5.0"
delivery_base_monthly_dollarsstring
Utility (TDSP) fixed monthly delivery charge in dollars.
Example: "5.0"
plan_monthly_cost_dollarsstring
Fixed monthly base charge in dollars.
Example: "40.0"
early_termination_fee_dollarsstring
Fee in dollars for ending the contract early.
Example: "100.0"
assumed_unlimited_kwh_usageinteger
Monthly kWh usage assumed for an unlimited-usage plan.
Example: 0
storage_monthly_credit_dollarsstring
Monthly bill credit in dollars for enrolled storage.
Example: "30.0"
storage_monthly_credit_per_kwh_dollarsoptional, string
Monthly bill credit in dollars per kWh of storage, for customers with energy storage.
Example: "0.01"
assumed_storage_kwhoptional, string
Storage capacity in kWh assumed for the credit calculation.
Example: "10"
solar_preactivation_credit_percentinteger
Credit percentage applied before solar activation.
Example: 20
export_rate_cents_per_kwhstring
Credit in cents per kWh for energy exported to the grid. This is 0 when export_rate_type is real_time.
Example: "5.0"
assumed_export_kwhinteger
Monthly kWh assumed to be exported to the grid.
Example: 0
has_solar_buybackboolean
Whether the plan buys back exported solar energy.
export_rate_typestring
How the plan credits exported energy. fixed: at export_rate_cents_per_kwh. real_time: at the real-time wholesale price for each interval.
Possible values: fixed, real_time
Example: "fixed"
renewable_percentoptional, integer
Share of the plan's energy from renewable sources, as a percentage.
Example: 100
device_program_termsarray of ProgramTerms
Device program terms attached to the plan.
ev_monthly_cost_dollarsoptional, string
Deprecated; always null.
Example: null
ev_charge_hour_startoptional, integer
Deprecated; always null.
Example: null
ev_charge_hour_endoptional, integer
Deprecated; always null.
Example: null
uuidstring
The contract's unique identifier.
Example: "e49f47fd-f721-494c-a430-87ffe85f40c9"
location_uuidstring
The unique identifier of the service location.
Example: "440e8400-e29b-41d4-a716-446655440000"
account_uuidstring
The unique identifier of the account.
Example: "a14b20c3-809a-483f-98dc-3d35911eec42"
plan_uuidstring
The unique identifier of the plan.
Example: "db94f2a7-84ab-4081-9896-4de2bdde984e"
plan_group_uuidstring
The unique identifier of the plan group.
Example: "bb7d3c4d-3402-4291-b3a4-e537a8b3225d"
namestring
The name of the plan.
Example: "Clean Energy"
statestring
The contract's current state. active: the contract is currently active. ended: the customer ended the contract early by moving out or switching service. expired: the contract expired. queued: the contract is scheduled to activate in the future.
Example: "active"
start_datestring
The date the contract begins service.
Example: "2025-07-29"
end_dateoptional, string
The date the contract ended prematurely, null if the contract has not ended early.
Example: null
expiration_datestring
The date the contract's term expires.
Example: "2026-07-29"
partner_commission_dollarsoptional, string
The monthly commission paid to the partner, in dollars.
Example: "10.00"
affiliate_commission_dollarsoptional, string
The monthly commission paid to the affiliate, in dollars.
Example: "7.00"

CreateAccountRequest #

first_namestring
Customer's first name.
Example: "John"
last_namestring
Customer's last name.
Example: "Doe"
emailstring
Customer's email address.
Example: "john@example.com"
phone_numberoptional, string
Customer's phone number, used for customer support. Required before service can be activated.
Example: "5551234567"
birth_dateoptional, string
Customer's date of birth in ISO 8601 (YYYY-MM-DD) format. Required before service can be activated.
Example: "1983-04-17"
service_start_dateoptional, string
Requested date for service to start.
Example: "2026-08-20"
preliminary_addressoptional, PreliminaryAddressInput
Preliminary service address for the account.
Example: 
{
  "address_1": "123 Main St",
  "address_2": "Apt 1",
  "city": "Dallas",
  "postal_code": "75201",
  "state": "TX"
}
location_metadataoptional, AccountLocationMetadata
Additional metadata about the service location, such as solar and battery details.
Example: 
{
  "battery_capacity_kwh": "13.5",
  "solar_estimated_annual_kwh": 12000,
  "solar_system_size_watts": 9000
}
account_linksoptional, AccountLinks
Custom billing and renewal URLs for the account.
Example: 
{
  "billing_url": "https://example.com/billing",
  "renewals_url": "https://example.com/renewals"
}
external_idoptional, string
Partner-assigned identifier for the account. You can also set or change it later with the update account endpoint.
Example: "external-id-456"
metadataoptional, object
Freeform partner-supplied string metadata. Fields are shallow-merged into the stored object: a value adds or overwrites that key, null removes it, and omitted keys are left unchanged. At most 50 keys, and each key together with its value may be at most 100 characters.
Example: 
{
  "building_name": "Maple Court",
  "move_in_date": "2026-08-20",
  "move_out_date": "2027-08-19"
}
term_month_optionsoptional, array of integer
Contract terms in months the customer may choose from during enrollment. Overrides the plan's default term options. Omit to use the plan's default options. Only applies to term plans.
Example: [12,24,36]
planoptional, string
UUID of the plan to preselect for the account.
Example: "bb7d3c4d-3402-4291-b3a4-e537a8b3225d"
broker_terms_agreedoptional, boolean
Whether the customer has been shown, and agreed to, the broker terms of service. Pass true only if the customer has already agreed.

CreateAppLoginRequest #

routeoptional, string
Where to send the user after login in Light Hosted Application.
Possible values: home, enroll, billing, documents, update_payment_method
Example: "billing"
plan_groupoptional, string
UUID of the plan group to preselect in the hosted application.
Example: "bb7d3c4d-3402-4291-b3a4-e537a8b3225d"

CreateBatteryRequest #

Request to create battery devices by manufacturer identifier.

The identifier value depends on the manufacturer:

  • tesla: The energy_site_id from the Tesla API
  • solaredge: The siteId from the SolarEdge API
  • enphase: The system_id from the Enphase API
  • epcube: The EP Cube device ID
  • generac: The PWRcell 2 gateway serial number
  • foxess: The stationID from the FoxESS API, or the inverter or hub serial number
  • sonnen: The battery serial number
manufacturerstring
The device manufacturer name.
Possible values: tesla, solaredge, enphase, sigenergy, franklin, ecoflow, duracell, foxess, sonnen, generac, epcube
Example: "tesla"
identifierstring
Manufacturer-specific identifier. For Tesla: energy_site_id. For SolarEdge: siteId. For Enphase: system_id. For EP Cube: the EP Cube device ID. For Generac: the PWRcell 2 gateway serial number. For FoxESS: stationID, or the inverter or hub serial number. For Sonnen: the battery serial number.
Example: "429124"
preliminary_capacity_kwhnumber | string
The total kWh capacity for all batteries at this location. Send a number or a decimal string. This value is only used as a placeholder until Light has an authorized connection to the battery.
Example: 13.5

CreateEVSERequest #

Request to create an EVSE (Electric Vehicle Supply Equipment) device by manufacturer identifier.

manufacturerstring
The EVSE manufacturer name.
Example: "emporia"
identifierstring
Manufacturer-specific charger identifier.
Example: "charger-001"

CreateFlowLoginRequest #

scopestring
Scope of the session. enrollment opens the enrollment flow, update-payment-method the payment method update flow, documents the documents flow, billing the invoices flow, renewal the renewal flow for the active service location, and connect-battery the battery connection flow.
Possible values: enrollment, update-payment-method, documents, billing, renewal, connect-battery
Example: "enrollment"
behavioroptional, string
How the pre-authenticated link is delivered. "embedded" launches Embedded Flow, a link opened inside your app as an iframe or webview, so customers stay in your product. "hosted" launches Light Hosted Flow, a branded standalone page hosted by Light, typically sent by email or SMS, for out-of-band flows like renewals or battery connection. Both behaviors support all scopes.
Possible values: embedded, hosted
Example: "embedded"
attributionoptional, string
Optional partner-defined attribution tag recorded with the session.
Example: "marketing-page"
plan_groupoptional, string
UUID of the plan group to preselect for the session.
Example: "bb7d3c4d-3402-4291-b3a4-e537a8b3225d"

CreatePaymentSessionResponse #

provideroptional, string
Payment provider for the session.
Example: "stripe"
client_secretstring
Client secret used to complete the payment on the provider.
Example: "pi_1J2k3L4M5N6O7P8Q9R0"

CreateVehicleRequest #

Request to create a vehicle device by manufacturer identifier.

manufacturerstring
The vehicle manufacturer name.
Possible values: hyundai, volvo, rivian, genesis
Example: "hyundai"
identifierstring
VIN or manufacturer-specific vehicle unique identifier.
Example: "KM8KRDDF3RU000001"

CreditCheckRequest #

ssnstring
Customer's full Social Security number, formatted as 123-45-6789.
Example: "123-45-6789"
agree_to_termsboolean
Whether the customer agreed to the credit-check terms. Must be true.

CustomPlanRequest #

esi_idoptional, string
ESI ID (meter identifier) for the service location.
Example: "55512345671234567"
postal_codeoptional, string
Postal code of the service location.
Example: "77098"
utilityoptional, string
Identifier of the utility (TDSP) serving the location.
Example: "CENTERPOINT"
plan_groupoptional, string
UUID of the plan group to request a rate for.
Example: "bb7d3c4d-3402-4291-b3a4-e537a8b3225d"
term_monthsoptional, integer
Contract term length in months being requested.
Example: 12
energy_rate_cents_per_kwhoptional, number | string | null
Energy rate in cents per kWh. Will be rounded to nearest 2 decimal places.
Example: "10.0"
partner_commission_per_month_dollarsoptional, number | string | null
Partner commission per month in dollars. Will be rounded to nearest 2 decimal places.
Example: "10.0"

CustomPlanResponse #

term_monthsinteger
Contract term length in months.
Example: 12
default_term_month_optionsarray of integer
The term lengths offered by default for this plan: its term_months plus any additional options, deduplicated. Not exhaustive — any term within the plan's range can also be quoted on request.
Example: [12,24]
avg_cents_per_kwh_500string
Average all-in rate in cents per kWh at 500 kWh of monthly usage.
Example: "16.0"
avg_cents_per_kwh_1000string
Average all-in rate in cents per kWh at 1,000 kWh of monthly usage.
Example: "15.0"
avg_cents_per_kwh_2000string
Average all-in rate in cents per kWh at 2,000 kWh of monthly usage.
Example: "14.0"
energy_rate_cents_per_kwhstring
Energy charge in cents per kWh.
Example: "10.0"
tdu_namestring
Full name of the utility (TDSP) delivering power.
Example: "Oncor Electric Delivery"
tdu_shortnamestring
Short name of the utility (TDSP) delivering power.
Example: "ONCOR"
delivery_rate_cents_per_kwhstring
Utility (TDSP) delivery charge in cents per kWh.
Example: "5.0"
delivery_base_monthly_dollarsstring
Utility (TDSP) fixed monthly delivery charge in dollars.
Example: "5.0"
plan_monthly_cost_dollarsstring
Fixed monthly base charge in dollars.
Example: "40.0"
early_termination_fee_dollarsstring
Fee in dollars for ending the contract early.
Example: "100.0"
assumed_unlimited_kwh_usageinteger
Monthly kWh usage assumed for an unlimited-usage plan.
Example: 0
storage_monthly_credit_dollarsstring
Monthly bill credit in dollars for enrolled storage.
Example: "30.0"
storage_monthly_credit_per_kwh_dollarsoptional, string
Monthly bill credit in dollars per kWh of storage, for customers with energy storage.
Example: "0.01"
assumed_storage_kwhoptional, string
Storage capacity in kWh assumed for the credit calculation.
Example: "10"
solar_preactivation_credit_percentinteger
Credit percentage applied before solar activation.
Example: 20
export_rate_cents_per_kwhstring
Credit in cents per kWh for energy exported to the grid. This is 0 when export_rate_type is real_time.
Example: "5.0"
assumed_export_kwhinteger
Monthly kWh assumed to be exported to the grid.
Example: 0
has_solar_buybackboolean
Whether the plan buys back exported solar energy.
export_rate_typestring
How the plan credits exported energy. fixed: at export_rate_cents_per_kwh. real_time: at the real-time wholesale price for each interval.
Possible values: fixed, real_time
Example: "fixed"
renewable_percentoptional, integer
Share of the plan's energy from renewable sources, as a percentage.
Example: 100
device_program_termsarray of ProgramTerms
Device program terms attached to the plan.
ev_monthly_cost_dollarsoptional, string
Deprecated; always null.
Example: null
ev_charge_hour_startoptional, integer
Deprecated; always null.
Example: null
ev_charge_hour_endoptional, integer
Deprecated; always null.
Example: null
earliest_start_datestring
Earliest date service can start on this plan.
Example: "2026-08-18"
latest_start_datestring
Latest date service can start on this plan.
Example: "2026-09-17"
uuidstring
Unique identifier of the plan (rate).
Example: "db94f2a7-84ab-4081-9896-4de2bdde984e"
group_uuidstring
Unique identifier of the plan group.
Example: "bb7d3c4d-3402-4291-b3a4-e537a8b3225d"
is_default_for_appoptional, boolean
Whether this is the app's default plan.
namestring
Display name of the plan.
Example: "Clean Energy"
linksRateLinks
Links to the plan's rate documents.
usage_profile_uuidoptional, string
UUID of the most recent completed usage profile for this ESI ID (if available within the past 30 days).
Example: "e5f6a7b8-c9d0-4e1f-8a3b-4c5d6e7f8a9b"
presentationPlanPresentation
Presentation content for rendering the plan.
partner_commission_per_month_dollarsstring
Partner commission in dollars per month for the plan.
Example: "10.0"

DailyUsageDataResponse #

monthinteger
Month number the data covers.
Example: 2
yearinteger
Year the data covers.
Example: 2024
unitsstring
Unit of the usage values.
Example: "kWh"
daysarray of DayUsageData
Per-day usage for the month.
nextoptional, string
URL for the next month of daily usage, when available.
Example: 
"https://api.light.dev/v1/account/locations/440e8400-e29b-41d4-a716-446655440000/usage/daily?month=9&year=2026"
previousoptional, string
URL for the previous month of daily usage, when available.
Example: 
"https://api.light.dev/v1/account/locations/440e8400-e29b-41d4-a716-446655440000/usage/daily?month=7&year=2026"

DayIntervalUsageData #

datestring
Calendar date of the readings.
Example: "2024-07-02"
consumptionarray of string
Per-interval energy consumption for the day, in the response units.
Example: ["1.234"]
generationarray of string
Per-interval energy generation for the day, in the response units.
Example: ["1.234"]

DayUsageData #

datestring
Calendar date of the usage.
Example: "2024-07-02"
consumptionstring
Energy consumed on the day, in the response units.
Example: "1.234"
generationstring
Energy generated on the day, in the response units.
Example: "1.234"
vehicle_chargingstring
Energy used for vehicle charging on the day, in the response units.
Example: "1.234"
eligible_vehicle_chargingstring
Vehicle charging energy covered by the monthly subscription price, in the response units. Vehicle charging plans only.
Example: "1.234"

DeviceProgram #

Device program enrollment with compliance status.

uuidstring
The device program's unique identifier.
Example: "3f2e1d0c-9b8a-4c7d-8e6f-5a4b3c2d1e0f"
is_compliantboolean
Whether the device currently satisfies all requirements of the program.
compliance_checklistoptional, array of ComplianceItem
The compliance checklist items evaluated for the device's program enrollment.

DisallowedDateResponse #

Response containing a single disallowed date with reason.

datestring
Date that is not allowed for service start.
Example: "2026-01-01"
reasonstring
Reason the date is disallowed (weekend or holiday).
Possible values: weekend, holiday
Example: "holiday"
nameoptional, string
Holiday name if applicable.
Example: "New Year's Day"

DisallowedDatesResponse #

Response containing all disallowed dates for the upcoming period.

disallowed_datesarray of DisallowedDateResponse
List of dates that cannot be selected for service start.

DocumentsResponse #

uuidstring
Unique identifier of the contract these documents belong to.
Example: "e49f47fd-f721-494c-a430-87ffe85f40c9"
plan_namestring
Name of the plan these documents belong to.
Example: "Simple 12"
eflstring
URL to the plan's Electricity Facts Label (EFL) PDF.
Example: "https://example.com/efl.pdf"
tosstring
URL to the plan's Terms of Service PDF.
Example: "https://example.com/tos.pdf"
yracstring
URL to the plan's Your Rights as a Customer (YRAC) PDF.
Example: "https://example.com/yrac.pdf"
contract_startstring
Start date of the contract these documents cover.
Example: "2025-01-21"
contract_endstring
End date of the contract these documents cover.
Example: "2026-01-21"
is_activeboolean
Whether this contract is currently active.
is_queuedboolean
Whether this contract is queued to start in the future.

ESIIDSearchRequest #

esi_idstring
ESI ID (meter identifier) to look up.
Example: "55512345671234567"

EVChargingDetails #

base_feeoptional, string
Monthly fee for one enrolled vehicle or charger.
Example: "10.00"
base_fee_two_deviceoptional, string
Total monthly fee for two enrolled vehicles or chargers, null if the program takes only one.
Example: "20.00"
base_fee_three_deviceoptional, string
Total monthly fee for three enrolled vehicles or chargers, null if the program takes fewer.
Example: "30.00"
max_enrolled_devicesinteger
Vehicles or chargers a consumer can enroll in the program.
Example: 2
schedulesoptional, array of EVChargingScheduleSchema
Daily charging windows that define when usage is billed at the on-schedule rate.
on_schedule_ratesoptional, array of EVChargingPricingTierSchema
Pricing tiers applied to usage within the on-schedule charging windows.
assumed_charging_kwhinteger
Assumed monthly EV charging usage, in kWh, used to estimate program cost.
Example: 300

EVChargingPricingTierSchema #

tierinteger
Position of this pricing tier within the schedule, ordered from 1.
Example: 1
nameoptional, string
Label for this pricing tier.
Example: "Base"
capoptional, string
Maximum on-schedule kWh billed at this tier's rate before usage rolls to the next tier, null if the tier is uncapped.
Example: "200.00"
ratestring
Rate in cents per kWh.
Example: "10.00"

EVChargingScheduleSchema #

nameoptional, string
Label for this charging schedule window.
Example: "Daytime"
start_timestring
Start of the charging window, in local time (HH:MM:SS).
Example: "08:00:00"
end_timestring
End of the charging window, in local time (HH:MM:SS).
Example: "20:00:00"

EVSEDetails #

identifierstring
The EVSE's unique identifier.
Example: "charger-001"
manufacturerstring
The EVSE's manufacturer.
Example: "emporia"
modelstring
The EVSE's model name.
Example: "Classic"

EligibilityRequest #

postal_codestring
Postal code of the service location.
Example: "75201"
address_1optional, string
First line of the street address.
Example: "123 Main St"
address_2optional, string
Second line of the street address, such as a unit or apartment.
Example: "Apt 1"
cityoptional, string
City of the address.
Example: "Dallas"
stateoptional, string
Two-letter state code of the address.
Example: "TX"
utility_numberoptional, string
Utility meter identifier (ESI ID) for the location.
Example: "55512345671234567"

EligibilityResponse #

eligibility_likelihoodinteger
Likelihood the address can enroll, from 0 to 100. 0 means there is no evidence that the postal code is eligible, and 100 means it is eligible. We recommend that you let any user with a score above 0 enroll.
Example: 0
utilitiesarray of Utility
Utilities (TDSPs) that may serve the address. The first utility is the most likely.
Example: 
[
  {
    "display_name": "ONCOR",
    "full_name": "Oncor Electric Delivery",
    "id": "ONCOR",
    "name": "ONCOR",
    "short_name": "ONCOR"
  },
  {
    "display_name": "CenterPoint",
    "full_name": "CenterPoint Energy",
    "id": "CENTERPOINT",
    "name": "CENTERPOINT",
    "short_name": "CenterPoint"
  }
]
potential_non_choice_utilitiesoptional, array of NonChoiceUtility
Non-choice utilities that may serve part of this postal code, and so may not be able to enroll. A postal-code level approximation returned alongside utilities, not confirmation for a specific address. These include municipally owned utilities, electric cooperatives, and investor-owned utilities. Treat an entry as a reason to collect a full address, not as a rejection. Each entry has a nullable website, useful as a fallback when a user cannot find their ESI ID.
Example: 
[
  {
    "display_name": "Austin Energy",
    "name": "AUSTIN_ENERGY",
    "website": "https://austinenergy.com/"
  }
]

EnrollmentEventResponse #

recordedoptional, boolean
Whether the event was recorded.

EnrollmentEvidenceResponse #

pdf_urlstring
URL to the PDF documenting evidence of the customer's enrollment authorization.
Example: 
"https://example.com/accounts/123e4567-e89b-42d3-a456-426614174000/enrollment-evidence.pdf"

EnrollmentOptOutEventRequest #

prospectoptional, EventProspectIdentity
Optional prospect identifiers. Omit or set to null when the partner does not yet have identifying data for this customer.
Example: {"email":"customer@example.com"}
account_uuidoptional, string
Light account UUID, if the partner has already created one for this prospect.
Example: "a14b20c3-809a-483f-98dc-3d35911eec42"
occurred_atoptional, string
When the event occurred on the partner's side (ISO 8601 with timezone). Defaults to the server receive time if omitted.
Example: "2026-03-15T14:30:00Z"
plan_uuidsoptional, array of string
UUIDs of plans shown to the customer, from the plans/request response.
Example: ["db94f2a7-84ab-4081-9896-4de2bdde984e"]
propertiesoptional, object
Optional partner-defined key-value data attached to the event in analytics. When the customer has not yet created a Light account, include esi_id and service_address if you have them. Any additional keys are allowed, up to 50 keys.
Example: {"esi_id":"55512345671234567","service_address":"123 Main St, Dallas, TX 75201"}
eventstring
Record when a customer declines to continue enrollment.
Example: "enrollment_opt_out"
reasonoptional, string
Machine-readable reason code from GET /accounts/enroll/opt-out/reasons, other, or a partner-defined code.
Example: "found_cheaper_rate"
labeloptional, string
Human-readable reason text shown to the customer.
Example: "I don't want to switch right now"
flowoptional, string
Which enrollment flow the customer opted out of. One of enrollment_switch, enrollment_move_in, or renewal.
Possible values: enrollment_switch, enrollment_move_in, renewal
Example: "enrollment_switch"
detailoptional, string
Free-text follow-up the customer provided after selecting a reason (e.g. which competitor plan, what question they had). Corresponds to the follow_up_placeholder on the selected reason.
Example: "Acme Energy 12-month plan"

EventProspectIdentity #

emailoptional, string
Prospect's email address.
Example: "customer@example.com"

FlowLoginResponse #

login_linkstring
Pre-authenticated URL that launches the enrollment flow for the customer.
Example: "https://flow.light.dev/login?token=6277d9fb7b76832d1fc7545d4ed649d7"
scopestring
Scope granted to the session.
Example: "enrollment"
behaviorstring
How the pre-authenticated link is delivered.
Example: "embedded"
expires_atstring
When the login link expires, 1 hour after it is created.
Example: "2026-08-20T14:30:00Z"

IdentityRequest #

ssn_last4optional, string
Last four digits of the customer's Social Security number.
Example: "1234"
mothers_maiden_nameoptional, string
Customer's mother's maiden name, used for identity verification.
Example: "Smith"
birth_cityoptional, string
City where the customer was born, used for identity verification.
Example: "Dallas"
birth_dateoptional, string
Customer's date of birth in ISO 8601 (YYYY-MM-DD) format. Required before service can be activated.
Example: "1983-04-17"
drivers_license_numberoptional, string
Customer's driver's license number.
Example: "1234567890"

IntervalUsageDataResponse #

monthinteger
Month number the data covers.
Example: 2
yearinteger
Year the data covers.
Example: 2024
unitsstring
Unit of the usage values.
Example: "kWh"
interval_minutesinteger
Length of each interval, in minutes.
Example: 15
daysarray of DayIntervalUsageData
Per-day interval usage for the month.
nextoptional, string
URL for the next month of interval usage, when available.
Example: 
"https://api.light.dev/v1/account/locations/440e8400-e29b-41d4-a716-446655440000/usage/intervals?month=9&year=2026"
previousoptional, string
URL for the previous month of interval usage, when available.
Example: 
"https://api.light.dev/v1/account/locations/440e8400-e29b-41d4-a716-446655440000/usage/intervals?month=7&year=2026"

InvoiceChargeGroupResponse #

keystring
Machine-readable key for the charge group.
Example: "energy_charges"
namestring
Display name of the charge group.
Example: "Energy Charges"
total_centsinteger
Total of the group's charges, in cents.
Example: 1000
totalstring
Total of the group's charges, in dollars.
Example: "10.00"
chargesarray of InvoiceChargeResponse
Individual charges in the group.

InvoiceChargeResponse #

categorystring
Category of the charge.
Example: "enery_charges"
typestring
Specific type of the charge.
Example: "home_energy"
taxableboolean
Whether the charge is taxable.
descriptionstring
Human-readable description of the charge.
Example: "Home energy"
quantity_textstring
Quantity for the charge, formatted for display.
Example: "100 kWh"
rate_textstring
Rate for the charge, formatted for display.
Example: "10.0¢/kWh"
amount_centsinteger
Charge amount in cents.
Example: 1000
amountstring
Charge amount in dollars.
Example: "10.00"

InvoiceDetailResponse #

numberstring
Invoice number, as shown on the invoice. Use it to fetch the invoice details.
Example: "INV-123456"
invoice_datestring
Date the invoice was issued.
Example: "2026-09-01"
payment_due_datestring
Date payment is due.
Example: "2026-09-15"
billing_period_startstring
First date of the billing period.
Example: "2026-08-01"
billing_period_endstring
Last date of the billing period.
Example: "2026-08-31"
subtotal_centsoptional, integer
Subtotal before miscellaneous charges, in cents.
Example: 1000
subtotaloptional, string
Subtotal before miscellaneous charges, in dollars.
Example: "10.00"
misc_total_centsoptional, integer
Total of miscellaneous charges, in cents.
Example: 1000
misc_totaloptional, string
Total of miscellaneous charges, in dollars.
Example: "10.00"
total_centsinteger
Invoice total in cents.
Example: 1000
totalstring
Invoice total in dollars.
Example: "10.00"
total_kwhstring
Total energy imported from the grid during the billing period, in kWh.
Example: "100.0"
exported_kwhstring
Total energy exported to the grid during the billing period, in kWh. 0 for locations that do not export.
Example: "25.0"
avg_cents_per_kwhstring
Average all-in rate on the invoice, in cents per kWh.
Example: "10.0"
pdfstring
URL to the invoice PDF.
Example: "https://example.com/invoice.pdf"
paid_atoptional, string
When the invoice was paid.
Example: "2026-08-20T14:30:00Z"
voided_atoptional, string
When the invoice was voided.
Example: "2026-08-20T14:30:00Z"
is_deferredboolean
Whether the invoice's payment is deferred to future invoices. This occurs when the amount is below the minimum payment threshold or a deferred payment plan covers it.
rebill_invoiceoptional, string
Number of the invoice that rebills this one after a billing error or adjustment, when applicable.
Example: null
last_payment_failed_atoptional, string
When the most recent payment attempt failed, or null if no attempt failed. Use this, not the due date and paid status, to tell if a payment failed.
Example: "2026-08-20T14:30:00Z"
charge_groupsarray of InvoiceChargeGroupResponse
Charges on the invoice, grouped by category.
payment_failuresarray of PaymentFailureResponse
Failed payment attempts for the invoice, newest first.

InvoiceResponse #

numberstring
Invoice number, as shown on the invoice. Use it to fetch the invoice details.
Example: "INV-123456"
invoice_datestring
Date the invoice was issued.
Example: "2026-09-01"
payment_due_datestring
Date payment is due.
Example: "2026-09-15"
billing_period_startstring
First date of the billing period.
Example: "2026-08-01"
billing_period_endstring
Last date of the billing period.
Example: "2026-08-31"
subtotal_centsoptional, integer
Subtotal before miscellaneous charges, in cents.
Example: 1000
subtotaloptional, string
Subtotal before miscellaneous charges, in dollars.
Example: "10.00"
misc_total_centsoptional, integer
Total of miscellaneous charges, in cents.
Example: 1000
misc_totaloptional, string
Total of miscellaneous charges, in dollars.
Example: "10.00"
total_centsinteger
Invoice total in cents.
Example: 1000
totalstring
Invoice total in dollars.
Example: "10.00"
total_kwhstring
Total energy imported from the grid during the billing period, in kWh.
Example: "100.0"
exported_kwhstring
Total energy exported to the grid during the billing period, in kWh. 0 for locations that do not export.
Example: "25.0"
avg_cents_per_kwhstring
Average all-in rate on the invoice, in cents per kWh.
Example: "10.0"
pdfstring
URL to the invoice PDF.
Example: "https://example.com/invoice.pdf"
paid_atoptional, string
When the invoice was paid.
Example: "2026-08-20T14:30:00Z"
voided_atoptional, string
When the invoice was voided.
Example: "2026-08-20T14:30:00Z"
is_deferredboolean
Whether the invoice's payment is deferred to future invoices. This occurs when the amount is below the minimum payment threshold or a deferred payment plan covers it.
rebill_invoiceoptional, string
Number of the invoice that rebills this one after a billing error or adjustment, when applicable.
Example: null
last_payment_failed_atoptional, string
When the most recent payment attempt failed, or null if no attempt failed. Use this, not the due date and paid status, to tell if a payment failed.
Example: "2026-08-20T14:30:00Z"

Location #

address_1string
First line of the street address.
Example: "123 Main St"
address_2optional, string
Second line of the street address, such as a unit or apartment.
Example: "Apt 1"
citystring
City of the address.
Example: "Dallas"
statestring
Two-letter state code of the address.
Example: "TX"
postal_codestring
Five-digit postal code of the address.
Example: "75201"
uuidstring
Unique identifier of the service location.
Example: "440e8400-e29b-41d4-a716-446655440000"
utility_numberstring
Utility meter identifier (ESI ID) for the location.
Example: "55512345671234567"
service_start_datestring
Date service starts at the location.
Example: "2026-08-20"
final_service_dateoptional, string
Date service ends at the location, when scheduled.
Example: "2027-08-20"
is_service_activeboolean
Whether service is currently active at the location.
has_usage_historyboolean
Whether usage history is available for the location.
estimated_next_reading_dateoptional, string
Estimated date of the next meter reading.
Example: "2026-09-18"
plan_nameoptional, string
Name of the plan the location is enrolled on.
Example: "Simple 12"
plan_uuidoptional, string
Unique identifier of the plan the location is enrolled on.
Example: "bb7d3c4d-3402-4291-b3a4-e537a8b3225d"
plan_typeoptional, string
The type of plan the consumer is on. TERM is a fixed-rate plan for a set number of months. MONTH_TO_MONTH is a variable-rate plan with no fixed term. FALLBACK is a plan that expired contracts are automatically moved onto.
Possible values: TERM, MONTH_TO_MONTH, FALLBACK
Example: "TERM"
fallback_parent_nameoptional, string
When plan_type is FALLBACK, the plan whose expired contracts roll onto this one — i.e. the plan the consumer originally signed up for. null otherwise.
Example: "Clean Energy 12"
fallback_parent_uuidoptional, string
UUID of the plan named by fallback_parent_name. null unless plan_type is FALLBACK.
Example: "bb7d3c4d-3402-4291-b3a4-e537a8b3225d"
tdsp_idoptional, string
The unique identifier for the utility (TDSP) serving the location.
Possible values: AEP_CENTRAL, AEP_NORTH, CENTERPOINT, LUBBOCK, ONCOR, TNMP, PECO, PPL
Example: "ONCOR"
tdsp_nameoptional, string
Full name of the utility (TDSP) serving the location.
Example: "Oncor Electric Delivery"
tdsp_shortnameoptional, string
Short name of the utility (TDSP) serving the location.
Example: "ONCOR"
tdsp_phoneoptional, string
Phone number for the utility (TDSP) serving the location.
Example: "888-313-4747"
tdsp_outage_urloptional, string
URL of the utility's (TDSP) outage map.
Example: "https://stormcenter.oncor.com"
contract_endoptional, string
End date of the active contract. null when there is no active contract, or when the plan has no fixed term.
Example: "2026-08-31"

LocationPlan #

term_monthsinteger
Contract term length in months.
Example: 12
default_term_month_optionsarray of integer
The term lengths offered by default for this plan: its term_months plus any additional options, deduplicated. Not exhaustive — any term within the plan's range can also be quoted on request.
Example: [12,24]
avg_cents_per_kwh_500string
Average all-in rate in cents per kWh at 500 kWh of monthly usage.
Example: "16.0"
avg_cents_per_kwh_1000string
Average all-in rate in cents per kWh at 1,000 kWh of monthly usage.
Example: "15.0"
avg_cents_per_kwh_2000string
Average all-in rate in cents per kWh at 2,000 kWh of monthly usage.
Example: "14.0"
energy_rate_cents_per_kwhstring
Energy charge in cents per kWh.
Example: "10.0"
tdu_namestring
Full name of the utility (TDSP) delivering power.
Example: "Oncor Electric Delivery"
tdu_shortnamestring
Short name of the utility (TDSP) delivering power.
Example: "ONCOR"
delivery_rate_cents_per_kwhstring
Utility (TDSP) delivery charge in cents per kWh.
Example: "5.0"
delivery_base_monthly_dollarsstring
Utility (TDSP) fixed monthly delivery charge in dollars.
Example: "5.0"
plan_monthly_cost_dollarsstring
Fixed monthly base charge in dollars.
Example: "40.0"
early_termination_fee_dollarsstring
Fee in dollars for ending the contract early.
Example: "100.0"
assumed_unlimited_kwh_usageinteger
Monthly kWh usage assumed for an unlimited-usage plan.
Example: 0
storage_monthly_credit_dollarsstring
Monthly bill credit in dollars for enrolled storage.
Example: "30.0"
storage_monthly_credit_per_kwh_dollarsoptional, string
Monthly bill credit in dollars per kWh of storage, for customers with energy storage.
Example: "0.01"
assumed_storage_kwhoptional, string
Storage capacity in kWh assumed for the credit calculation.
Example: "10"
solar_preactivation_credit_percentinteger
Credit percentage applied before solar activation.
Example: 20
export_rate_cents_per_kwhstring
Credit in cents per kWh for energy exported to the grid. This is 0 when export_rate_type is real_time.
Example: "5.0"
assumed_export_kwhinteger
Monthly kWh assumed to be exported to the grid.
Example: 0
has_solar_buybackboolean
Whether the plan buys back exported solar energy.
export_rate_typestring
How the plan credits exported energy. fixed: at export_rate_cents_per_kwh. real_time: at the real-time wholesale price for each interval.
Possible values: fixed, real_time
Example: "fixed"
renewable_percentoptional, integer
Share of the plan's energy from renewable sources, as a percentage.
Example: 100
device_program_termsarray of ProgramTerms
Device program terms attached to the plan.
ev_monthly_cost_dollarsoptional, string
Deprecated; always null.
Example: null
ev_charge_hour_startoptional, integer
Deprecated; always null.
Example: null
ev_charge_hour_endoptional, integer
Deprecated; always null.
Example: null
uuidstring
Unique identifier of the plan (rate).
Example: "db94f2a7-84ab-4081-9896-4de2bdde984e"
group_uuidstring
Unique identifier of the plan group.
Example: "bb7d3c4d-3402-4291-b3a4-e537a8b3225d"
is_default_for_appoptional, boolean
Whether this is the app's default plan.
plan_typeoptional, string
The type of plan the consumer is on. TERM is a fixed-rate plan for a set number of months. MONTH_TO_MONTH is a variable-rate plan with no fixed term. FALLBACK is a plan that expired contracts are automatically moved onto.
Possible values: TERM, MONTH_TO_MONTH, FALLBACK
Example: "TERM"
contract_startstring
Start date of the contract.
Example: "2025-01-21"
contract_endstring
End date of the contract.
Example: "2026-01-21"
is_activeboolean
Whether the contract is currently active.
is_queuedboolean
Whether the contract is queued to start in the future.
namestring
Display name of the plan.
Example: "Clean Energy"

MonthUsageData #

monthstring
Calendar month the usage covers.
Example: "2024-07"
consumptionstring
Energy consumed in the month, in the response units.
Example: "1.234"
generationstring
Energy generated in the month, in the response units.
Example: "1.234"
vehicle_chargingstring
Energy used for vehicle charging in the month, in the response units.
Example: "1.234"
eligible_vehicle_chargingstring
Vehicle charging energy covered by the monthly subscription price, in the response units. Vehicle charging plans only.
Example: "1.234"

MonthlyUsageDataResponse #

yearinteger
Year the data covers.
Example: 2024
unitsstring
Unit of the usage values.
Example: "kWh"
monthsarray of MonthUsageData
Per-month usage for the year.
nextoptional, string
URL for the next year of monthly usage, when available.
Example: 
"https://api.light.dev/v1/account/locations/440e8400-e29b-41d4-a716-446655440000/usage/monthly?year=2027"
previousoptional, string
URL for the previous year of monthly usage, when available.
Example: 
"https://api.light.dev/v1/account/locations/440e8400-e29b-41d4-a716-446655440000/usage/monthly?year=2025"

NonChoiceUtility #

A utility outside the Texas retail choice market, which may be municipally owned, an electric cooperative, or investor-owned.

namestring
Machine-readable identifier of the utility.
Example: "AUSTIN_ENERGY"
display_namestring
Display name of the utility.
Example: "Austin Energy"
websiteoptional, string
Utility's website URL, when available.
Example: "https://austinenergy.com/"

OptOutReasonOption #

reasonstring
Machine-readable code for the opt-out reason.
Example: "found_cheaper_rate"
labelstring
Human-readable text for the opt-out reason.
Example: "I found a cheaper price elsewhere"
bylineoptional, string
Optional copy shown when the customer selects this reason to help prevent churn. Includes the app's configured support phone number when relevant.
Example: "We're happy to answer any questions at 833-555-0100."
follow_up_placeholderoptional, string
When present, the UI should show a text input after the customer selects this reason. The placeholder text guides what detail to collect. Submit the customer's response in the detail field of the opt-out request.
Example: "Tell us which plan"

PagedAppAccountDevice #

dataarray of AppAccountDevice
The page of results, ordered as the endpoint returns them.
has_moreboolean
Whether more results exist after this page.
limitinteger
Maximum number of results returned per page.
Example: 20
offsetinteger
Number of results skipped before this page.
Example: 0
next_page_urloptional, string
URL of the next page, or null when this is the last page.
Example: "https://api.light.dev/v1/app/accounts?limit=20&offset=20"

PagedAppAccountResponse #

dataarray of AppAccountResponse
The page of results, ordered as the endpoint returns them.
has_moreboolean
Whether more results exist after this page.
limitinteger
Maximum number of results returned per page.
Example: 20
offsetinteger
Number of results skipped before this page.
Example: 0
next_page_urloptional, string
URL of the next page, or null when this is the last page.
Example: "https://api.light.dev/v1/app/accounts?limit=20&offset=20"

PagedContractResponse #

dataarray of ContractResponse
The page of results, ordered as the endpoint returns them.
has_moreboolean
Whether more results exist after this page.
limitinteger
Maximum number of results returned per page.
Example: 20
offsetinteger
Number of results skipped before this page.
Example: 0
next_page_urloptional, string
URL of the next page, or null when this is the last page.
Example: "https://api.light.dev/v1/app/accounts?limit=20&offset=20"

PagedDocumentsResponse #

dataarray of DocumentsResponse
The page of results, ordered as the endpoint returns them.
has_moreboolean
Whether more results exist after this page.
limitinteger
Maximum number of results returned per page.
Example: 20
offsetinteger
Number of results skipped before this page.
Example: 0
next_page_urloptional, string
URL of the next page, or null when this is the last page.
Example: "https://api.light.dev/v1/app/accounts?limit=20&offset=20"

PagedInvoiceResponse #

dataarray of InvoiceResponse
The page of results, ordered as the endpoint returns them.
has_moreboolean
Whether more results exist after this page.
limitinteger
Maximum number of results returned per page.
Example: 20
offsetinteger
Number of results skipped before this page.
Example: 0
next_page_urloptional, string
URL of the next page, or null when this is the last page.
Example: "https://api.light.dev/v1/app/accounts?limit=20&offset=20"

PagedLocationPlan #

dataarray of LocationPlan
The page of results, ordered as the endpoint returns them.
has_moreboolean
Whether more results exist after this page.
limitinteger
Maximum number of results returned per page.
Example: 20
offsetinteger
Number of results skipped before this page.
Example: 0
next_page_urloptional, string
URL of the next page, or null when this is the last page.
Example: "https://api.light.dev/v1/app/accounts?limit=20&offset=20"

PayInvoiceRequest #

allow_payment_before_due_dateoptional, boolean
Whether to allow paying the invoice before its due date. Must be true to pay an invoice that is not yet due.

PaymentFailureResponse #

failed_atstring
When the payment attempt failed.
Example: "2026-08-20T14:30:00Z"
amount_centsinteger
Failed payment amount in cents.
Example: 1000
amountstring
Failed payment amount in dollars.
Example: "10.00"
reasonstring
Machine-readable code for why the payment failed. One of insufficient_funds, card_expired, card_declined, incorrect_card_details, processing_error, or other.
Example: "insufficient_funds"
descriptionstring
Human-readable explanation of the payment failure, suitable to show to the customer.
Example: "The payment was declined due to insufficient funds."

PaymentMethodAddedRequest #

payment_method_idoptional, string
Identifier of the payment method to add.
Example: "pm_1J2k3L4M5N6O7P8Q9R0"

PaymentMethodResponse #

typestring
Type of the payment method.
Example: "STRIPE_CARD"
card_brandstring
Card brand.
Example: "visa"
card_last4string
Last four digits of the card number.
Example: "4242"
card_exp_monthinteger
Card expiration month.
Example: 12
card_exp_yearinteger
Card expiration year.
Example: 2030
card_postal_codeoptional, string
Billing postal code for the card, when available.
Example: "75201"

PendingPlan #

term_monthsinteger
Contract term length in months.
Example: 12
default_term_month_optionsarray of integer
The term lengths offered by default for this plan: its term_months plus any additional options, deduplicated. Not exhaustive — any term within the plan's range can also be quoted on request.
Example: [12,24]
avg_cents_per_kwh_500string
Average all-in rate in cents per kWh at 500 kWh of monthly usage.
Example: "16.0"
avg_cents_per_kwh_1000string
Average all-in rate in cents per kWh at 1,000 kWh of monthly usage.
Example: "15.0"
avg_cents_per_kwh_2000string
Average all-in rate in cents per kWh at 2,000 kWh of monthly usage.
Example: "14.0"
energy_rate_cents_per_kwhstring
Energy charge in cents per kWh.
Example: "10.0"
tdu_namestring
Full name of the utility (TDSP) delivering power.
Example: "Oncor Electric Delivery"
tdu_shortnamestring
Short name of the utility (TDSP) delivering power.
Example: "ONCOR"
delivery_rate_cents_per_kwhstring
Utility (TDSP) delivery charge in cents per kWh.
Example: "5.0"
delivery_base_monthly_dollarsstring
Utility (TDSP) fixed monthly delivery charge in dollars.
Example: "5.0"
plan_monthly_cost_dollarsstring
Fixed monthly base charge in dollars.
Example: "40.0"
early_termination_fee_dollarsstring
Fee in dollars for ending the contract early.
Example: "100.0"
assumed_unlimited_kwh_usageinteger
Monthly kWh usage assumed for an unlimited-usage plan.
Example: 0
storage_monthly_credit_dollarsstring
Monthly bill credit in dollars for enrolled storage.
Example: "30.0"
storage_monthly_credit_per_kwh_dollarsoptional, string
Monthly bill credit in dollars per kWh of storage, for customers with energy storage.
Example: "0.01"
assumed_storage_kwhoptional, string
Storage capacity in kWh assumed for the credit calculation.
Example: "10"
solar_preactivation_credit_percentinteger
Credit percentage applied before solar activation.
Example: 20
export_rate_cents_per_kwhstring
Credit in cents per kWh for energy exported to the grid. This is 0 when export_rate_type is real_time.
Example: "5.0"
assumed_export_kwhinteger
Monthly kWh assumed to be exported to the grid.
Example: 0
has_solar_buybackboolean
Whether the plan buys back exported solar energy.
export_rate_typestring
How the plan credits exported energy. fixed: at export_rate_cents_per_kwh. real_time: at the real-time wholesale price for each interval.
Possible values: fixed, real_time
Example: "fixed"
renewable_percentoptional, integer
Share of the plan's energy from renewable sources, as a percentage.
Example: 100
device_program_termsarray of ProgramTerms
Device program terms attached to the plan.
ev_monthly_cost_dollarsoptional, string
Deprecated; always null.
Example: null
ev_charge_hour_startoptional, integer
Deprecated; always null.
Example: null
ev_charge_hour_endoptional, integer
Deprecated; always null.
Example: null
earliest_start_datestring
Earliest date service can start on this plan.
Example: "2026-08-18"
latest_start_datestring
Latest date service can start on this plan.
Example: "2026-09-17"

PlanBenchmark #

term_monthsinteger
Contract term length in months.
Example: 12
default_term_month_optionsarray of integer
The term lengths offered by default for this plan: its term_months plus any additional options, deduplicated. Not exhaustive — any term within the plan's range can also be quoted on request.
Example: [12,24]
avg_cents_per_kwh_500string
Average all-in rate in cents per kWh at 500 kWh of monthly usage.
Example: "16.0"
avg_cents_per_kwh_1000string
Average all-in rate in cents per kWh at 1,000 kWh of monthly usage.
Example: "15.0"
avg_cents_per_kwh_2000string
Average all-in rate in cents per kWh at 2,000 kWh of monthly usage.
Example: "14.0"
energy_rate_cents_per_kwhstring
Energy charge in cents per kWh.
Example: "10.0"
tdu_namestring
Full name of the utility (TDSP) delivering power.
Example: "Oncor Electric Delivery"
tdu_shortnamestring
Short name of the utility (TDSP) delivering power.
Example: "ONCOR"
delivery_rate_cents_per_kwhstring
Utility (TDSP) delivery charge in cents per kWh.
Example: "5.0"
delivery_base_monthly_dollarsstring
Utility (TDSP) fixed monthly delivery charge in dollars.
Example: "5.0"
plan_monthly_cost_dollarsstring
Fixed monthly base charge in dollars.
Example: "40.0"
early_termination_fee_dollarsstring
Fee in dollars for ending the contract early.
Example: "100.0"
assumed_unlimited_kwh_usageinteger
Monthly kWh usage assumed for an unlimited-usage plan.
Example: 0
storage_monthly_credit_dollarsstring
Monthly bill credit in dollars for enrolled storage.
Example: "30.0"
storage_monthly_credit_per_kwh_dollarsoptional, string
Monthly bill credit in dollars per kWh of storage, for customers with energy storage.
Example: "0.01"
assumed_storage_kwhoptional, string
Storage capacity in kWh assumed for the credit calculation.
Example: "10"
solar_preactivation_credit_percentinteger
Credit percentage applied before solar activation.
Example: 20
export_rate_cents_per_kwhstring
Credit in cents per kWh for energy exported to the grid. This is 0 when export_rate_type is real_time.
Example: "5.0"
assumed_export_kwhinteger
Monthly kWh assumed to be exported to the grid.
Example: 0
has_solar_buybackboolean
Whether the plan buys back exported solar energy.
export_rate_typestring
How the plan credits exported energy. fixed: at export_rate_cents_per_kwh. real_time: at the real-time wholesale price for each interval.
Possible values: fixed, real_time
Example: "fixed"
renewable_percentoptional, integer
Share of the plan's energy from renewable sources, as a percentage.
Example: 100
device_program_termsarray of ProgramTerms
Device program terms attached to the plan.
ev_monthly_cost_dollarsoptional, string
Deprecated; always null.
Example: null
ev_charge_hour_startoptional, integer
Deprecated; always null.
Example: null
ev_charge_hour_endoptional, integer
Deprecated; always null.
Example: null
monthly_dollar_savings_500_kwhstring
Estimated monthly savings in dollars at 500 kWh of usage.
Example: "20.50"
monthly_dollar_savings_1000_kwhstring
Estimated monthly savings in dollars at 1,000 kWh of usage.
Example: "50.15"
monthly_dollar_savings_2000_kwhstring
Estimated monthly savings in dollars at 2,000 kWh of usage.
Example: "105.20"

PlanGroupResponse #

uuidstring
Unique identifier of the plan group.
Example: "bb7d3c4d-3402-4291-b3a4-e537a8b3225d"
namestring
Display name of the plan group.
Example: "Clean Energy"
is_default_for_appboolean
Whether this is the app's default plan group.
term_monthsinteger
Contract term length in months.
Example: 12
default_term_month_optionsarray of integer
The term lengths offered by default for this plan: its term_months plus any additional options, deduplicated. Not exhaustive — any term within the plan's range can also be quoted on request.
Example: [12,24]
renewable_percentinteger
Share of the plan's energy from renewable sources, as a percentage.
Example: 100
early_termination_fee_dollarsstring
Fee in dollars for ending the contract early.
Example: "100.0"
has_solar_buybackoptional, boolean
Whether the plan buys back exported solar energy.
statestring
Current state of the plan group.
Example: "active"
plan_monthly_cost_dollarsoptional, string
Fixed monthly base charge in dollars.
Example: "10.0"
storage_monthly_credit_dollarsoptional, string
Monthly bill credit in dollars for enrolled storage.
Example: "30.0"
solar_preactivation_credit_percentoptional, integer
Credit percentage applied before solar activation.
Example: 20
renewal_rate_group_uuidoptional, string
UUID of the plan group this one renews into, when set.
Example: "bb7d3c4d-3402-4291-b3a4-e537a8b3225d"
device_program_termsoptional, array of ProgramTerms
Device program terms attached to the plan group.
has_unlimited_ev_chargingoptional, boolean
Deprecated; always false.
ev_monthly_cost_dollarsoptional, string
Deprecated; always null.
Example: null
ev_charge_hour_startoptional, integer
Deprecated; always null.
Example: null
ev_charge_hour_endoptional, integer
Deprecated; always null.
Example: null

PlanHeadline #

idstring
Stable key for the logic that produced the headline.
Example: "headline_solar"
headlinestring
Short headline for the plan.
Example: "Earn free grid energy for when you need it"
descriptionoptional, string
Optional longer description of the plan.
Example: 
"The ACME Solar Plan earns you free grid energy for nights by earning credit for your solar panels' excess energy:"

PlanHighlight #

A ready-to-render reason-to-renew for a plan. Lower ranking = more emphasis.

idstring
Stable key for the highlight type (rollover_credits, bill_change, term).
Example: "rollover_credits"
rankinginteger
Display priority among this plan's highlights; lower number = more emphasis.
Example: 1
labeloptional, string
Short label for the highlight.
Example: "Keep your credits"
summaryoptional, string
Brief summary of the highlight, e.g. $50 in credits already earned, -$8, or 12 months. Dollar figures are whole dollars.
Example: "$50 in credits already earned"
descriptionoptional, string
Longer description of the highlight.
Example: 
"Other providers won't take your credits. Enroll in this plan to use what you've earned."
hintoptional, string
Supplementary hint text for the highlight.
Example: "per 1000 kWh"

PlanPresentation #

headlinePlanHeadline
Headline block summarizing the plan.
Example: 
{
  "description": "The ACME Solar Plan earns you free grid energy for nights by earning credit for your solar panels' excess energy:",
  "headline": "Earn free grid energy for when you need it",
  "id": "headline_solar"
}
value_propositionsarray of PlanValueProp
List of value propositions associated with the plan.
Example: 
[
  {
    "callouts": [
      {
        "matches": "seamless transition",
        "text": "Your power won't turn off during a transition. We coordinate the switch with your current provider if you have one."
      }
    ],
    "icon": "heart-hand",
    "id": "switch_easy",
    "text": "We handle the switch for you with a seamless transition"
  }
]

PlanRequest #

esi_idoptional, string
ESI ID (meter identifier) for the service location.
Example: "55512345671234567"
postal_codeoptional, string
Postal code of the service location.
Example: "77098"
utilityoptional, string
Identifier of the utility (TDSP) serving the location.
Example: "CENTERPOINT"
plan_groupoptional, string
UUID of the plan group to request a rate for.
Example: "bb7d3c4d-3402-4291-b3a4-e537a8b3225d"
term_monthsoptional, integer
Contract term length in months being requested.
Example: 12

PlanResponse #

term_monthsinteger
Contract term length in months.
Example: 12
default_term_month_optionsarray of integer
The term lengths offered by default for this plan: its term_months plus any additional options, deduplicated. Not exhaustive — any term within the plan's range can also be quoted on request.
Example: [12,24]
avg_cents_per_kwh_500string
Average all-in rate in cents per kWh at 500 kWh of monthly usage.
Example: "16.0"
avg_cents_per_kwh_1000string
Average all-in rate in cents per kWh at 1,000 kWh of monthly usage.
Example: "15.0"
avg_cents_per_kwh_2000string
Average all-in rate in cents per kWh at 2,000 kWh of monthly usage.
Example: "14.0"
energy_rate_cents_per_kwhstring
Energy charge in cents per kWh.
Example: "10.0"
tdu_namestring
Full name of the utility (TDSP) delivering power.
Example: "Oncor Electric Delivery"
tdu_shortnamestring
Short name of the utility (TDSP) delivering power.
Example: "ONCOR"
delivery_rate_cents_per_kwhstring
Utility (TDSP) delivery charge in cents per kWh.
Example: "5.0"
delivery_base_monthly_dollarsstring
Utility (TDSP) fixed monthly delivery charge in dollars.
Example: "5.0"
plan_monthly_cost_dollarsstring
Fixed monthly base charge in dollars.
Example: "40.0"
early_termination_fee_dollarsstring
Fee in dollars for ending the contract early.
Example: "100.0"
assumed_unlimited_kwh_usageinteger
Monthly kWh usage assumed for an unlimited-usage plan.
Example: 0
storage_monthly_credit_dollarsstring
Monthly bill credit in dollars for enrolled storage.
Example: "30.0"
storage_monthly_credit_per_kwh_dollarsoptional, string
Monthly bill credit in dollars per kWh of storage, for customers with energy storage.
Example: "0.01"
assumed_storage_kwhoptional, string
Storage capacity in kWh assumed for the credit calculation.
Example: "10"
solar_preactivation_credit_percentinteger
Credit percentage applied before solar activation.
Example: 20
export_rate_cents_per_kwhstring
Credit in cents per kWh for energy exported to the grid. This is 0 when export_rate_type is real_time.
Example: "5.0"
assumed_export_kwhinteger
Monthly kWh assumed to be exported to the grid.
Example: 0
has_solar_buybackboolean
Whether the plan buys back exported solar energy.
export_rate_typestring
How the plan credits exported energy. fixed: at export_rate_cents_per_kwh. real_time: at the real-time wholesale price for each interval.
Possible values: fixed, real_time
Example: "fixed"
renewable_percentoptional, integer
Share of the plan's energy from renewable sources, as a percentage.
Example: 100
device_program_termsarray of ProgramTerms
Device program terms attached to the plan.
ev_monthly_cost_dollarsoptional, string
Deprecated; always null.
Example: null
ev_charge_hour_startoptional, integer
Deprecated; always null.
Example: null
ev_charge_hour_endoptional, integer
Deprecated; always null.
Example: null
earliest_start_datestring
Earliest date service can start on this plan.
Example: "2026-08-18"
latest_start_datestring
Latest date service can start on this plan.
Example: "2026-09-17"
uuidstring
Unique identifier of the plan (rate).
Example: "db94f2a7-84ab-4081-9896-4de2bdde984e"
group_uuidstring
Unique identifier of the plan group.
Example: "bb7d3c4d-3402-4291-b3a4-e537a8b3225d"
is_default_for_appoptional, boolean
Whether this is the app's default plan.
namestring
Display name of the plan.
Example: "Clean Energy"
linksRateLinks
Links to the plan's rate documents.
usage_profile_uuidoptional, string
UUID of the most recent completed usage profile for this ESI ID (if available within the past 30 days).
Example: "e5f6a7b8-c9d0-4e1f-8a3b-4c5d6e7f8a9b"
presentationPlanPresentation
Presentation content for rendering the plan.

PlanValueProp #

idstring
Stable key for the value proposition.
Example: "switch_easy"
textstring
Value proposition text shown to the customer.
Example: "We handle the switch for you with a seamless transition"
iconstring
Enum of icon to display along side the value proposition.
Possible values: battery-charging, battery-full, car, check-circle, clock, cloud-lightning, coins, heart-hand, layers, leaf, piggy-bank, sun, tag, tool, truck
Example: "heart-hand"
calloutsarray of PlanValuePropCallout
A list of additional notes to call out from the text.
Example: 
[
  {
    "matches": "seamless transition",
    "text": "Your power won't turn off during a transition. We coordinate the switch with your current provider if you have one."
  }
]

PlanValuePropCallout #

textstring
Callout text explaining the highlighted portion of the value proposition.
Example: 
"Your power won't turn off during a transition. We coordinate the switch with your current provider if you have one."
matchesstring
Snippet of text from the value proposition to match the callout to.
Example: "seamless transition"

PlansViewedEventRequest #

prospectoptional, EventProspectIdentity
Optional prospect identifiers. Omit or set to null when the partner does not yet have identifying data for this customer.
Example: {"email":"customer@example.com"}
account_uuidoptional, string
Light account UUID, if the partner has already created one for this prospect.
Example: "a14b20c3-809a-483f-98dc-3d35911eec42"
occurred_atoptional, string
When the event occurred on the partner's side (ISO 8601 with timezone). Defaults to the server receive time if omitted.
Example: "2026-03-15T14:30:00Z"
plan_uuidsoptional, array of string
UUIDs of plans shown to the customer, from the plans/request response.
Example: ["db94f2a7-84ab-4081-9896-4de2bdde984e"]
propertiesoptional, object
Optional partner-defined key-value data attached to the event in analytics. When the customer has not yet created a Light account, include esi_id and service_address if you have them. Any additional keys are allowed, up to 50 keys.
Example: {"esi_id":"55512345671234567","service_address":"123 Main St, Dallas, TX 75201"}
eventstring
Record when plans are rendered in your UI.
Example: "plans_viewed"

PreliminaryAddress #

Preliminary address is not as constrained as a final address since it is provided by the the app and may not be formatted the same.

Some fields may be empty strings if only a partial address was provided.

address_1string
First line of the street address.
Example: "123 Main St"
address_2optional, string
Second line of the street address, such as a unit or apartment.
Example: "Apt 1"
citystring
City of the address.
Example: "Dallas"
statestring
State of the address.
Example: "TX"
postal_codestring
Postal code of the address.
Example: "75201"

PreliminaryAddressInput #

Allows for partial addresses, with a minimum of a postal code.

address_1optional, string
First line of the street address.
Example: "123 Main St"
address_2optional, string
Second line of the street address, such as a unit or apartment.
Example: "Apt 1"
cityoptional, string
City of the address.
Example: "Dallas"
stateoptional, string
State of the address.
Example: "TX"
postal_codestring
Postal code of the address.
Example: "75201"

ProgramTerms #

uuidstring
Unique identifier for this version of the program terms.
Example: "2d1c0b9a-8f7e-4d6c-9b5a-4c3d2e1f0a9b"
namestring
Name of the program.
Example: "Battery Credit"
program_typestring
Type of program these terms apply to.
Possible values: BATTERY, EVCHARGING
Example: "BATTERY"
ownership_typestring
Indicates whether the device is owned by the customer or partner.
Possible values: CUSTOMER, PARTNER
Example: "CUSTOMER"
terms_of_service_urlstring
URL to the PDF terms of service for this program version.
Example: "https://example.com/terms.pdf"
battery_detailsoptional, BatteryDetails
Battery program economics, null if this program does not include battery storage.
Example: 
{
  "storage_minimum_capacity_kwh": "10.00",
  "storage_monthly_credit_dollars": "40.00",
  "storage_monthly_credit_per_kwh_dollars": null
}
ev_chargingoptional, EVChargingDetails
EV charging program economics, null if this program does not include EV charging.

RateLinks #

eflstring
URL to the plan's Electricity Facts Label (EFL) PDF.
Example: "https://example.com/efl.pdf"
tosstring
URL to the plan's Terms of Service PDF.
Example: "https://example.com/terms.pdf"
yracstring
URL to the plan's Your Rights as a Customer (YRAC) PDF.
Example: "https://example.com/yrac.pdf"

RecordClientAgentRequest #

client_agent_accepted_atoptional, string
When the customer accepted the power-of-attorney agreement. Defaults to the current time. Cannot be in the future or more than one year in the past.
Example: "2026-03-01T14:30:00Z"
agreement_pdfoptional, string
Base64-encoded PDF of the power of attorney agreement, at most 10MB. A new document replaces the previous one.
Example: "JVBERi0xLjQ="

RenewalPlanResponse #

term_monthsinteger
Contract term length in months.
Example: 12
default_term_month_optionsarray of integer
The term lengths offered by default for this plan: its term_months plus any additional options, deduplicated. Not exhaustive — any term within the plan's range can also be quoted on request.
Example: [12,24]
avg_cents_per_kwh_500string
Average all-in rate in cents per kWh at 500 kWh of monthly usage.
Example: "16.0"
avg_cents_per_kwh_1000string
Average all-in rate in cents per kWh at 1,000 kWh of monthly usage.
Example: "15.0"
avg_cents_per_kwh_2000string
Average all-in rate in cents per kWh at 2,000 kWh of monthly usage.
Example: "14.0"
energy_rate_cents_per_kwhstring
Energy charge in cents per kWh.
Example: "10.0"
tdu_namestring
Full name of the utility (TDSP) delivering power.
Example: "Oncor Electric Delivery"
tdu_shortnamestring
Short name of the utility (TDSP) delivering power.
Example: "ONCOR"
delivery_rate_cents_per_kwhstring
Utility (TDSP) delivery charge in cents per kWh.
Example: "5.0"
delivery_base_monthly_dollarsstring
Utility (TDSP) fixed monthly delivery charge in dollars.
Example: "5.0"
plan_monthly_cost_dollarsstring
Fixed monthly base charge in dollars.
Example: "40.0"
early_termination_fee_dollarsstring
Fee in dollars for ending the contract early.
Example: "100.0"
assumed_unlimited_kwh_usageinteger
Monthly kWh usage assumed for an unlimited-usage plan.
Example: 0
storage_monthly_credit_dollarsstring
Monthly bill credit in dollars for enrolled storage.
Example: "30.0"
storage_monthly_credit_per_kwh_dollarsoptional, string
Monthly bill credit in dollars per kWh of storage, for customers with energy storage.
Example: "0.01"
assumed_storage_kwhoptional, string
Storage capacity in kWh assumed for the credit calculation.
Example: "10"
solar_preactivation_credit_percentinteger
Credit percentage applied before solar activation.
Example: 20
export_rate_cents_per_kwhstring
Credit in cents per kWh for energy exported to the grid. This is 0 when export_rate_type is real_time.
Example: "5.0"
assumed_export_kwhinteger
Monthly kWh assumed to be exported to the grid.
Example: 0
has_solar_buybackboolean
Whether the plan buys back exported solar energy.
export_rate_typestring
How the plan credits exported energy. fixed: at export_rate_cents_per_kwh. real_time: at the real-time wholesale price for each interval.
Possible values: fixed, real_time
Example: "fixed"
renewable_percentoptional, integer
Share of the plan's energy from renewable sources, as a percentage.
Example: 100
device_program_termsarray of ProgramTerms
Device program terms attached to the plan.
ev_monthly_cost_dollarsoptional, string
Deprecated; always null.
Example: null
ev_charge_hour_startoptional, integer
Deprecated; always null.
Example: null
ev_charge_hour_endoptional, integer
Deprecated; always null.
Example: null
earliest_start_datestring
Earliest date service can start on this plan.
Example: "2026-08-18"
latest_start_datestring
Latest date service can start on this plan.
Example: "2026-09-17"
uuidstring
Unique identifier of the plan (rate).
Example: "db94f2a7-84ab-4081-9896-4de2bdde984e"
group_uuidstring
Unique identifier of the plan group.
Example: "bb7d3c4d-3402-4291-b3a4-e537a8b3225d"
is_default_for_appoptional, boolean
Whether this is the app's default plan.
namestring
Display name of the plan.
Example: "Clean Energy"
linksRateLinks
Links to the plan's rate documents.
usage_profile_uuidoptional, string
UUID of the most recent completed usage profile for this ESI ID (if available within the past 30 days).
Example: "e5f6a7b8-c9d0-4e1f-8a3b-4c5d6e7f8a9b"
presentationPlanPresentation
Presentation content for rendering the plan.
renewal_highlightsarray of PlanHighlight
Ready-to-render reasons to renew for this plan, ordered by ranking (lower number = more emphasis). Empty when no highlight applies.

SupportInfoResponse #

support_phoneoptional, string
Support phone number the customer can call, when configured.
Example: "800-555-5555"
support_emailoptional, string
Support email address the customer can contact, when configured.
Example: "support@example.com"
tdu_namestring
Full name of the utility (TDSP) delivering power to the service location.
Example: "CenterPoint Energy"
tdu_shortnamestring
Short name of the utility (TDSP) delivering power to the service location.
Example: "CenterPoint"
tdu_phonestring
Phone number for the utility (TDSP) serving the location.
Example: "800-555-5555"

UpdateAccountRequest #

first_nameoptional, string
Customer's first name.
Example: "John"
last_nameoptional, string
Customer's last name.
Example: "Doe"
emailoptional, string
Customer's email address.
Example: "john@example.com"
phone_numberoptional, string
Customer's phone number, used for customer support. Required before service can be activated.
Example: "5551234567"
service_start_dateoptional, string
Requested date for service to start.
Example: "2026-08-20"
preliminary_addressoptional, PreliminaryAddressInput
Preliminary service address for the account.
Example: 
{
  "address_1": "123 Main St",
  "address_2": "Apt 1",
  "city": "Dallas",
  "postal_code": "75201",
  "state": "TX"
}
location_metadataoptional, AccountLocationMetadata
Additional metadata about the service location, such as solar and battery details.
Example: 
{
  "battery_capacity_kwh": "13.5",
  "solar_estimated_annual_kwh": 12000,
  "solar_system_size_watts": 9000
}
account_linksoptional, AccountLinks
Custom billing and renewal URLs for the account.
Example: 
{
  "billing_url": "https://example.com/billing",
  "renewals_url": "https://example.com/renewals"
}
external_idoptional, string
Partner-assigned identifier for the account. Omit to leave unchanged, send null to clear, or send a string to set.
Example: "external-id-456"
metadataoptional, object
Freeform partner-supplied string metadata. Fields are shallow-merged into the stored object: a value adds or overwrites that key, null removes it, and omitted keys are left unchanged. At most 50 keys, and each key together with its value may be at most 100 characters.
Example: 
{
  "building_name": "Maple Court",
  "move_in_date": "2026-08-20",
  "move_out_date": "2027-08-19"
}
term_month_optionsoptional, array of integer
Contract terms in months the customer may choose from during enrollment. Omit to leave unchanged, send null to revert to the plan's default options, or send a list to set. Only applies to term plans.
Example: [12,24,36]
planoptional, string
UUID of the plan to preselect for the account.
Example: "bb7d3c4d-3402-4291-b3a4-e537a8b3225d"
broker_terms_agreedoptional, boolean
Whether the customer has been shown, and agreed to, the broker terms of service. Pass true only if the customer has already agreed. An agreement can't be revoked, so false is ignored.

UpdateBillingAddressRequest #

same_as_service_addressoptional, boolean
Whether the billing address is the same as the service address.
addressoptional, Address
Billing address, required when it differs from the service address.

UsagePeriodResponse #

period_startstring
First date of the usage period.
Example: "2026-08-01"
period_endstring
Last date of the usage period.
Example: "2026-08-31"
total_kwhstring
Total energy used during the period, in kWh.
Example: "100.0"

UsageProfile #

Response schema for usage profile resource.

uuidstring
UUID of the usage profile.
Example: "e5f6a7b8-c9d0-4e1f-8a3b-4c5d6e7f8a9b"
statusstring
Status: pending, completed, or failed.
Example: "pending"
utility_account_numberoptional, string
ESI ID / utility account number.
Example: "10123456789012345678"
error_messageoptional, string
Error message if status is 'failed'.
Example: "Invalid interval data format"
created_atstring
When the usage profile was created.
Example: "2026-08-20T14:30:00Z"
start_dateoptional, string
Start date of interval data.
Example: "2023-01-01"
end_dateoptional, string
End date of interval data.
Example: "2023-12-31"

UsageProfileDayData #

Single day of interval data for usage profile upload.

datestring
Date in ISO format YYYY-MM-DD.
Example: "2023-12-14"
importarray of number | string
Import intervals in kWh. Typically 96 values (15-min intervals), but 92 for DST spring forward or 100 for DST fall back.
Example: ["0.768","1.622"]
exportoptional, array of number | string
Export intervals in kWh. Optional, defaults to zeros if not provided.
Example: ["0.0","0.0"]

UsageProfileFetchRequest #

comparison_invoice_uuidstring
UUID of the comparison invoice to fetch usage data for.
Example: "f1a2b3c4-d5e6-4f7a-8b9c-0d1e2f3a4b5c"
user_authorizes_usage_fetchboolean
Whether the user has authorized the usage fetch. In Texas, this is using Smart Meter Texas to fetch usage data.

UsageProfileUploadRequest #

Request schema for usage profile upload.

dataarray of UsageProfileDayData
Array of daily interval data. At least 1 year of data required. Each day must have 92-100 intervals (typically 96 for non-DST days).
Example: [{"date":"2023-12-14","export":[0,0],"import":[0.768,1.622]}]
utility_account_numberstring
ESI ID / utility account number associated with the usage profile.
Example: "10123456789012345678"
timezoneoptional, string
Timezone for interval data. Currently only America/Chicago is supported.
Example: "America/Chicago"
interval_minutesoptional, integer
Minutes per interval. Currently only 15 is supported.
Example: 15

Utility #

idstring
The utility's unique identifier.
Possible values: AEP_CENTRAL, AEP_NORTH, CENTERPOINT, LUBBOCK, ONCOR, TNMP, PECO, PPL
Example: "ONCOR"
short_namestring
The utility's short name.
Example: "ONCOR"
full_namestring
The utility's full legal name.
Example: "Oncor Electric Delivery"
namestring
Deprecated, use id instead.
Example: "ONCOR"
display_namestring
Deprecated, use short_name instead.
Example: "ONCOR"

VehicleDetails #

identifierstring
The vehicle's unique identifier (VIN).
Example: "KM8KRDDF3RU000001"
manufacturerstring
The vehicle's manufacturer.
Example: "hyundai"
modelstring
The vehicle's model name.
Example: "Ioniq 5"