Yield Management Auction Tier service

The Yield Management Auction Tier Service allows you to modify the standard auction mechanics such that certain bids will be considered before others, provided that those bids are associated with certain members and meet particular pricing requirements. You may also use this service to exclude certain members from consideration altogether.

Note

Auction tiers must be associated with an existing Yield Management Profile.

REST API

HTTP Method	Endpoint	Description
POST	https://api.appnexus.com/ym-auction-tier (auction-tier JSON)	Add an auction tier.
PUT	https://api.appnexus.com/ym-auction-tier?id=AUCTION_TIER_ID (auction-tier JSON)	Modify an auction tier.
GET	https://api.appnexus.com/ym-auction-tier	View all of your auction tiers.
GET	https://api.appnexus.com/ym-auction-tier?id=AUCTION_TIER_ID	View a specific auction tier.
GET	https://api.appnexus.com/ym-auction-tier?id=1,2,3	View multiple auction tiers by ID using a comma-separated list.
DELETE	https://api.appnexus.com/ym-auction-tier?id=AUCTION_TIER_ID	Delete an auction tier.

JSON fields

Field	Type	Description
id	int	The unique identifier for this auction tier. Default: Auto-generated number. Required On: PUT, in query string.
name	string	The name of this tier. Required On: POST
code	string	An optional custom code that you can use to map between this object's identifier in your system and in ours. Default: null
description	string	An optional description.
profile_id	int	An optional profile_id is used to determine when to apply a tier. A profile is a generic set of rules for targeting inventory, and certain tiers may only apply to certain slices of inventory. For details, see the Profile Service. Default: null
priority	int	You'll rank each auction tier from 1 to 10 in ascending priority. Those with higher priorities are checked first for a match. If two tiers happen to match the bid in question, and their priorities are equal, the winner is chosen at random. Default: 5
ym_profile_id	int	An auction tier is associated with a Yield Management Profile. This is that profile's identifier. Required On: POST
min_price	decimal	The minimum price that must be bid by the members in the buyer_members array for inclusion in this tier. This can be null if the member_action is set to "exclude". Note: Whether a buyer has met the value of min_price is checked after AppNexus' revenue sharing fee has been removed; in other words, min_price is checked against their net bid. For example, if you've set min_price to $2.00, and the buyer bids $2.00, their net bid may be reduced to $1.70. This would mean they do not qualify for the tier. The solution is for buyers to take into account their revenue sharing agreement with AppNexus when submitting bids for inclusion in tiers. Default: null
member_action	enum	This setting determines what action is to be taken against the buyer_members array. Permissible values are "include" and "exclude". Default: exclude
member_id	int	This is your member ID.
buyer_members	array of objects	This array includes the buyers you're targeting for inclusion or exclusion in this Auction Tier. For details, see the Buyer Members Array below. Default: null

Buyer members array

Field	Type	Description
id	int	The ID of the member you're targeting for inclusion or exclusion.
name	string	The name of the member you're targeting for inclusion or exclusion.

Examples

View all of your auction tiers

$ curl -b cookies -c cookies 'https://api.appnexus.com/ym-auction-tier'

{
    "response": {
        "status": "OK",
        "count": 328,
        "start_element": null,
        "num_elements": null,
        "ym-auction-tiers": [
            {
                "id": 1,
                "name": "Buyer 1 Tier",
                "code": null,
                "description": null,
                "profile_id": null,
                "priority": 10,
                "ym_profile_id": 2785,
                "min_price": "3.000000",
                "member_action": "include",
                "member_id": 752,
                "buyer_members": [
                    {
                        "id": 1094,
                        "name": "Buyer 1"
                    }
                ]
            },
            {
                "id": 2,
                "name": "Buyer 2 Tier",
                "code": null,
                "description": null,
                "profile_id": null,
                "priority": 10,
                "ym_profile_id": 2785,
                "min_price": "4.000000",
                "member_action": "include",
                "member_id": 752,
                "buyer_members": [
                    {
                        "id": 232,
                        "name": "Buyer 2"
                    }
                ]
            },
            {
                "id": 3,
                "name": "Buyer 3 Tier",
                "code": null,
                "description": null,
                "profile_id": null,
                "priority": 10,
                "ym_profile_id": 2785,
                "min_price": "2.500000",
                "member_action": "include",
                "member_id": 752,
                "buyer_members": [
                    {
                        "id": 903,
                        "name": "Buyer 3"
                    }
                ]
            },
            ...
        ]
    }
}

Add an auction tier - Exclude a member

We must include our {{member_id}} and the {{ym_profile_id}} we'd like to associate this tier with.

$ cat add-tier.json
{
    "ym-auction-tier": {
        "member_id": 67890,
        "ym_profile_id": 271828,
        "description": "Bidder 9 from Outer Space has advanced alien bidding technology. They must be stopped!",
        "name": "Exclude Bidder 9 from Outer Space",
        "member_action": "exclude",
        "priority": 10,
        "min_price": null,
        "buyer_members": [
        {
            "id": 12345,
            "name": "Bidder 9 from Outer Space"
        }
        ]
     }
}

$ curl -b cookies -X POST -d @update.json "https://api.appnexus.com/ym-auction-tier"
{
 "response": {
  "id": 1105,
  "ym-auction-tier": {
   "profile_id": null,
   "code": null,
   "id": 5813,
   "description": "Bidder 9 from Outer Space has advanced alien bidding technology. They must be stopped!",
   "name": "Exclude Bidder 9 from Outer Space",
   "member_id": 67890,
   "member_action": "exclude",
   "priority": 10,
   "buyer_members": [{"id":12345,"name":"Bidder 9 from Outer Space"}],
   "ym_profile_id": 271828,
   "min_price": null
  },
  "status": "OK",
  "start_element": null,
  "count": 1,
  "num_elements": null
 }
}

Add an auction tier - Include a member

Notice that this member must meet an extremely high {{min_price}} in order for this tier to apply. Since we haven't specified a {{priority}}, it defaults to 5.

$ cat add-tier.json
{
    "ym-auction-tier": {
    "ym_profile_id": 456,
    "name": "A High Bar for Member 12 to clear",
    "member_id":123,
    "member_action": "include",
        "min_price": "314159.00",
        "buyer_members": [
        {
        "id": 12,
        "name": "Member 12"
        }
    ]
    }
}



$ curl -b cookies -X POST -d @add-tier.json "https://api.appnexus.com/ym-auction-tier"
{
 "response": {
  "id": 1110,
  "ym-auction-tier": {
   "profile_id": null,
   "code": null,
   "id": 1110,
   "description": null,
   "name": "A high bar for Member 12 to clear",
   "member_id": 123,
   "member_action": "include",
   "priority": 5,
   "buyer_members": [
    {
     "id": 12,
     "name": "Member 12"
    }
   ],
   "ym_profile_id": 456,
   "min_price": "314159.000000"
  },
  "status": "OK",
  "start_element": null,
  "count": 1,
  "num_elements": null
 }
}

Update an auction tier

We've modified our financial arrangement with Member 19, and we'd like them to bid a minimum $1.25 CPM in order to remain in their current Auction Tier.

$ cat update.json
{
    "ym-auction-tier": {
    "id": 001,
    "member_id": 19,
        "min_price": "1.25"
    }
}

$ curl -b cookies -X PUT -d @update.json "https://api.appnexus.com/ym-auction-tier?id=001"
{
 "response": {
  "id": 001,
  "ym-auction-tier": {
   "profile_id": null,
   "code": null,
   "id": 001,
   "description": null,
   "name": "Member 19's Tier",
   "member_id": 19,
   "member_action": "include",
   "priority": 7,
   "buyer_members": [
    {
     "id": 19,
     "name": "Member 19"
    }
   ],
   "ym_profile_id": 002,
   "min_price": "1.25"
  },
  "status": "OK",
  "start_element": null,
  "count": 1,
  "num_elements": null
 }
}

Delete an auction tier

$ curl -b cookies -X DELETE "https://api.appnexus.com/ym-auction-tier?id=003"
{
 "response": {
  
  "status": "OK"
 }
}