# Retrieve a MRR report

Retrieves a Monthly Recurring Revenue (MRR) report.

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

Endpoint: GET /experimental/reports/monthly-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)
    Monthly Recurring Revenue (MRR) data.

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

  - `data.total` (number)
    Total Monthly Recurring Revenue (MRR) amount.
    Example: 245

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

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

  - `data.breakdown.new` (number)
    Occurs when new customers sign up.
New MRR 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 MRR amount of $40.
    Example: 40

  - `data.breakdown.reactivation` (number)
    Occurs when a customer stops being a customer for a period but later signs up again.
Reactivation MRR 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 MRR amount of $25.
    Example: 25

  - `data.breakdown.churned` (number)
    Occurs when a subscription is churned.
Churn occurs when the paid service period on a subscription order expires.
Churned MRR 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 MRR amount of $80.
    Example: 80

  - `data.breakdown.contraction` (number)
    Occurs when an existing customer changes items which result in a smaller MRR.
Contraction MRR is the amount before the change minus the amount and 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 MRR amount of $20.
    Example: 20

  - `data.breakdown.expansion` (number)
    Occurs when existing customers change items which result in a bigger MRR.
Expansion MRR is the amount after the change minus the amount and 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 MRR amount of $60.
    Example: 60

## 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.