Reminder: v201702 will be sunset on February 28, 2018.

DFP Sales Manager Rates and Rate Cards

This guide explains what RateCards, BaseRates, and PremiumFeatures are, how to create each in the API, and how to use them with the various Sales Manager objects they support.

Primer

Rate cards and base rates in DFP Sales Manager are objects used for setting pricing information for Product Templates, Products, and Proposal Line Items. Rate cards are also the objects responsible for tying Workflows to Proposals.

Rate Cards

Rate cards are the top-level objects that only contain a few fields, namely the CurrencyCode the rates will be applied in and the teams that have visibility over your Sales Manager objects associated with the rate card.

Base Rates

Base rates have three distinct types:

Each are similar in function, namely that they dictate the pricing information, but for each type of sales trafficking object, you will need a distinct BaseRate object bound to a rate card for each type.

Premium Features

Premium features are pricing adjustments applied to the base rate associated with a rate card. These pricing adjustments are applied based on what targeting and features your product, product template, or product package item contains (e.g. if CustomTargeting is used on a proposal line item, you would apply a price increase as stipulated by the premium value). Premium features can specify adjustments depending on the delivery rate type of the object.

Creating a rate card via the API

To create a rate card, only two fields are required: the name and the currency code.

Java

  // Get the RateCardService.
  RateCardServiceInterface rateCardService =
      dfpServices.get(session, RateCardServiceInterface.class);

  // Create a rate card.
  RateCard rateCard = new RateCard();
  rateCard.setName("RateCard #" + new Random().nextInt(Integer.MAX_VALUE));
  rateCard.setCurrencyCode(currencyCode);
  rateCard.setPricingModel(PricingModel.NET);
    

Python

  # Initialize appropriate service.
  rate_card_service = client.GetService('RateCardService', version='v201705')

  # Create a rate card.
  rate_card = {
      'name': 'RateCard #%d' % random.randint(0, 100000000),
      'currencyCode': CURRENCY_CODE,
      'pricingModel': 'NET',
  }
    

If you have any teams for which you want to restrict visibility, you can do this on the rate card by setting an array of team IDs:

Java

  rateCard.setAppliedTeamIds(teamIds);
    

Python

  rate_card['appliedTeamIds'] = TEAM_IDS
    

Once these fields have been set, create new RateCard objects by invoking createRateCards on an array of rate card objects:

Java

  // Create the rate card on the server.
  RateCard[] rateCards = rateCardService.createRateCards(new RateCard[] {rateCard});
    

Python

  result = rate_card_service.createRateCards([rate_card])
    

Since rate cards are just shell objects that tie together the multiple facets of pricing and cataloging in DFP Sales Manager, the next step is to create base rates for the various objects supported as well as creating feature premiums for price adjustments.

Creating a base rate via the API

You can create three types of base rates: those applied to products, product templates, or product package items.

Java

  // Get the BaseRateService.
  BaseRateServiceInterface baseRateService =
      dfpServices.get(session, BaseRateServiceInterface.class);
  // Create a base rate for a product.
  ProductBaseRate productBaseRate = new ProductBaseRate();
  // Create a base rate for a product template.
  ProductTemplateBaseRate productTemplateBaseRate = new ProductTemplateBaseRate();
  // Create a base rate for a product package item.
  ProductPackageItemBaseRate productPackageItemBaseRate = new ProductPackageItemBaseRate();
    

All three types require you to set the rate card to associate the base rate with, the actual rate, and the associated product, product template, or product package item ID.

For a product:

Java

  // Set the rate card ID that the product base rate belongs to.
  productBaseRate.setRateCardId(rateCardId);

  // Set the product the base rate will be applied to.
  productBaseRate.setProductId(productId);
  
  // Create a rate worth $2 and set that on the product base rate.
  Money rate = new Money();
  rate.setCurrencyCode("USD");
  rate.setMicroAmount(2000000L);
  productBaseRate.setRate(rate);
    

Python

  # Create a product base rate.
  product_base_rate = {
      'xsi_type': 'ProductBaseRate',
      # Set the rate card ID that the product base rate belongs to.
      'rateCardId': rate_card_id,
      # Set the product id the base rate will be applied to.
      'productId': product_id,
      # Set the rate to be $2.
      'rate': {
          'currencyCode': 'USD',
          'microAmount': 2000000
      }
  }
    

For a product template:

Java

  // Set the rate card ID that the product template base rate belongs to.
  productTemplateBaseRate.setRateCardId(rateCardId);

  // Set the product template the base rate will be applied to.
  productTemplateBaseRate.setProductTemplateId(productTemplateId);
  
  // Create a rate worth $2 and set that on the product template base rate.
  Money rate = new Money();
  rate.setCurrencyCode("USD");
  rate.setMicroAmount(2000000L);
  productTemplateBaseRate.setRate(rate);
    

Python

  # Create a product template base rate.
  product_template_base_rate = {
      'xsi_type': 'ProductTemplateBaseRate',
      # Set the rate card ID that the product template base rate belongs to.
      'rateCardId': rate_card_id,
      # Set the product template the base rate will be applied to.
      'productTemplateId': product_template_id,
      # Set the rate to be $2.
      'rate': {
          'currencyCode': 'USD',
          'microAmount': 2000000
      }
  }
    

For a product package item:

Java

  // Set the rate card ID that the product package item base rate belongs to.
  productPackageItemBaseRate.setRateCardId(rateCardId);

  // Set the product package item the base rate will be applied to.
  productPackageItemBaseRate.setProductPackageItemId(productPackageItemId);
  
  // Create a rate worth $2 USD and set that on the product package item base rate.
  Money rate = new Money();
  rate.setCurrencyCode("USD");
  rate.setMicroAmount(2000000L);
  productPackageItemBaseRate.setRate(rate);
    

Python

  # Create a base rate for a product package item.
  product_package_item_base_rate = {
      'xsi_type': 'ProductPackageItemBaseRate',
      # Set the rate card ID that the product package item base rate
      # belongs to.
      'rateCardId': RATE_CARD_ID,
      # Set the product package item the base rate will be applied to.
      'productPackageItemId': PRODUCT_PACKAGE_ITEM_ID,
      # Create a rate worth $2 USD and set that on the product package item
      # base rate.
      'rate': {
          'xsi_type': 'Money',
          'currencyCode': 'USD',
          'microAmount': 2000000,
      }
  }
    

Once the required fields have been set, you can create them in DFP:

Java

      // Create the product base rate on the server.
  BaseRate[] baseRates = baseRateService.createBaseRates(
      new BaseRate[] {productBaseRate});
      // Create the product template base rate on the server.
  BaseRate[] baseRates = baseRateService.createBaseRates(
      new BaseRate[] {productTemplateBaseRate});
      // Create the product package item base rate on the server.
  BaseRate[] baseRates = baseRateService.createBaseRates(new BaseRate[] {
      productPackageItemBaseRate});
    

Python

  # Create the product base rate on the server.
  base_rates = base_rate_service.createBaseRates(
      [product_base_rate])
  # Create the product template item base rate on the server.
  base_rates = base_rate_service.createBaseRates(
      [product_template_base_rate])
  # Create the product package item base rate on the server.
  result = base_rate_service.createBaseRates([product_package_item_base_rate])
    

Creating premium rates for features via the API

To create a premium rate, you need to specify what type of feature you want to modify the rate card with. In the case below, an ad unit premium will be created:

Java

  // Get the PremiumRateService.
  PremiumRateServiceInterface premiumRateService =
      dfpServices.get(session, PremiumRateServiceInterface.class);
  
  PremiumRate premiumRate = new PremiumRate();
  
  // Create an ad unit premium to apply to the rate card.
  AdUnitPremiumFeature adUnitPremiumFeature = new AdUnitPremiumFeature();
    

Python

  # Initialize appropriate services.
  premium_rate_service = client.GetService('PremiumRateService',
                                           version='v201705')

  # Create an ad unit premium to apply to the rate card.
  ad_unit_premium_feature = {
      'xsi_type': 'AdUnitPremiumFeature'
  }
    

On the premium feature, you would create and assign a PremiumRateValue to specify the pricing type, the adjustment size, and the adjustment type, as well as the premium feature to apply the rate value to. When the adjustment type is ABSOLUTE_VALUE the adjustment is done in the units of the currency specified as a microamount:

Java

  // Create a CPM based premium rate value with adjustments in micro amounts.
  // This will adjust a CPM priced proposal line item that has
  // inventory targeting specified by 2 units of the currency associated with
  // the rate card (this comes from absolute value adjustment).
  PremiumRateValue cpmPremiumRateValue = new PremiumRateValue();
  cpmPremiumRateValue.setPremiumFeature(adUnitPremiumFeature);
  cpmPremiumRateValue.setRateType(RateType.CPM);
  cpmPremiumRateValue.setAdjustmentSize(2000000L);
  cpmPremiumRateValue.setAdjustmentType(PremiumAdjustmentType.ABSOLUTE_VALUE);
    

Python

  # Create a CPM based premium rate value with adjustments in micro amounts.
  # This will adjust a CPM priced proposal line item that has
  # inventory targeting specified by 2 units of the currency associated with
  # the rate card (this comes from absolute value adjustment).
  cpm_premium_rate_value = {
      'premiumFeature': ad_unit_premium_feature,
      'rateType': 'CPM',
      'adjustmentSize': 2000000,
      'adjustmentType': 'ABSOLUTE_VALUE'
  }
    

The adjustment can also be of type percentage, as demonstrated when creating a CPC premium rate value:

Java

  // Create a CPC based premium rate value with adjustments in milli amounts.
  // This will adjust a CPC priced proposal line item that has
  // inventory targeting specified by 10% of the cost associated with the rate
  // card (this comes from a percentage adjustment).
  PremiumRateValue cpcPremiumRateValue = new PremiumRateValue();
  cpcPremiumRateValue.setPremiumFeature(adUnitPremiumFeature);
  cpcPremiumRateValue.setRateType(RateType.CPC);
  cpcPremiumRateValue.setAdjustmentSize(10000L);
  cpcPremiumRateValue.setAdjustmentType(PremiumAdjustmentType.PERCENTAGE);
    

Python

  # Create a CPC based premium rate value with adjustments in milli amounts.
  # This will adjust a CPC priced proposal line item that has
  # inventory targeting specified by 10% of the cost associated with the rate
  # card (this comes from a percentage adjustment).
  cpc_premium_rate_value = {
      'premiumFeature': ad_unit_premium_feature,
      'rateType': 'CPC',
      'adjustmentSize': 10000,
      'adjustmentType': 'PERCENTAGE'
  }
    

Once the premium rates have been created and associated with the premium feature, set the following information: rate card, pricing method, any premium features, and all of the premium rate values you’ve created.

Java

  // Associate premium rate with the rate card and set premium information.
  // This premium will apply for proposal line items targeting 'any' ad unit
  // for both CPM and CPC rate types.
  premiumRate.setRateCardId(rateCardId);
  premiumRate.setPricingMethod(PricingMethod.ANY_VALUE);
  premiumRate.setPremiumFeature(adUnitPremiumFeature);
  premiumRate.setPremiumRateValues(new PremiumRateValue[] {
      cpmPremiumRateValue, cpcPremiumRateValue});
    

Python

  # Create premium rate.
  # Associate premium rate with the rate card and set premium information.
  # This premium will apply for proposal line items targeting 'any' ad unit
  # for both CPM and CPC rate types.
  premium_rate = {
      'rateCardId': rate_card_id,
      'pricingMethod': 'ANY_VALUE',
      'premiumFeature': ad_unit_premium_feature,
      'premiumRateValues': [cpc_premium_rate_value, cpm_premium_rate_value]
  }
    

Once you’ve set all the requisite fields, you can create your premium rates on the server:

Java

  PremiumRate[] createdPremiumRates =
      premiumRateService.createPremiumRates(new PremiumRate[] {premiumRate});
    

Python

  # Add premium_rates.
  premium_rates = premium_rate_service.createPremiumRates([premium_rate])
    

Using rate cards, base rates, and premium rates for features

Once you’ve created all of your pricing objects, all subsequent usage will be done by referencing the IDs of the rate cards. The objects that reference rate cards are:

  • ProposalLineItems
  • Products
  • ProductTemplates
  • ProductPackages
  • Packages

Next Steps

Enviar comentarios sobre…

DoubleClick for Publishers
DoubleClick for Publishers
¿Necesitas ayuda? Visita nuestra página de asistencia.