Bulk editor

The bulk editor tool makes it easier to create and edit Promoted Pins if you want to promote and optimize many Pins at once. To use the bulk editor, hover over Ads in the navigation bar and select Bulk editor in the dropdown, or go directly to https://ads.pinterest.com/bulk_editor/.  

How to use the bulk editor
Tips for using the bulk editor
Protected boards
Targeting codes
Troubleshooting bulk editor error messages

How to use the bulk editor 
  1. Access the bulk editor by selecting “Bulk editor” in the Ads dropdown in the navigation bar, or go directly to https://ads.pinterest.com/bulk_editor/

  2. Download the template

    • Select “Download existing campaigns” for a sheet with your data.

    • Select “Download sample sheet” for a blank template with sample data. You can use this as a reference for how to format your own data.

  3. Fill out the necessary fields – use the descriptions in row 2 or the sample sheet as guidance, and refer to the tips in the sections below.

    • Creating new entities - to create new entities (campaigns, ad groups, Promoted Pins or keywords) add a new row and specify “Create” as the desired action in column A.

      • When creating objects, leave the object IDs blank, as these haven’t been created yet.

      • If you’re creating a new object within an existing campaign or ad group, make sure you specify the ID of the campaign or ad group you’re adding the object to. If you do not specify the parent ID, we will infer the parent via locality (i.e. looking at the sheet structure, we’ll infer the parent of the entity you’re adding is the one your new row is nested under)

    • Editing existing entities - in the data you’ve exported, designate the “Edit” action in column A for the rows you want to modify. You can use the bulk editor to make any changes you would do in the Ads Manager UI.

  4. Upload your bulk template and images (if you’re creating new Pins).

    • Preview your changes - Click on the “Preview” button and you’ll see a summary table of how many entities you’re creating and how many you’re editing. You can cancel or process your template.

    • Process your changes - Click on the “Process” button and your bulk sheet and any images you’re using will immediately be processed with no intermediary preview step.

  5. Confirm your template was successfully uploaded by viewing your change history. The “History of changes” table will keep uploads for 30 days and downloads for 1 day.

    • If the status of the upload switches to “Succeeded”, your sheet was processed without any errors.

    • If the status shows “Errors”, download the results and view the “Status” (column AN) to see what changes need to be made. Simply make your changes and re-upload – we’ll ignore any rows without an “Action” designated (column A)


Get more details, diagrams, tips and tricks in the Bulk Editor guide.  

Campaign structure
  • Learn more about a campaign structure here and the attributes of campaigns here.

  • The fields in the bulk templates all have help text right under the column names to help guide you in filling out your sheets.

  • If you want to add a new ad group or Promoted Pin to an existing campaign, simply reference the parent ID in the bulk template you’re editing, and leave the other fields for that parent object blank. E.g. reference your campaign ID when adding an ad group; reference your ad group ID when adding a keyword or Promoted Pin.

  • Keep in mind that your budgets and bids will run in your account currency, e.g. if your business is in the US, you will run and be charged in USD.

Bulk sheet formatting
  • Do not change the contents of rows 1 and 2 (field name and help text) in the bulk template – the bulk sheet will not successfully upload if the field names have been modified or if row 2 is missing.  Do not delete or change the order of any columns.

  • Save your Excel file using the CSV UTF-8 file format to ensure all of the values in your template are properly formatted.

  • If you already have existing Promoted Pins running, you can download all your data to take a look at how the spreadsheet is formatted.

  • Using the new version of the bulk editor, you can remove the values for spend caps and ad group end dates by replacing existing values with: CLEAR

Campaign setup
  • When creating new objects, set your Statuses to Active if you’re ready to go live, but remember, your Promoted Pins will still need to be reviewed

  • Enter campaign dates as [YYYY-MM-DD] – the brackets will prevent the date from getting reformatted

  • Promoted Pin creation:

    • To use a Pin that’s already saved on your profile: Copy and paste the organic Pin ID, prefaced with the letter ‘P’ (e.g. P580682945675999524), and leave the Pin description and organic Pin URL fields blank. You can find your organic Pin IDs in the URL of the Pin you want to use (e.g. https://www.pinterest.com/pin/580682945675999524/). Include a Promoted Pin URL if you want to track this Promoted Pin separately, or if this Promoted Pin has a different landing page. If you leave the Promoted Pin URL blank, we’ll default to the existing organic Pin URL.

    • To create brand new Pins to promote: In the bulk template, reference file names of the images you’ll upload (be sure to include the extension, e.g. test_image.png). Also fill out the template with a Pin description (required), organic Pin URL (the destination URL for the organic pin, required), Promoted Pin name (optional) and Promoted Pin URL (where the Promoted Pin will drive to, if you want to add specific tracking parameters; if you leave the Promoted Pin URL blank, we’ll default to the organic Pin URL)

  • To create multiple Pins in a campaign, just copy and paste the same campaign and ad group info for all Pins within that campaign

  • Learn more about your different targeting options and the best practices for applying targeting here.

  • Keyword targeting (for the NEW version of the bulk editor only)

    • To add new keywords, you need to “create” new keywords. Each keyword should have its own row.

    • You can assign keyword-level bids – if this is left blank, we’ll use the bid set at the ad group level.

    • If keywords are being added to an existing ad group, be sure to specify the ad group ID

    • Other targeting details (e.g. interest, devices, gender, etc) are still defined at the ad group level.

  • Find the targeting codes you can use in your bulk sheet at the bottom of this article, here.

  • Keep in mind: for any comma separated lists (e.g. interests, keywords, locations), please make sure to enclose your lists with brackets. For example, interests: [exotic pets,insects,mammals,cute animals] or locations: [662,525,124522,826047]


Get more details, tips, and tricks in the Bulk Editor guide.  

Protected boards

Pins created using the bulk editor are automatically added to protected boards. A new protected board is created every time the bulk editor is used; you cannot bulk create Pins to existing boards.

Protected boards do not live publicly on your profile, so Pinners won’t be able to find the protected board unless they have the URL. Protected boards live in a specific section on your profile, which only you can see, and you can Pin to them as you would any other board.

Protected boards are named by default and will appear as: Created by Ads Bulk Editor date/time. You can rename the protected boards created, edit the board description and change the board category to reflect the content of the Pins on these boards.

Targeting codes
Interest codes Interest codes
Location codes Location codes
Language codes Language codes
Device codes Device codes
Audience codes Audience codes

Below is a list of common error codes and how to update your sheet.

Error 1559: Invalid UTC start date, start date should be before the end date and after today’s date. Check to make sure you have a indicated a start date in the future, but before the end date.

Error 1569: Invalid placement. You cannot edit the placement of a campaign once it’s been created. If you’d like to test additional placements, you can duplicate the existing campaign and update the placement.

Error 1619: Organic pin promotion image, description or URL is missing. You are trying to create a new Pin, but are missing one of the three required fields to create a new Pin. Check to make sure that you’ve included an image file, description and landing page for the new Pin.

Error 1622: Duplicate keywords found under the same parent entity. Please remove all duplicates. You have the same keywords and the same match types within a single campaign or ad group. The first instance of this will be created; you will need to remove the duplicates from the sheet.

Error 2009: This row is missing information. A name or ID column must be filled in. You are either creating a campaign that doesn’t have a name, or you are trying to edit a campaign or ad group without specifying the ID of the campaign or ad group you are trying to edit.

Error 2016: Unable to find a parent row. Download the create template to see an example file layout. Address the errors in the parent row. This error typically occurs because there was an issue creating the parent.  

Error 2016: Unable to find a parent row. If this is a campaign keyword the match type should start with CAMPAIGN. E.g. CAMPAIGN_NEGATIVE_PHRASE The incorrect match types were used for campaign-level keywords. You can only add negative keywords at the campaign level. To do so, specify ‘CAMPAIGN_NEGATIVE_PHRASE’ or ‘CAMPAIGN_NEGATIVE_EXACT’.

Error 2017: Column has an invalid value - Invalid entity ID. The formatting for an ID column is incorrect. Most commonly, this means you are missing the prefix for each ID. Use ‘C’ to specify campaign, ‘AG’ to specify ad group, ‘KW’ to specify keyword, ‘P’ to specify an organic Pin ID, ‘PP’ to specify a Promoted Pin ID and ‘COL’ to specify a campaign order line. Refer to row 2 in the bulk sheet for proper formatting.

Error 2017: Column ‘Interests’ has an invalid value. You have uploaded a list of interests that are not formatted properly. Please refer to row 2 in the bulk sheet for proper formatting.

Error 2017: Invalid value - Pin could not be created. An Image, Pin Description and Organic Pin URL must be provided. Make sure the image file name you upload matches the image file name set in your csv. You are trying to create a new Pin, but are missing one of the three required fields to create a new Pin. Check to make sure that you’ve included an image file, description and landing page for the new Pin. Make sure the image file name you upload matches the image file name specified in your bulk sheet.

Error 2017: Column "Existing Pin ID" has an invalid value - Pin is not promotable. Check to make sure that your Pin can be promoted. Make sure the organic Pin has a destination URL, it’s on a public or protected board (you cannot promote from secret boards) and is owned by you.

Error 2017: Column “Promoted Pin Status” has an invalid value - ‘ARCHIVED’. To archive an object (Promoted Pin, ad group or campaign), you must specify ‘Archive’ as the action to take in Column A. You will not be able to archive an object by changing the status of the object.

Error 2017: Column "Promoted Pin URL" has an invalid value - Invalid URL provided. Please check your Promoted Pin URL - it may have spaces or incorrect formatting which need to be updated.  

Error 2018: An error occurred. Upload again and retry. We’re experiencing an error on the backend. Please try uploading the file at a later time. If you continue to experience issues, please contact us at: https://help.pinterest.com/en/contact.

Error 2019: There is an error in one of the parents. Fix those errors and upload this file again. The parent object was not successfully created, so we can’t create or update the objects nested within it. For example, if there is an error with the campaign (parent), we can’t create the ad group underneath the campaign. Check the error messages for the parent object and address that first.

Error 2020: Column has invalid characters. Only UTF8 values are allowed. Excel is reformatting your text. Try saving the file as a ‘CSV UTF-8’ file and try uploading the file again.

Error 2033: The row contains fields from multiple entities. Please include fields from only one entity: campaign, ad group, pin promotion or keyword. You have filled out columns that don’t belong to the object you’re trying to create or edit. In this instance, each row represents a different object (campaign, ad group, Pin or keyword), and the bulk sheet reflects a nested structure, with Pins and keywords under ad groups, and ad groups under campaigns. Check to make sure the columns you have filled out are applicable only to the object in the row you are creating.

Error 2038: This row was not processed. Make sure that you have an update on this row. This error appears when you have specified an ‘Edit’ or ‘Create’ action in column A, but haven’t filled out the columns to create anything, or made any edits in the existing workbook.

Error 2044: A keywords with the same value and match type already exists. Please re-download your sheet. You are uploading new keywords and match types that already exist in your current ad groups or campaigns. While there are no duplicates in your bulk sheet, you will not be able to create what you already have in your current set up.

Error 12: An unknown error occurred processing this row. Check your account to verify this action. This error may occur more commonly with large files. Please try uploading the file at a later time.