Skip to main content
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

ScopePublic sandbox grantUnlocksNotes
utility:readYesPOST /v1/utility/getLook up utilities and rate plans.
homes:readYesHome lookup and list routesRequires a sandbox home.
homes:writeYesCreate, update, and remove sandbox homesUse only non-production test records.
price_signal:readYesHome-backed price signalsPublic price signals require home context.
bill_impact:readYesHome-backed and no-home bill routesThe no-home route supports quote-stage rate-plan bills.
battery:estimateYesBattery estimated savingsEstimate solar+battery savings for sandbox homes.
feedback:writeYesPOST /v1/feedbackSend 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.