Skip to main content

Billing

The retail-choice electricity market requires a certain method of billing customers that is centered around invoicing based on metered usage. This section covers how to retrieve and update payment methods, billing addresses, and access invoice information using the Light API.

Getting the payment method​

To retrieve the current default payment method for a consumer's account, you can use the GET /account/billing/payment-method API endpoint.

GET /account/billing/payment-method​

Example response payload​

{
  "type": "STRIPE_CARD",
  "card_brand": "visa",
  "card_last4": "4242",
  "card_exp_month": 12,
  "card_exp_year": 2030,
  "card_postal_code": "75201"
}

Updating the payment method​

To update the payment method, you can use the same process as described in the Enrollment section for adding a payment method. The APIs for creating a payment session and ensuring a payment method is added are the same:

  1. POST /account/billing/payment-session
  2. POST /account/billing/ensure-payment-method-added

Getting the billing address​

To retrieve the current billing address for a consumer's account, you can use the GET /account/billing/address API endpoint.

GET /account/billing/address​

Example response payload​

{
  "same_as_service_address": false,
  "address_1": "123 Main St",
  "address_2": "Apt 1",
  "city": "Dallas",
  "state": "TX",
  "postal_code": "75201"
}

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

Updating the billing address​

To update the billing address, you can use the PUT /account/billing/address API endpoint. This process is similar to the one described in the Enrollment section for confirming billing address.

PUT /account/billing/address​

Example request payload​

{
  "same_as_service_address": false,
  "address": {
    "address_1": "456 Elm St",
    "address_2": "Suite 2",
    "city": "Houston",
    "state": "TX",
    "postal_code": "77002"
  }
}

Listing invoices​

To retrieve a list of invoices for a consumer's account, you can use the GET /account/billing/invoices API endpoint. This will include invoices that have been paid, voided, or are still due with the most recent invoices appearing first. You can see an example of displaying this data below.

GET /account/billing/invoices​

Example response payload​

[
  {
    number: "INV-123456",
    invoice_date: "2023-05-01",
    payment_due_date: "2023-05-15",
    billing_period_start: "2023-04-01",
    billing_period_end: "2023-04-30",
    total_cents: 10000,
    total: "100.00",
    total_kwh: "500.0",
    avg_cents_per_kwh: "20.0",
    pdf: "https://example.com/invoice-123456.pdf",
    paid_at: "2023-05-10T14:30:00Z",
    voided_at: null,
  },
  // ... more invoices
];

Getting invoice details​

To retrieve detailed information about a specific invoice, including itemized charges, you can use the GET /account/billing/invoices/{invoice_number} API endpoint. This API is is designed to include all of the charge groups and line items so that you can easily render the invoice similar to the example below, matching the format of the invoice PDF. A link to download the PDF is also included in the response.

GET /account/billing/invoices/{invoice_number}​

Example response payload​

{
  "number": "INV-123456",
  "invoice_date": "2023-05-01",
  "payment_due_date": "2023-05-15",
  "billing_period_start": "2023-04-01",
  "billing_period_end": "2023-04-30",
  "total_cents": 10000,
  "total": "100.00",
  "total_kwh": "500.0",
  "avg_cents_per_kwh": "20.0",
  "pdf": "https://example.com/invoice-123456.pdf",
  "paid_at": "2023-05-10T14:30:00Z",
  "voided_at": null,
  "charge_groups": [
    {
      "key": "energy_charges",
      "name": "Energy Charges",
      "total_cents": 8000,
      "total": "80.00",
      "charges": [
        {
          "category": "energy_charges",
          "type": "home_energy",
          "description": "Home energy",
          "taxable": true,
          "quantity_text": "500 kWh",
          "rate_text": "16.0¢/kWh",
          "amount_cents": 8000,
          "amount": "80.00"
        }
      ]
    },
    {
      "key": "delivery_charges",
      "name": "Delivery Charges",
      "total_cents": 2000,
      "total": "20.00",
      "charges": [
        {
          "category": "delivery_charges",
          "type": "base_fee",
          "description": "Base monthly fee",
          "taxable": false,
          "quantity_text": "1 month",
          "rate_text": "$20.00/month",
          "amount_cents": 2000,
          "amount": "20.00"
        }
      ]
    }
  ]
}