PlacementService provides operations for managing placements.

• Operations
• WSDL (sandbox)
• WSDL (production)
• About Placements
• Manage Placements

About Placements

A placement contains ad placement details for available ad space. It includes the placement start and end dates, price settings for the preferred buying type (guaranteed or non-guaranteed delivery), ad attributes (such as ad size IDs, ad delivery mode IDs, ad behavior IDs, and ad format ID), ad optimization settings, ad linking settings (for guaranteed delivery only), content targeting attributes (such as site structure settings or content topics, content types, custom content categories, sections, and/or sites), audience targeting attributes (targeting profile), inventory search filter (for guaranteed delivery only), delivery pacing, placement discounts (if any), and pixels.

Understanding Placement Statuses

Manage Placements

PlacementService provides operations for adding, copying, updating, retrieving, stopping, and deleting placements.

Add Placements

To add a placement, use the addPlacement operation and to add a list of placements, use the addPlacements operation.

Copy Placements

To copy a placement (specified by ID) to an order (specified by ID), use the copyPlacement operation and to copy multiple placements (specified by IDs) to an order (specified by ID), use the copyPlacements operation.

Note: When you create a copy of a placement:

• The new placement will inherit the name of the original placement with a number appended to the name.
• The new placement will inherit the original placement's content and audience targeting attributes and all other settings including the ads, discounts, pixels, and comments.

Update Placements

To update a placement, use the updatePlacement operation and to update a list of placements, use the updatePlacements operation. You can update a placement when the order (that the placement is associated with) is in Proposal, PendingApproval, PendingCommittal, Committed, or Running statuses.

When you update a placement, if the placement is:

• In Proposal state, the update operation will update the placement and keep it in Proposal state.
• In PendingApproval state, the update operation will update the placement, revert its status to Proposal, and cancel all existing placement level approval tasks.
• In Rejected state, the update operation will update the placement and revert its status to Proposal.
• In Pending state with:
  • Guaranteed buying type, the update operation will change its status to RevisedPending and create a new version of the placement (revision) in Proposal state. The new placement will be updated and returned (with the original placement details) for approval. If the new placement is:
    • Rejected, the rejected placement can be updated and re-submitted for approval. The original placement will be in RevisedPending state until the rejected new placement is deleted.
    • Canceled, the original placement will return to Pending state. However, if the start date has been reached, the original placement will have a status of Active.
    • Deleted, the original placement will return to Pending state and will not require approvals.
    • Approved, the original placement (in RevisedPending state) will be deleted and the new placement will take a status of Pending until the order is approved.
  • Non-guaranteed buying type, the update operation will update the placement.
  If the original placement is canceled (when the new placement is in Proposal or PendingApproval state), all approvals for the placement and order will also be canceled.
• In Expired state, the update operation will update the placement and revert its status to Proposal.
• In Committed state with:
  • Guaranteed buying type, the update operation will change its status to RevisedCommitted and create a new version of the placement (revision) in Proposal state. The new placement will be updated and returned (with the original placement details) for approval. If the new placement is:
    • Rejected, the rejected placement can be updated and re-submitted for approval. The original placement will be in RevisedCommitted state until the rejected new placement is deleted.
    • Canceled, the original placement will return to Committed state. However, if the start date has been reached, the original placement will have a status of Active.
    • Deleted, the original placement will return to Pending state and will not require approvals.
    • Approved, the original placement (in RevisedCommitted state) will be deleted and the new placement will take a status of Pending until the order is approved.
  • Non-guaranteed buying type, the update operation will update the placement.
  If the original placement is canceled (when the new placement is in Proposal or PendingApproval state), all approvals for the placement and order will also be canceled.

Note: There can be only one instance of a revision at a time. You cannot create two revision proposals for the same placement at the same time.

To update the name of a placement (specified by ID), use the updatePlacementName operation. The status of the placement determines how you access the placement for updating. If the placement has a status of:

• Proposal, you can update the placement directly.
• Active or Committed, you must stop and transfer the placement before you can update the placement.
• Pending, PendingApproval, or Rejected, you must revise the placement.

Stop and Transfer Placements

To modify a running order, stop the active placement, make a copy of the placement, and edit that placement. When you stop and transfer a placement, all of the information in the original placement is copied over to the new placement.

To stop a placement (specified by ID) and create a copy of the placement, use the stopAndTransferPlacement operation and to stop multiple placements (specified by IDs) and create copies of the (stopped) placements, use the stopAndTransferPlacements operation.

Note: When you create copies of multiple placements, the new placements will inherit the names of the original placements with a number appended to the name.

To copy the ads (as well) assigned to the placement, set the value for the boolean parameter, transferAds, to true. You can, alternatively, use the copyAllAds operation in AdService to copy the ads to the new placement.

Note: You can stop and transfer an active or committed placement. When you stop a placement, you release the inventory booked for the placement. The new placement's:

• status will be set to Proposal.
• startDate will be set to the date the placement was transferred.
• impressionGoal will reflect the difference between the impression goal in the original placement and the number of impressions delivered (via the original placement).
• price will reflect the remainder of the price amount from the original placement.
• Ad level flight dates will adopt the placement start and end dates.

Stop Placements

To stop an active placement (specified by ID), use the stopPlacement operation and to stop multiple active placements (specified by IDs), use the stopPlacements operation.

Note: When you stop an active or committed placement, the placement will stop serving and you cannot perform further actions on the placement. The placement's:

• impressionGoal will reflect the number of impressions delivered.
• price will reflect the amount spent for the placement.
• endDate will be set to the date the placement was stopped.

Pause and Resume Placements

To temporarily suspend serving of ads, you can pause a placement in Active or Committed state. You can stop or stop and transfer a paused placement. When you pause a placement:

• The ad serving dates and placement (start and end) dates are not affected.
• The inventory remains reserved until the placement resumes.

To pause a placement (specified by ID), use the pausePlacement operation and to pause multiple placements (specified by IDs), use the pausePlacements operation.

To resume ad serving, resume the placement. To resume a paused placement (specified by ID), use the resumePlacement operation and to resume multiple placements (specified by IDs), use the resumePlacements operation. When you resume a placement, the placement transitions to:

• Committed state if the placement start date is in the future.
• Active state if the placement start date has been reached.
• Stopped state if the:
  • Placement:
    • Has been stopped.
    • Has been Stopped/Transferred.
  • Order has been canceled.
• Complete state if the placement end date has been reached.

Delete Placements

To delete a placement, use the deletePlacement operation and to delete a list of placements, use the deletePlacements operation.

You can only delete a placement in Proposal, PendingApproval, or Rejected state.

Note: You can delete a new version of a (revised) placement when the placement is in Proposal, PendingApproval, or Rejected state. If you delete the new version of a placement, the original placement (in Revised state) will revert to Pending state and no approval will be required for the original placement.

When you delete a placement, the placement's:

• Unused budget is released to the available budget for the order.
• Reserved inventory is released.

Retrieve Placements

To retrieve a placement (specified by ID), use the getPlacement operation and to retrieve a list of placements (specified by IDs), use the getPlacements operation. To retrieve details (including discounts, pixel, and audience targeting preferences) for a placement (specified by ID), use the getPlacementDetail operation and to retrieve details for multiple placements (specified by IDs), use the getPlacementDetails operation.

To retrieve a count of the placements in an order (specified by ID), use the getPlacementCountByOrderID operation and to retrieve a count of the placements in specific statuses in an order (specified by ID), use the getPlacementCountByOrderIDByStatuses operation. To retrieve the placements in an order, use the getPlacementsByOrderID operation and to retrieve the placements in specific statuses in an order, use the getPlacementsByOrderIDByStatuses operation. To retrieve the details (including discounts, pixel, and audience targeting preferences) on the placements in an order (specified by ID), use the getPlacementDetailsByOrderID operation and to retrieve the details on the placements in specific statuses in an order (specified by ID), use the getPlacementDetailsByOrderIDByStatuses operation.

To retrieve the placements, in specified statuses, to which an ad (specified by its ID in the ad library) has been assigned, use the getPlacementsByLibraryAdIDByStatuses operation.

Retrieve Placements From (Legacy) Ad Group(s)

To retrieve the IDs of placements from a legacy ad group (specified by ID), use the getPlacementIDsByAdGroupID operation. To retrieve the ID of the (legacy) ad group that a placement (specified by ID) belonged to, use the getLegacyAdGroupIDByPlacementID operation.

Retrieve Inventory for Placement

To retrieve the inventory available for a placement, use the updateInventoryForPlacement operation and to retrieve inventory available for a list of placements, use the updateInventoryForPlacements operation.

Manage Discounts

To set discounts for a placement (specified by ID), use the setPlacementDiscounts operation. You can set discounts for placements in Proposal, Pending, PendingApproval, Rejected and Committed statuses. To retrieve the discounts for a placement (specified by ID), use the getPlacementDiscounts operation.

Manage Pixels

To set the pixel (specified by ID) for a placement (specified by ID), use the setPlacementPixel operation. To retrieve pixel associated with a placement (specified by ID), use the getPlacementPixel operation. To delete pixel (code) associated with a placement (specified by ID), use the deletePixelFromPlacement operation.

Note: Use the operations in PixelService to create and manage pixels.

Manage Placement Targeting Preferences

You can:

• Manage audience targeting preferences
• Manage content targeting preferences
• Manage ad attributes
• Retrieve placement targeting details

Manage Audience Targeting Preferences
Placement audience targeting preferences are saved as a targeting profile using TargetingProfileService API. Use the operations in TargetingProfileService to create and manage the audience targeting preferences for a placement. You can set audience targeting attributes to placement when placement is in Proposal, Revised, or Rejected states.

To set the audience targeting profiles (specified by IDs) for a placement (specified by ID), use the setAudienceTargetingProfiles operation.

To exclude certain types of audience from your ad campaign (negative targeting), set the isExcluded boolean parameter value for the audience targeting attribute (in your targeting profile) to true.

Note: You cannot define the same targeting attributes using multiple targeting profiles. When assigning targeting profiles to a placement, please ensure that each targeting profile has a unique set of targeting attributes.

To retrieve the audience targeting profiles associated with a placement (specified by ID), use the getPlacementAudienceTargetingProfiles operation.

To remove the association between a placement (specified by ID) and one or more audience targeting profiles (specified by IDs), use the unsetPlacementAudienceTargetingProfiles operation. You can unset an audience targeting profile when the placement is in:

• Proposal, PendingApproval, or Rejected state without triggering a revision of the placement.
• Pending or Committed state, but a placement revision will be triggered.

Manage Content Targeting Preferences
You can either target site structure or one or more content topics, content types, custom content categories, sections, and/or sites using your placement settings. To exclude one or more types of inventory from your ad campaign, set the isExcluded boolean parameter value for the content targeting attribute(s) to true.

Manage Ad Attributes
To set the ad attributes (to target) for a placement, use the placement AdAttributes object.

Retrieve Placement Targeting Details

To retrieve the (ad, frequency, content, and audience) targeting attributes associated with a placement (specified by ID), use the getTargetingDetailsByPlacementID operation and to retrieve the targeting details for multiple placements (specified by IDs), use the getTargetingDetailsByPlacementIDs operation.