---
openapi: 3.0.3
info:
title: Braze REST API – Export revenue data by time
description: 'Use this endpoint to return the total money spent in your app over a time range.
'
version: 1.0.0
contact:
name: Braze Support
url: https://www.braze.com/docs/braze_support/
license:
name: Braze Documentation
url: https://www.braze.com/docs/api/home/
servers:
- url: https://rest.iad-01.braze.com
description: US-01
- url: https://rest.iad-02.braze.com
description: US-02
- url: https://rest.iad-03.braze.com
description: US-03
- url: https://rest.iad-04.braze.com
description: US-04
- url: https://rest.iad-05.braze.com
description: US-05
- url: https://rest.iad-06.braze.com
description: US-06
- url: https://rest.iad-07.braze.com
description: US-07
- url: https://rest.iad-08.braze.com
description: US-08
- url: https://rest.us-10.braze.com
description: US-10
- url: https://rest.fra-01.braze.eu
description: EU-01
- url: https://rest.fra-02.braze.eu
description: EU-02
- url: https://rest.au-01.braze.com
description: AU-01
- url: https://rest.id-01.braze.com
description: ID-01
- url: https://rest.jp-01.braze.com
description: JP-01
- url: https://rest.kr-01.braze.com
description: KR-01
security:
- BearerAuth: []
paths:
"/purchases/revenue_series":
get:
summary: Export revenue data by time
description: |
## Prerequisites
To use this endpoint, you'll need an [API key]({{site.baseurl}}/api/basics#rest-api-key-permissions) with the `purchases.revenue_series` permission.
## Rate limit
We apply a shared rate limit of 1,000 requests per hour to this endpoint. This rate limit is shared with the `/custom_attributes`, `/events`, and `/events/list` endpoints, as documented in [API rate limits]({{site.baseurl}}/api/api_limits/).
## Request parameters
The following table lists the request parameters for this endpoint.
| Parameter | Required | Data Type | Description |
|---|---|---|---|
| `ending_at` | Optional | Datetime ([ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) string) | Date on which the data export should end. Defaults to time of the request. |
| `length` | Required | Integer | Maximum number of days before `ending_at` to include in the returned series. Must be between 1 and 100 (inclusive). |
| `unit` | Optional | String | Unit of time between data points. Can be day or hour, defaults to day. |
| `app_id` | Optional | String | App API identifier retrieved from the [API Keys]({{site.baseurl}}/user_guide/administer/global/workspace_settings/apis_and_identifiers/) page. If excluded, results for all apps in a workspace will be returned. |
| `product` | Optional | String | Name of product to filter response by. If excluded, results for all apps will be returned. |
## Example request
The following sample request shows an example of how to export revenue data by time.
```
curl --location --request GET 'https://rest.iad-01.braze.com/purchases/revenue_series?length=100' \
--header 'Authorization: Bearer YOUR_REST_API_KEY'
```
## Response
The following sample response shows an example of the response returned when you export revenue data by time.
```json
{
"message": (string) returns 'success' when the request completes without errors,
"data" : [
{
"time" : (string) the date as ISO 8601 date,
"revenue" : (int) amount of revenue for the time period
},
...
]
}
```
## Response status codes
The following table lists the responses for this endpoint, the error message you may receive, and how to resolve it.
| Status code | Meaning | Error message | How to resolve |
| --- | --- | --- | --- |
| `200 OK` | The request succeeded and the response body includes the requested data. | `success` | No action needed. |
| `400 Bad Request` | The `product` value, if included, isn't a string. | `'product' must be a string for the name of a product if included` | Pass the product name as a string, or omit `product`. |
| `400 Bad Request` | The `length` is missing, isn't an integer, or is out of range. | `an integer length must be provided`
`series range must be greater than 0 and less than 100` | Pass an integer `length` between 1 and 100. |
| `400 Bad Request` | The `unit` value isn't `day` or `hour`. | `allowed values for unit are 'hour' and 'day'` | Set `unit` to `day` or `hour`. |
| `400 Bad Request` | The `ending_at` value is improperly formatted or out of range. | `ending_at time is improperly formatted`
`ending_at time is out of range` | Provide `ending_at` as an ISO-8601 datetime that isn't in the future or before the year 2000. |
| `400 Bad Request` | The `app_id` value isn't a valid app API key for this workspace. | `app_id must be a valid app api key for this app group` | Pass a valid `app_id` from the API Keys page, or omit it. |
| `401 Unauthorized` | The REST API key is missing, malformed, or sent to the wrong REST endpoint. | `Invalid API key` | Send the key as `Authorization: Bearer YOUR_REST_API_KEY` to the correct [REST endpoint]({{site.baseurl}}/api/basics/#endpoints). For more causes, see [Errors and responses]({{site.baseurl}}/api/errors/#fatal-errors). |
| `403 Access Denied` | The REST API key doesn't have the required permission. | `Access Denied` | Use a REST API key that has the `purchases.revenue_series` permission. |
| `429 Rate Limited` | You exceeded the rate limit for this endpoint. | `Over rate limit` | Slow your request rate and retry with exponential backoff. See [API rate limits]({{site.baseurl}}/api/api_limits/). |
| `5XX Internal Server Error` | An unexpected error occurred on the Braze server. | `Internal Server Error` | Retry with exponential backoff. If the error persists, contact [Support]({{site.baseurl}}/braze_support/). |
operationId: get_purchases_revenue_series_get_revenue_series
tags:
- Export
responses:
'200':
description: The request succeeded and the response body includes the requested data.
content:
application/json:
schema:
$ref: '#/components/schemas/RevenueSeriesResponse'
'400':
description: |-
Bad Request. Causes include:
- `'product' must be a string for the name of a product if included` — The `product` value, if included, isn't a string.
- The `length` is missing, isn't an integer, or is out of range.
- `allowed values for unit are 'hour' and 'day'` — The `unit` value isn't `day` or `hour`.
- The `ending_at` value is improperly formatted or out of range.
- `app_id must be a valid app api key for this app group` — The `app_id` value isn't a valid app API key for this workspace.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: The REST API key is missing, malformed, or sent to the wrong REST endpoint.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: The REST API key doesn't have the required permission.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: You exceeded the rate limit for this endpoint.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'5XX':
description: An unexpected error occurred on the Braze server.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
parameters:
- name: ending_at
in: query
required: false
description: Date on which the data export should end. Defaults to time of the request.
schema:
type: string
- name: length
in: query
required: true
description: Maximum number of days before `ending_at` to include in the returned series. Must be between 1 and 100 (inclusive).
schema:
type: integer
- name: unit
in: query
required: false
description: Unit of time between data points. Can be day or hour, defaults to day.
schema:
type: string
- name: app_id
in: query
required: false
description: App API identifier retrieved from the API Keys page. If excluded, results for all apps in a workspace will be returned.
schema:
type: string
- name: product
in: query
required: false
description: Name of product to filter response by. If excluded, results for all apps will be returned.
schema:
type: string
components:
schemas:
RevenueSeriesResponse:
type: object
properties:
message:
type: string
description: Returns 'success' when the request completes without errors.
data:
type: array
items:
type: object
properties:
time:
type: string
description: The date as ISO 8601 date.
revenue:
type: integer
description: Amount of revenue for the time period.
ErrorResponse:
type: object
properties:
message:
type: string
description: The error message describing why the request failed.
errors:
type: array
description: Non-fatal errors encountered while processing the request. Data unaffected by these errors is still processed.
items:
type: object
properties:
type:
type: string
description: The error type.
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: REST API key