Skip to main content

Billing

Intro​

The retail-choice electricity market requires a certain method to bill customers that is based on metered usage. This section covers how to retrieve and update payment methods, billing addresses, and access invoice information. Only AccountToken authentication is needed to access billing information.

The billing experience can be completely integrated into your existing billing experience by using our API. Light also provides two embedded flow scopes (prebuilt UI) that you can embed in your UI if you prefer.

Should I use the API or embedded flow for billing?

We recommend using the API experience to create a bespoke billing experience within your existing customer dashboard. The embedded flow is great for shipping a complete billing management experience fast within an existing product.

Embedded flow​

The embedded flow lets you skip all of the UI work needed to create a billing management flow. Use the billing and update-payment-method scopes to surface these specific experiences. Learn more

  • The billing scope includes a list of invoices and their details. It also provides a way to manually pre-pay an invoice.
  • The update-payment-method scope lets you update/change a payment method for an account.

API​

The API requires you retrieve a user's AccountToken for the billing experience. Refer to the authentication docs for more details.

View payment method​

To see what payment method is currently associated with the account, use the GET /account/billing/payment-method API. This will return the payment method, including its last four digits, expiration date, and type.

Update payment method​

Updating a payment method is the same API endpoints as adding a new payment method. View those instructions in the enrollment guide.

View invoices​

To retrieve a list of invoices for the customer, use the GET /account/billing/invoices API. This will return a paginated list of invoices with details such as the invoice date, due date, amount, and status. It is recommended to surface if an invoice is paid, voided, or past due. It can also be helpful to surface the payment due date when the auto-pay will attempt to pay the invoice.

For the most simple implementation, you can list these invoices with links to their PDFs. If you want a more branded experience, we recommend using the "View invoice details" API below once an invoice is selected.

View invoice details​

To get detailed information about a specific invoice, use the GET /account/billing/invoices/{invoice_id} API. This will return comprehensive details including line items, usage data, charges, and payment information. Map over charges_groups and their charges to display a detailed breakdown without needing to open the PDF.

View billing address​

You can retrieve the current billing address using the GET /account/billing/address API. This will return the current billing address information associated with the customer's account.

The address fields will be populated regardless of whether the same_as_service_address field is set to true or false. If same_as_service_address is true, Light populates the address fields with the service address information.

Update billing address​

Most of the time the billing address will be the same as the service address. In this case, you don't need to set the billing address and the service address will be used.

Use the PUT /account/billing/address API to update the billing address.

Webhooks allow your application to receive real-time notifications about events that occur within the Light platform. This enables you to build responsive and up-to-date integrations without the need for constant polling. Learn more

account.payment_method_added​

Triggered when a new payment method is added to an account.

account.billing_address_updated​

Triggered when a billing address is updated.

account.payment_failed​

Triggered when a payment for an invoice fails for an account.

account.payment_successful​

Triggered when a payment for an invoice is successful for an account.