API Workflows

  • Creating a deal involves checking for existing products, creating an order, and then creating a product under that order, recommending storing generated IDs for future retrieval.

  • Cancelling a deal is achieved by updating the order status to Cancelled, which is a final state and cannot be reactivated.

  • Deal details can be obtained by getting information on an order or a specific product, and a list of deals can be retrieved by listing orders or products with relevant filters.

  • Updating a deal allows for changes to publisher contact information at the order level and specific deal terms at the product level, with certain fields being non-updatable and updates to rate details or creative config requiring buyer acceptance.

  • To check if a user has accepted a deal, retrieve the order details and check the status field, or if the order ID is unknown, list products by external deal ID to find the order name and then get the order details.

This guide describes common API workflows for creating, canceling, retrieving, updating, and negotiating deals using the Deal Sync API.

Create a Deal

  1. Check whether a product has already been created by calling LIST products with the externalDealId filter. Note that both camelCase externalDealId and snake_case external_deal_id are supported in the filter string. external_deal_id must be unique across all products.

    GET https://dv360seller.googleapis.com/v1beta1/{parent=exchanges/*/orders/*}/products?filter=externalDealId="{external_deal_id}"

  2. Create Order. The Order Name is generated by DV360, and we recommend storing this ID in your system for future retrieval.

  3. Create Product under Order. The Product Name is generated by DV360, and we recommend storing this ID in your system for future retrieval.

Alternatively, you can call LIST with external_deal_id. The resource Name contains both the Order ID and Product ID, so you can identify the parent Order.

Cancel a Deal

  1. Update Order status to CANCELED. Canceling is only supported if the order hasn't yet been accepted. Canceled is a terminal state; an Order can't be reactivated once canceled. If the Order contained any products, their external_deal_id can't be reused.

Get details of a Deal

  1. Get details of an Order. The status is updated once the user accepts, archives, or cancels the Order.
  2. Get details of a Product.

Get a list of Deals

  1. LIST orders with a status filter to get all accepted or pending acceptance orders.
  2. LIST products with the external_deal_id filter.
  3. LIST all products within an Order.

Update a deal

  1. Update Order for publisher contact information.
    1. name can't be updated (can't be set in the updateMask). Status can only be set to CANCELED using the API.
    2. partner_id can't be updated.
  2. Update Product for a specific deal term update.
    1. name, externalDealId, transactionType, pricingType, and updateTime can't be updated.
    2. Updating displayName doesn't require user re-acceptance.
    3. Updating rateDetails or creativeConfig changes the parent Order status to PENDING_ACCEPTANCE. DV360 advertisers will be asked to accept the new terms on the Negotiations page, regardless of whether the previous Order was already accepted.

Check if the user has accepted the deal

  1. Get Order if you know the corresponding Order Name. Check the status field.
  2. If the Order Name wasn't tracked: List Products with external_deal_id filter, identify Order Name from Product Name, and then call Get Order. Check the status field.

Check if the user has configured the deal (Programmatic Guaranteed only)

  1. Get Inventory Source. The resource name is exchanges/{exchangeId}/inventorysources/{external_deal_id}. Check Buyer Status.
    1. Reservation deals:
      1. BUYER_STATUS_ACTIVE: The deal has been accepted and configured. The deal will begin spending when DV360 receives bid requests that match the deal terms. A line item is auto-generated during deal configuration. See Deal Configuration for details.
      2. BUYER_STATUS_PENDING: The Order has been accepted, but the deal hasn't yet been configured. No spending occurs in this state.
      3. BUYER_STATUS_PAUSED: The deal has been paused by the advertiser. No spending occurs in this state.
    2. Non-reservation deals:
      1. BUYER_STATUS_ACTIVE: The deal has been accepted. The deal will begin spending when DV360 receives matching bid requests, an active line item targets the deal, and bid requests match the line item targeting criteria. See Line Items for details. (Note: There is no Seller API to query whether a deal is targeted by line items).
      2. BUYER_STATUS_PENDING: Not applicable for non-reservation deals.
      3. BUYER_STATUS_PAUSED: The deal has been explicitly paused by the advertiser. No spending occurs in this state.

Pause and unpause a deal after acceptance

  1. Update Inventory Source Seller Status.
    1. Pausing or unpausing doesn't stop deal serving. A seller pausing a deal displays an informational message to advertisers in the DV360 UI to help troubleshoot non-spending deals.

Renegotiation (updating a deal after acceptance)

Renegotiation refers to updates made to a deal after it has been accepted by the buyer. This allows exchanges and buyers to adjust terms on existing deals. For example, an exchange may find that the flight end time for an accepted deal is incorrect; the exchange can use Product Patch to push updates to DV360 buyers before the deal begins serving.

Allowed and disallowed changes

See the Display & Video 360 Help Center articles for a full breakdown of deal negotiations and renegotiation rules:

Previous
Entity Structure
Next
Beta Process