Yield Management Auction Tier service

Article
03/11/2024

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"
 }
}

Partager via