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](https://developers.google.com/display-video/seller/reference/rest/v1beta1/exchanges.orders.products/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](https://developers.google.com/display-video/seller/reference/rest/v1beta1/exchanges.orders/create).
   The Order Name is generated by DV360, and we recommend storing this ID in
   your system for future retrieval.

3. [Create Product under
   Order](https://developers.google.com/display-video/seller/reference/rest/v1beta1/exchanges.orders.products/create).
   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](https://developers.google.com/display-video/seller/reference/rest/v1beta1/exchanges.orders/patch). 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](https://developers.google.com/display-video/seller/reference/rest/v1beta1/exchanges.orders/get). The status is updated once the user accepts, archives, or cancels the Order.
2. [Get details of a
   Product](https://developers.google.com/display-video/seller/reference/rest/v1beta1/exchanges.orders.products/get).

## Get a list of Deals

1. [LIST](https://developers.google.com/display-video/seller/reference/rest/v1beta1/exchanges.orders/list) orders with a status filter to get all accepted or pending acceptance orders.
2. [LIST](https://developers.google.com/display-video/seller/reference/rest/v1beta1/exchanges.orders.products/list) products with the `external_deal_id` filter.
3. [LIST](https://developers.google.com/display-video/seller/reference/rest/v1beta1/exchanges.orders.products/list) all products within an Order.

## Update a deal

1. [Update](https://developers.google.com/display-video/seller/reference/rest/v1beta1/exchanges.orders/patch) 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](https://developers.google.com/display-video/seller/reference/rest/v1beta1/exchanges.orders.products/patch) 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](https://developers.google.com/display-video/seller/reference/rest/v1beta1/exchanges.orders/get) 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](https://developers.google.com/display-video/seller/reference/rest/v1beta1/exchanges.orders.products/list), [identify Order Name from Product
   Name](https://developers.google.com/display-video/seller/reference/rest/v1beta1/exchanges.orders.products), and then call [Get
   Order](https://developers.google.com/display-video/seller/reference/rest/v1beta1/exchanges.orders/get). Check the `status` field.

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

1. [Get Inventory
   Source](https://developers.google.com/display-video/seller/reference/rest/v1beta1/exchanges.inventorySources/get). The resource name is `exchanges/{exchangeId}/inventorysources/{external_deal_id}`. Check [Buyer
   Status](https://developers.google.com/display-video/seller/reference/rest/v1beta1/exchanges.inventorySources).
   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](https://support.google.com/displayvideo/answer/7067656) 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](https://support.google.com/displayvideo/answer/2891312) 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](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).
   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](https://developers.google.com/display-video/seller/reference/rest/v1beta1/exchanges.orders.products/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:

- [Renegotiate a Programmatic Guaranteed
  deal](https://support.google.com/displayvideo/answer/7067656#renegotiate)
- [Negotiate a deal in Display \& Video
  360](https://support.google.com/displayvideo/answer/7505945)