Billing Statements API: it is not clear which permissions are required to access API

[wolendranh]

Describe the bug New Billing statements API was added to AD API documentation. https://advertising.amazon.com/API/docs/en-us/billing-statements

From API doc page it is not clear which Scope is required for application to access this API

URL of the content Provide the advanced tools center or GitHub URL where you see the bug.

Description of what the documentation currently says No information about permissions/scope

Description of what the documentation should say Information about which scopes are required for API application to have for Billing Statements API

Additional context It would be useful and very helpful to have Documentation page with table mapping each API available to permissions/scopes required and links on how to obtain those permissions, as currently this data is spread across multiple pages of docs and it is hard to find.

[jerirose]

Hi @wolendrah, apologies for the slow response on this issue. I hope the below will answer some of your questions while a user guide for this API remains in development.

---

Scope

The term "scope" is used two ways in the Ads API:

• The permission scope, e.g., advertising::campaign_management as specified in creating the authorization grant. The standard permission scope for the API enables access to the billing statements API.
• The Amazon-Advertising-API-Scope, which is required for many requests to the API and is used to pass a profile ID. This header is not required for the billing statements API, but can be used as described below.

Headers and account identity

Global account

The billing statements API can instead accept the Amazon-Ads-AccountId header, whose value is the global ID for an advertising account, which may include multiple marketplaces. This ID is in the format amzn1.ads-account.g.123456789abcdefgh and can be found using the recently released account management API:

• Retrieve accounts (user guide)
• Account management API specification

The value for the Amazon-Ads-AccountId header will be value of the adsAccountId field for a given account returned from the account management API.

A successful request using this header will create a CSV file whose name begins with the account name.

Profile

Alternatively, the billing statements API can be used with the Amazon-Advertising-API-Scope header, using a profile ID similarly to many other endpoints in the Amazon Ads API. A successful request using this header will generate a CSV file that includes the specified profile only and whose filename begins with the entity ID for that profile.

Permissions

The Amazon user account used to generate the authorization grant must have either View or View and Edit permissions for Billing history on the account or profile in question in order to retrieve a billing statement.

Notes

• Use one of the above headers for both the POST request to generate the statement and the GET request to achieve the statement URL. Using both headers in a request may result in "unauthorized" or "forbidden" error responses.
• We have recently published user guides for other billing-related endpoints. Unfortunately, these do not currently cover the billing statements API, but you may find the information in these documents useful:
  • Billing: Getting started
  • Billing profiles
  • Payments
  • Invoices

---

Thank you for submitting this issue! Please let me know if you have any follow-up questions.

I'll leave this issue open until we have published the user guide for this endpoint.