API Migration

Overview

This document is aimed to provide instruction to Commerce Grid API users on how to migrate from 3 layers structure (Supply Deal -> Package -> Demand Deal) to 2 layers structure (Supply Package -> Demand Deal). This migration simplifies the operational flow and minimizes the number of steps needed to execute deal creation.

Below are listed some highlights that we will elaborate further in this document:

  1. The API endpoint stays the same, it is just the structure of entities that is going to slightly change

  2. The Package entity is not needed anymore and should no longer be created. We will also deprecate this entity by June 30th, so we are kindly encouraging you to migrate your API scripts over to the new 2-layer structure within the 2 months window prior to the deprecation.

  3. New deals’ creation flow. Hints on creating supply package and demand deals with just one request

  4. The legacy deals creation flow (just for reference)

Endpoint

The API endpoint remains unchanged, you should continue using https://curate.themediagrid.com/api/ for all your existing and new supply packages and deals.

Creating Supply Packages and Demand Deals has become simpler

We not only have deprecated Package as an entity, but we have supported another enhancement. You can now create a Supply Package and a linked Demand Deal has by sending a single POST request. To create Supply Packages and Demand deals together you will need to specify only one additional field create_demand_deals or demand_deals.

  1. Using the field create_demand_deals you can create Demand Deals and set options for each seat. You will no longer need to create a Package separately and edit automatically created Demand Deals.

"create_demand_deals": {
  "demand_deals_options": [
    {
      "seat": {
        "id": 0,
        "name": "string"
      },
      "price": 0.01,
      "deal_sync": true
    }
  ],
  "agency_curation_fee": 0,
  "agency_curation_fee_type": 0,
  "contact_email": "string"

  1. You can also use the field demand_deals to link some of your Demand Deals that you have previously created to a supply package. You can populate this field with Demand Deals information obtained in the response from other requests.

"demand_deals": [
  {
    "id": 0,
    "name": "string"
  }
]

Examples of the new simplified flow

  1. Create new Supply Package and new Deals (Generate new Demand deal for each selected Seat)

    We have added a new field create_demand_deals – you can use this field to specify several demand deals that you want to create using different seats and pricing rules. Use POST https://staging-curate.themediagrid.com/api/supply_deals/ .

Request
{
  'app_list_targetings': [],
  'browser_targetings': [],
  'device_targetings': [],
  'domain_list_targetings': [],
  'end_date': None,
  'geo_targetings': [],
  'is_active': True,
  'is_dynamic_bidding': True,
  'is_true_price_opt_enable': False,
  'media_type': 'banner',
  'name': 'Test 123',
  'operating_system_targetings': [],
  'size_targetings': [],
  'start_date': '2024-04-04 00:00:00+0000',
  'create_demand_deals': {
    'agency_curation_fee': 1,
    'agency_curation_fee_type': 0,
    'demand_deals_options': [{
      {'id': < Your seat ID >},
   }],
      'contact_email': 'contact_email@example.com'
   }
 }
Response
{
  'demand_deals': [{ // list of generated demand deals
    'id': 456789,
    'name': 'Test SP 123: Test Seat 123'
  }],
  'id': 123456,
  'name': 'Test 123',
  'packages': [{ // deprecated field, will disappear after June 30
    'id': 567890,
    'name': 'Package for: Test SP 123: Test Seat 123'
  }],
 ... (other fields) }

  1. Create a new Supply Package and Add to an existing Demand Deal(s)

    We have added a new field ‘demand_deals” – you can use this field to link your new Supply Package to some existing demand deals

    POST https://staging-curate.themediagrid.com/api/supply_deals/

Request
{
  'app_list_targetings': [],
  'browser_targetings': [],
  'device_targetings': [],
  'domain_list_targetings': [],
  'end_date': None,
  'geo_targetings': [],
  'is_active': True,
  'is_dynamic_bidding': True,
  'is_true_price_opt_enable': False,
  'media_type': 'banner',
  'name': 'Test 123',
  'operating_system_targetings': [],
  'size_targetings': [],
  'start_date': '2024-04-04 00:00:00+0000',
  'demand_deals': [{
    'id': 234567,
  }],
}
Response
{
  'demand_deals': [{'id': 234567, 'name': 'Test Package 123: Test Seat 123'}]
  'id': 123456,
  'name': 'Test 123',
  'packages': [{ // deprecated field, will disappear after June 30th
    'id': 345678,
    'name': 'Test Package 123'
   }],
   ... (other fields)
}

  1. Also, you still could view and edit your Demand Deal

    Use Demand Deal ID in GET or PUT methods from the previous step (see ‘demand_deals’ field in response) to access your demand deal, view it and / or make changes. GET https://staging-curate.themediagrid.com/api/demand_deals/234567/

Response
{
  'id': 234567,
  'name': 'Test Package 123 : Test Seat 123',
  'package': { deprecated field
    'id': 345678,
    'name': 'Test Package 123'
},
  'seat': <Your seat ID object>,
  'dsp': <DSP object of the the selected seat>,
  'supply_deals': [{
    'id': 123456,
    'name': 'Test Deal 123',
    ... (other supply deal fields)
  }],
  ... (other fields)
}

The old scheme of creating deals and packages

For reference we’re sharing here the legacy approach so that you compare before vs after when moving over to the new approach.

  1. Create a supply deal POST https://staging-curate.themediagrid.com/api/supply_deals/

Request
{
  'app_list_targetings': [],
  'browser_targetings': [],
  'device_targetings': [],
  'domain_list_targetings': [],
  'end_date': None, 'geo_targetings': [],
  'is_active': True,
  'is_dynamic_bidding': True,
  'is_true_price_opt_enable': False,
  'media_type': 'banner',
  'name': 'Test Deal 123',
  'operating_system_targetings': [],
  'size_targetings': [],
  'start_date': '2024-04-04 00:00:00+0000',
}
Response
{
  'demand_deals': [],
  'id': 123456,
  'name': 'Test Deal 123',
  'packages': [], // deprecated field
  ... (other fields)
}

  1. Create a Package (deprecated step)

    Description: Set name and seats, use Supply Deal IDs from the previous step POST https://staging-curate.themediagrid.com/api/packages/

Request
{
  'name': 'Test Package 123',
  'seats': [{
    'value': True,
    'seat': {'id': <Your seat ID>},
    'dsp': {'id': <DSP ID of the the selected seat>}
  }],
  'supply_deals': [
     {'id': 123456}, // ID of created Supply Deal in the previous step
  ]
}
Response
{
  'demand_deals': [ // Generated Demand Deal
    {
      'id': 234567,
      'name': ' Test Package 123 : Test Seat 123', .
      .. (other fields)
    }
  ],
  'id': 345678,
  'name': 'Test Package 123',
  'seats': [
    {
      'value': True,
      'seat': <Your seat ID object>,
      'dsp': <DSP object of the the selected seat>,
    }
  ],
  'supply_deals': [
    {
      'id': 123456, // ID of created Supply Deal in the previous step
      'name': 'Test Deal 123',
      ... (other fields)
    }
  ],
  ... (other fields)
}

  1. Check automatically generated demand deal, after the package is created

    Use the Demand Deal ID in GET or PUT methods from the previous step (see the demand_deals field in response)

    GET https://staging-curate.themediagrid.com/api/demand_deals/234567/

Response
{
  'id': 234567,
  'name': 'Test Package 123 : Test Seat 123',
  'package': { deprecated field
    'id': 345678,
    'name': 'Test Package 123'
  },
  'seat': <Your seat ID object>,
  'dsp': <DSP object of the the selected seat>,
  'supply_deals': [{
    'id': 123456,
    'name': 'Test Deal 123',
    ... (other supply deal fields)
  }],
  ... (other fields)
}