All URIs are relative to https://api.pinterest.com/v5
| Method | HTTP request | Description |
|---|---|---|
| product_group_promotions_create | POST /ad_accounts/{ad_account_id}/product_group_promotions | Create product group promotions |
| product_group_promotions_get | GET /ad_accounts/{ad_account_id}/product_group_promotions/{product_group_promotion_id} | Get a product group promotion by id |
| product_group_promotions_list | GET /ad_accounts/{ad_account_id}/product_group_promotions | Get product group promotions |
| product_group_promotions_update | PATCH /ad_accounts/{ad_account_id}/product_group_promotions | Update product group promotions |
| product_groups_analytics | GET /ad_accounts/{ad_account_id}/product_groups/analytics | Get product group analytics |
ProductGroupPromotionResponse product_group_promotions_create(ad_account_id, product_group_promotion_create_request)
Create product group promotions
Add one or more product groups from your catalog to an existing ad group. (Product groups added to an ad group are a 'product group promotion.')
- OAuth Authentication (pinterest_oauth2):
import time
import openapi_generated.pinterest_client
from openapi_generated.pinterest_client.api import product_group_promotions_api
from openapi_generated.pinterest_client.model.error import Error
from openapi_generated.pinterest_client.model.product_group_promotion_create_request import ProductGroupPromotionCreateRequest
from openapi_generated.pinterest_client.model.product_group_promotion_response import ProductGroupPromotionResponse
from pprint import pprint
# Defining the host is optional and defaults to https://api.pinterest.com/v5
# See configuration.py for a list of all supported configuration parameters.
configuration = openapi_generated.pinterest_client.Configuration(
host = "https://api.pinterest.com/v5"
)
# The client must configure the authentication and authorization parameters
# in accordance with the API server security policy.
# Examples for each auth method are provided below, use the example that
# satisfies your auth use case.
# Configure OAuth2 access token for authorization: pinterest_oauth2
configuration = openapi_generated.pinterest_client.Configuration(
host = "https://api.pinterest.com/v5"
)
configuration.access_token = 'YOUR_ACCESS_TOKEN'
# Enter a context with an instance of the API client
with openapi_generated.pinterest_client.ApiClient(configuration) as api_client:
# Create an instance of the API class
api_instance = product_group_promotions_api.ProductGroupPromotionsApi(api_client)
ad_account_id = "4" # str | Unique identifier of an ad account.
product_group_promotion_create_request = ProductGroupPromotionCreateRequest(
ad_group_id="2680059592705",
product_group_promotion=[
ProductGroupPromotion(
id="2680059592705",
ad_group_id="2680059592705",
bid_in_micro_currency=14000000,
included=True,
definition="*/product_type_0='kitchen'/product_type_1='beverage appliances'",
relative_definition="product_type_1='beverage appliances'",
parent_id="1231234",
slideshow_collections_title="slideshow title",
slideshow_collections_description="slideshow description",
is_mdl=True,
status=EntityStatus("ACTIVE"),
tracking_url="https://www.pinterest.com",
catalog_product_group_id="1231235",
catalog_product_group_name="catalogProductGroupName",
creative_type=CreativeType("REGULAR"),
collections_hero_pin_id="123123",
collections_hero_destination_url="http://www.pinterest.com",
),
],
) # ProductGroupPromotionCreateRequest | List of Product Group Promotions to create, size limit [1, 30].
# example passing only required values which don't have defaults set
try:
# Create product group promotions
api_response = api_instance.product_group_promotions_create(ad_account_id, product_group_promotion_create_request)
pprint(api_response)
except openapi_generated.pinterest_client.ApiException as e:
print("Exception when calling ProductGroupPromotionsApi->product_group_promotions_create: %s\n" % e)| Name | Type | Description | Notes |
|---|---|---|---|
| ad_account_id | str | Unique identifier of an ad account. | |
| product_group_promotion_create_request | ProductGroupPromotionCreateRequest | List of Product Group Promotions to create, size limit [1, 30]. |
- Content-Type: application/json
- Accept: application/json
| Status code | Description | Response headers |
|---|---|---|
| 200 | Success | - |
| 0 | Unexpected error | - |
[Back to top] [Back to API list] [Back to Model list] [Back to README]
ProductGroupPromotionResponse product_group_promotions_get(ad_account_id, product_group_promotion_id)
Get a product group promotion by id
Get a product group promotion by id
- OAuth Authentication (pinterest_oauth2):
import time
import openapi_generated.pinterest_client
from openapi_generated.pinterest_client.api import product_group_promotions_api
from openapi_generated.pinterest_client.model.error import Error
from openapi_generated.pinterest_client.model.product_group_promotion_response import ProductGroupPromotionResponse
from pprint import pprint
# Defining the host is optional and defaults to https://api.pinterest.com/v5
# See configuration.py for a list of all supported configuration parameters.
configuration = openapi_generated.pinterest_client.Configuration(
host = "https://api.pinterest.com/v5"
)
# The client must configure the authentication and authorization parameters
# in accordance with the API server security policy.
# Examples for each auth method are provided below, use the example that
# satisfies your auth use case.
# Configure OAuth2 access token for authorization: pinterest_oauth2
configuration = openapi_generated.pinterest_client.Configuration(
host = "https://api.pinterest.com/v5"
)
configuration.access_token = 'YOUR_ACCESS_TOKEN'
# Enter a context with an instance of the API client
with openapi_generated.pinterest_client.ApiClient(configuration) as api_client:
# Create an instance of the API class
api_instance = product_group_promotions_api.ProductGroupPromotionsApi(api_client)
ad_account_id = "4" # str | Unique identifier of an ad account.
product_group_promotion_id = "4" # str | Unique identifier of a product group promotion
# example passing only required values which don't have defaults set
try:
# Get a product group promotion by id
api_response = api_instance.product_group_promotions_get(ad_account_id, product_group_promotion_id)
pprint(api_response)
except openapi_generated.pinterest_client.ApiException as e:
print("Exception when calling ProductGroupPromotionsApi->product_group_promotions_get: %s\n" % e)| Name | Type | Description | Notes |
|---|---|---|---|
| ad_account_id | str | Unique identifier of an ad account. | |
| product_group_promotion_id | str | Unique identifier of a product group promotion |
- Content-Type: Not defined
- Accept: application/json
| Status code | Description | Response headers |
|---|---|---|
| 200 | Success | - |
| 0 | Unexpected error | - |
[Back to top] [Back to API list] [Back to Model list] [Back to README]
bool, date, datetime, dict, float, int, list, str, none_type product_group_promotions_list(ad_account_id)
Get product group promotions
List existing product group promotions associated with an ad account. Include either ad_group_id or product_group_promotion_ids in your request. Note: ad_group_ids and product_group_promotion_ids are mutually exclusive parameters. Only provide one. If multiple options are provided, product_group_promotion_ids takes precedence over ad_group_ids. If none are provided, the endpoint returns an error.
- OAuth Authentication (pinterest_oauth2):
import time
import openapi_generated.pinterest_client
from openapi_generated.pinterest_client.api import product_group_promotions_api
from openapi_generated.pinterest_client.model.error import Error
from openapi_generated.pinterest_client.model.paginated import Paginated
from pprint import pprint
# Defining the host is optional and defaults to https://api.pinterest.com/v5
# See configuration.py for a list of all supported configuration parameters.
configuration = openapi_generated.pinterest_client.Configuration(
host = "https://api.pinterest.com/v5"
)
# The client must configure the authentication and authorization parameters
# in accordance with the API server security policy.
# Examples for each auth method are provided below, use the example that
# satisfies your auth use case.
# Configure OAuth2 access token for authorization: pinterest_oauth2
configuration = openapi_generated.pinterest_client.Configuration(
host = "https://api.pinterest.com/v5"
)
configuration.access_token = 'YOUR_ACCESS_TOKEN'
# Enter a context with an instance of the API client
with openapi_generated.pinterest_client.ApiClient(configuration) as api_client:
# Create an instance of the API class
api_instance = product_group_promotions_api.ProductGroupPromotionsApi(api_client)
ad_account_id = "4" # str | Unique identifier of an ad account.
product_group_promotion_ids = [
"4",
] # [str] | List of Product group promotion Ids. (optional)
entity_statuses = ["ACTIVE","PAUSED"] # [str] | Entity status (optional) if omitted the server will use the default value of ["ACTIVE","PAUSED"]
ad_group_id = "123123123" # str | Ad group Id. (optional)
page_size = 25 # int | Maximum number of items to include in a single page of the response. See documentation on <a href='/docs/getting-started/pagination/'>Pagination</a> for more information. (optional) if omitted the server will use the default value of 25
order = "ASCENDING" # str | The order in which to sort the items returned: “ASCENDING” or “DESCENDING” by ID. Note that higher-value IDs are associated with more-recently added items. (optional)
bookmark = "bookmark_example" # str | Cursor used to fetch the next page of items (optional)
# example passing only required values which don't have defaults set
try:
# Get product group promotions
api_response = api_instance.product_group_promotions_list(ad_account_id)
pprint(api_response)
except openapi_generated.pinterest_client.ApiException as e:
print("Exception when calling ProductGroupPromotionsApi->product_group_promotions_list: %s\n" % e)
# example passing only required values which don't have defaults set
# and optional values
try:
# Get product group promotions
api_response = api_instance.product_group_promotions_list(ad_account_id, product_group_promotion_ids=product_group_promotion_ids, entity_statuses=entity_statuses, ad_group_id=ad_group_id, page_size=page_size, order=order, bookmark=bookmark)
pprint(api_response)
except openapi_generated.pinterest_client.ApiException as e:
print("Exception when calling ProductGroupPromotionsApi->product_group_promotions_list: %s\n" % e)| Name | Type | Description | Notes |
|---|---|---|---|
| ad_account_id | str | Unique identifier of an ad account. | |
| product_group_promotion_ids | [str] | List of Product group promotion Ids. | [optional] |
| entity_statuses | [str] | Entity status | [optional] if omitted the server will use the default value of ["ACTIVE","PAUSED"] |
| ad_group_id | str | Ad group Id. | [optional] |
| page_size | int | Maximum number of items to include in a single page of the response. See documentation on <a href='/docs/getting-started/pagination/'>Pagination</a> for more information. | [optional] if omitted the server will use the default value of 25 |
| order | str | The order in which to sort the items returned: “ASCENDING” or “DESCENDING” by ID. Note that higher-value IDs are associated with more-recently added items. | [optional] |
| bookmark | str | Cursor used to fetch the next page of items | [optional] |
bool, date, datetime, dict, float, int, list, str, none_type
- Content-Type: Not defined
- Accept: application/json
| Status code | Description | Response headers |
|---|---|---|
| 200 | Success | - |
| 0 | Unexpected error | - |
[Back to top] [Back to API list] [Back to Model list] [Back to README]
ProductGroupPromotionResponse product_group_promotions_update(ad_account_id, product_group_promotion_update_request)
Update product group promotions
Update multiple existing Product Group Promotions (by product_group_id)
- OAuth Authentication (pinterest_oauth2):
import time
import openapi_generated.pinterest_client
from openapi_generated.pinterest_client.api import product_group_promotions_api
from openapi_generated.pinterest_client.model.error import Error
from openapi_generated.pinterest_client.model.product_group_promotion_update_request import ProductGroupPromotionUpdateRequest
from openapi_generated.pinterest_client.model.product_group_promotion_response import ProductGroupPromotionResponse
from pprint import pprint
# Defining the host is optional and defaults to https://api.pinterest.com/v5
# See configuration.py for a list of all supported configuration parameters.
configuration = openapi_generated.pinterest_client.Configuration(
host = "https://api.pinterest.com/v5"
)
# The client must configure the authentication and authorization parameters
# in accordance with the API server security policy.
# Examples for each auth method are provided below, use the example that
# satisfies your auth use case.
# Configure OAuth2 access token for authorization: pinterest_oauth2
configuration = openapi_generated.pinterest_client.Configuration(
host = "https://api.pinterest.com/v5"
)
configuration.access_token = 'YOUR_ACCESS_TOKEN'
# Enter a context with an instance of the API client
with openapi_generated.pinterest_client.ApiClient(configuration) as api_client:
# Create an instance of the API class
api_instance = product_group_promotions_api.ProductGroupPromotionsApi(api_client)
ad_account_id = "4" # str | Unique identifier of an ad account.
product_group_promotion_update_request = ProductGroupPromotionUpdateRequest(
ad_group_id="2680059592705",
product_group_promotion=[
ProductGroupPromotion(
id="2680059592705",
ad_group_id="2680059592705",
bid_in_micro_currency=14000000,
included=True,
definition="*/product_type_0='kitchen'/product_type_1='beverage appliances'",
relative_definition="product_type_1='beverage appliances'",
parent_id="1231234",
slideshow_collections_title="slideshow title",
slideshow_collections_description="slideshow description",
is_mdl=True,
status=EntityStatus("ACTIVE"),
tracking_url="https://www.pinterest.com",
catalog_product_group_id="1231235",
catalog_product_group_name="catalogProductGroupName",
creative_type=CreativeType("REGULAR"),
collections_hero_pin_id="123123",
collections_hero_destination_url="http://www.pinterest.com",
),
],
) # ProductGroupPromotionUpdateRequest | Parameters to update Product group promotions
# example passing only required values which don't have defaults set
try:
# Update product group promotions
api_response = api_instance.product_group_promotions_update(ad_account_id, product_group_promotion_update_request)
pprint(api_response)
except openapi_generated.pinterest_client.ApiException as e:
print("Exception when calling ProductGroupPromotionsApi->product_group_promotions_update: %s\n" % e)| Name | Type | Description | Notes |
|---|---|---|---|
| ad_account_id | str | Unique identifier of an ad account. | |
| product_group_promotion_update_request | ProductGroupPromotionUpdateRequest | Parameters to update Product group promotions |
- Content-Type: application/json
- Accept: application/json
| Status code | Description | Response headers |
|---|---|---|
| 200 | Success | - |
| 0 | Unexpected error | - |
[Back to top] [Back to API list] [Back to Model list] [Back to README]
ProductGroupAnalyticsResponse product_groups_analytics(ad_account_id, start_date, end_date, product_group_ids, columns, granularity)
Get product group analytics
Get analytics for the specified product groups in the specified ad_account_id, filtered by the specified options. - The token's user_account must either be the Owner of the specified ad account, or have one of the necessary roles granted to them via <a href="https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts\">Business Access: Admin, Analyst, Campaign Manager. - If granularity is not HOUR, the furthest back you can are allowed to pull data is 90 days before the current date in UTC time and the max time range supported is 90 days. - If granularity is HOUR, the furthest back you can are allowed to pull data is 8 days before the current date in UTC time and the max time range supported is 3 days.
- OAuth Authentication (pinterest_oauth2):
import time
import openapi_generated.pinterest_client
from openapi_generated.pinterest_client.api import product_group_promotions_api
from openapi_generated.pinterest_client.model.product_group_analytics_response import ProductGroupAnalyticsResponse
from openapi_generated.pinterest_client.model.error import Error
from openapi_generated.pinterest_client.model.granularity import Granularity
from pprint import pprint
# Defining the host is optional and defaults to https://api.pinterest.com/v5
# See configuration.py for a list of all supported configuration parameters.
configuration = openapi_generated.pinterest_client.Configuration(
host = "https://api.pinterest.com/v5"
)
# The client must configure the authentication and authorization parameters
# in accordance with the API server security policy.
# Examples for each auth method are provided below, use the example that
# satisfies your auth use case.
# Configure OAuth2 access token for authorization: pinterest_oauth2
configuration = openapi_generated.pinterest_client.Configuration(
host = "https://api.pinterest.com/v5"
)
configuration.access_token = 'YOUR_ACCESS_TOKEN'
# Enter a context with an instance of the API client
with openapi_generated.pinterest_client.ApiClient(configuration) as api_client:
# Create an instance of the API class
api_instance = product_group_promotions_api.ProductGroupPromotionsApi(api_client)
ad_account_id = "4" # str | Unique identifier of an ad account.
start_date = dateutil_parser('1970-01-01').date() # date | Metric report start date (UTC). Format: YYYY-MM-DD. Cannot be more than 90 days back from today.
end_date = dateutil_parser('1970-01-01').date() # date | Metric report end date (UTC). Format: YYYY-MM-DD. Cannot be more than 90 days past start_date.
product_group_ids = [
"4",
] # [str] | List of Product group Ids to use to filter the results.
columns = [
"TOTAL_CONVERSIONS",
] # [str] | Columns to retrieve, encoded as a comma-separated string. **NOTE**: Any metrics defined as MICRO_DOLLARS returns a value based on the advertiser profile's currency field. For USD,($1/1,000,000, or $0.000001 - one one-ten-thousandth of a cent). it's microdollars. Otherwise, it's in microunits of the advertiser's currency.<br/>For example, if the advertiser's currency is GBP (British pound sterling), all MICRO_DOLLARS fields will be in GBP microunits (1/1,000,000 British pound).<br/>If a column has no value, it may not be returned
granularity = Granularity("DAY") # Granularity | TOTAL - metrics are aggregated over the specified date range.<br> DAY - metrics are broken down daily.<br> HOUR - metrics are broken down hourly.<br>WEEKLY - metrics are broken down weekly.<br>MONTHLY - metrics are broken down monthly
click_window_days = 1 # int | Number of days to use as the conversion attribution window for a pin click action. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to `30` days. (optional) if omitted the server will use the default value of 30
engagement_window_days = 30 # int | Number of days to use as the conversion attribution window for an engagement action. Engagements include saves, closeups, link clicks, and carousel card swipes. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to `30` days. (optional) if omitted the server will use the default value of 30
view_window_days = 1 # int | Number of days to use as the conversion attribution window for a view action. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to `1` day. (optional) if omitted the server will use the default value of 1
conversion_report_time = "TIME_OF_AD_ACTION" # str | The date by which the conversion metrics returned from this endpoint will be reported. There are two dates associated with a conversion event: the date that the user interacted with the ad, and the date that the user completed a conversion event. (optional) if omitted the server will use the default value of "TIME_OF_AD_ACTION"
# example passing only required values which don't have defaults set
try:
# Get product group analytics
api_response = api_instance.product_groups_analytics(ad_account_id, start_date, end_date, product_group_ids, columns, granularity)
pprint(api_response)
except openapi_generated.pinterest_client.ApiException as e:
print("Exception when calling ProductGroupPromotionsApi->product_groups_analytics: %s\n" % e)
# example passing only required values which don't have defaults set
# and optional values
try:
# Get product group analytics
api_response = api_instance.product_groups_analytics(ad_account_id, start_date, end_date, product_group_ids, columns, granularity, click_window_days=click_window_days, engagement_window_days=engagement_window_days, view_window_days=view_window_days, conversion_report_time=conversion_report_time)
pprint(api_response)
except openapi_generated.pinterest_client.ApiException as e:
print("Exception when calling ProductGroupPromotionsApi->product_groups_analytics: %s\n" % e)| Name | Type | Description | Notes |
|---|---|---|---|
| ad_account_id | str | Unique identifier of an ad account. | |
| start_date | date | Metric report start date (UTC). Format: YYYY-MM-DD. Cannot be more than 90 days back from today. | |
| end_date | date | Metric report end date (UTC). Format: YYYY-MM-DD. Cannot be more than 90 days past start_date. | |
| product_group_ids | [str] | List of Product group Ids to use to filter the results. | |
| columns | [str] | Columns to retrieve, encoded as a comma-separated string. NOTE: Any metrics defined as MICRO_DOLLARS returns a value based on the advertiser profile's currency field. For USD,($1/1,000,000, or $0.000001 - one one-ten-thousandth of a cent). it's microdollars. Otherwise, it's in microunits of the advertiser's currency.<br/>For example, if the advertiser's currency is GBP (British pound sterling), all MICRO_DOLLARS fields will be in GBP microunits (1/1,000,000 British pound).<br/>If a column has no value, it may not be returned | |
| granularity | Granularity | TOTAL - metrics are aggregated over the specified date range.<br> DAY - metrics are broken down daily.<br> HOUR - metrics are broken down hourly.<br>WEEKLY - metrics are broken down weekly.<br>MONTHLY - metrics are broken down monthly | |
| click_window_days | int | Number of days to use as the conversion attribution window for a pin click action. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to `30` days. | [optional] if omitted the server will use the default value of 30 |
| engagement_window_days | int | Number of days to use as the conversion attribution window for an engagement action. Engagements include saves, closeups, link clicks, and carousel card swipes. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to `30` days. | [optional] if omitted the server will use the default value of 30 |
| view_window_days | int | Number of days to use as the conversion attribution window for a view action. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to `1` day. | [optional] if omitted the server will use the default value of 1 |
| conversion_report_time | str | The date by which the conversion metrics returned from this endpoint will be reported. There are two dates associated with a conversion event: the date that the user interacted with the ad, and the date that the user completed a conversion event. | [optional] if omitted the server will use the default value of "TIME_OF_AD_ACTION" |
- Content-Type: Not defined
- Accept: application/json
| Status code | Description | Response headers |
|---|---|---|
| 200 | Success | - |
| 400 | Invalid ad account ads analytics parameters. | - |
| 0 | Unexpected error | - |
[Back to top] [Back to API list] [Back to Model list] [Back to README]