API Workflows
Stay organized with collections
Save and categorize content based on your preferences.
Create a Deal
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}"
Create Order. Name is generated by DV3, and we recommend you store this Id somewhere in your system for future retrieval.
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
- 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
- Get details of an order. The status gets updated once the user Accept, Archive or Cancel the Order.
- Get details of Product.
Get a list of Deals
- LIST orders with a status filter to get all accepted/pending acceptance orders.
- LIST products with external_deal_id filter.
- LIST all products within an Order.
Update a deal
- Update Order for Publisher contact information.
- name, does not allow update(cannot be set in the field_mask). Status only allow to be set to Canceled via API.
- partner_id does not allow update.
- Update Product for a specific deal term update.
- name, externalDealId, transactionType, pricingType, updateTime cannot be updated.
- Update displayName does not require user acceptance.
- 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
- Get Order if you know the corresponding order id. Check the status field.
- 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.
- Get Inventory Source. The name is ‘exchanges/{exchangeId}/inventorysources/{external_deal_id}’. Check Buyer Status.
- Reservation deals
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.
BUYER_STATUS_PENDING
means Order has been accepted, but deal has not yet been configured. No spending will happen in this state.
BUYER_STATUS_PAUSED
means Deal has been explicitly paused by advertisers. No spending will happen in this state.
- Non Reservation deals
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. **
BUYER_STATUS_PENDING
not applicable.
BUYER_STATUS_PAUSED
means Deal has been explicitly paused by advertisers. No spending will happen in this state.
Pause/Unpause a deal after acceptance
- Update Inventory Source Seller Status.
- 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.
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-07-09 UTC.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-07-09 UTC."],[[["\u003cp\u003eDeals are created by creating an Order and then a Product under that Order, using unique external deal IDs for tracking.\u003c/p\u003e\n"],["\u003cp\u003eCancelling a deal involves updating the Order status to "Cancelled," which is a final and irreversible state.\u003c/p\u003e\n"],["\u003cp\u003eDeal details can be retrieved by fetching Order and Product information using their respective IDs.\u003c/p\u003e\n"],["\u003cp\u003eA deal's status (accepted, pending, or configured) can be checked through the Order or Inventory Source, providing insights into the deal's progress and buyer engagement.\u003c/p\u003e\n"],["\u003cp\u003eRenegotiating a deal involves updating specific fields of the Product after acceptance, subject to certain restrictions and validations based on the deal's timeframe and critical serving parameters.\u003c/p\u003e\n"]]],["Key actions include creating, canceling, getting details of, listing, and updating deals. Creating involves checking for existing products via `external_deal_id`, creating an order, and then a product. Canceling requires updating the order status to \"Cancelled.\" Updating allows changes to orders and products, with limitations on certain fields like `name` and critical serving fields. Getting details uses `get` for orders and products, while listing uses `list`. Checking user acceptance involves `get` order status or listing products and then getting order details. Checking user configuration is done via getting the `inventory source` and pause/unpause are updating the `inventory source`. Renegotiation consists of updating products after acceptance, with restrictions based on the deal's start and end times.\n"],null,["# API Workflows\n\nCreate a Deal\n-------------\n\n1. See if a product has already been created by [LIST](https://developers.google.com/display-video/seller/reference/rest/v1beta1/exchanges.orders.products/list) products with external_deal_id filter. External_deal_id must be unique across all products.\n\n GET https://dv360seller.googleapis.com/v1beta1/{parent=exchanges/*/orders/*}/products?filter=externalDealId=\"{external_deal_id}\"\n\n2. [Create Order](https://developers.google.com/display-video/seller/reference/rest/v1beta1/exchanges.orders/create). Name is generated by DV3, and we recommend you store this Id somewhere in your system for future retrieval.\n\n3. [Create Product under Order](https://developers.google.com/display-video/seller/reference/rest/v1beta1/exchanges.orders.products/create). Product name is generated by DV3, and we recommend you store this Id somewhere in your system for future retrieval.\n\n 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.\n\nCancel a Deal\n-------------\n\n1. [Update Order status to Cancelled](https://developers.google.com/display-video/seller/reference/rest/v1beta1/exchanges.orders/patch) Only Supports Canncel if the order has not been accepted. Cancelled is a final state. Cannot re-activate the Order once cancelled.\n\nGet details of a Deal\n---------------------\n\n1. [Get details of an order.](https://developers.google.com/display-video/seller/reference/rest/v1beta1/exchanges.orders/get) The status gets updated once the user Accept, Archive or Cancel the Order.\n2. [Get details of Product](https://developers.google.com/display-video/seller/reference/rest/v1beta1/exchanges.orders.products/get).\n\nGet a list of Deals\n-------------------\n\n1. [LIST](https://developers.google.com/display-video/seller/reference/rest/v1beta1/exchanges.orders/list) orders with a status filter to get all accepted/pending acceptance orders.\n2. [LIST](https://developers.google.com/display-video/seller/reference/rest/v1beta1/exchanges.orders.products/list) products with external_deal_id filter.\n3. [LIST](https://developers.google.com/display-video/seller/reference/rest/v1beta1/exchanges.orders.products/list) all products within an Order.\n\nUpdate a deal\n-------------\n\n1. [Update](https://developers.google.com/display-video/seller/reference/rest/v1beta1/exchanges.orders/patch) Order for Publisher contact information.\n 1. name, does **not** allow update(cannot be set in the field_mask). Status only allow to be set to Canceled via API.\n 2. partner_id does **not** allow update.\n2. [Update](https://developers.google.com/display-video/seller/reference/rest/v1beta1/exchanges.orders.products/patch) Product for a specific deal term update.\n 1. name, externalDealId, transactionType, pricingType, updateTime **cannot** be updated.\n 2. Update displayName does not require user acceptance.\n 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.\n\nSee if user has accepted the deal\n---------------------------------\n\n1. [Get Order](https://developers.google.com/display-video/seller/reference/rest/v1beta1/exchanges.orders/get) if you know the corresponding order id. Check the status field.\n2. If order id was not tracked: [List Products with external_deal_id filter](https://developers.google.com/display-video/seller/reference/rest/v1beta1/exchanges.orders.products/list), [figure out order name from product name](https://developers.google.com/display-video/seller/reference/rest/v1beta1/exchanges.orders.products), and then [Get Order](https://developers.google.com/display-video/seller/reference/rest/v1beta1/exchanges.orders/get). Check the status field.\n\nSee if user has configured(Only for PG) the deal\n------------------------------------------------\n\n1. [Get Inventory Source.](https://developers.google.com/display-video/seller/reference/rest/v1beta1/exchanges.inventorySources/get) The name is 'exchanges/{exchangeId}/inventorysources/{external_deal_id}'. Check [Buyer Status](https://developers.google.com/display-video/seller/reference/rest/v1beta1/exchanges.inventorySources).\n 1. Reservation deals\n 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](https://support.google.com/displayvideo/answer/7067656?hl=en) for more details.\n 2. `BUYER_STATUS_PENDING`means Order has been accepted, but deal has not yet been configured. No spending will happen in this state.\n 3. `BUYER_STATUS_PAUSED`means Deal has been explicitly paused by advertisers. No spending will happen in this state.\n 2. Non Reservation deals\n 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](https://support.google.com/displayvideo/answer/2891312?hl=en) for more details.\\*\\* There is NO Seller API to query for whether a deal has been targeted by line items. \\*\\*\n 2. `BUYER_STATUS_PENDING`not applicable.\n 3. `BUYER_STATUS_PAUSED`means Deal has been explicitly paused by advertisers. No spending will happen in this state.\n\nPause/Unpause a deal after acceptance\n-------------------------------------\n\n1. [Update](https://developers.google.com/display-video/seller/reference/rest/v1beta1/exchanges.inventorySources/patch) Inventory Source [Seller Status](https://developers.google.com/display-video/seller/reference/rest/v1beta1/exchanges.inventorySources).\n 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.\n\nRenegotiation (Update deal after accept)\n----------------------------------------\n\nRenegotiation 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](https://developers.google.com/display-video/seller/reference/rest/v1beta1/exchanges.orders.products/patch) Product to push updates to DV3 buyers if the deal has not started yet.\n\n### What changes are allowed and disallowed.\n\nWe 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](https://developers.google.com/display-video/seller/reference/rest/v1beta1/exchanges.orders.products/patch) Product will throw validation error."]]