Solar + Storage Proposal Sandbox

Use this sandbox flow to evaluate proposal-stage solar and storage economics before creating production customer records. It uses public WattShift APIs, public sandbox credentials, and live utility/rate-plan discovery.

Sandbox Scope Matrix

Scope	Public sandbox grant	Unlocks	Notes
`utility:read`	Yes	`POST /v1/utility/get`	Look up utilities and rate plans.
`homes:read`	Yes	Home lookup and list routes	Requires a sandbox home.
`homes:write`	Yes	Create, update, and remove sandbox homes	Use only non-production test records.
`price_signal:read`	Yes	Home-backed price signals	Public price signals require home context.
`bill_impact:read`	Yes	Home-backed and no-home bill routes	The no-home route supports quote-stage rate-plan bills.
`battery:estimate`	Yes	Battery estimated savings	Estimate solar+battery savings for sandbox homes.
`feedback:write`	Yes	`POST /v1/feedback`	Send implementation feedback from tests.

1. Request Sandbox Access

Create or sign in to a sandbox account from Get API Key, then create a sandbox key with the scopes needed for the flow. For an automated agent credential flow, request these scopes:

[
  "utility:read",
  "homes:read",
  "homes:write",
  "price_signal:read",
  "bill_impact:read",
  "battery:estimate",
  "feedback:write"
]

If battery:estimate is granted, continue through the battery savings step after creating or selecting a sandbox home with the chosen rate plan.

2. Look Up Utility And Rate Plans

Use a ZIP code in the target service territory and ask for solar-aware ordering.

curl -s https://api.wattshift.com/v1/utility/get \
  -H "x-ws-api-key: <sandbox_api_key>" \
  -H "content-type: application/json" \
  -d '{
    "zipcode": "95313",
    "detailLevel": "minimal",
    "isSolarPrioritizedOrder": true
  }'

Choose the PG&E E-ELEC or NBT plan from ratePlans[].

Use ratePlans[].id as ratePlanId in WattShift API paths and request bodies.
Use ratePlans[].rateID as the semantic tariff reference for display and audit trails.
Inspect solarBillingProgram and exportCompensationRefs to confirm export compensation coverage.

3. Calculate A Quote-Stage Bill

Use the no-home rate-plan period route when the proposal has a selected tariff but should not persist a home yet. Quote-stage requests must cover complete calendar months or complete calendar years: startDate must be the first day of a month, and endDate must be the first day of a later month.

POST /v1/homes/bill/period/rateplan/{ratePlanId}

curl -s "https://api.wattshift.com/v1/homes/bill/period/rateplan/<selected_ratePlans_id>" \
  -H "x-ws-api-key: <sandbox_api_key>" \
  -H "content-type: application/json" \
  --data-binary @july-period-bill.json

july-period-bill.json must be strict JSON with one 96-value daily array for every day in July:

{
  "usage": [
    [0.3125, 0.3125, 0.3125 /* 93 more 15-minute values */],
    /* one daily array for every day in July */
  ],
  "export": [
    [0, 0, 0 /* 93 more 15-minute values */],
    /* optional; same number of daily arrays as usage */
  ],
  "startDate": "2026-07-01",
  "endDate": "2026-08-01",
  "debug": true,
}

Expected response fields:

{
  "billTotal": 268.37,
  "exportCompensationCredit": 0,
  "startDate": "2026-07-01",
  "endDate": "2026-08-01"
}

The exact billTotal depends on the selected live rate plan and interval profile. Treat the response shape as the stable contract and refresh fixture totals when updating sandbox docs.

4. Calculate Battery Savings

Battery estimated savings is home-backed:

curl -s "https://api.wattshift.com/v1/homes/<homeId>/battery/estimate_savings" \
  -H "x-ws-api-key: <sandbox_api_key>" \
  -H "content-type: application/json" \
  -d '{
    "days": 1,
    "solarCapacity": 7.2,
    "maxCapacityKiloWattHours": 13.5,
    "chargingPowerKiloWatts": 5,
    "dischargingPowerKiloWatts": 5,
    "chargingEfficiency": 0.95,
    "dischargingEfficiency": 0.95,
    "currentSOC": 0.5,
    "minPreferredSOC": 0.2,
    "maxPreferredSOC": 0.9,
    "months": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]
  }'

Use calendar month numbers for months, where 1 is January and 12 is December. The sandbox credential must include battery:estimate for this step.

Home

Getting Started

Onboard Sites

Optimize Shifts and Calculate Impacts

Advanced Options

Sandbox Scope Matrix

1. Request Sandbox Access

2. Look Up Utility And Rate Plans

3. Calculate A Quote-Stage Bill

4. Calculate Battery Savings

​Sandbox Scope Matrix

​1. Request Sandbox Access

​2. Look Up Utility And Rate Plans

​3. Calculate A Quote-Stage Bill

​4. Calculate Battery Savings

Sandbox Scope Matrix

1. Request Sandbox Access

2. Look Up Utility And Rate Plans

3. Calculate A Quote-Stage Bill

4. Calculate Battery Savings