Splits service

The Splits Service creates and modifies programmable splits for augmented line items. When you create a line item, you specify the inventory you'd like to target, the budget you'd like to spend over the flight, how you want to track revenue, and how to use Xandr optimization. Programmable splits can further target subsets of that total inventory, allocate the specified budget to different targets, set bidding criteria, and distribute creatives. The targeting on the line item acts as a filter; impressions must match the criteria specified by the line item before they'll be passed on to splits. For more information on how splits work, see Understanding Splits in the UI documentation.

The Splits Service allows you to specify:

• Targeting conditions
• Bidding rules
• Budget allocation
• Which creatives are associated with a split.

REST API

The Splits service works a little differently from most of Xandr's other API services. By default, the budget-splitter (Splits) service creates or modifies all the splits on the line item at the same time instead of creating or modifying a single split. Rather than creating a single split, the service creates a budget-splitter object (an array) that is associated with the line item. The budget-splitter array contains two or more splits, and must meet the following requirements:

• The sum of the budget allocation for all splits on a line item must always equal 100. This ensures that all impressions for a line item are accounted for by at least one split.
• Each split must be assigned a priority, which determines the split to which an incoming impression will be assigned if the impression meets the targeting requirements for more than one split. The same priority cannot be used for more than one split.
• One split must be defined as the default split. This is the fallback split to which impressions will be assigned if they don't meet the conditions of any of the other splits. The default split is referred to as the "Line Item Remainder" in the UI.
• The default split must be named "Default" or "default" and appear as the last split listed in the budget-splitter array. It cannot be assigned any conditions or assigned a capped (constrained) allocation strategy, because it is meant as a fallback in case other conditions don't apply. You can, however, allocate 0% of your budget to the default split, which means it will never serve.
• The default split may only have a bid modifier of "1" or null.
• The default split must be assigned an order, but no matter what order it is assigned, it will be prioritized last.

The POST method is not supported for the Split service.

To modify an individual split, you must use the PATCH method as described in the examples below.

Unlike other Xandr API services, the JSON for the budget-splitters array does not appear inside a wrapper named after the object. It appears simply as an unnamed array. For example, this is the JSON file to create a budget-splitters array with three splits:

Example budget-splitter object

[
    {
        "active": true,
        "allocation_percent": 40,
        "allocation_strategy": "unconstrained",
        "bid_modifier": null,
        "conditions": [
            {
                "field": "browser",
                "operator": "in",
                "value": [
                    8
                ]
            }
        ],
        "creative_macros": [],
        "creatives": [],
        "expected_value": 2,
        "is_default": false,
        "name": "Split 1",
        "order": 1
    },
    {
        "active": true,
        "allocation_percent": 30,
        "allocation_strategy": "unconstrained",
        "bid_modifier": null,
        "conditions": [
            {
                "field": "segment_group",
                "operator": "and",
                "value": [
                            [
                                {
                                "segment_id": 275913,
                                "start_minutes": 0,
                                "expire_minutes": 1440
                                }
                            ]
                         ]    
            }
        ],
        "creative_macros": [],
        "creatives": [],
        "expected_value": 1,
        "is_default": false,
        "name": "Split 2",
        "order": 2
    },
    {
        "active": true,
        "allocation_percent": 30,
        "allocation_strategy": "unconstrained",
        "bid_modifier": null,
        "expected_value": 0.5,
        "is_default": true,
        "name": "Default",
        "order": 3
    }

HTTP Method	Endpoint	Description
PUT	https://api.appnexus.com/budget-splitter/LINE-ITEM-ID/splits (budget-splitter JSON)	Add splits to a line item which has none.
GET	https://api.appnexus.com/budget-splitter/LINE-ITEM-ID/splits	View all splits for a line item.
PUT	https://api.appnexus.com/budget-splitter/LINE-ITEM-ID/splits (budget-splitter JSON)	Update all splits for a line item.
DELETE	https://api.appnexus.com/budget-splitter/LINE-ITEM-ID/splits	Delete all splits from a line item. This will delete all splits from the line item permanently. The information for past splits traffic will still appear in reporting.
PATCH	https://api.appnexus.com/budget-splitter/LINE-ITEM-ID/splits (split-update JSON) The split ID must appear in the split-update JSON.	Modify a single split.

JSON fields

Field	Type	Description
id	int	The ID of the split. Example: "id":21197314 Default: Auto-generated number. Required On: PUT/PATCH/DELETE, in JSON.
name	string (255)	The name you assign the split. Example: "name":"Split 123" Note: The default split must be named "Default" or "default".
is_default	boolean	Specifies whether this is the default split, which is used when an impression does not meet the targeting requirements for any other splits. Every line item must have one and only one default split. The default split must be named "Default" or "default" and cannot have any conditions. Possible values are "true" and "false". Example: "is_default":true
conditions	array	The targeting conditions for the split. A condition is specified by an array containing a field, an operator, and a value. Example: "conditions":[{"field":"city","operator":"in","value":[196646]}] See Conditions below for more information.
active	boolean	Specifies the status of a split. Possible values are "true" or "false". Example: "active":true
order	int	The priority of this split in the budget_splitters array. In the UI, this field is referred to as "Priority". If an impression meets the targeting requirements for multiple splits, the priority determines the split to which the impression will be assigned. For example, suppose that Split A (priority 1) is targeting "domain=cnn.com" and Split B (priority 2) is targeting "city=Boston", and an impression is available from a user in Boston visiting cnn.com. The impression will be assigned to Split A because it has a higher priority than Split B. You cannot set the same priority for multiple splits. The order can start at any value, so long as the values are sequential. For example, the order for three splits can be 0, 1, 2 or 4, 5, 6. Example: "order":1
allocation_percent	int	The percentage of the line item budget assigned to this split. The allocation for each split should be between 0 and 100. The sum of the allocation percentages for all splits in a line item must equal 100. Example: "allocation_percent":30
allocation_strategy	enum	Specifies how to handle conflicts between the split allocation goal and the line item delivery goal. Possible values are: - "unconstrained" - Line item delivery is prioritized over allocation. When a line item with uncapped splits is underdelivering, the uncapped splits are permitted to exceed the allocation goal to reach the line item delivery goal. In the UI, this state is called "uncapped". - "constrained" - Allocation is prioritized over delivery. Even when line items are underdelivering, capped splits are not permitted to exceed the allocation goal to help the line item reach its delivery goal. This will prevent overspend on a split, but may cause the line item to underdeliver. In the UI, this state is called "capped". For more information, see Understanding Splits in the UI documentation. Example: "allocation_strategy":"unconstrained" Default: "unconstrained"
bid_modifier	float	The number used to modify the bid for this split. A bid modifier can only be applied to a split when the line item's booked revenue type is CPM and optimization is not enabled. The value of the bid modifier will be multiplied by the CPM booked revenue to serve as the maximum CPM that the split can bid. Example: "bid_modifier":1.25 Note: - The default split may only have a bid modifier of "1" or null. Inactive splits must be assigned a bid modifier of "0". - The bid_modifier field is not used by GDALI.
expected_value	float	The expected value of the impression for this split. An expected value must be included for each split when the line item's booked revenue type is cost plus or dCPM and optimization is not enabled. The expected value serves as the maximum CPM that the split can bid. Example: "expected_value":10.50 Note: The expected_value field is not used by GDALI.
creatives	array	Optional. The IDs of the creatives to be served on this split. Example: "creatives":[{"creative_id":123},{"creative_id":456}]
creative_macros	array of strings	Optional. Any creative macros that are added to the served creative. For more information, see Creative Macro Check Service. Note: The creative_macros field is not used by GDALI.
user_test_group_percent	int	Optional. Targets distinct groups of users per split for A/B testing. Note: When the Line Item Remainder split is set to "active" or has a budget allocation greater than 0%, the line item remainder will always include the remaining pool of users not targeted by the other splits. Additionally, the Line Item Remainder split will always include cookieless users. If you do not want to serve cookieless users: - If you're using allocations, on the default split, set allocation_percent to "0". - If you're not using allocations, on the default split, set active to "false".

Conditions

A condition is specified by an array containing a field, an operator, and a value. For example, to create a condition that targets impressions from the United States, the condition is:

"conditions": [
  {
    "field": "country",
    "operator": "=",
    "value": [
      233
    ]
  }
]

Custom categories

Evaluate impressions based on specific custom categories present.

Field	Operator	Value
content_category	=, in, not_in	Custom category ID. Use the Content Category Service to retrieve custom category IDs. Warning: Custom categories should only be targeted to managed inventory.

Key-value

Evaluate impressions based on specific key-values present.

Field	Operator	Value
key_group	and, or	A nested conditions array that specifies key groups. Each key group array includes key ID(s), action(s) ("include" or "exclude"), and value(s): Warning: Key-values should only be targeted to managed inventory. - key_id - the ID of the key. Use the Targeting Key Service to retrieve key IDs. - action - can be "include" or "exclude". - value_equals is an array of value IDs that must be matched in the auction for the split to be eligible to serve. Use the Targeting Key Service to retrieve value IDs. When one value is passed, that key-value combination must be present on the request for the split to be eligible to serve. When multiple values are defined in the array, one of the key-value combinations must be present. - value_less is the high end of the range of permitted values, exclusive. - value_greater is the low end of the range of permitted values, exclusive.Key-values may be passed on the impression request. See Xandr’s Seller Tag (AST) for more information.

The following Key-Value example (see JSON below) evaluates to

[ [include Key ID 123: value ID: [1 OR 2 OR 9] ] AND [exclude Key ID 234: value ID: [20] ] ] OR [include Key ID 789: value ID: [15] ]

{
   "conditions": [{
      "field": "key_group",
      "operator": "or",
      "value": [
         [{
               "key_id": 123,
               "action": "include",
               "value_equals": [1, 2, 9]
            },
            {
               "key_id": 234,
               "action": "exclude",
               "value_equals": [20]
            }
         ],
         [{
            "key_id": 789,
            "action": "include",
            "value_equals": [15]
         }]
      ]
   }]
}

Country

Evaluate impressions based on the user's country.

Field	Operator	Value
country	=, in, not_in	Country ID or code, such as 233 or "US".Use the Country Service to retrieve these IDs or codes.

Region

Evaluate impressions based on the user's geographic region.

Field	Operator	Value
region	=, in, not_in	Region ID or country/region code combination, such as "US:NY". Use the Region Service to retrieve these IDs and codes.

City

Evaluate impressions based on the user's city.

Field	Operator	Value
city	=, in, not_in	City ID or country/region/city code combination, such as "US:NY:New York". Use the City Service to retrieve these IDs and codes.

DMA

Evaluate impressions based on the user's DMA (designated market area).

Field	Operator	Value
dma	=, in, not_in	DMA ID, such as 602 (for Chicago metro area). Use the City Service to retrieve DMA IDs.

Postal code

Evaluate impressions based on the user's postal code. Postal code is available only for some mobile impressions and impressions from external supply partners.

Field	Operator	Value
postal_code	=, in, not_in	Postal code ID (an integer) or country/postal code combination (a string such as "CA:J0K 1B0" or "US:10010"). Includes US zip codes. Use the Postal Code Service (documented in the Profile Service) to retrieve postal code IDs.

Postal code list

Evaluate impressions based on the user's post codes in the postal code list.

Field	Operator	Value
postal_code_list	in, not_in	Postal code list ID (an integer). Use the Postal Code List Service (documented in Postal Code List Service) to retrieve postal code list IDs.

Size

Evaluate impressions based on placement size. Please note that in case promo_sizes are passed in the ad call, the evaluation will be performed using the primary size only.

Field	Operator	Value
size	=, in, not_in	String representing placement dimensions, formatted as "WIDTHxHEIGHT".

Inventory URL ID

Evaluate impressions based on specific inventory url IDs.

Field	Operator	Value
inventory_url_id	=, in, not_in	Inventory URL ID. Use Validate Inventory Item Service to retrieve these IDs.

Domain

Evaluate impressions based on domain.

Field	Operator	Value
domain	=, in, not_in	String representing a top-level domain name, such as "food.com" or "books".

Mobile app

Evaluate impressions based on specific mobile apps.

Field	Operator	Value
mobile_app_bundle	=, in, not_in	Mobile app ID or names. Use Mobile App Service to retrieve these IDs or names.

Placement

Evaluate impressions based on specific placements.

Field	Operator	Value
placement	=, in, not_in	Placement ID. Placement ID is listed as tag_id in log-level data.

Publisher

Evaluate impressions based on specific publishers.

Field	Operator	Value
publisher	=, in, not_in	Publisher ID. Tip: Publisher ID is listed as publisher_id in log-level data.

Seller member

Evaluate impressions based on specific seller members.

Field	Operator	Value
seller_member_id	=, in, not_in	Member ID of the seller.

Deal ID

Target deal inventory.

Field	Operator	Value
deal_id	=, in, not_in	Deal ID.

Deal list ID

Target deal list inventory.

Field	Operator	Value
deal_list	in, not_in	Deal List ID.

Operating system family

Evaluate impressions based on the user's operating system.

Field	Operator	Value
os_family	=, in, not_in	Operating System Family ID or name, such as 2 or "Android". Use the Operating System Family Service to retrieve these IDs and names.

Operating system version

Evaluate impressions based on the specific version of the user's operating system.

Field	Operator	Value
os_extended	=, in, not_in	Operating System Extended ID, such as 81 for "10.8 Mountain Lion". Use the Operating System Extended Service to retrieve these IDs. Note: Operating system ID is listed as operating_system in log-level data.

Browser

Evaluate impressions based on the user's browser.

Field	Operator	Value
browser	=, in, not_in	Browser ID or name, such as 8 or "Chrome (all versions)". Use the Browser Service to retrieve these IDs and names.

Browser language

Evaluate impressions based on the browser language.

Field	Operator	Value
language	=, in, not_in	Language ID. Use the Language Service to retrieve these IDs.

Device type

Evaluate impressions based on specific types of physical devices.

Field	Operator	Value
device_type	=, in, not_in	Device type name. Possible values: - "pc & other devices" - Use this value to target desktops and laptops. - "phone" - Use this value to target mobile phones. - "tablet" - Use this value to target mobile tablets.

Device model

Evaluate impressions based on specific models of physical devices.

Field	Operator	Value
device_model	=, in, not_in	Device model ID. Use the Device Model Service to retrieve these IDs. Device model ID is listed as device_id in log-level data.

Carrier

Evaluate impressions based on specific mobile carriers.

Field	Operator	Value
carrier	=, in, not_in	Mobile carrier ID or name, such as 14 or "Verizon". Use the Carrier Service to retrieve these IDs and names.

Predicted IAB viewability rate

Previously known as "Estimated IAB Viewability Rate". Evaluate web display impressions by how likely they are to be measured as viewable by the IAB standard, as determined by the Optimization Guide (available in the UI documentation).

Field	Operator	Value
predicted_iab_view_rate	<, <=, =, >, >=	Decimal number between 0 and 1, representing a percentage.

Predicted IAB video viewability rate

Evaluate web video impressions by how likely they are to be measured as viewable by the IAB standard, as determined by the Optimization Guide (available in the UI documentation).

Field	Operator	Value
predicted_iab_video_view_rate	<, <=, =, >, >=	Decimal number between 0 and 1, representing a percentage.

Predicted video completion rate

Evaluate web video impressions by how likely they are to be completed, as determined by the Optimization Guide (available in the UI documentation).

Field	Operator	Value
estimated_video_completion_rate	<, <=, =, >, >=	Decimal number between 0 and 1, representing a percentage. 0 represents non-video inventory.

Creative

The creatives to serve on this split.

Field	Operator	Value
creative	in	List of creative IDs. Use the Creative Service to retrieve these IDs.

Segment group

Field	Operator	Value
segment_group Use Segment Service to retrieve segment IDs.	and, or	A nested conditions array that specifies segment groups. Each segment_group array includes segment_ID, age, value, and action ("include" or "exclude"). - action may be "include" or "exclude". - start_minutes is the lower bound of minutes since the user has been added to this segment, inclusive. "start_minutes": 5 includes users who have been added to the segment from the five-minute mark, including 5:00. - expire_minutes is the upper bound of minutes since the user has been added to this segment, inclusive. "expire_minutes": 10 includes users who have been added to the segment until the ten-minute mark, including 10:00. - value_less is the low end of the range of permitted values, exclusive. "value_less" : 5 includes only values greater than, but not including, 5. - value_greater is the high end of the range of permitted values, exclusive. "value_greater" : 10 includes only values up to, but not including, 10. - value_equals is the exact match to the permitted value. “value_equals” : 5 includes only values equal to 5. - Unlike the Profile Service, the Splits service allows you to target segment values of zero (0). See example for value_equals below. Segment values may be passed in a number of ways, for example, through the Batch Segment Service or a first-party or third-party segment query string.

Example for the value_equals field

"conditions": [
{
"field": "segment_group",
"operator": "and",
"value": [
[
{
"segment_ID": SEGMENT_ID,
"action": SEGMENT_ACTION,
"start_minutes": YOUNGEST_SEGMENT_AGE,
"expire_minutes": OLDEST_SEGMENT_AGE,
"value_less": LOWER_BOUND_SEGMENT_VALUE,
"value_greater": UPPER_BOUND_SEGMENT_VALUE,
"value_equals": EXACT_SEGMENT_VALUE
}

]
]
}
]

Segment

Field	Operator	Value
segment[SEGMENTID,...] where SEGMENTID is an optional list of segment IDs. Use Segment Service to retrieve segment IDs.	<, <=, =, >, >=, present, absent	A nested conditions array that specifies segment age, value, or presence. - Segment presence is "present" or "absent". - Segment age is measured in minutes and must be a positive integer. - Segment value is a non-zero, positive integer representing a user-defined value. See example for value below. Segment values may be passed in a number of ways, for example, through the Batch Segment Service or a first-party or third-party segment query string.

Example for the value field

Evaluate impressions based on the presence, absence, value, or segment age of the user in a first-party or third-party segment.

"conditions": [
{
"field": "segment[]",
"operator": "any",
"value": [
{
"conditions": [
{
"field": "age",
"operator": "<=",
"value": 1440
}
],
"id": 275913
}
]
}
],

Daily frequency

The number of ads seen by a user for an advertiser, line item, or split on the current day.

Field	Operator	Value
OBJECT[ID].day_frequency where the object is advertiser, line_item, or campaign (representing split), and ID is the object ID. Use the Advertiser Service, Line Item Service, or Splits Service to retrieve IDs.	>, =>, <, =<, = Important: Although the operator = is supported for frequency and recency, we strongly recommend that you do not use it, as it tends to cause underdelivery. This is because when you target an impression with frequency=5, you exclude impressions with frequencies equal to 0, 1, 2, 3, or 4.	Positive integer. 0 indicates no frequency information is available (the user has not seen this object on the current day).

Lifetime frequency

The number of ads seen by a user over the lifetime of an advertiser, line item, or split.

Field	Operator	Value
OBJECT[ID].lifetime_frequency where the object is advertiser, line_item, or campaign (representing split), and ID is the object ID. Use the Advertiser Service, Line Item Service, or Splits Service to retrieve IDs. CAUTION: Although the operator = is supported for frequency and recency, we strongly recommend that you do not use it, as it tends to cause underdelivery. This is because when you target an impression with frequency=5, you exclude impressions with frequencies equal to 0, 1, 2, 3, or 4.	>, =>, <, =<, =	Positive integer. 0 indicates no frequency information is available (the user has never seen this object).

Recency

The number of minutes since a user has seen an ad. This can be determined for a user for all ads under an advertiser, line item, or split.

Field	Operator	Value
OBJECT[ID].recency where the object is advertiser, line_item, or campaign (representing split), and ID is the object ID. Use the Advertiser Service, Line Item Service, or Splits Service to retrieve IDs.	>, =>, <, =<, = Important: Although the operator = is supported for frequency and recency, we strongly recommend that you do not use it, as it tends to cause underdelivery. This is because when you target an impression with frequency=5, you exclude impressions with frequencies equal to 0, 1, 2, 3, or 4.	A positive integer indicating the number of minutes since a user has seen an impression, rounded down. 59 seconds will evaluate to 0, 61 seconds will evaluate to 1. 0 means the impression was seen very recently. Null means no recency data is available (the user has not seen this impression before).

Inventory type

The type of inventory ("app" or "web") targeted by the split. "App" targets mobile app inventory and "web" targets web inventory (including pages shown in mobile web browsers).

Field	Operator	Value
inventory_type	=, in, not_in	"web", "app" See Example.

Example for the inventory_type field

"conditions": [
{
"field": "inventory_type",
"operator": "in",
"value": [
"app",
"web"
]
}
]

Inventory URL list

Target an allowlist or blocklist established at the Network level. You can only target a single list.

Field	Operator	Value
inventory_url_list	all, not in	Inventory list ID. "conditions":[{"field":"inventory_url_list","operator":"not in","value":[12345]}] To create an inventory list, or retrieve the list IDs for use in split targeting, use the Inventory List Service.

Examples

Create splits for a line item with cost-plus booked revenue and optimization disabled

This example creates three splits for Line Item 6377624:

• Split 1 - User must be using the Chrome browser. Impressions are assigned an expected value of 2. Forty percent of the line item's traffic is allocated to this split, which is first in priority. Allocation is unconstrained.
• Split 2 - Impressions must belong to Segment 275913 and must have been added within the last 1440 minutes. They are assigned an expected value of ``1. Thirty percent of the line item's traffic is allocated to this split, which is second in priority. Allocation is unconstrained.
• Split 3 (unnamed) - The default split. Impressions are assigned an expected value of 0.5. Thirty percent of the line item's traffic is allocated to this split, which is third in priority. Allocation is unconstrained.

Since optimization is disabled, we are setting expected values for the splits.

$ cat ali_cost_plus_ev.json
[
    {
        "active": true,
        "allocation_percent": 40,
        "allocation_strategy": "unconstrained",
        "bid_modifier": null,
        "conditions": [
            {
                "field": "browser",
                "operator": "in",
                "value": [
                    8
                ]
            }
        ],
        "creative_macros": [],
        "creatives": [],
        "expected_value": 2,
        "is_default": false,
        "name": "Split 1",
        "order": 1
    },
    {
        "active": true,
        "allocation_percent": 30,
        "allocation_strategy": "unconstrained",
        "bid_modifier": null,
        "conditions": [
            {
                "field": "segment_group",
                "operator": "and",
                "value": [
                            [
                                {
                                "segment_id": 275913,
                                "start_minutes": 0,
                                "expire_minutes": 1440
                                }
                            ]
                         ]    
            }
        ],
        "creative_macros": [],
        "creatives": [],
        "expected_value": 1,
        "is_default": false,
        "name": "Split 2",
        "order": 2
    },
    {
        "active": true,
        "allocation_percent": 30,
        "allocation_strategy": "unconstrained",
        "bid_modifier": null,
        "expected_value": 0.5,
        "is_default": true,
        "name": "Default",
        "order": 3
    }

$ curl -b cookies -X PUT -s -d '@ali_cost_plus_ev.json' "https://api.appnexus.com/budget-splitter/6377624/splits"   
[
    {
        "active": true,
        "allocation_percent": 40,
        "allocation_strategy": "unconstrained",
        "bid_modifier": null,
        "conditions": [
            {
                "field": "browser",
                "operator": "in",
                "value": [
                    8
                ]
            }
        ],
        "creative_macros": [],
        "creatives": [],
        "expected_value": 2,
        "id": 24025228,
        "is_default": false,
        "name": "Split 1",
        "order": 1
    },
    {
        "active": true,
        "allocation_percent": 30,
        "allocation_strategy": "unconstrained",
        "bid_modifier": null,
        "conditions": [
            {
                "field": "segment_group",
                "operator": "and",
                "value": [
                            [
                                {
                                "segment_id": 275913,
                                "start_minutes": 0,
                                "expire_minutes": 1440
                                }
                            ]
                         ]    
            }
        ],
        "creative_macros": [],
        "creatives": [],
        "expected_value": 1,
        "id": 24025229,
        "is_default": false,
        "name": "Split 2",
        "order": 2
    },
    {
        "active": true,
        "allocation_percent": 30,
        "allocation_strategy": "unconstrained",
        "bid_modifier": null,
        "expected_value": 0.5,
        "id": 24025230,
        "is_default": true,
        "name": "Default",
        "order": 3
    }
]

Create splits for a line item with cost-plus booked revenue and optimization enabled

This example creates three splits for Line Item 6377631:

• Split 1 - User must be using the Chrome browser. Impressions are assigned an expected value of 2. Forty percent of the line item's traffic is allocated to this split, which is first in priority. Allocation is unconstrained.
• Split 2 - Impressions must belong to Segment 275913 and must have been added within the last 1440 minutes. They are assigned an expected value of 1. Thirty percent of the line item's traffic is allocated to this split, which is second in priority. Allocation is unconstrained.
• Split 3 (unnamed) - The default split. Impressions are assigned an expected value of 0.5. Thirty percent of the line item's traffic is allocated to this split, which is third in priority. Allocation is unconstrained.

$ cat ali_cost_plus_opt.json
[
    {
        "active": true,
        "allocation_percent": 40,
        "allocation_strategy": "unconstrained",
        "bid_modifier": null,
        "conditions": [
            {
                "field": "browser",
                "operator": "in",
                "value": [
                    8
                ]
            }
        ],
        "creative_macros": [],
        "creatives": [],
        "expected_value": null,
        "is_default": false,
        "name": "Split 1",
        "order": 1
    },
    {
        "active": true,
        "allocation_percent": 30,
        "allocation_strategy": "unconstrained",
        "bid_modifier": null,
        "conditions": [
            {
                "field": "segment_group",
                "operator": "and",
                "value": [
                            [
                                {
                                "segment_id": 275913,
                                "start_minutes": 0,
                                "expire_minutes": 1440
                                }
                            ]
                         ]    
            }
        ],
        "creative_macros": [],
        "creatives": [],
        "expected_value": null,
        "is_default": false,
        "name": "Split 2",
        "order": 2
    },
    {
        "active": true,
        "allocation_percent": 30,
        "allocation_strategy": "unconstrained",
        "bid_modifier": null,
        "expected_value": null,
        "is_default": true,
        "name": "Default",
        "order": 3
    }


$ curl -b cookies -X PUT -s -d '@ali_cost_plus_opt.json' "https://api.appnexus.com/budget-splitter/6377631/splits"
[
    {
        "active": true,
        "allocation_percent": 40,
        "allocation_strategy": "unconstrained",
        "bid_modifier": null,
        "conditions": [
            {
                "field": "browser",
                "operator": "in",
                "value": [
                    8
                ]
            }
        ],
        "creative_macros": [],
        "creatives": [],
        "expected_value": null,
        "id": 24025315,
        "is_default": false,
        "name": "Split 1",
        "order": 1
    },
    {
        "active": true,
        "allocation_percent": 30,
        "allocation_strategy": "unconstrained",
        "bid_modifier": null,
        "conditions": [
            {
                "field": "segment_group",
                "operator": "and",
                "value": [
                            [
                                {
                                "segment_id": 275913,
                                "start_minutes": 0,
                                "expire_minutes": 1440
                                }
                            ]
                         ]    
            }
        ],
        "creative_macros": [],
        "creatives": [],
        "expected_value": null,
        "id": 24025316,
        "is_default": false,
        "name": "Split 2",
        "order": 2
    },
    {
        "active": true,
        "allocation_percent": 30,
        "allocation_strategy": "unconstrained",
        "bid_modifier": null,
        "expected_value": null,
        "id": 24025317,
        "is_default": true,
        "name": "Default",
        "order": 3

Create splits for a line item with CPM booked revenue and optimization disabled

This example creates three splits for Line Item 6377633:

• Split 1 - User must be using the Chrome browser. Bids are multiplied by 0.5. Forty percent of the line item's traffic is allocated to this split, which is first in priority. Allocation is unconstrained.
• Split 2 - Impressions must belong to Segment 275913 and must have been added within the last 1440 minutes. Bids are multiplied by 0.4. Thirty percent of the line item's traffic is allocated to this split, which is second in priority. Allocation is unconstrained.
• Split 3 (unnamed) - The default split. Bids are multiplied by 1 (they remain the same). Thirty percent of the line item's traffic is allocated to this split, which is third in priority. Allocation is unconstrained.

Since optimization is disabled, we are setting bid modifiers for each split.

$ cat ali_cpm_bid_modifier.json
[
    {
        "active": true,
        "allocation_percent": 40,
        "allocation_strategy": "unconstrained",
        "bid_modifier": 0.5,
        "conditions": [
            {
                "field": "browser",
                "operator": "in",
                "value": [
                    8
                ]
            }
        ],
        "creative_macros": [],
        "creatives": [],
        "expected_value": null,
        "is_default": false,
        "name": "Split 1",
        "order": 1
    },
    {
        "active": true,
        "allocation_percent": 30,
        "allocation_strategy": "unconstrained",
        "bid_modifier": 0.4,
        "conditions": [
            {
                "field": "segment_group",
                "operator": "and",
                "value": [
                            [
                                {
                                "segment_id": 275913,
                                "start_minutes": 0,
                                "expire_minutes": 1440
                                }
                            ]
                         ]    
            }
        ],
        "creative_macros": [],
        "creatives": [],
        "expected_value": null,
        "is_default": false,
        "name": "Split 2",
        "order": 2
    },
    {
        "active": true,
        "allocation_percent": 30,
        "allocation_strategy": "unconstrained",
        "bid_modifier": 1,
        "expected_value": null,
        "is_default": true,
        "name": "Default",
        "order": 3
    }

$ curl -b cookies -X PUT -s -d '@ali_cpm_bid_modifier.json' "https://api.appnexus.com/budget-splitter/6377633/splits"   
[
    {
        "active": true,
        "allocation_percent": 40,
        "allocation_strategy": "unconstrained",
        "bid_modifier": 0.5,
        "conditions": [
            {
                "field": "browser",
                "operator": "in",
                "value": [
                    8
                ]
            }
        ],
        "creative_macros": [],
        "creatives": [],
        "expected_value": null,
        "id": 24025342,
        "is_default": false,
        "name": "Split 1",
        "order": 1
    },
    {
        "active": true,
        "allocation_percent": 30,
        "allocation_strategy": "unconstrained",
        "bid_modifier": 0.4,
        "conditions": [
            {
                "field": "segment_group",
                "operator": "and",
                "value": [
                            [
                                {
                                "segment_id": 275913,
                                "start_minutes": 0,
                                "expire_minutes": 1440
                                }
                            ]
                         ]    
            }
        ],
        "creative_macros": [],
        "creatives": [],
        "expected_value": null,
        "id": 24025343,
        "is_default": false,
        "name": "Split 2",
        "order": 2
    },
    {
        "active": true,
        "allocation_percent": 30,
        "allocation_strategy": "unconstrained",
        "bid_modifier": 1,
        "expected_value": null,
        "id": 24025344,
        "is_default": true,
        "name": "Default",
        "order": 3
    }
]

Update one split on a line item

In this example, Line Item 5200075 already has 3 splits, all with unconstrained allocation strategies. We update Split 1 to use a constrained allocation strategy.

# View the current splits
$ curl -b cookies 'https://api.appnexus.com/budget-splitter/5200075/splits'
    {
        "id": 24025093,
        "name": "Split 1",
        "is_default": false,
        "active": true,
        "bid_modifier": null,
        "expected_value": 2,
        "allocation_percent": 40,
        "allocation_strategy": "unconstrained",
        "order": 1,
        "conditions": [
            {
                "field": "browser",
                "operator": "in",
                "value": [
                    8
                ]
            }
        ],
        "creatives": [

        ],
        "creative_macros": [

        ]
    },
    {
        "id": 24025094,
        "name": "Split 2",
        "is_default": false,
        "active": true,
        "bid_modifier": null,
        "expected_value": 1,
        "allocation_percent": 30,
        "allocation_strategy": "unconstrained",
        "order": 2,
        "conditions": [
            {
                "field": "segment_group",
                "operator": "and",
                "value": [
                            [
                                {
                                "segment_id": 275913,
                                "start_minutes": 0,
                                "expire_minutes": 1440
                                }
                            ]
                         ]    
            }
        ],
        "creatives": [

        ],
        "creative_macros": [

        ]
    },
    {
        "id": 24025096,
        "name": "Default",
        "is_default": true,
        "active": true,
        "bid_modifier": null,
        "expected_value": 0.5,
        "allocation_percent": 30,
        "allocation_strategy": "unconstrained",
        "order": 3
    }
]

# View the split1-update JSON 
$ cat split1-update.json
[
    {
        "id": 24025093,
        "name": "Split 1",
        "is_default": false,
        "active": true,
        "bid_modifier": null,
        "expected_value": 2,
        "allocation_percent": 40,
        "allocation_strategy": "constrained",
        "order": 1,
        "conditions": [
            {
                "field": "browser",
                "operator": "in",
                "value": [
                    8
                ]
            }
        ],
        "creatives": [
        ],
        "creative_macros": [
        ]
    }
]

# Update Split 1

$ curl -b cookies -X PATCH -d @split1_update.json 'https://api.appnexus.com/budget-splitter/5200075/splits'
[
    {
        "id": 24025093,
        "name": "Split 1",
        "is_default": false,
        "active": true,
        "bid_modifier": null,
        "expected_value": 2,
        "allocation_percent": 40,
        "allocation_strategy": "constrained",
        "order": 1,
        "conditions": [
            {
                "field": "browser",
                "operator": "in",
                "value": [
                    8
                ]
            }
        ],
        "creatives": [

        ],
        "creative_macros": [

        ]
    },
    {
        "id": 24025094,
        "name": "Split 2",
        "is_default": false,
        "active": true,
        "bid_modifier": null,
        "expected_value": 1,
        "allocation_percent": 30,
        "allocation_strategy": "unconstrained",
        "order": 2,
        "conditions": [
            {
                "field": "segment_group",
                "operator": "and",
                "value": [
                            [
                                {
                                "segment_id": 275913,
                                "start_minutes": 0,
                                "expire_minutes": 1440
                                }
                            ]
                         ]    
            }
        ],
        "creatives": [

        ],
        "creative_macros": [

        ]
    },
    {
        "id": 24025096,
        "name": "Default",
        "is_default": true,
        "active": true,
        "bid_modifier": null,
        "expected_value": 0.5,
        "allocation_percent": 30,
        "allocation_strategy": "unconstrained",
        "order": 3
    }
]

Related topics

• Line Item Service - ALI
• Splits Service Troubleshooting