v5.28.0

API Changelog (5.23.0 → 5.28.0)

Client-Impacting Breaking Changes Only

Ad Accounts

POST /ad_accounts/{ad_account_id}/reports

• ⚠️ added the new required request property end_date
• ⚠️ added the new required request property granularity
• ⚠️ added the new required request property start_date

POST /ad_accounts/{ad_account_id}/mmm_reports

• ⚠️ removed the enum value AD_GROUP_TARGETING of the request property level
• ⚠️ removed the enum value CAMPAIGN_TARGETING of the request property level
• ⚠️ removed the enum value DAY of the request property granularity
• ⚠️ removed the enum value WEEK of the request property granularity
• ⚠️ removed the optional property code from the response with the 200 status
• ⚠️ removed the optional property data from the response with the 200 status

GET /ad_accounts/{ad_account_id}/mmm_reports

• ⚠️ removed the optional property code from the response with the 200 status
• ⚠️ removed the optional property data from the response with the 200 status

POST /ad_accounts/{ad_account_id}/reports/brand_category_sku

• ⚠️ removed the enum value ADVERTISER of the request property level
• ⚠️ removed the enum value AD_GROUP of the request property level
• ⚠️ removed the enum value CAMPAIGN of the request property level
• ⚠️ removed the enum value MONTH of the request property granularity
• ⚠️ removed the enum value TOTAL of the request property granularity
• ⚠️ removed the enum value WEEK of the request property granularity
• ⚠️ removed the enum value BRAND_ATTRIBUTION of the request property conversion_product_attribution_type
• ⚠️ removed the enum value DEFAULT of the request property conversion_product_attribution_type
• ⚠️ the report_status response's property type/format changed from string/to/`` for status 200

GET /ad_accounts/{ad_account_id}/templates

• ⚠️ the response's body type/format changed from / to object/`` for status 200

---

Ad Groups

POST /ad_accounts/{ad_account_id}/ad_groups

• ⚠️ added the new required request property /items/billable_event
• ⚠️ added the new required request property /items/campaign_id
• ⚠️ added the new required request property /items/name

PATCH /ad_accounts/{ad_account_id}/ad_groups

• ⚠️ added the new required request property /items/id

GET /ad_accounts/{ad_account_id}/ad_groups

• ⚠️ the response's body type/format changed from / to object/`` for status 200

POST /ad_accounts/{ad_account_id}/bid_floor

• ⚠️ removed the enum value CLICKTHROUGH of the request property bid_floor_specs/items/billable_event
• ⚠️ removed the enum value IMPRESSION of the request property bid_floor_specs/items/billable_event
• ⚠️ removed the enum value VIDEO_V_50_MRC of the request property bid_floor_specs/items/billable_event
• ⚠️ removed the enum value AWARENESS of the request property bid_floor_specs/items/objective_type
• ⚠️ removed the enum value CATALOG_SALES of the request property bid_floor_specs/items/objective_type
• ⚠️ removed the enum value CONSIDERATION of the request property bid_floor_specs/items/objective_type
• ⚠️ removed the enum value VIDEO_COMPLETION of the request property bid_floor_specs/items/objective_type
• ⚠️ removed the enum value WEB_CONVERSION of the request property bid_floor_specs/items/objective_type
• ⚠️ removed the enum value CAROUSEL of the request property bid_floor_specs/items/creative_type
• ⚠️ removed the enum value COLLAGE of the request property bid_floor_specs/items/creative_type
• ⚠️ removed the enum value COLLECTION of the request property bid_floor_specs/items/creative_type
• ⚠️ removed the enum value IDEA of the request property bid_floor_specs/items/creative_type
• ⚠️ removed the enum value MAX_VIDEO of the request property bid_floor_specs/items/creative_type
• ⚠️ removed the enum value QUIZ of the request property bid_floor_specs/items/creative_type
• ⚠️ removed the enum value REGULAR of the request property bid_floor_specs/items/creative_type
• ⚠️ removed the enum value SHOPPING of the request property bid_floor_specs/items/creative_type
• ⚠️ removed the enum value SHOP_THE_PIN of the request property bid_floor_specs/items/creative_type
• ⚠️ removed the enum value SHOWCASE of the request property bid_floor_specs/items/creative_type
• ⚠️ removed the enum value VIDEO of the request property bid_floor_specs/items/creative_type
• ⚠️ removed all individual currency enum values (USD, EUR, GBP, etc.) of the request property bid_floor_specs/items/currency
• ⚠️ removed the request property targeting_spec/AGE_BUCKET
• ⚠️ removed the request property targeting_spec/APPTYPE
• ⚠️ removed the request property targeting_spec/AUDIENCE_EXCLUDE
• ⚠️ removed the request property targeting_spec/AUDIENCE_INCLUDE
• ⚠️ removed the request property targeting_spec/GENDER
• ⚠️ removed the request property targeting_spec/GEO
• ⚠️ removed the request property targeting_spec/INTEREST
• ⚠️ removed the request property targeting_spec/LOCALE
• ⚠️ removed the request property targeting_spec/LOCATION
• ⚠️ removed the request property targeting_spec/MAXIMUM_AGE
• ⚠️ removed the request property targeting_spec/MINIMUM_AGE
• ⚠️ removed the request property targeting_spec/SHOPPING_RETARGETING
• ⚠️ removed the request property targeting_spec/TARGETING_STRATEGY

---

Ads

POST /ad_accounts/{ad_account_id}/ads

• ⚠️ added the new required request property /items/ad_group_id
• ⚠️ added the new required request property /items/creative_type
• ⚠️ added the new required request property /items/pin_id

PATCH /ad_accounts/{ad_account_id}/ads

• ⚠️ added the new required request property /items/id

GET /ad_accounts/{ad_account_id}/ads

• ⚠️ the response's body type/format changed from / to object/`` for status 200

---

Advanced Auction

POST /advanced_auction/items/get

• ⚠️ added the new required request property items/items/country
• ⚠️ added the new required request property items/items/item_id
• ⚠️ added the new required request property items/items/language
• ⚠️ the catalog_id request property type/format changed from string/to/``
• ⚠️ the items/items/ request property type/format changed from / to object/``
• ⚠️ the catalog_id response's property type/format changed from string/to/`` for status 200
• ⚠️ the items/items/ response's property type/format changed from / to object/`` for status 200

POST /advanced_auction/items/submit

• ⚠️ added the new required request property items/items/oneOf[.../AdvancedAuctionItemsSubmitDeleteRecord]/country
• ⚠️ added the new required request property items/items/oneOf[.../AdvancedAuctionItemsSubmitDeleteRecord]/item_id
• ⚠️ added the new required request property items/items/oneOf[.../AdvancedAuctionItemsSubmitDeleteRecord]/language
• ⚠️ added the new required request property items/items/oneOf[.../AdvancedAuctionItemsSubmitDeleteRecord]/operation
• ⚠️ added the new required request property items/items/oneOf[.../AdvancedAuctionItemsSubmitUpsertRecord]/bid_options
• ⚠️ added the new required request property items/items/oneOf[.../AdvancedAuctionItemsSubmitUpsertRecord]/country
• ⚠️ added the new required request property items/items/oneOf[.../AdvancedAuctionItemsSubmitUpsertRecord]/item_id
• ⚠️ added the new required request property items/items/oneOf[.../AdvancedAuctionItemsSubmitUpsertRecord]/language
• ⚠️ added the new required request property items/items/oneOf[.../AdvancedAuctionItemsSubmitUpsertRecord]/operation
• ⚠️ added the new required request property items/items/oneOf[.../AdvancedAuctionItemsSubmitUpsertRecord]/update_mask
• ⚠️ the catalog_id request property type/format changed from string/to/``
• ⚠️ the delete/upsert record items request property type/format changed from / to object/``
• ⚠️ removed the required property items/items/operation from the response with the 200 status
• ⚠️ removed the required property items/items/operation from the response with the 206 status
• ⚠️ the catalog_id response's property type/format changed from string/to/`` for status 200
• ⚠️ the catalog_id response's property type/format changed from string/to/`` for status 206
• ⚠️ the delete/upsert record items response's property type/format changed from / to object/`` for status 200 and 206

---

Audience Sharing

PATCH /ad_accounts/{ad_account_id}/audiences/ad_accounts/shared
PATCH /businesses/{business_id}/audiences/ad_accounts/shared

• ⚠️ added the new required request property audience_id
• ⚠️ added the new required request property operation_type
• ⚠️ added the new required request property recipient_account_ids

PATCH /ad_accounts/{ad_account_id}/audiences/businesses/shared
PATCH /businesses/{business_id}/audiences/businesses/shared

• ⚠️ added the new required request property audience_id
• ⚠️ added the new required request property operation_type
• ⚠️ added the new required request property recipient_business_ids

GET /ad_accounts/{ad_account_id}/audiences/shared/accounts
GET /businesses/{business_id}/audiences/shared/accounts

• ⚠️ the response's body type/format changed from / to object/`` for status 200

GET /businesses/{business_id}/audiences

• ⚠️ the response's body type/format changed from / to object/`` for status 200

---

Audiences

GET /ad_accounts/{ad_account_id}/audiences

• ⚠️ the response's body type/format changed from / to object/`` for status 200

---

Billing

GET /ad_accounts/{ad_account_id}/ads_credit/discounts
GET /ad_accounts/{ad_account_id}/billing_profiles

• ⚠️ the response's body type/format changed from / to object/`` for status 200

GET /ad_accounts/{ad_account_id}/billing_invoi...

v5.23.0

API Changelog (5.22.0 → 5.23.0)

Ad Groups

GET /ad_accounts/{ad_account_id}/ad_groups
GET /ad_accounts/{ad_account_id}/ad_groups/{ad_group_id}
PATCH /ad_accounts/{ad_account_id}/ad_groups
POST /ad_accounts/{ad_account_id}/ad_groups

• ⚠️ Changed targeting_spec/AUDIENCE_EXCLUDE and AUDIENCE_INCLUDE minItems from 100 to 0.

---

Ads

GET /ad_accounts/{ad_account_id}/ads
GET /ad_accounts/{ad_account_id}/ads/{ad_id}
PATCH /ad_accounts/{ad_account_id}/ads
POST /ad_accounts/{ad_account_id}/ads

• Added optional disclosure_type and disclosure_url properties to requests and responses.

---

Bulk Operations

POST /ad_accounts/{ad_account_id}/bulk/upsert

• ⚠️ Changed update/labels/items/status to not nullable.
• ⚠️ Removed 'ACTIVE' and 'undefined' enum values from update/labels/items/status.
• Added optional disclosure_type and disclosure_url to create/ads and update/ads.

---

Reports

POST /ad_accounts/{ad_account_id}/reports

• ⚠️ Updated request body schema structure (allOf changes).

POST /ad_accounts/{ad_account_id}/templates/{template_id}/reports

• ⚠️ Added new enum values to report_status: CANCELLED, DOES_NOT_EXIST, EXPIRED, FAILED, FINISHED, IN_PROGRESS.
• Removed pattern validation from template_id parameter.
• Added error responses: 401, 403, 404, 429.
• Added 201 success response.
• report_status and template_id now required in 200 response.

---

Targeting Templates

GET /ad_accounts/{ad_account_id}/targeting_templates
POST /ad_accounts/{ad_account_id}/targeting_templates

• ⚠️ Changed targeting_attributes/AUDIENCE_EXCLUDE and AUDIENCE_INCLUDE minItems from 100 to 0.

PATCH /ad_accounts/{ad_account_id}/targeting_templates

• Added optional targeting_attributes request property.
• Added 'UPDATE' enum value to operation_type.

---

Trends

GET /trends/product_categories/details
GET /trends/product_categories/trending
GET /trends/topics/featured

• New endpoints added.

v5.22.0

API Changelog (5.21.0 → 5.22.0)

Ad Accounts

POST /ad_accounts/{ad_account_id}/ad_groups/audience_sizing

• ⚠️ Request body is now required.

GET /ad_accounts/{ad_account_id}/advertiser_defined_events

• ⚠️ Added mapped_conversion_type enum values: APP_OPEN, CONTACT, CUSTOMIZE_PRODUCT, FIND_LOCATION, SCHEDULE, START_TRIAL, SUBMIT_APPLICATION.

GET /ad_accounts/{ad_account_id}/audiences

• ⚠️ Restructured event_data: currency and line_items now use schema references (Currency, LineItem).
• ⚠️ Removed inline currency enum values and line_items properties (product_brand, product_category, product_id, product_name, product_price, product_quantity, product_variant, product_variant_id).

---

Catalogs

POST /catalogs/items/batch

• ⚠️ Added multiple new optional attributes for retail items: ad_video_0/1/2_link, ad_video_0/1/2_tag, android_deep_link, ios_deep_link.
• ⚠️ Hotel item guest_ratings properties (max_score, number_of_reviewers, rating_system, score) are now nullable.
• Response property created_time is now required.

GET /catalogs/items/batch/{batch_id}

• ⚠️ Response property created_time is now nullable and required.

---

Integrations

POST /integrations/commerce
PATCH /integrations/commerce/{external_business_id}

• ⚠️ Request body is now required for both endpoints.

---

OAuth

POST /oauth/conversion_token

• New endpoint added.

---

Note: Many detailed schema changes were made to audience event_data structures and catalog item attributes. See full API documentation for complete property listings.

v5.21.0

API Changelog (5.20.0 → 5.21.0)

Ad Accounts

GET /ad_accounts

• ⚠️ Response body type changed from ''/'' to 'object'/''.
• Removed '#/components/schemas/Paginated, subschema 2' from response body 'allOf' list.
• Added error responses: 400, 401, 403, 404, 429.
• Added optional bookmark and required items properties.

POST /ad_accounts

• ⚠️ Owner response property type changed from 'object'/'' to ''/'' for status 200.
• ⚠️ Removed optional properties: owner/id, owner/username.
• ⚠️ Added new enum values to permissions/items: FINANCE_EDIT, FINANCE_VIEW.
• Added error responses: 400, 401, 403, 404, 429.
• Properties now read-only: created_time, owner, permissions, updated_time.
• Added '#/components/schemas/AdAccountOwner' to owner property 'allOf' list.
• Property 'id' is now required with pattern '^\d+$'.
• Added success response with status 201.

GET /ad_accounts/{ad_account_id}

• ⚠️ Owner response property type changed from 'object'/'' to ''/'' for status 200.
• ⚠️ Removed optional properties: owner/id, owner/username.
• ⚠️ Added new enum values to permissions/items: FINANCE_EDIT, FINANCE_VIEW.
• Added error responses: 400, 401, 403, 404, 429.
• Properties now read-only: created_time, owner, permissions, updated_time.
• Added '#/components/schemas/AdAccountOwner' to owner property 'allOf' list.
• Property 'id' is now required with pattern '^\d+$'.

---

Ad Groups

GET /ad_accounts/{ad_account_id}/ad_groups
PATCH /ad_accounts/{ad_account_id}/ad_groups
POST /ad_accounts/{ad_account_id}/ad_groups
GET /ad_accounts/{ad_account_id}/ad_groups/{ad_group_id}

• Added optional targeting_spec properties: MAXIMUM_AGE, MINIMUM_AGE.

POST /ad_accounts/{ad_account_id}/ad_groups/audience_sizing

• Added optional request properties: targeting_spec/MAXIMUM_AGE, targeting_spec/MINIMUM_AGE.

---

Bulk Operations

POST /ad_accounts/{ad_account_id}/bulk/upsert

• Added optional request properties for create/update ad_groups: targeting_spec/MAXIMUM_AGE, targeting_spec/MINIMUM_AGE.

---

Bid Floor

POST /ad_accounts/{ad_account_id}/bid_floor

• Added optional request properties: targeting_spec/MAXIMUM_AGE, targeting_spec/MINIMUM_AGE.

---

Targeting Templates

GET /ad_accounts/{ad_account_id}/targeting_templates
POST /ad_accounts/{ad_account_id}/targeting_templates

• Added optional targeting_attributes properties: MAXIMUM_AGE, MINIMUM_AGE.

v5.20.0

API Changelog (5.18.0 → 5.20.0)

Ads & Ad Groups

GET /ad_accounts/{ad_account_id}/ads
PATCH /ad_accounts/{ad_account_id}/ads
POST /ad_accounts/{ad_account_id}/ads
GET /ad_accounts/{ad_account_id}/ads/{ad_id}

• ⚠️ Added new creative_type enum values: 'COLLAGE', 'MAX_WIDTH_REGULAR_COLLECTION', 'MAX_WIDTH_VIDEO_COLLECTION'.

GET /ad_accounts/{ad_account_id}/ad_groups/targeting_analytics
GET /ad_accounts/{ad_account_id}/ads/targeting_analytics

• ⚠️ Removed 'HOUSEHOLD' and 'INDIVIDUAL' enum values from attribution_types.
• ⚠️ Changed attribution_types type from 'string' to 'array'.

POST /ad_accounts/{ad_account_id}/ad_previews

• ⚠️ customizable_cta_type for AdPreviewShopping now non-nullable with schema changes.
• ⚠️ Removed enum values: 'BOOK_NOW', 'GET_DEAL', 'ON_SALE', 'SHOP_NOW', 'undefined'.
• Added 'REGULAR' enum value to creative_type.

GET /ad_accounts/{ad_account_id}/advertiser_defined_events

• Endpoint added.

---

Audiences

POST /ad_accounts/{ad_account_id}/audiences/custom

• ⚠️ API path removed without deprecation.

---

Bid Floor

POST /ad_accounts/{ad_account_id}/bid_floor

• Added new creative_type enum values: 'COLLAGE', 'MAX_WIDTH_REGULAR_COLLECTION', 'MAX_WIDTH_VIDEO_COLLECTION'.

---

Bulk Operations

POST /ad_accounts/{ad_account_id}/bulk/download

• Added 'SCHEDULE' enum value to entity_types.

POST /ad_accounts/{ad_account_id}/bulk/upsert

• ⚠️ Changed pattern for create/labels/items/parent_id from '^\d+$' to '^[C]?\d+$'.
• Added optional properties: create/catalog_product_groups, update/catalog_product_groups.
• Multiple properties became nullable: create/labels/items/labels/items/label_type, update/labels/items/status.
• Added 'BUY_ONLINE_PICKUP_IN_STORE' enum value to customizable_cta_type.
• Added new creative_type enum values across ads, campaigns, and product groups: 'COLLAGE', 'MAX_WIDTH_REGULAR_COLLECTION', 'MAX_WIDTH_VIDEO_COLLECTION'.

---

Campaigns

GET /ad_accounts/{ad_account_id}/campaigns
GET /ad_accounts/{ad_account_id}/campaigns/analytics
POST /ad_accounts/{ad_account_id}/campaigns
PATCH /ad_accounts/{ad_account_id}/campaigns
GET /ad_accounts/{ad_account_id}/campaigns/{campaign_id}

• Added new objective_type enum values: 'AD_RECALL_LIFT', 'BRAND_AWARENESS', 'VIDEO_VIEWS_10S', 'VIDEO_VIEWS_15S'.

---

Catalogs & Products

POST /catalogs/items
POST /catalogs/items/batch
GET /catalogs/product_groups/{product_group_id}/products
POST /catalogs/products/get_by_product_group_filters

• ⚠️ Response properties removed: note.
• ⚠️ Added new creative_type enum values: 'COLLAGE', 'MAX_WIDTH_REGULAR_COLLECTION', 'MAX_WIDTH_VIDEO_COLLECTION'.
• Added BoardOwner schema to board_owner property.

GET /catalogs/product_groups
POST /catalogs/product_groups
PATCH /catalogs/product_groups
GET /catalogs/product_groups/{product_group_id}
DELETE /catalogs/product_groups/{product_group_id}

• Added 'BUY_ONLINE_PICKUP_IN_STORE' enum value to customizable_cta_type.

---

Keywords

GET /ad_accounts/{ad_account_id}/keywords
PATCH /ad_accounts/{ad_account_id}/keywords
POST /ad_accounts/{ad_account_id}/keywords
GET /ad_accounts/{ad_account_id}/keywords/metrics

• ⚠️ Removed 'UNSPECIFIED' enum value from match_type parameter.
• Added 'TARGETING_INTERESTS' enum value to match_type.

---

Pins

POST /pins
GET /pins/{pin_id}
PATCH /pins/{pin_id}
POST /pins/{pin_id}/save

• ⚠️ Removed 'note' property from requests and responses.
• ⚠️ Added new creative_type enum values: 'COLLAGE', 'MAX_WIDTH_REGULAR_COLLECTION', 'MAX_WIDTH_VIDEO_COLLECTION'.
• Added BoardOwner schema to board_owner property.

---

Boards

GET /boards/{board_id}/pins
GET /boards/{board_id}/sections/{section_id}/pins
GET /search/boards
GET /user_account/following/boards

• ⚠️ Response schema refactored: removed individual properties (name, board_pins_modified_at, collaborator_count, created_at, description, follower_count, id, is_ads_only, media, owner, pin_count) in favor of BoardBase schema.
• ⚠️ privacy property type changed, now uses BoardPrivacy schema instead of enum strings.
• Removed enum values: 'PROTECTED', 'PUBLIC', 'SECRET' from privacy (consolidated into schema).

---

Search

GET /search/pins

• ⚠️ Removed 'note' property from response.
• ⚠️ Added new creative_type enum values: 'COLLAGE', 'MAX_WIDTH_REGULAR_COLLECTION', 'MAX_WIDTH_VIDEO_COLLECTION'.
• Added BoardOwner schema to board_owner property.

---

Trends

GET /trends/keywords/{region}/top/{trend_type}

• Added optional property: trends/items/predicted_time_series.

---

Note:
The creative_type enum expansion ('COLLAGE', 'MAX_WIDTH_REGULAR_COLLECTION', 'MAX_WIDTH_VIDEO_COLLECTION') affects numerous endpoints across ads, pins, catalogs, and search functionality.

v5.18.0

API Changelog (5.17.0 → 5.18.0)

Bulk Operations

POST /ad_accounts/{ad_account_id}/bulk/download

• Added 'LABEL' enum value to entity_types.

POST /ad_accounts/{ad_account_id}/bulk/upsert

• Added optional request properties: create/labels, update/labels.

---

Catalogs

GET /catalogs/feeds/{feed_id}/processing_results

• Added optional warnings: AD_VIDEO_LENGTH_TOO_SHORT, VIDEO_DOWNLOAD_VIDEO_TOO_SHORT.

POST /catalogs/items

• ⚠️ Added new PinMedia* schemas to media response types.
• Many response fields changed type/format, removed old props, stricter read-only/required status.
• Added discriminator handling.

POST /catalogs/items/batch

• Added optional save_pin_disabled to batch properties.

GET /catalogs/processing_results/{processing_result_id}/item_issues

• ⚠️ Added 'INSTALLMENT_PRICE', 'UNIT_PRICE_BASE_MEASURE', 'UNIT_PRICE_TOTAL_MEASURE' enums to multiple error/warning props.

GET /catalogs/product_groups/{product_group_id}/products
POST /catalogs/products/get_by_product_group_filters

• ⚠️ Added PinMedia* schemas to product media.
• Many board_owner, creative_type, media prop changes as above.

---

Pins

GET /pins

• ⚠️ Response body now type object, added bookmark & items, error responses 401/403/404/429.

POST /pins

• ⚠️ Request body no longer nullable.
• ⚠️ Added PinMedia* to media field.
• Removed: is_removable, product_tags, media_source.
• More strict: id/is_standard/pin_metrics, new media_source options/discriminator.
• Added 200, 401 responses.

DELETE /pins/{pin_id}

• ⚠️ Added pin_id pattern validation, error responses 400/401/429.

GET/PATCH /pins/{pin_id}, POST /pins/{pin_id}/save

• ⚠️ Added/changed PinMedia*, updated property types, removed obsolete properties, stricter field requirements/readonly.

---

Boards

GET /boards/{board_id}/pins
GET /boards/{board_id}/sections/{section_id}/pins

• ⚠️ Added PinMedia* schemas for media, board_owner and field type changes, discriminator additions. Cleaned/properties.

---

Trends

GET /trends/keywords/{region}/top/{trend_type}

• Added optional query: include_demographics, include_prediction.
• Response includes demographics/has_prediction.

---

Labels

GET /ad_accounts/{ad_account_id}/labels

• ⚠️ Changed default for entity_statuses to [ACTIVE]. Added label_types param.

PATCH /ad_accounts/{ad_account_id}/labels

• ⚠️ Set maxLength=100 for labels/items/value.

POST /ad_accounts/{ad_account_id}/labels

• ⚠️ Set maxLength=100 for labels/items/value.
• Added 'CUSTOM' enum value to label_type.

---

Reports

POST /ad_accounts/{ad_account_id}/reports

• Added 'LOCAL_ADS_STORE_CODE' enum value.

---

Search

GET /search/pins
GET /search/partner/pins

• ⚠️ Added PinMedia* to media property, board_owner & creative_type type changes, removed old/unused fields.

---

Note:
PinMedia* = PinMediaWithImage, PinMediaWithVideo, PinMediaWithImages, PinMediaWithVideos, PinMediaWithImageAndVideo.
Many fields and error types harmonized for stricter validation and enum consistency.

v5.17.0

API Changelog

Ad Groups

GET /ad_accounts/{ad_account_id}/ad_groups

• Added reporting_event property to conversion tag v3 goal metadata.

POST /ad_accounts/{ad_account_id}/ad_groups

• Added reporting_event property to conversion tag v3 goal metadata in requests and responses.

PATCH /ad_accounts/{ad_account_id}/ad_groups

• Added reporting_event property to conversion tag v3 goal metadata in requests and responses.

GET /ad_accounts/{ad_account_id}/ad_groups/{ad_group_id}

• Added reporting_event property to conversion tag v3 goal metadata.

---

Ad Previews

POST /ad_accounts/{ad_account_id}/ad_previews

• Added preferred_media_type property for shopping ad previews.
• Added video_tag property for shopping ad previews.

---

Bid Floor

POST /ad_accounts/{ad_account_id}/bid_floor

• Added reporting_event property to conversion tag v3 goal metadata in bid floor specs.

---

Bulk Operations

POST /ad_accounts/{ad_account_id}/bulk/upsert

• Added reporting_event property to conversion tag v3 goal metadata for both create and update ad group operations.

---

Promotions

GET /ad_accounts/{ad_account_id}/promotions

• ⚠️ Added new CUSTOM enum value to promotion types.
• Added custom_text property to template values.

POST /ad_accounts/{ad_account_id}/promotions

• ⚠️ Added new CUSTOM enum value to promotion types for requests and responses.
• Added custom_text property to template values.

PATCH /ad_accounts/{ad_account_id}/promotions

• ⚠️ Added new CUSTOM enum value to promotion types for requests and responses.
• Added custom_text property to template values.

GET /ad_accounts/{ad_account_id}/promotions/{promotion_id}

• ⚠️ Added new CUSTOM enum value to promotion types.
• Added custom_text property to template values.

---

Reports

POST /ad_accounts/{ad_account_id}/reports

• ⚠️ Updated request body schema structure.

GET /ad_accounts/{ad_account_id}/reports/brand_category_sku

• � New endpoint added.

POST /ad_accounts/{ad_account_id}/reports/brand_category_sku

• � New endpoint added.

---

Catalogs

POST /catalogs

• Added new RETAIL enum value to catalog types.

POST /catalogs/feeds

• ⚠️ Made catalog_id non-nullable for hotel and creative assets feeds.
• Added optional catalog_id for retail feeds.

POST /catalogs/items

• Added promotion_id property to retail item attributes.

POST /catalogs/items/batch

• Added optional catalog_id for retail batch requests.
• Added promotion_id property support across all retail item operations (create, update, upsert).

v5.16.0

API Changelog

Pins

GET /pins

• Added properties for is_removable and product_tags.

POST /pins

• Added properties for is_removable and product_tags.

GET /pins/{pin_id}

• Added properties for is_removable and product_tags.

PATCH /pins/{pin_id}

• Added properties for is_removable and product_tags.

POST /pins/{pin_id}/save

• Added properties for is_removable and product_tags.

GET /search/pins

• Added properties for is_removable and product_tags.

GET /boards/{board_id}/pins

• Added properties for is_removable and product_tags.

GET /boards/{board_id}/sections/{section_id}/pins

• Added properties for is_removable and product_tags.

---

Campaigns

GET /ad_accounts/{ad_account_id}/campaigns

• Added bid_options property.
• Removed VIDEO_VIEW and WEB_SESSIONS from objective_type.

POST /ad_accounts/{ad_account_id}/campaigns

• Removed VIDEO_VIEW and WEB_SESSIONS from objective_type.
• Added is_campaign_budget_optimization and bid_options properties.

PATCH /ad_accounts/{ad_account_id}/campaigns

• Removed VIDEO_VIEW and WEB_SESSIONS from objective_type.
• Added is_campaign_budget_optimization and bid_options properties.

GET /ad_accounts/{ad_account_id}/campaigns/{campaign_id}

• Added bid_options property.
• Removed VIDEO_VIEW and WEB_SESSIONS from objective_type.

---

Ad Groups

GET /ad_accounts/{ad_account_id}/ad_groups

• Added promotion_application_level property.

POST /ad_accounts/{ad_account_id}/ad_groups

• Added promotion_application_level property.

PATCH /ad_accounts/{ad_account_id}/ad_groups

• Added promotion_application_level property.

---

Audiences

GET /ad_accounts/{ad_account_id}/audiences

• Removed VIDEO_VIEW and WEB_SESSIONS from response enums.

POST /ad_accounts/{ad_account_id}/audiences

• Removed VIDEO_VIEW and WEB_SESSIONS from request and response enums.

---

Bulk

POST /ad_accounts/{ad_account_id}/bulk/download

• Removed VIDEO_VIEW and WEB_SESSIONS from objective_type.

POST /ad_accounts/{ad_account_id}/bulk/upsert

• Removed VIDEO_VIEW and WEB_SESSIONS from objective_type.
• Removed is_campaign_budget_optimization from update requests.
• Added several new properties related to promotions.

---

Analytics

GET /ad_accounts/{ad_account_id}/campaigns/analytics

• Added reporting_timezone as a query parameter.

GET /ad_accounts/{ad_account_id}/campaigns/targeting_analytics

• Added reporting_timezone as a query parameter.

GET /ad_accounts/{ad_account_id}/ad_groups/analytics

• Added reporting_timezone as a query parameter.

GET /ad_accounts/{ad_account_id}/ad_groups/targeting_analytics

• Added reporting_timezone as a query parameter.

GET /ad_accounts/{ad_account_id}/ads/analytics

• Added reporting_timezone as a query parameter.

GET /ad_accounts/{ad_account_id}/ads/targeting_analytics

• Added reporting_timezone as a query parameter.

GET /ad_accounts/{ad_account_id}/analytics

• Added reporting_timezone as a query parameter.

GET /ad_accounts/{ad_account_id}/pins/analytics

• Endpoint added.

---

Catalogs

POST /catalogs/items/batch

• Changed type/format of GTIN fields from integer to unspecified.
• Added support for up to 20 ad image links and tags.

POST /catalogs/product_groups/multiple

• Made country and locale optional for retail.

GET /catalogs/product_groups/{product_group_id}/products

• Added is_removable and product_tags for products.

POST /catalogs/products/get_by_product_group_filters

• Added is_removable and product_tags for products.

GET /catalogs/feeds/{feed_id}/processing_results

• Added new warnings and error codes for downloadable links and media processing.

---

Boards

GET /boards

• Added is_ads_only property.

POST /boards

• Added is_ads_only property.

GET /boards/{board_id}

• Added is_ads_only property.

PATCH /boards/{board_id}

• Added is_ads_only property.

---

Authentication

POST /oauth/token

• Removed support for everlasting_refresh token type.

POST /oauth/token/revoke

• Endpoint added.

---

Notifications

POST /notifications

• Endpoint added.

v5.15.0

What's Changed

Pins

GET /pins

• Removed media_type from response, added support for video cover frame time and improved video media structure.

POST /pins

• Removed media_type, added sponsor_id and video cover frame time, improved media schema. Now supports client_credentials.

DELETE /pins/{pin_id}

• Now supports client_credentials security.

GET /pins/{pin_id}

• Same as GET /pins: removed media_type, added video frame time, improved media schema.

PATCH /pins/{pin_id}

• Removed media_type, added video cover frame time. Now supports client_credentials.

POST /pins/{pin_id}/save

• Same media property changes as POST /pins.

GET /search/partner/pins

• Removed media_type, improved media structure and added ID property.

---

Ad Accounts

GET /ad_accounts

• Now supports client_credentials.

POST /ad_accounts

• Added optional property: currency.

GET /ad_accounts/{ad_account_id}

• Now supports client_credentials.

---

Campaigns

GET /ad_accounts/{ad_account_id}/campaigns

• Added automated and Performance+ campaign properties.
• Now supports client_credentials.

PATCH /ad_accounts/{ad_account_id}/campaigns

• Added automated, Performance+ campaign properties; removed old automated property.

GET /ad_accounts/{ad_account_id}/campaigns/{campaign_id}

• Added automated and Performance+ campaign properties.
• Now supports client_credentials.

GET /ad_accounts/{ad_account_id}/campaigns/analytics

• Analytics: campaign_id now optional, added aggregate reporting support.

---

Ad Groups

GET /ad_accounts/{ad_account_id}/ad_groups

• Added creative optimization, promotion ID, bid multiplier; expanded age targeting with 19+ and 20+.
• Now supports client_credentials.

PATCH /ad_accounts/{ad_account_id}/ad_groups

• Frequency goal min/max changed (2–20); added creative optimization, promotion ID, bid multiplier, new age buckets.

GET /ad_accounts/{ad_account_id}/ad_groups/{ad_group_id}

• Same new fields as GET.
• Now supports client_credentials.

---

Ads

GET /ad_accounts/{ad_account_id}/ads

• Added new CTAs (e.g., "BUY_TICKETS", "DONATE_NOW", "DOWNLOAD", "PLAY_GAME", "TRY_IT"). Now supports client_credentials.

PATCH /ad_accounts/{ad_account_id}/ads

• Same as above for CTAs and property expansions.

POST /ad_accounts/{ad_account_id}/ads

• Same as above for CTAs and property expansions.

---

Audiences

GET /ad_accounts/{ad_account_id}/audiences

• Added created_by_company_name.
• Now supports client_credentials.

POST /ad_accounts/{ad_account_id}/audiences

• Added created_by_company_name.

POST /ad_accounts/{ad_account_id}/audiences/custom

• Added created_by_company_name.

PATCH /ad_accounts/{ad_account_id}/audiences/ad_accounts/shared

• Added permissions: CATALOGS_VIEWER, FINANCE_EDIT, FINANCE_VIEW.

PATCH /ad_accounts/{ad_account_id}/audiences/businesses/shared

• Added permissions: CATALOGS_VIEWER, FINANCE_EDIT, FINANCE_VIEW.

GET /ad_accounts/{ad_account_id}/audiences/shared/accounts

• Now supports client_credentials.

---

Promotions

POST /ad_accounts/{ad_account_id}/promotions

• New endpoint for promotion creation.

PATCH /ad_accounts/{ad_account_id}/promotions

• New endpoint for updating promotions.

DELETE /ad_accounts/{ad_account_id}/promotions/{promotion_id}

• New endpoint for deleting promotions.

GET /ad_accounts/{ad_account_id}/promotions/{promotion_id}

• New endpoint for retrieving promotion details.

---

Conversion Tags

GET /ad_accounts/{ad_account_id}/conversion_tags

• Added support for external measurement ID.
• Now supports client_credentials.

POST /ad_accounts/{ad_account_id}/conversion_tags

• Added support for external measurement ID.

GET /ad_accounts/{ad_account_id}/conversion_tags/{conversion_tag_id}

• Added support for external measurement ID.
• Now supports client_credentials.

---

Catalogs & Product Groups

POST /catalogs/products/get_by_product_group_filters

• Expanded filtering with new custom label operators/types.
• Removed media_type from product pin media.

GET /catalogs/feeds

• Now under catalog_feeds API tag; improved error/warning reporting.

POST /catalogs/feeds

• Now under catalog_feeds, improved handling of warnings/errors.

PATCH /catalogs/feeds/{feed_id}

• Now under catalog_feeds tag, expanded warnings.

DELETE /catalogs/feeds/{feed_id}

• Now under catalog_feeds tag.

POST /catalogs/feeds/{feed_id}/ingest

• Now under catalog_feeds tag.

GET /catalogs/feeds/{feed_id}

• Now under catalog_feeds tag.

GET /catalogs/feeds/{feed_id}/processing_results

• Now under catalog_feeds tag.

---

Miscellaneous

GET /businesses/{business_id}/members/{member_id}/assets

• Added CATALOG asset type, added catalog IDs in response.

GET /businesses/{business_id}/partners/{partner_id}/assets

• Same as above.

PATCH /businesses/{business_id}/partners/assets

• Permissions: added CATALOGS_VIEWER, FINANCE_EDIT, FINANCE_VIEW.

POST /businesses/{business_id}/requests/assets/access

• Permissions: added CATALOGS_VIEWER, FINANCE_EDIT, FINANCE_VIEW.

---

Full Changelog: v5.14.0...v5.15.0

v5.14.0

What's Changed

• v5.14.0 release by @suihanki in #20
• New tags advanced_auction, audience_sharing
• Removed deprecated product_groups tag/endpoints
• "Get ad analytics" now supports a list of Pin ids for filtering
• Numerous documentation/link updates to support our new docs UI on https://developers.pinterest.com/docs
• New endpoints
  • List received audiences for a business
  • List accounts with access to an audience owned by an ad account
  • Update audience sharing between ad accounts
  • Update audience sharing from an ad account to businesses
  • List accounts with access to an audience owned by a business
  • Update audience sharing from a business to ad accounts
  • Update audience sharing between businesses
  • Create a new asset group
  • Update asset groups
  • Create lead forms
  • Update lead forms
  • Create a request to export leads collected from a lead ad
  • Get the lead export from the lead export create call
  • Get item bid options (POST)
  • Operate on item level bid options
  • Create catalog

Full Changelog: v5.13.0...v5.14.0