FAQ

Users

Q: How do I remove a user and all of its data?

By deleting the user (DELETE /users/{userId}), all related data, such as user enrollment, registered locations and resources, will also be deleted. If you only want to remove one location and the location’s related resources, use DELETE /users/{userId}/locations/{locationId}.

Q: If we delete a user from the Spark program, will they still be compensated for the current month?

In such a case, the user will not be compensated for the current month as we will no longer have the necessary information for a rebate. We advice you to inform the user about this before deleting them from the program.

Q: Should I wait for a user to become eligible before registering resources or enrolling the user?

You do not need to wait, the order does not matter here. Once a user is both eligible and enrolled, PriceCurveEvents will be sent to the users resources. However, you should consider if waiting until the user is eligible for the program before asking for the user’s consent works better for you.

Neighbourhoods and Locations

Q: How are neighbourhoods and locations defined within the context of this system?

A NH is an area which has a strict definition in our systems, it’s not based on address but instead based on an analysis of the electrical grid and which meterpoints are in the same part of the local grid and as such should be coordinated locally.

In essence, we define a location as being inside a NH if that location, either:

• Has a MeterPointId (Mpid) set on it which corresponds to a specific Mpid which our analysis has shown exists within the a NH
• Or, has Coordinates set on it which lands within a specific NH polygon/boundary box

Events

Q: What constitutes user eligibility?

An eligible user is one that has a location inside a “neighbourhood” (NH) that we have pre-screened as being eligible for one more more use-cases. One of these use-cases is stimulating more consumption of electricity when there is solar production. We’re working on developing new use-cases, so the list of “eligible” NHs will grow in the future.

Q: What triggers the ‘UserEligibilityUpdated’ event?

Any update to locations or neighbourhoods will trigger it, given that the update has a significant impact on users eligibility. This type of event is generated in batches with a 10-min interval. We collapse all triggered “eligibility changes” to a single UserEligibilityUpdated per partner such that a single batch is transmitted within any given interval.

Q: Can a user become lose it’s eligibility?

As of right now we do not have a specific event for this action. We have a separate endpoint for a complete list of eligible users under /users/eligible. In the future we are likely to expand upon this.

Q: How does event timestamp and resolution work?

Timestamps for points will start on the hour, and as of right now the resolution will be 1 hour. Only hours with a possible compensation will be included in the event.

Q: What do the prices in the priceCurverepresent?

The prices in the priceCurve represent the delta in price compared to the spot price. If the delta is negative, it means that we want to encourage higher consumption. The prices are in the local currency of the location.

Q: What decides which currency will be in the priceCurve?

Right now the currency in the price curve is in €, but before the release date 1st June, we will change this to provide the local currency. In Norway you will get NOK, in Sweden you will get SEK and so on.

Q: Are PriceCurveEvents only sent once for specific hours or can they change multiple times per day?

PriceCurveEvents are sent once per day, and the event will contain all the information for the day. There might however be duplicate messages, but the data on the duplicate should be identical to the original message. We use the eventId to manage idempotence. Reasons for duplicate messages might be due to network errors with repeat messages even though you have already processed the event.

Q: Is it possible to receive multiple price curve events that pertain to the same time interval and targets?

As of right now, we only send one unique PriceCurveEvent per day. However, if there are any changes to the event, we will send a new event with the updated information and a new unique eventId.

Q: At what time of the day can we expect to receive a new price curve?.

The events are generated on a daily basis around 13pm.

Reports

Q: How accurate do the reports need to be with regards to time interval?

The reports should be as accurate as possible and match the event with regards to resolution. The reports should be sent after the event has ended, and the actual consumption is known. If the event is for 3 hours, but the user stops charging after 2.5 hours, the report should reflect the actual consumption and all 3 hours should be included in the report. As of right now all events and reports should start on the hour and stop on the hour with a 1-hour resolution.

Q: Should we report usage for all hours in the event, or only the hours where the resource has consumed any energy?

It is only necessary to report usage for the hours where the resource has consumed any energy. If the resource has not consumed any energy during a specific hour, there is no need to report usage for that hour.

Q: When should we send energy usage reports?

You decide yourself when to send the report, but keep in mind that a report must be addressing a specific event. So if you send usage data for three days targeting an event that only has an incentive for the first day only that day will get any compensation from that specific report.

Q: When is it too late to send reports?

It’s advised to not delay the reports too much as this would prohibit us from verifying that the information is correct and as such would make it harder for your end-users to correct potential problems, such as not having an MPID registered. But as of right, the final deadline for sending a report is the last day of the month when the event took place. There will be a grace period such that reporting on the last day of the month is still possible.

Q: What is the relationship between curvePoints in a report and priceCurveDelta in an event?

The curvePointsin a report should be a 1-to-1 relation with the pointsin priceCurveDelta in the event. A CurvePoint contains information about the total energy usage for a given time period with a timestamp indicating the start of said period. As of right now we operate on time periods of 1 hour.

Webhooks

Q: Why do I need a webhook secret?

The webhook secret is used by us to compute a HMAC SHA256 signature of the http body being sent to you via the webhook call, where the signature itself is sent in the header X-Payload-Signature as a base64 string. So in essence it is a way for you to verify that indeed the webhook is being called by Spark because the payload has been signed with the secret you’ve shared with us. This is optional, but recommended.

Compensations

Q: How will my users get compensated?

Your users will receive compensation from the grid operators at the end of each month. The compensation is calculated per meterpoint the user owns based on the user’s energy usage reports and a minimum compensation decided by the grid operator.