jerirose
commented
7 months ago 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_managementas 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:
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
POSTrequest to generate the statement and theGETrequest 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:
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.
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.