API Workflows

Create a Deal

  1. See if a product has already been created by LIST products with external_deal_id filter. 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. Name is generated by DV3, and we recommend you store this Id somewhere in your system for future retrieval.

  3. Create Product under Order. Product name is generated by DV3, and we recommend you store this Id somewhere in your system for future retrieval.

    Alternatively you can always do LIST with external_deal_id. The name field contains both Order Id and Product Id, so you can easily identify the parent in this way.

Cancel a Deal

  1. Update Order status to Cancelled Only Supports Canncel if the order has not been accepted. Cancelled is a final state. Cannot re-activate the Order once cancelled.

Get details of a Deal

  1. Get details of an order. The status gets updated once the user Accept, Archive or Cancel the Order.
  2. Get details of Product.

Get a list of Deals

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

Update a deal

  1. Update Order for Publisher contact information.
    1. name, does not allow update(cannot be set in the field_mask). Status only allow to be set to Canceled via API.
    2. partner_id does not allow update.
  2. Update Product for a specific deal term update.
    1. name, externalDealId, transactionType, pricingType, updateTime cannot be updated.
    2. Update displayName does not require user acceptance.
    3. Update rateDetails, creativeConfig will make the change parent Order status to Pending Acceptance. DV3 advertisers will be asked to accept the new term in the negotiation page, regardless of whether the previous Order was accepted or not.

See if user has accepted the deal

  1. Get Order if you know the corresponding order id. Check the status field.
  2. If order id was not tracked: List Products with external_deal_id filter, figure out order name from product name, and then Get Order. Check the status field.

See if user has configured(Only for PG) the deal

  1. Get Inventory Source. The name is ‘exchanges/{exchangeId}/inventorysources/{external_deal_id}’. Check Buyer Status.
    1. Reservation deals
      1. BUYER_STATUS_ACTIVE means a deal has been accepted & configured. Deal is expected to be spending in this state when DV3 receives bid request that matches the deal terms. A line item is auto generated during Deal Configuration step. See Deal Configuration for more details.
      2. BUYER_STATUS_PENDINGmeans Order has been accepted, but deal has not yet been configured. No spending will happen in this state.
      3. BUYER_STATUS_PAUSEDmeans Deal has been explicitly paused by advertisers. No spending will happen in this state.
    2. Non Reservation deals
      1. BUYER_STATUS_ACTIVE means a deal has been accepted. Deal is expected to be spending in this state when DV3 receives bid request that matches the deal terms AND there is an Active line item targeting this deal AND the bid request matches the line item targeting criterias. See line item for more details.** There is NO Seller API to query for whether a deal has been targeted by line items. **
      2. BUYER_STATUS_PENDINGnot applicable.
      3. BUYER_STATUS_PAUSEDmeans Deal has been explicitly paused by advertisers. No spending will happen in this state.

Pause/Unpause a deal after acceptance

  1. Update Inventory Source Seller Status.
    1. Pause/unpause does not affect deal serving. Seller pausing a deal only shows a string message to advertisers as FYI. This helps advertiser troubleshoot a non spending deal.

Renegotiation (Update deal after accept)

Renegotiation refers to updates made to a deal after it has been accepted by the buyer. This can be very useful to both exchanges and buyers to push new changes to accepted deals. For example, exchange may find that the deal end time for an accepted deal is not correct and exchange can use DV3 Update Product to push updates to DV3 buyers if the deal has not started yet.

What changes are allowed and disallowed.

We allow changes to all fields except some serving critical fields like: startTime, endTime, rateDetails, creativeConfig and etc. We have validations around these serving critical fields. Generally speaking, updates to these fields except creativeConfig are allowed if deal's start time is at least 1 day later in future. Only incremental updates are allowed for in flight deals, of which start time is in the past but end time is in future. No changes are allowed for completed deals, of which the end time is in the past. For example, updating the rateDetails of a deal completed one year ago, is not allowed. In cases like this, DV3 Update Product will throw validation error.

Previous
Entity Structure
Next
Beta Process