Contextual category pricing and rates

During the contextual data pricing and logic integration process, you will create the data elements from your taxonomy and assign them to your contextual categories in the platform. See also Contextual data integration.

IMPORTANT: Before you can implement your pricing and logic into The Trade Desk platform, you must have a contextual data taxonomy approved by The Trade Desk Data Partnerships team.

Workflow diagram

The following diagram illustrates the process outlined in the next section, which also includes links to the respective step-by-step instructions and provides additional guidance on the decisions you might need to make along the way.

Integration workflow

The following table outlines the process step by step, while the diagram in the preceding section illustrates the decision-making workflow.

Create a data element

To enable advertisers in The Trade Desk platform to use your contextual data for targeting, you must create data elements for the contextual categories you plan to onboard.

Here's what you need to know about creating data elements:

• After you create an element, you cannot modify it.
• The ChargeGroupId field must contain the ID for your brand. To retrieve this ID, use the POST /v3/contextualdata/{providerId}/chargegroup/query endpoint.
• You must assign the same pre-bid tactic that you specified for the data element in your taxonomy.
• There are two parent elements that you can use that determine how your categories are labeled in the platform, one for standard and another for custom.
• Data element names must be unique.
• You cannot delete a data element after you create it.
• To create a data element that is not listed in your taxonomy, you must first contact your Data Partnerships Manager for approval.

To create a data element (charge), use the POST /v3/contextualdata/{providerId}/charge endpoint with all appropriate IDs.

{
  "BrandId": "br-ctx",
  "ChargeGroupId": "br_charge_all",
  "Name": "YourBrand standard contextual Flights",
  "Description": "for standard categories",
  "ParentElementId": 1234,
  "Tactic": "ContextualCategory"
}

A successful response returns the ProviderElementId value, which is the ID that advertisers will use to implement your data in their targeting strategies.

{
  "BrandId": "br-ctx",
  "ChargeGroupId": "br_charge_all",
  "Name": "YourBrand standard contextual Flights",
  "Description": "for standard categories",
  "ParentElementId": 1234,
  "Tactic": "ContextualCategory",
  "ProviderElementId": 123
}

After you have created all your data elements, use the provider element IDs to assign rates to them.

Assign rates to data elements

Creating a new data element and rate always requires approval by The Trade Desk Data Partnerships team. Updating the following types of rates requires approval by The Trade Desk Data Partnerships team before new data rates can take effect:

• Extreme rates that may result in very expensive categories or vice versa near 0% of media cost and/or $0 CPM cap, regardless of the rate level.
• If you exceed the update limit, you will receive an error message with the date when you can retry sending the batch.

For details about these requirements, contact your Data Partnerships Manager.

Create a data rate batch

To specify how much you want to charge advertisers to use your contextual data, you need to assign rates to your data elements in a batch request.

Here’s what you need to know about assigning rates to data elements:

• Be sure to have all your data elements created.
• You can include multiple data elements and assign rates to them in a single batch request.
• Rates must be assigned as hybrid rates that use a percentage of media cost with a maximum CPM cap.
• You must assign a rate to each data element that you created.
• A batch can include a maximum of 5000 rates.

To assign rates to your data elements, in a POST /v3/datarate/batch call, for each data element you created, include a DataRates object with the appropriate IDs and rate information.

{
  "ProviderId": "Your provider ID",
  "DataRates": [
    {
      "ProviderElementId": "2130",
      "BrandId": "br-ctx",
      "RateLevel": "System",
      "RateType": "Hybrid",
      "PercentOfMediaCostRate": 0.25,
      "CPMRate": {
        "Amount": 1.25,
        "CurrencyCode": "USD"
      }
    },
    {
      "ProviderElementId": "2132",
      "BrandId": "br-ctx",
      "RateLevel": "Partner",
      "PartnerId": "partnerXYZ",
      "RateType": "Hybrid",
      "PercentOfMediaCostRate": 0.10,
      "CPMRate": {
        "Amount": 0.50,
        "CurrencyCode": "USD"
      }
    },
    {
      "ProviderElementId": "2133",
      "BrandId": "br-ctx",
      "RateLevel": "Advertiser",
      "AdvertiserId": "advertiserXYZ",
      "RateType": "Hybrid",
      "PercentOfMediaCostRate": 0.11,
      "CPMRate": {
        "Amount": 0.75,
        "CurrencyCode": "USD"
      }
    }
  ]
}

After submission, data rate batches are assigned a batch ID and are queued for processing and approval, for a fixed period of time, known as the processing queue eligibility period. For details on approval criteria, see Data rate approval criteria. If you need help with reviews and approvals, contact your Data Partnerships Manager.

Rate processing queue eligibility period

After submission using the POST /v3/datarate/batch endpoint, a data rate batch (identified by its BatchId value) becomes eligible for processing after 24 hours for standard categories and 2 hours for custom categories.

Here's what you need to know about the processing queue eligibility period:

• This time window is fixed and cannot be shortened.
• You can check the processing date in the EstimatedProcessAtUtc field of the response.

To check the processing of your data rate batch, in a GET /v3/datarate/batch/{batchId} call, include the BatchId value returned in the response from the POST /v3/datarate/batch request.

After your batch of data rates is done processing, create your standard or custom contextual categories.

Assign a category to a data element

IMPORTANT: To assign categories to your data elements for pricing, you must first get your rates approved by The Trade Desk Data Partnerships team. Then, depending on whether you plan to make your data available to all buyers in the platform or only selected ones, you must create your custom or standard categories.

After you’ve created your contextual categories, you must assign them to the appropriate data elements.

Here's what you need to know about assigning categories to data elements:

• Be sure to assign the correct category type based on the custom or standard parent element that you assigned.
• If you re-assign a category to a different element, you will remove it from its original assigned data element.
• The Trade Desk recommends assigning multiple categories to a single data element whenever possible.
• You can assign multiple categories to a single data element. For example, if you want to assign the same price to multiple categories, add those categories to a single data element.

To assign a category to a data element, in a POST /v3/contextualdata/{providerId}/categorycharge call, include your brand ID, the ID of the category you want to assign, and the ID of the data element.

{
  "BrandId": "br-ctx",
  "CategoryId": "br_214m",
  "ProviderElementId": -123
}

Manage data elements and charges

After you set up and create your data elements, rates, and category charges, you might need to retrieve the data element or charge details to update them.

Data rate update considerations

You can create or update data rates by submitting them in batches using the third-party data rate Platform APIs.

Here’s what you need to know about updating data rates:

• Rate update batches are sent for a combination of provider and brand IDs.
• Each batch can include one rate update or many, and the request can include updates across rate levels.
• For each rate level, send rate updates in as few batches as possible.
• After a batch has been processed and approved, the rates take effect at 00:00 UTC after the processing queue eligibility period.

Retrieve a list of parent elements

To retrieve a list of parent element IDs, use the GET /v3/contextualdata/{providerId}/parentelementid endpoint.

A successful response returns a list of parent elements that specify the type of categories for which they are used.

{
  "Result": [
    {
      "BrandId": "br-ctx",
      "ParentElementId": -101,
      "Name": "brand standard categories",
      "Description": "for standard categories"
    },
    {
      "BrandId": "br-ctx",
      "ParentElementId": -102,
      "Name": "brand custom categories",
      "Description": "for custom categories"
    }
  ],
  "ResultCount": 2
}

Data rate approval criteria

After a data rate batch is submitted, the The Trade Desk Data Partnerships team reviews it for processing. The following table describes various rate types and their approval criteria.

NOTE: When the CPM or rate set exceeds the minimum requirements, approval is granted automatically, except in the case of rate changes for syndicated taxonomies.

If you have questions about rate approvals, contact your Data Partnerships Representative.

FAQs

The following is a list of commonly asked questions about charging for your contextual categories.

Can I modify or change a data element?

After you create an element, you cannot modify it.

Can I make all my contextual categories available only to specific partners or advertisers?

No. Since you cannot assign standard categories to partners, your categories will be available to advertisers on our platform with the exception of custom categories that you can individually assign to specific partners or advertisers.

Can I create my contextual categories before the data elements and rates?

No. Due to the approval process, you must create your data elements and rates before you can create your contextual categories.

How do I retrieve a charge-all group ID?

To retrieve your charge-all group ID, use the POST /v3/contextualdata/{providerId}/chargegroup/query endpoint.

Can I assign more than one category to an element?

Yes. The Trade Desk recommends assigning multiple categories to a data element whenever possible.

Can I assign a category to more than one data element?

No. If you assign a category to a different element, you will remove it from its original data element.

What happens after my integration enters closed beta?

The following table summarizes each release period.

Can I set custom pricing for specific advertisers and agencies?

Yes, however, this pricing must first be approved by The Trade Desk. To set custom pricing, use the POST /v3/datarate/batch, set the RateLevel value to either Partner or Advertiser and include the appropriate advertiser or partner ID.

Can I assign a different pre-bid tactic from the one in the taxonomy?

No. If you assign a different pre-bid tactic, you will receive an error.