# Retrieve an ARR report

Retrieves an Annual Recurring Revenue (ARR) report.

Use ARR reports to view information on the predictable recurring revenue for your business over a period of months.

Endpoint: GET /experimental/reports/annual-recurring-revenue
Version: latest
Security: SecretApiKey, JWT

## Query parameters:

  - `currency` (string, required)
    Revenue currency. If not provided, the organization reporting currency is used.
    Example: "USD"

  - `periodStart` (string, required)
    Date and time when the report starts. If not provided or null, the report starts from the previous month.
    Example: "2022-01"

  - `periodEnd` (string, required)
    Date and time when the report ends. If not provided or null, the report ends at the current month.
    Example: "2022-06"

  - `limit` (integer)
    Limits the number of collection items to be returned.

  - `offset` (integer)
    Specifies the starting point within the collection of items to be returned.

## Response 200 fields (application/json):

  - `data` (array)
    Annual Recurring Revenue (ARR) data.

  - `data.period` (string)
    Revenue month.
    Example: "2022-06"

  - `data.total` (number)
    Total Annual Recurring Revenue (ARR) amount.
    Example: 300

  - `data.breakdown` (object)
    ARR categories are described below.

  - `data.breakdown.change` (number)
    Difference in total ARR between the current and previous period.
    Example: 500

  - `data.breakdown.new` (number)
    Occurs when new customers sign up.
New ARR is the amount of the new customer's subscription.

Example: A new customer signs up to a $40 per month plan.
This is a new ARR amount of $480 ($40 multiplied by 12 months).
    Example: 480

  - `data.breakdown.reactivation` (number)
    Occurs when a customer stops being a customer for a period but later signs up again.
Reactivation ARR is the amount of the customer's new subscription.

Example: A customer cancels their subscription, but signs up again and purchases a $25 per month plan.
This is a reactivation ARR amount of $300 ($25 multiplied by 12 months).
    Example: 300

  - `data.breakdown.churned` (number)
    Occurs when a subscription is churned.
Churn occurs when the paid service period on a subscription order expires.
Churned ARR is the amount that is lost as a result of the churned subscription.

Example: When a subscription is churned, the value of a subscription goes from $80 per month to $0 per month.
This is a churned ARR amount of $960 ($80 multiplied by 12 months).
    Example: 960

  - `data.breakdown.contraction` (number)
    Occurs when an existing customer changes items which result in a smaller ARR.
Contraction ARR is the amount before the change minus the amount after the change.

Example: A customer downgrades from a plan that is $100 per month to plan that is $80 per month.
This is a contraction ARR amount of $240 ($20 multiplied by 12 months).
    Example: 240

  - `data.breakdown.expansion` (number)
    Occurs when existing customers change items which result in a bigger ARR.
Expansion ARR is the amount after the change minus the amount before the change.

Example: A customer upgrades from a plan that is $40 per month to a plan that is $100 per month.
This is an expansion ARR amount of $720 ($60 multiplied by 12 months).
    Example: 720

## Response 401 fields (application/json):

  - `status` (integer)
    HTTP status code.

  - `type` (string)
    Problem type in the form of a [URI](https://tools.ietf.org/html/rfc3986) reference.
It should provide human-readable documentation for the problem type.
When this member is not present, its value is assumed to be "about:blank".

  - `title` (string)
    Short, human-readable summary of the problem type.
Other than for the purposes of localization, this should not change from occurrence to occurrence of the problem.

  - `detail` (string)
    Human-readable explanation that is specific to this occurrence of the problem.

  - `instance` (string)
    URI reference that identifies the specific occurrence of the problem.
It may or may not yield further information if dereferenced.

## Response 403 fields (application/json):

  - `status` (integer)
    HTTP status code.

  - `type` (string)
    Problem type in the form of a [URI](https://tools.ietf.org/html/rfc3986) reference.
It should provide human-readable documentation for the problem type.
When this member is not present, its value is assumed to be "about:blank".

  - `title` (string)
    Short, human-readable summary of the problem type.
Other than for the purposes of localization, this should not change from occurrence to occurrence of the problem.

  - `detail` (string)
    Human-readable explanation that is specific to this occurrence of the problem.

  - `instance` (string)
    URI reference that identifies the specific occurrence of the problem.
It may or may not yield further information if dereferenced.

## Response 422 fields (application/json):

  - `status` (integer)
    HTTP status code.

  - `type` (string)
    Problem type in the form of a [URI](https://tools.ietf.org/html/rfc3986) reference.
It should provide human-readable documentation for the problem type.
When this member is not present, its value is assumed to be "about:blank".

  - `title` (string)
    Short, human-readable summary of the problem type.
Other than for the purposes of localization, this should not change from occurrence to occurrence of the problem.

  - `detail` (string)
    Human-readable explanation that is specific to this occurrence of the problem.

  - `instance` (string)
    URI reference that identifies the specific occurrence of the problem.
It may or may not yield further information if dereferenced.

  - `invalidFields` (array)
    Invalid field details.
    Example: [{"field":"field1","message":"field1 is invalid"},{"field":"subObject.field2","message":"field2 is invalid"},{"field":"subObject.field2","message":"another error in the field2"}]

  - `invalidFields.field` (string)
    Name of the field.
Dot notation is used for nested object field names.

  - `invalidFields.message` (string)
    Message field.