Migrating Pinterest Ads (v.3) to Pinterest Ads (v.4)


Pinterest Ads recently deployed API v.4, deprecating the previous API version. While Pinterest did say they would deprecate the API, they took it offline without further warning which is why we rushed a hotfix on Friday night. This resulted in changes in the schema which might affect your models.

What Changed

To view all changes, please check out the following Pinterest Ads v.4 release guide.

Change Type Table(s) Comment
Renaming ad_group_pin_promotions => ads

pin_promotion_delivery_metrics remains unaffected

Renaming item_delivery_metrics => product_item_delivery_metrics

report only offers the last 92 days


entity field mapping (i.e., tables like the campaign_delivery_metrics table will not include a campaign_status field anymore and need to be joined instead) 


Action Items

  1. Save your historical data. Due to the 92-day report limit for the product_item_delivery_metrics table, any historical data from that table will be deleted with the new import. To preserve historical data, you have two options:
    • Create an Automation with BigQuery as the destination and export your existing Pinterest data. This old data can then be rejoined with the new data.
    • Add a new Pinterest Ads integration (which will have the updated schema) and keep the old integration for historical data. If you chose this option, please remember to remove the old integration from any orchestration.
  2. Update the schema. According to the option selected in the previous point, there are two ways to update the schema:
    • Refresh the integration schema from the 'Structure' section of the Pinterest Ads integration. Click on 'Reconnect to refresh view' as shown in the screenshot below. Once the schema is refreshed click on 'Import'Screenshot_2022-03-07_at_10.53.25.png
    • Add a new integration (leaving the structure for the old one as is)
  3. Implement the necessary changes in your model(s), according to the updates mentioned in the previous section. This includes but is not limited to:
    • Changing input table(s) for any changed table(s).
    • Joining tables to rebuild denormalized table(s)


  • How will the 92 days import limit for product_item_delivery_metrics affect my reports?
    • Any full import will only catch data from the past 92 days, but subsequent incremental imports will allow you to add new data without losing the oldest ones. In order to avoid losing historical data imported with the previous API version, we suggest setting up an automation that stores your data into a BigQuery table, which can be joined with new data.
  • I'm missing specific table fields. Where do I find those?
    • Due to the deprecation of the entity field mapping, certain fields can only be accessed by being joined back into a denormalized table. For example, to find the campaign_status in the campaign_delivery_metrics, you have to join the campaigns table via the id.


Was this article helpful?
0 out of 0 found this helpful