.. index:: Release Notes
.. _release_notes:

Release Notes
=============

This section gives insight on what our current and previous releases contain.

Feb 2023: 'Campaigns & Micros'
------------------------------

Synopsis
""""""""

* changing wording of ``cpc`` to ``bid``, Functionality has not changed.
* For bid, budgets & spent values we now communicate in micros: 1 cent == 10000 micros. Fields representing a monetary value will now also be named accordingly, mentioning whether they represent a value in cents or micros. This will result in fields like ``bidMicros`` and ``amountCents``. The change into micros is also represented in the category data, where the interval of allowed values is defined.
* Introduced campaigns, campaign ID not (yet) mandatory while placing ads. Campaigns have their own daily/total budgets. Since currently only 1 campaign is allowed per user, the budgets from this campaign effectively act on all ads.
* Moved price and related fields into a struct.

Removed Fields
^^^^^^^^^^^^^^

* removed externalID, use vendorID instead.
* removed currency, 1 country == 1 currency anyway. Monetary values always in local currency.
* removed pageNumber & suggestedCpcForPageOne: In the desktop-era the majority of traffic was generated by leaf category browse actions, which lead to the introduction of the "suggested cpc for page one". Today, traffic from additional sources like search actions and personal recommendations have become dominant. As these traffic sources use different ranking methods, the relevance of the "suggested cpc for page one" has diminished.
* Use the V2 version of /metrics/ads and /metrics/report to get spent and bid values in micros too, to avoid confusion. V1 is deprecated.
* User endpoint updated to V4, this adds 1 new field to V3 (which added 1 field to V2). Older versions than V4 are deprecated.

Ads
"""

See :ref:`ads` for full details.

.. list-table::
 :widths: 20 80
 :header-rows: 1

 * - Field
   - Change synopsis
 * - cpc 		            
   - moved to bidMicros. Now allows for 'AUTOMATIC' too.
 * - totalBudget            
   - moved to budgets.total.limitMicros. Now allows 'UNLIMITED' too.
 * - spentBudget               
   - moved to budgets.total.spentMicros
 * - dailyBudget            
   - moved to budgets.daily.limitMicros. Now allows 'UNLIMITED' too.
 * - dailySpent            
   - moved to budgets.daily.spentMicros
 * - campaignId          
   - new, not yet mandatory.
 * - status             
   - can now contain "DOMAIN_PENDING", requiring the seller to confirm the new clickout url domain before the can go active.
 * - price                
   - moved to price.amountCents
 * - priceType            
   - moved to price.priceType
 * - priceUnit            
   - moved to price.priceUnit
 * - originalPrice       
   - moved to price.originalAmountCents
 * - currency             
   - removed
 * - externalId           
   - removed
 * - statusReasons        
   - removed, status is expanded
 * - pageNumber           
   - removed
 * - suggestedCpcForPageOne
   - removed
 * - allowPaypal            
   - removed


Categories
""""""""""

See :ref:`categories` for full details.

.. list-table::
 :widths: 20 80
 :header-rows: 1

 * - Field
   - Change synopsis
 * - currency               
   - removed
 * - cpc
   - moved to bidMicros.
 * - totalBudget            
   - moved to totalBudgetMicros.
 * - minDailyBudget
   - moved to dailyBudgetMicros. This is now an interval instead of min value.
 * - paypalEnabled
   - removed
 * - paypalBpEnabled
   - removed
 * - suggestedCpcForPageOne
   - removed

Campaigns
"""""""""
Added first campaign support. See :ref:`campaigns` for full details.

* :ref:`get_campaigns` to get list of campaigns for a user. Expected 0 or 1 result.
* :ref:`get_campaign_id` to fetch the individual campaign.
* :ref:`post_campaign` to create a campaign. Currently only 1 allowed per seller.
* :ref:`put_campaign_id` to update the campaign. Currently only status & budgets can be updated.
* :ref:`put_campaign_id_status` to manage the campaign status (ACTIVE,PAUSED) directly.
* :ref:`put_campaign_id_budgets` to manage the campaign's budgets directly.

.. note::
 For the time being, we will create a campaign underwater for users who start placing ads without first having created a campaign. All subsequent ads will belong to that default campaign.
 Be sure to check the budgets of that campaign as a default campaign will have unlimited budget.
 Deleting a campaign is currently not allowed.

User
""""

See :ref:`get_user` for full details.

Start using V4. There are 2 new fields in comparison with V2:
``hasAds`` (**bool**), whether a user has ads in the system and 
``isApiManaged`` (**bool**), whether we see API partners managing ads for the user (not true if an api partner is using RO scopes only)


Deprecation list
""""""""""""""""

The following calls are deprecated and scheduled to be removed on May 1st, 2023:

.. list-table::
 :widths: 80 80
 :header-rows: 1

 - * deprecated endpoint
   * replaced by 
 - * :ref:`get_ad_v4`
   * :ref:`get_ad_v5`
 - * :ref:`get_ad_id_v3`
   * :ref:`get_ad_id_v5`
 - * :ref:`get_ad_id_v2`
   * :ref:`get_ad_id_v5`
 - * :ref:`get_ad_vendor_id_v3`
   * :ref:`get_ad_vendor_id_v5`
 - * :ref:`get_ad_vendor_id_v2`
   * :ref:`get_ad_vendor_id_v5`
 - * :ref:`post_ad_v3`
   * :ref:`post_ad_v5`
 - * :ref:`post_ad_v2`
   * :ref:`post_ad_v5`
 - * :ref:`put_ad_id_v3`
   * :ref:`put_ad_id_v5`
 - * :ref:`put_ad_id_v2`
   * :ref:`put_ad_id_v5`
 - * :ref:`get_user_v2`
   * :ref:`get_user_v4`
 - * :ref:`get_user_v3`
   * :ref:`get_user_v4`
 - * :ref:`get_category_id_v2`
   * :ref:`get_category_id_v5`
 - * :ref:`get_categories_v1`
   * :ref:`get_categories_v5`