Storage Profiles API

Use the Storage Profiles API to model battery storage behavior, generate post-storage profiles, and include storage impacts in Switch savings analyses.

The Storage feature creates profiles that account for a storage system's charging, discharging, imports, and exports. You can use dispatch strategies to control how the battery operates, then include the generated post-storage profiles in a Savings Analysis. For the full profile workflow, see Profile APIs Overview.

Data definitions

Storage Profile

A storage profile is a generated Profile that represents grid imports, solar exports, or battery grid interactions after storage dispatch is applied. The storage profile endpoint creates these profiles from a base consumption profile, optional solar profiles, tariff context, and battery configuration.

Key features

The table below summarizes currently supported storage capabilities and planned areas for later development.

*Arcadia makes approximations for certain kinds of tier charges and complex ratchets. For tariffs with these features, the schedules generated by the optimal dispatch logic will produce feasible, though not necessarily optimal, battery dispatch schedules.

**Arcadia's Synthetic Intervals service estimates 15-minute usage curves based on site-specific characteristics, even when only an address is known. By using NREL's ComStock database, it provides proxy curves that support energy analyses for greenfield projects, sites without published interval data, and other scenarios where real interval data is inaccessible or too costly. Available via API or UI, it provides metrics that help you assess a site's DER development potential. For more information, see Search for Synthetic Intervals.

Integration with Switch

Storage in Switch integrates with the existing Switch platform in two steps:

1. Create storage profiles: Send battery specifications, consumption profiles, solar production profiles, and tariff context to /rest/v1/profiles/storage to generate post-storage profiles.
2. Use storage profiles in a Savings Analysis: Include the generated profiles in a Savings Analysis so results reflect the storage system and dispatch strategy.

Use this flow when you need savings results that include solar-plus-storage or standalone storage behavior.

Solution diagram

Resource URI

POST /rest/v1/profiles/storage

Try this out on the Add Storage Profile endpoint.

PUT requests are not allowed.

Making a request to this endpoint simulates the battery storage system and generates three new post-storage profiles. These profiles adjust the base consumption and solar profiles to account for the battery's energy timeshifting. Use the generated profiles in a Savings Analysis.

These three new profiles are:

1. Post-storage grid imports to site: Grid-to-site kWh, excluding additional kWh imported to directly charge the battery.
2. Post-storage grid exports from solar: Solar-to-grid export kWh after self-consumption and battery charging.
3. Grid imports and exports to and from the battery: Two data series representing net grid imports and net grid exports directly attributable to battery grid charging and battery exports.

These post-storage profiles can be identified by the -usage, -solar, or -storage suffix on their providerProfileId values.

Together, these profiles represent the net imports and exports measured at the meter after the battery system is operational. They capture only the system's interaction with the grid because those transactions can be associated with a tariff rate. Other behind-the-meter power flows, such as battery-to-site, are not stored in these profiles because they cannot be priced against a tariff rate. Store those schedules in your application if you need to persist them.

How does the storage model use the Switch Usage Profile?

• The storage model requires the ELECTRICITY profile to be an hourly consumption time series. Many Switch users create ELECTRICITY profiles from monthly statements instead of interval data. When the Storage Profile endpoint receives an ELECTRICITY profile without a full 8,760-reading array, it automatically transforms the available Reading Data into a time series that can be passed to the storage model. See Intelligent Baselining for more information. Use hourly solar profiles whenever possible for accurate results.
• If you provide your own intervals, the Storage Profile endpoint only ensures they are dated for a future time horizon.

What dispatch options does the storage model support?
Pass dispatchStrategy when creating a storage profile to control how the battery charges and discharges. dispatchStrategy supports three options:

1. { "dispatchStrategy": { "optimize": true } }: create a storage profile with an optimized dispatch schedule to maximize savings for the given tariff (also passed as a parameter). This dispatch strategy is appropriate for granular TOU tariffs and hardware controls that support hourly schedules. For tariffs with tiers or demand charges, the schedules generated by the optimal dispatch logic will produce feasible, though not necessarily optimal, battery plans.
2. { "dispatchStrategy": { "chargeOnSurplus": true } }: create a storage profile where the battery charges on surplus solar whenever generation exceeds consumption, and discharges to meet unmet site demand otherwise. For this strategy, the storage system does not charge from, or export to, the grid. This dispatch option is designed to support grid-independent installations.
3. { "dispatchStrategy": { "fixedSchedule": { "chargeTous": [], "dischargeTous": [] } } }: create a storage profile where the battery charges and discharges on a fixed schedule. To specify this schedule, pass in arrays of time-of-use objects. All fields are allowed, but only a subset is required. These examples can be taken directly from tariff JSON to facilitate charging off-peak and discharging on-peak. The battery will attempt to charge as much as possible during charge periods and discharge as much as possible during discharge periods. When there is not enough generation to cover both site consumption and battery charging, we apply the following prioritization:
   1. When the battery can charge from the grid { "allowGridToBattery": true } we prioritize charging the battery from solar and send surplus generation to the site.
   2. When the battery can only charge from solar { "allowBatteryToGrid": false } we prioritize powering the home, and only charge the battery from surplus generation.

Switch defaults to the optimized dispatch strategy when dispatchStrategy is not included in the request.

Input parameter notes:

• "serviceType": "ELECTRICITY": There is no new service type for the storage profile. Instead, we use ELECTRICITY, same as a Usage Profile.
• The endpoint supports either or both accountId and providerAccountId, consistent with usage and solar profiles.
• For solar and consumption profile lookup, the endpoint supports either or both profileId and providerProfileId, consistent with usage and solar profiles.
• Most inputs under storage are optional and use defaults. Defaults are displayed below.
• storage.mainTariffId is required and should be the post-solar tariff used by the storage model. Depending on the account configuration, the account's primary tariff may be a pre-solar tariff, so always specify the desired solar tariff in a Storage Profile request.
• The storage model supports one or more solar profiles, allowing users to upload multiple arrays per project, each under a different profile. This implementation assumes a single inverter such that when more than one solar profile is passed to the storage endpoint, the service will sum up all generation per time step.
• When passing a solar profile, users have the option of scaling the production using the dataFactor parameter (see example call below). This input field acts as a scalar, multiplying each of the solar curve's readings by the given value. For example, "dataFactor": 4 will result in a 400% increase in each of the solar profile's intervals.
• Top-level providerProfileId is used as a prefix for the IDs of the three new profiles created by the call. Switch appends the profile type (usage, solar, or storage) so you can track which profiles belong together for a Savings Analysis. For example, if you set "providerProfileId": "sins-example-jun23-poststorage", the three new profiles have these providerProfileId values:
  • "sins-example-jun23-poststorage-usage"
  • "sins-example-jun23-poststorage-solar"
  • "sins-example-jun23-poststorage-storage"
• profileName is used as a prefix for the names of the three new profiles created by the call. For example, if you set "profileName": "Fav Customer", the three new profiles have these profileName values:
  • "Fav Customer - Post-storage grid imports to site"
  • "Fav Customer - Post-storage grid exports from solar"
  • "Fav Customer - Grid imports and exports to and from battery"
• Four power flow parameters customize the model for the site installation. By default, all power flows are enabled (true).
  • allowGridToBattery
  • allowBatteryToGrid
  • allowSolarToGrid
  • allowSolarToBattery
• Battery hardware specifications are captured in the storage object. Common fields include batteryNameplatePower, batteryNameplateCapacity, batteryMinSoc, batteryMaxSoc, batteryInitialSoc, and battery efficiency settings.
• fromDateTime should match the value used in the usage and solar profiles. Pass the timezone in your request. This timestamp should be the same as was used for the electricity profile, solar profile, and Savings Analysis.
• exportLimitKwhAc restricts exports to the grid per time step in kWh AC. Leave unspecified for unlimited exports, or set to 0 to forbid them.
• batteryMinSoc ("0.1"): This is the minimum state of charge for the battery, expressed as a fraction of the total capacity. In this case, the minimum SoC is 10% of the battery's full capacity.
• batteryMaxSoc ("1.0"): This is the maximum state of charge for the battery, expressed as a fraction of the total capacity. Here, the maximum SoC is 100% of the battery's full capacity.
• batteryInitialSoc ("0.5"): This is the initial state of charge of the battery when it starts operating, expressed as a fraction of the total capacity. In this case, the battery starts at 50% of its full capacity.
• Arcadia's storage model supports two options for passing battery power ratings, which define the rate at which a battery can charge and discharge. Pass one of these options, not both:
  • batteryNameplatePower: For batteries that have the same charge and discharge rate limits. This is the default option used by the system.
  • A combination of batteryNameplateChargePowerKwDc and batteryNameplateDischargePowerKwDc: For batteries that have different charge and discharge rate limits.

Response notes

• The response automatically creates three new profiles within the account. Each profile uses the same providerProfileId prefix and source.requestId to indicate that they are part of the same set. If no providerProfileId is sent in the initial request, the request ID is included in the default providerProfileId and profileName.
• The original power flows returned by the storage model are available under storageOptimizationResponse. Behind-the-meter (BTM) power flows are not stored under the new optimized profiles. Store these outputs in your application if you need them later.

The following sections summarize the most important response components.

Bold indicates a nested object holding other parameters, the contents are summarized in the description.

• Usage Profile Response:

  usageProfile Object	Description
  profileId	System-generated identifier for the new optimized usage profile.
  providerProfileId	The new identifier for the optimized usage profile. This will be your original providerProfileId with -usage appended to the end.
  profileName	The new name for the optimized usage profile. This will be your original profileName with - Post-storage grid imports to site appended to the end.
  accountId	Account ID associated with the usage profile.
  source	Object containing the source of the information. In this case, it is Spark Storage Optimization because that generated the profile information.
  readingDataSummaries	Includes the start date time, end date time, and total count of the readings on the profile.
  baselineMeasures	Estimated numbers when baselining is performed to generate the usage curve. null when not applicable.

• Solar Profile Response:

  solarProfile Object	Description
  profileId	System-generated identifier for the new optimized solar profile.
  providerProfileId	The new identifier for the optimized solar profile. This will be your original providerProfileId with -solar appended to the end.
  profileName	The new name for the optimized solar profile. This will be your original profileName with - Post-storage grid exports from solar to site appended to the end.
  accountId	Account ID associated with the solar profile.
  source	Object containing the source of the information. In this case, it is Spark Storage Optimization because that generated the profile information.
  readingDataSummaries	Includes the start date time, end date time, and total count of the readings on the profile.
  baselineMeasures	Estimated numbers when baselining is performed to generate the usage curve. null when not applicable

• Storage Profile Response:

  storageProfile Object	Description
  profileId	System-generated identifier for the new optimized storage profile.
  providerProfileId	The new identifier for the optimized storage profile. This will be your original providerProfileId with -storage appended to the end.
  profileName	The new name for the optimized storage profile. This will be your original profileName with - Grid imports and exports to and from battery to site appended to the end.
  accountId	Account ID associated with the storage profile.
  serviceTypes	Types of services included (e.g., ELECTRICITY).
  source	Object containing the source of the information. In this case, it is Spark Storage Optimization because that generated the profile information.
  readingDataSummaries	Includes the start date time, end date time, and total count of the readings on the profile.
  baselineMeasures	Estimated numbers when baselining is performed to generate the usage curve. null when not applicable.
  storageOptimizationRequest	Includes all of the information passed in the call to the storage endpoint, populating the defaults for any fields that were not passed in.

• Storage Optimization Response: The storage optimization response will return several dataSeries containing hourly intervals for the year (8,760 readings) that represent the different flows of energy.

  storageOptimizationResponse Object Contents	Description
  grid_to_site_kwh_ac	The electricity drawn from the grid to meet the energy needs of the site when local generation or storage is insufficient.
  grid_to_battery_kwh_ac	The energy drawn from the grid and stored in the battery, typically used to ensure that there is a reserve of electricity available when needed, such as during periods of high demand or low renewable energy generation.
  solar_to_battery_kwh_dc	The energy produced by the solar panels that is stored in the battery for later use, rather than being used immediately on-site or fed into the grid.
  solar_to_site_kwh_ac	The energy produced by the solar panels that is used immediately on-site to meet the site's energy needs.
  solar_to_grid_kwh_ac	The surplus energy generated by the solar panels that is not used on-site and is instead fed back into the grid.
  solar_curtailed_kwh_dc	The kilowatt-hours (kWh) that were generated but not used or stored, and therefore wasted. This situation typically occurs when the generation capacity exceeds the consumption and storage capacity, leading to excess energy that cannot be utilized.
  battery_to_site_kwh_ac	The energy supplied by the battery to meet the site's energy demands.
  battery_to_grid_kwh_ac	The energy discharged from the battery and sent back to the grid, which can occur when there is excess stored energy that the site does not need.
  battery_soc	Percentage representing how much energy the battery currently holds compared to its total capacity.
  net_load_kwh_ac	The total electricity demand after accounting for any energy contributions from onsite generation or storage systems.
  from_date_time	Start date and time of the optimization response

Next steps

1. Return to Profile APIs Overview to choose another profile workflow.
2. Use Add Storage Profile to generate post-storage profiles.
3. Use Storage-in-Switch Request Template to include generated storage profiles in a Savings Analysis request.