App Scopes

Retail Media API endpoints are protected by OAuth 2.0 scopes. Each endpoint requires one scope. Calling an endpoint without that scope results in 403 Forbidden errors at runtime.

Scopes are granted at app creation time and cannot be widened afterwards. If your app is missing a scope, you need to create a new app with the correct scope set and obtain consent again.

Available scopes

Scope	What it covers
`RetailMedia_Accounts_Read`	Read access to accounts, brands, sellers, and fees
`RetailMedia_Accounts_Manage`	Create and manage accounts, brands, sellers, fees, and consent
`RetailMedia_Campaign_Read`	Read access to campaigns, line items, creatives, products, keywords, and catalog data
`RetailMedia_Campaign_Manage`	Create and manage campaigns, line items, creatives, products, keywords, and catalog exports
`RetailMedia_Analytics_Read`	Read access to performance, revenue, attribution, and reporting endpoints
`RetailMedia_Audience_Read`	Read access to audience segments and contact lists
`RetailMedia_Audience_Manage`	Create and manage audience segments and contact lists
`RetailMedia_Balance_Read`	Read access to balances and balance history
`RetailMedia_Balance_Manage`	Create and manage balances, add funds, and change balance dates
`RetailMedia_Billing_Read`	Read access to billing and partner reports
`RetailMedia_Catalog_Manage`	Create and manage store inventory in the product catalog

Endpoint scope requirements

Accounts

Method	Endpoint	Required scope
`POST`	`/2027-01/retail-media/account-management/accounts/{accountId}/brands/add`	`RetailMedia_Accounts_Manage`
`POST`	`/2027-01/retail-media/account-management/accounts/{accountId}/brands/remove`	`RetailMedia_Accounts_Manage`
`POST`	`/2027-01/retail-media/account-management/accounts/{accountId}/create-brand-account`	`RetailMedia_Accounts_Manage`
`POST`	`/2027-01/retail-media/account-management/accounts/{accountId}/create-seller-account`	`RetailMedia_Accounts_Manage`
`GET`	`/2027-01/retail-media/account-management/accounts/{accountId}/private-market-child-accounts`	`RetailMedia_Accounts_Read`
`PUT`	`/2027-01/retail-media/account-management/accounts/{accountId}/sellers`	`RetailMedia_Accounts_Manage`
`GET`	`/2027-01/retail-media/accounts`	`RetailMedia_Accounts_Read`
`POST`	`/2027-01/retail-media/accounts/fees/search`	`RetailMedia_Accounts_Read`
`POST`	`/2027-01/retail-media/accounts/fees/update`	`RetailMedia_Accounts_Manage`
`POST`	`/2027-01/retail-media/accounts/sellers/search`	`RetailMedia_Accounts_Read`
`POST`	`/2027-01/retail-media/accounts/{accountId}/grant-consent`	`RetailMedia_Accounts_Manage`
`POST`	`/2027-01/retail-media/brands/search`	`RetailMedia_Accounts_Read`

Analytics

Method	Endpoint	Required scope
`POST`	`/2027-01/retail-media/reports/attributed-transactions`	`RetailMedia_Analytics_Read`
`POST`	`/2027-01/retail-media/reports/fillrate`	`RetailMedia_Analytics_Read`
`POST`	`/2027-01/retail-media/reports/missed-opportunities`	`RetailMedia_Analytics_Read`
`POST`	`/2027-01/retail-media/reports/performance`	`RetailMedia_Analytics_Read`
`POST`	`/2027-01/retail-media/reports/revenue`	`RetailMedia_Analytics_Read`
`POST`	`/2027-01/retail-media/reports/sync/attributed-transactions`	`RetailMedia_Analytics_Read`
`POST`	`/2027-01/retail-media/reports/sync/campaigns`	`RetailMedia_Analytics_Read`
`POST`	`/2027-01/retail-media/reports/sync/line-items`	`RetailMedia_Analytics_Read`
`POST`	`/2027-01/retail-media/reports/sync/real-time-performance`	`RetailMedia_Analytics_Read`
`POST`	`/2027-01/retail-media/reports/unfilled-placements`	`RetailMedia_Analytics_Read`
`GET`	`/2027-01/retail-media/reports/{reportId}/output`	`RetailMedia_Analytics_Read`
`GET`	`/2027-01/retail-media/reports/{reportId}/status`	`RetailMedia_Analytics_Read`

Audience

Method	Endpoint	Required scope
`PATCH`	`/2027-01/retail-media/accounts/{account-id}/audience-segments`	`RetailMedia_Audience_Manage`
`POST`	`/2027-01/retail-media/accounts/{account-id}/audience-segments/create`	`RetailMedia_Audience_Manage`
`POST`	`/2027-01/retail-media/accounts/{account-id}/audience-segments/delete`	`RetailMedia_Audience_Manage`
`POST`	`/2027-01/retail-media/accounts/{account-id}/audience-segments/search`	`RetailMedia_Audience_Read`
`GET`	`/2027-01/retail-media/accounts/{account-id}/audience-segments/{audience-segment-id}/contact-list`	`RetailMedia_Audience_Read`
`POST`	`/2027-01/retail-media/accounts/{account-id}/audiences/search`	`RetailMedia_Audience_Read`
`POST`	`/2027-01/retail-media/audience-segments/{audience-segment-id}/contact-list/add-remove`	`RetailMedia_Audience_Manage`
`POST`	`/2027-01/retail-media/audience-segments/{audience-segment-id}/contact-list/clear`	`RetailMedia_Audience_Manage`

Balance

Method	Endpoint	Required scope
`POST`	`/2027-01/retail-media/accounts/{account-id}/balances`	`RetailMedia_Balance_Manage`
`GET`	`/2027-01/retail-media/accounts/{account-id}/balances/{balance-id}`	`RetailMedia_Balance_Read`
`PATCH`	`/2027-01/retail-media/accounts/{account-id}/balances/{balance-id}`	`RetailMedia_Balance_Manage`
`POST`	`/2027-01/retail-media/accounts/{account-id}/balances/{balance-id}/add-funds`	`RetailMedia_Balance_Manage`
`POST`	`/2027-01/retail-media/accounts/{account-id}/balances/{balance-id}/change-dates`	`RetailMedia_Balance_Manage`
`GET`	`/2027-01/retail-media/accounts/{accountId}/balances`	`RetailMedia_Balance_Read`
`GET`	`/2027-01/retail-media/balances/{balance-id}/campaigns`	`RetailMedia_Balance_Read`
`GET`	`/2027-01/retail-media/balances/{balanceId}`	`RetailMedia_Balance_Read`
`GET`	`/2027-01/retail-media/balances/{balanceId}/history`	`RetailMedia_Balance_Read`

Billing

Method	Endpoint	Required scope
`POST`	`/2027-01/retail-media/billing/partner-report`	`RetailMedia_Billing_Read`
`GET`	`/2027-01/retail-media/billing/partner-report/{requestId}/output`	`RetailMedia_Billing_Read`
`GET`	`/2027-01/retail-media/billing/partner-report/{requestId}/status`	`RetailMedia_Billing_Read`

Campaign

Method	Endpoint	Required scope
`GET`	`/2027-01/retail-media/accounts/{account-id}/campaigns`	`RetailMedia_Campaign_Read`
`POST`	`/2027-01/retail-media/accounts/{account-id}/campaigns`	`RetailMedia_Campaign_Manage`
`GET`	`/2027-01/retail-media/accounts/{account-id}/creatives`	`RetailMedia_Campaign_Read`
`POST`	`/2027-01/retail-media/accounts/{account-id}/creatives`	`RetailMedia_Campaign_Manage`
`POST`	`/2027-01/retail-media/accounts/{account-id}/creatives/search`	`RetailMedia_Campaign_Read`
`GET`	`/2027-01/retail-media/accounts/{account-id}/creatives/{creative-id}`	`RetailMedia_Campaign_Read`
`PUT`	`/2027-01/retail-media/accounts/{account-id}/creatives/{creative-id}`	`RetailMedia_Campaign_Manage`
`GET`	`/2027-01/retail-media/accounts/{account-id}/keywords/in-review-report`	`RetailMedia_Campaign_Read`
`GET`	`/2027-01/retail-media/accounts/{account-id}/line-items`	`RetailMedia_Campaign_Read`
`POST`	`/2027-01/retail-media/accounts/{accountId}/brand-catalog-export`	`RetailMedia_Campaign_Manage`
`GET`	`/2027-01/retail-media/accounts/{accountId}/brands`	`RetailMedia_Campaign_Read`
`POST`	`/2027-01/retail-media/accounts/{accountId}/catalogs`	`RetailMedia_Campaign_Read`
`POST`	`/2027-01/retail-media/accounts/{accountId}/catalogs/sellers`	`RetailMedia_Campaign_Read`
`POST`	`/2027-01/retail-media/accounts/{accountId}/retailers/search`	`RetailMedia_Campaign_Read`
`POST`	`/2027-01/retail-media/accounts/{accountId}/seller-catalog-export`	`RetailMedia_Campaign_Manage`
`POST`	`/2027-01/retail-media/assets`	`RetailMedia_Campaign_Manage`
`GET`	`/2027-01/retail-media/auction-line-items/{lineItemId}`	`RetailMedia_Campaign_Read`
`PUT`	`/2027-01/retail-media/auction-line-items/{lineItemId}`	`RetailMedia_Campaign_Manage`
`POST`	`/2027-01/retail-media/balances/{balanceId}/campaigns/append`	`RetailMedia_Campaign_Manage`
`POST`	`/2027-01/retail-media/balances/{balanceId}/campaigns/delete`	`RetailMedia_Campaign_Manage`
`GET`	`/2027-01/retail-media/campaigns/{campaign-id}/preferred-line-items`	`RetailMedia_Campaign_Read`
`POST`	`/2027-01/retail-media/campaigns/{campaign-id}/preferred-line-items`	`RetailMedia_Campaign_Manage`
`GET`	`/2027-01/retail-media/campaigns/{campaignId}`	`RetailMedia_Campaign_Read`
`PUT`	`/2027-01/retail-media/campaigns/{campaignId}`	`RetailMedia_Campaign_Manage`
`GET`	`/2027-01/retail-media/campaigns/{campaignId}/auction-line-items`	`RetailMedia_Campaign_Read`
`POST`	`/2027-01/retail-media/campaigns/{campaignId}/auction-line-items`	`RetailMedia_Campaign_Manage`
`GET`	`/2027-01/retail-media/campaigns/{campaignId}/campaign-budget-overrides`	`RetailMedia_Campaign_Read`
`PUT`	`/2027-01/retail-media/campaigns/{campaignId}/campaign-budget-overrides`	`RetailMedia_Campaign_Manage`
`GET`	`/2027-01/retail-media/catalogs/{catalogId}/output`	`RetailMedia_Campaign_Read`
`GET`	`/2027-01/retail-media/catalogs/{catalogId}/status`	`RetailMedia_Campaign_Read`
`GET`	`/2027-01/retail-media/categories`	`RetailMedia_Campaign_Read`
`GET`	`/2027-01/retail-media/categories/{categoryId}`	`RetailMedia_Campaign_Read`
`GET`	`/2027-01/retail-media/line-items/{externalLineItemId}/keywords/recommended`	`RetailMedia_Campaign_Read`
`POST`	`/2027-01/retail-media/line-items/{id}/keywords/add-remove`	`RetailMedia_Campaign_Manage`
`POST`	`/2027-01/retail-media/line-items/{id}/keywords/set-bid`	`RetailMedia_Campaign_Manage`
`GET`	`/2027-01/retail-media/line-items/{line-item-id}`	`RetailMedia_Campaign_Read`
`GET`	`/2027-01/retail-media/line-items/{line-item-id}/bid-multipliers`	`RetailMedia_Campaign_Read`
`PUT`	`/2027-01/retail-media/line-items/{line-item-id}/bid-multipliers`	`RetailMedia_Campaign_Manage`
`POST`	`/2027-01/retail-media/line-items/{line-item-id}/keywords/review`	`RetailMedia_Campaign_Manage`
`GET`	`/2027-01/retail-media/line-items/{line-item-id}/products`	`RetailMedia_Campaign_Read`
`POST`	`/2027-01/retail-media/line-items/{line-item-id}/products/append`	`RetailMedia_Campaign_Manage`
`POST`	`/2027-01/retail-media/line-items/{line-item-id}/products/delete`	`RetailMedia_Campaign_Manage`
`POST`	`/2027-01/retail-media/line-items/{line-item-id}/products/pause`	`RetailMedia_Campaign_Manage`
`POST`	`/2027-01/retail-media/line-items/{line-item-id}/products/unpause`	`RetailMedia_Campaign_Manage`
`GET`	`/2027-01/retail-media/line-items/{lineItemId}/line-item-budget-overrides`	`RetailMedia_Campaign_Read`
`PUT`	`/2027-01/retail-media/line-items/{lineItemId}/line-item-budget-overrides`	`RetailMedia_Campaign_Manage`
`GET`	`/2027-01/retail-media/preferred-line-items/{line-item-id}`	`RetailMedia_Campaign_Read`
`PUT`	`/2027-01/retail-media/preferred-line-items/{line-item-id}`	`RetailMedia_Campaign_Manage`
`GET`	`/2027-01/retail-media/preferred-line-items/{line-item-id}/targeting/add-to-basket`	`RetailMedia_Campaign_Read`
`PUT`	`/2027-01/retail-media/preferred-line-items/{line-item-id}/targeting/add-to-basket`	`RetailMedia_Campaign_Manage`
`POST`	`/2027-01/retail-media/preferred-line-items/{line-item-id}/targeting/add-to-basket/append`	`RetailMedia_Campaign_Manage`
`POST`	`/2027-01/retail-media/preferred-line-items/{line-item-id}/targeting/add-to-basket/delete`	`RetailMedia_Campaign_Manage`
`GET`	`/2027-01/retail-media/preferred-line-items/{line-item-id}/targeting/audiences`	`RetailMedia_Campaign_Read`
`PUT`	`/2027-01/retail-media/preferred-line-items/{line-item-id}/targeting/audiences`	`RetailMedia_Campaign_Manage`
`POST`	`/2027-01/retail-media/preferred-line-items/{line-item-id}/targeting/audiences/append`	`RetailMedia_Campaign_Manage`
`POST`	`/2027-01/retail-media/preferred-line-items/{line-item-id}/targeting/audiences/delete`	`RetailMedia_Campaign_Manage`
`GET`	`/2027-01/retail-media/preferred-line-items/{line-item-id}/targeting/stores`	`RetailMedia_Campaign_Read`
`PUT`	`/2027-01/retail-media/preferred-line-items/{line-item-id}/targeting/stores`	`RetailMedia_Campaign_Manage`
`POST`	`/2027-01/retail-media/preferred-line-items/{line-item-id}/targeting/stores/append`	`RetailMedia_Campaign_Manage`
`POST`	`/2027-01/retail-media/preferred-line-items/{line-item-id}/targeting/stores/delete`	`RetailMedia_Campaign_Manage`
`GET`	`/2027-01/retail-media/retailers/{retailer-id}/templates`	`RetailMedia_Campaign_Read`
`GET`	`/2027-01/retail-media/retailers/{retailer-id}/templates/{template-id}`	`RetailMedia_Campaign_Read`
`POST`	`/2027-01/retail-media/retailers/{retailerId}/categories/search`	`RetailMedia_Campaign_Read`
`POST`	`/2027-01/retail-media/retailers/{retailerId}/cpc-min-bids`	`RetailMedia_Campaign_Manage`
`GET`	`/2027-01/retail-media/retailers/{retailerId}/pages`	`RetailMedia_Campaign_Read`
`POST`	`/2027-01/retail-media/retailers/{retailerId}/recommend-categories`	`RetailMedia_Campaign_Read`
`POST`	`/2027-01/retail-media/retailers/{retailerId}/recommend-keywords`	`RetailMedia_Campaign_Read`

Catalog

Method	Endpoint	Required scope
`POST`	`/2027-01/retail-media/catalog/merchants/{merchantId}/store-inventory/delete`	`RetailMedia_Catalog_Manage`
`POST`	`/2027-01/retail-media/catalog/merchants/{merchantId}/store-inventory/upsert`	`RetailMedia_Catalog_Manage`

Gateway

Method	Endpoint	Required scope
`GET`	`/2027-01/retail-media/me`	`(none)`

Introduction

Guides for Retail Media API

Available scopes

Endpoint scope requirements

Accounts

Analytics

Audience

Balance

Billing

Campaign

Catalog

Gateway

​Available scopes

​Endpoint scope requirements

​Accounts

​Analytics

​Audience

​Balance

​Billing

​Campaign

​Catalog

​Gateway

Available scopes

Endpoint scope requirements

Accounts

Analytics

Audience

Balance

Billing

Campaign

Catalog

Gateway