Payments

The /reports/payments resource provides access to payments you can expect to receive from sales of apps and in-app purchases, as well as ad revenue for all of your apps.

Scope: All of the resources in this route require read access in the private scope (private:read).

Getting total payments

Request

GET /reports/payments?start_date={start_date}&end_date={end_date}&products={products}&countries={countries}

Arguments

Argument Type Description
start_date Date (yyyy-MM-dd) Date, inclusive, to start reporting from. If you specify a granularity other than daily this will be rounded down to the nearest period. default: a long, long time ago.
end_date Date (yyyy-MM-dd) Date, inclusive, to stop reporting. If you specify a granularity other than daily this will be rounded up to the nearest period. default: distant future.
group_by List One or more pivots separated by a comma (,). Available pivots: product, country, date, and store.
products List (productId | productId1, productId2, …) specific products to include in the response, default: all active products in account
countries List (isoCode | isoCode1;isoCode2;isoCodeN) Countries to limit the report to (can be taken from /data/countries, default: include all countries)
format String> Output format: JSON or CSV. Defaults to JSON.

Note: To prevent excessive repetition, when format is set to csv sub-objects (like the product in /revenue/products/…) will not be fully serialized but only their reference will be.

Response

estimated_revenue The total amount expected to be paid at the end of the month based on daily reports.

This is available for all apps and from all sources, and is considered a best estimate which may not match exactly with the actual payment from the source. Common reasons for mismatches include transaction clearing times and exchange rate conversion.
financial_revenue The total amount to be paid for iOS and Mac apps.

At this time only Apple is supported for this type of revenue. This revenue is more accurate but is released about a month after the end of the fiscal month. so it won’t be available right away.
converted_revenue The total amount that has been paid for iOS and Mac apps.

At this time only Apple is supported for this type of revenue. This revenue is 100% accurate and will match the deposit from Apple, but is only available about two months after the end of the fiscal month.
revenue The most accurate payment information, from the previous three, that’s available for the app.

In the case of iOS and Mac apps, this will initially be estimated_revenue, then switch to financial_revenue about 30 days after the end of the fiscal month, and eventually converted_revenue about 30 days after. The specific times depend on Apple’s Fiscal Calendar.

Example Response

// /reports/payments?start_date=-30

{
    "revenue": 12091,
    "converted_revenue": 12091,
    "financial_revenue": 11997,
    "estimated_revenue": 11987,
}

Getting detailed payments

Payments can be broken down by several different dimensions:

  • Country
  • Type
  • Product
  • storefront

You can specify dimensions to group payments by using the group_by parameter. Use a comma to separate multiple parameters.

When specifying dimensions, the response will be nested in the order the dimensions were specified.

Example Response

Get payments for each app broken down by country and type

// /reports/payments?start_date=-30

{
    "1095138104": {
        "US": {
            "app": {
                "revenue": 0,
                "converted_revenue": 0,
                "financial_revenue": 0,
                "estimated_revenue": 0,
                "product_id": 1095138104,
                "iso": "US",
                "country": "United States",
                "type": "app"
            }
        },
        ...
    }
}