Themes

class ad_api.api.sb.Themes(account: str = 'default', marketplace: Marketplaces = Marketplaces.EU, credentials: Dict[str, str] | None = None, proxies: Dict[str, str] | None = None, verify: bool = True, timeout: int | None = None, debug: bool = False, access_token: str | None = None, verify_additional_credentials: bool = True)

Amazon Ads API - Sponsored Brands - Theme Targeting

Theme targeting automatically targets keywords related to your brand or landing pages.

list_themes(*args, **kwargs)

Gets a list of theme targets associated with the client identifier, filtered by specified criteria.

Request Body

‘nextToken’: string, {‘description’: ‘Token for pagination. Operations that return paginated results include a pagination token in this field.’}

‘maxResults’: number, {‘description’: ‘Maximum number of results to return. Defaults to API maximum.’}

‘campaignIdFilter’: object, {‘description’: ‘List of campaign identifiers to filter by (max 100).’}

‘adGroupIdFilter’: object, {‘description’: ‘List of ad group identifiers to filter by (max 100).’}

‘themeIdFilter’: object, {‘description’: ‘List of theme target identifiers to filter by (max 100).’}

‘stateFilter’: object, {‘description’: ‘List of theme target states to filter by. Valid values: enabled, paused, archived. Default: enabled, paused.’}

‘themeTypeFilter’: object, {‘description’: ‘List of theme types to filter by. Valid values: KEYWORDS_RELATED_TO_YOUR_BRAND, KEYWORDS_RELATED_TO_YOUR_LANDING_PAGES.’}

Returns:

ApiResponse

### Example Python

from ad_api.api.sb.themes import Themes

result = Themes().list_themes()
print(result)

create_themes(*args, **kwargs)

Create one or more theme targets.

Note that theme targets can be created on multi-adGroup campaigns where campaign serving status is not archived, terminated, rejected, or ended. Note that ad group state must not be archived. Note that only one target can be created for each themeType per adGroup. Note that this operation supports a maximum list size of 100 theme targets.

Request Body

‘themes’: array, {‘description’: ‘List of theme targets to create (max 100).’} | ‘adGroupId’: string, {‘description’: ‘The identifier of the ad group’} | ‘campaignId’: string, {‘description’: ‘The identifier of the campaign’} | ‘themeType’: string, {‘description’: ‘Theme type’, ‘Enum’: ‘KEYWORDS_RELATED_TO_YOUR_BRAND, KEYWORDS_RELATED_TO_YOUR_LANDING_PAGES’} | ‘bid’: number, {‘description’: ‘The bid amount’}

Returns:

ApiResponse

### Example Python

from ad_api.api.sb.themes import Themes
import json

# Example data for themes
themes_to_create = [
    {
        "adGroupId": "YOUR_ADGROUP_ID",
        "campaignId": "YOUR_CAMPAIGN_ID",
        "themeType": "KEYWORDS_RELATED_TO_YOUR_BRAND",
        "bid": 0.75
    }
    # Add more theme objects as needed, up to 100
]

# For a real scenario, you might read this from a file like in your Keywords example
# file = open("create_themes.json")
# data = file.read()
# file.close()
# result = Themes().create_themes(body=data)

result = Themes().create_themes(themes=themes_to_create)
print(result)

### Example JSON (for request body)

{
    "themes": [
        {
            "adGroupId": "string",
            "campaignId": "string",
            "themeType": "KEYWORDS_RELATED_TO_YOUR_BRAND|KEYWORDS_RELATED_TO_YOUR_LANDING_PAGES",
            "bid": 0.75
        }
    ]
}

update_themes(*args, **kwargs)

Updates one or more theme targets.

Note that theme targets can be updated on multi-adGroup campaigns where campaign serving status is not archived, terminated, rejected, or ended. Note that ad group state must not be archived. Note that this operation supports a maximum list size of 100 theme targets. Note that bid is only mutable when the corresponding campaign does not have any enabled optimization rule.

Request Body

‘themes’: array, {‘description’: ‘List of theme targets to update (max 100).’} | ‘themeId’: string, {‘description’: ‘The identifier of the theme target’} | ‘adGroupId’: string, {‘description’: ‘The identifier of the ad group’} | ‘campaignId’: string, {‘description’: ‘The identifier of the campaign’} | ‘state’: string, {‘description’: ‘Theme target state’, ‘Enum’: ‘enabled, paused, archived’} | ‘bid’: number, {‘description’: ‘The bid amount’}

Returns:

ApiResponse

### Example Python

from ad_api.api.sb.themes import Themes
import json

# Example data for themes to update
themes_to_update = [
    {
        "themeId": "YOUR_THEME_ID",
        "adGroupId": "YOUR_ADGROUP_ID",
        "campaignId": "YOUR_CAMPAIGN_ID",
        "state": "paused", # or "enabled", "archived"
        "bid": 0.80 # Optional, if updating bid
    }
    # Add more theme objects as needed, up to 100
]

# For a real scenario, you might read this from a file
# file = open("update_themes.json")
# data = file.read()
# file.close()
# result = Themes().update_themes(body=data)

result = Themes().update_themes(themes=themes_to_update)
print(result)

### Example JSON (for request body)

{
    "themes": [
        {
            "themeId": "string",
            "adGroupId": "string",
            "campaignId": "string",
            "state": "enabled|paused|archived",
            "bid": 0.80
        }
    ]
}

list_themes(**kwargs)

Gets a list of theme targets associated with the client identifier, filtered by specified criteria.

Request Body

‘nextToken’: string, {‘description’: ‘Token for pagination. Operations that return paginated results include a pagination token in this field.’}

‘maxResults’: number, {‘description’: ‘Maximum number of results to return. Defaults to API maximum.’}

‘campaignIdFilter’: object, {‘description’: ‘List of campaign identifiers to filter by (max 100).’}

‘adGroupIdFilter’: object, {‘description’: ‘List of ad group identifiers to filter by (max 100).’}

‘themeIdFilter’: object, {‘description’: ‘List of theme target identifiers to filter by (max 100).’}

‘stateFilter’: object, {‘description’: ‘List of theme target states to filter by. Valid values: enabled, paused, archived. Default: enabled, paused.’}

‘themeTypeFilter’: object, {‘description’: ‘List of theme types to filter by. Valid values: KEYWORDS_RELATED_TO_YOUR_BRAND, KEYWORDS_RELATED_TO_YOUR_LANDING_PAGES.’}

Returns:

ApiResponse

create_themes(**kwargs)

Create one or more theme targets.

Note that theme targets can be created on multi-adGroup campaigns where campaign serving status is not archived, terminated, rejected, or ended. Note that ad group state must not be archived. Note that only one target can be created for each themeType per adGroup. Note that this operation supports a maximum list size of 100 theme targets.

Request Body

‘themes’: array, {‘description’: ‘List of theme targets to create (max 100).’} | ‘adGroupId’: string, {‘description’: ‘The identifier of the ad group’} | ‘campaignId’: string, {‘description’: ‘The identifier of the campaign’} | ‘themeType’: string, {‘description’: ‘Theme type’, ‘Enum’: ‘KEYWORDS_RELATED_TO_YOUR_BRAND, KEYWORDS_RELATED_TO_YOUR_LANDING_PAGES’} | ‘bid’: number, {‘description’: ‘The bid amount’}

Returns:

ApiResponse

update_themes(**kwargs)

Updates one or more theme targets.

Note that theme targets can be updated on multi-adGroup campaigns where campaign serving status is not archived, terminated, rejected, or ended. Note that ad group state must not be archived. Note that this operation supports a maximum list size of 100 theme targets. Note that bid is only mutable when the corresponding campaign does not have any enabled optimization rule.

Request Body

‘themes’: array, {‘description’: ‘List of theme targets to update (max 100).’} | ‘themeId’: string, {‘description’: ‘The identifier of the theme target’} | ‘adGroupId’: string, {‘description’: ‘The identifier of the ad group’} | ‘campaignId’: string, {‘description’: ‘The identifier of the campaign’} | ‘state’: string, {‘description’: ‘Theme target state’, ‘Enum’: ‘enabled, paused, archived’} | ‘bid’: number, {‘description’: ‘The bid amount’}

Returns:

ApiResponse