Dry run requests

Orb's API supports the dry running of requests. Dry running API requests allows you to validate the correctness of a request without making any actual changes to the system. This feature is particularly useful for ensuring that the request does not contain any errors and for previewing the potential response before committing it.

For example, when performing a dry run on a request to the price intervals endpoint to add a new add-on price to a subscription, the response will contain the modified subscription object as if the price was successfully added. However, no changes will be made to the actual subscription. If you subsequently fetch the subscription, you will observe that the price has not been applied.

Header Semantics

To execute a dry run request, you must explicitly pass the following header in your API request:

Key	Value
Dry-Run	True

This header instructs the API to treat the request as a dry run, meaning it will process the request as if it were real but will not persist any changes.

Example

curl --request POST \
     --url https://api.withorb.com/v1/subscriptions \
     --header 'Dry-Run: True' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer null' \
     --header 'Content-Type: application/json'

Unsupported endpoints

While Orb's API broadly supports dry runs, there are specific event based endpoints where dry running is not supported. These endpoints are:

• POST /v1/ingest
• PATCH /v1/customers/<customer_id>/usage
• PUT /v1/events/<event_id>
• PUT /v1/events/<event_id>/deprecate

Response headers

When a request is sent with the Dry-Run header and the request is successfully processed as a dry run, the response will include the following header and value:

Key	Value
Orb-Dry-Run	true

This header in the response confirms that the request was treated as a dry run and that no changes were made to the data.

However, if the Dry-Run header is included in the request but, for any reason, the request was not processed as a dry run (for instance, if the request is sent to an unsupported endpoint), the Orb-Dry-Run header will not be present in the response. This absence indicates that the request was executed normally and not as a dry run.