> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wattshift.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Solar + Storage Proposal Sandbox

> Run a quote-stage solar and battery proposal flow with public sandbox APIs

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](/docs/get_started/get-api-keys), then create a sandbox key with the scopes needed for the flow. For an automated agent credential flow, request these scopes:

```json theme={null}
[
  "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.

```bash theme={null}
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.

```bash theme={null}
POST /v1/homes/bill/period/rateplan/{ratePlanId}
```

```bash theme={null}
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:

```jsonc theme={null}
{
  "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:

```json theme={null}
{
  "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:

```bash theme={null}
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.