# Conditional agreements
To comply with contractual rules for curtailing the power of a customer resource (e.g. an EV charging site), limit requests from the network owner must be handled by integrating with the Switch platform. The requests are generated as events within the OpenADR standard. Each event covers a 15-minute delivery period where average resource power levels must be below the specified limit. Each 15-minute delivery period can only contain a single event per resource. Resources must also report their real-time data by sending readings of their active power usage to the Switch API.
{% hint style="warning" %}
Readings must be frequent (once per minute is recommended), delivered in time (not more than 15 minutes after being generated) and use accurate UTC time stamps.
If average values are used, they must be divisors of 15. For example, 2/7/10 minute averages are not valid, but 1/3/5/15 minute averages are all OK.
Too many missing readings during a delivery period will result in validation failure and potential penalties (depending on contract between customer and network owner).
{% endhint %}
{% hint style="info" %}
It's highly recommended to first go through the guide on [How to send readings](/getting-started/guides/how-to-send-readings.md), after which steps 1 and 2 of this guide can be skipped.
{% endhint %}
## 1. Getting Started
First of all, you'll need to be set up and get accustomed to working with the [Switch API](/switch-api/overview.md). Next you need to create an [Organization Client](/switch-api/authentication/organization-client.md) and note the client ID and secret since you will need them further on.
## 2. Get Access Token
In order to be able to fetch or send readings, you first need a valid access token that will be used to authorize your request to the Switch API.
To accomplish this you will need the previously noted client ID and client secret and use them to retrieve valid access token by following the client credentials flow as described in [Client Credentials Flow](/switch-api/authentication/client-credentials-flow.md) page. Please note the endpoint for retrieving the token as stated in [Token Endpoint](/switch-api/authentication/token-endpoint.md) page depending on which environment you want to interface with.
When you have your access token ready, proceed with the next step.
## 3. Get Resource Information
You can use the [Get resources](/switch-api/api-reference/test/resource.md#get-api-grid-resource) endpoint to find information about the resources available in your organization. The ID of a specific resource is needed to handle requests and reports. It's also possible to view the resource information in the Switch app, as described in the [Concepts](/getting-started/concepts.md#less-than-resourceid-greater-than) section.
Some resources support an advanced mode of curtailing using dynamic limits. Dynamic limits differ from the normal behavior in two ways:
* The limit for a specific delivery period might not be equal to the configured resource limit. It can be set to a higher or equal value, but never lower.
* The delivery limit might change at any time before the delivery period starts. This is done by updating the OpenADR event for the delivery period.
{% hint style="info" %}
You can find the configured limit by checking the `conditionalDeliveryLimit` parameter of the Get resources response, or by looking at the `Resources` page of the Switch app.
Unless the the resource supports dynamic limits (indicated by the flag `conditionalUseDynamicDeliveryLimit`), this is the limit which will be used for all limit requests.
{% endhint %}
## 4. Setup OpenADR Credentials
To fetch limit requests in the form of events, you first need to create a VTN client and secret, as described in the [Authentication ](/openadr-3/authentication.md)section of the OpenADR 3 documentation.
Optionally, you can also setup a subscription to use webhooks for events instead of only using HTTP polling, as detailed in the [Webhooks](/openadr-3/webhooks.md) section.
{% hint style="info" %}
In case webhooks are used, keep in mind that to support dynamic power limits the subscription must be for both POST and PUT actions on the event entity.
{% endhint %}
## 5. Get Program
When you have an access token for OpenADR ready, you can test it by using the endpoint that [searches all programs](/openadr-3/api-reference/test/programs.md#get-programs). The response should contain the basic parameters of the OpenADR 3 program used by Switch, like the example below:
```json
{
"id": "980",
"createdDateTime": "2024-10-24T15:04:16.139Z",
"modificationDateTime": "2024-10-24T15:04:16.139Z",
"objectType": "PROGRAM",
"programName": "CondAgree",
"programLongName": "Conditional Agreement",
"timeZoneOffset": "PT0S",
"programDescriptions": [],
"bindingEvents": false,
"localPrice": false,
"payloadDescriptors": [],
"targets": []
}
```
## 6. Create Test Event
You can use the Switch app **(QA environment only)** to create your own events for test purposes. First, navigate to `Conditional agreements/Requests` in the top menu. On that page, in the top right corner you'll find the `Create manual request` button which when clicked will open the following dialog:
You can select one or multiple resources to create requests for. All created requests will be listed in the table on the page and will be available as OpenADR events.
## 7. Get Events
To fetch events, you can use the [searches all events](/openadr-3/api-reference/test/events.md#get-events) endpoint. We provide [code samples](/openadr-3/code-samples.md) as suggestions on how to implement authentication and polling for events. To learn more about the structure of a typical event, visit the [payloads ](/openadr-3/payloads.md#limit-request-event-payload)page.
Once you've successfully fetched an event you can proceed to the next step.
## 8. Acknowledge Events
All events must be acknowledged by sending a report back to the VTN using the [add a report endpoint](/openadr-3/api-reference/test/reports.md#post-reports). This must be done within 5 minutes after the event was created or the event limit was updated. To learn more about the structure of a typical acknowledgement report, visit the [payloads ](/openadr-3/payloads.md#openadr-acknowledgement-report)page.
## 9. Validate Delivery
To verify that the resource power levels was below the event delivery limit, you can check the updated data included in the event, which should be available within 30 minutes of the end of the delivery period (i.e. start time + 15 minutes). As shown in the payload example below, both the validation status and the reading value are included:
```json
{
"type": "POWER_LIMIT_VALIDATION_STATUS",
// Status of the validation. Possible values:
// - ok: validation succeeded (resource was below limit)
// - not_ok: validation failed (resource was above limit)
// - unable_to_validate: validation could not run, e.g due to missing readings or a bad configuration
"values": ["ok"]
},
{
"type": "POWER_LIMIT_VALIDATION_STATUS_TEXT",
// Human readable explanation of the status for debugging purposes.
"values": ["Validation succeeded."]
},
{
"type": "POWER_LIMIT_VALIDATION_TIMESTAMP",
// The time & date when the validation was run.
"values": ["2023-10-20T12:25:00Z"]
},
{
"type": "POWER_LIMIT_VALIDATION_READING",
// The reading value that was used for validation. Might be an average of several readings.
"values": [14000]
}
```
## 10. End-to-End Testing
When all previous steps are completed, you should be ready for a full test procedure. This typically involves on-site verification of enforced limits of e.g. EV chargers, based on a test event created by the grid owner. When the testing is completed, the resource may be approved for normal operation.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://developer.switchmarket.se/getting-started/guides/conditional-agreements.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.