Skip to end of metadata
Go to start of metadata

Package Service

Sellers use this service to create and manage their packages. Packages are pre-made combinations of inventory and/or data. Buyers can use the Package Buyer Access Service to browse packages and then use the Deal From Package Service to create deals from them "off-the-shelf", or they can use packages as a jumping-off point for deal negotiations. 

In cases where packages don't meet a buyer's needs, sellers can use the Deal Service to create one-off custom deals.

On This Page

REST API

Add a new package: 
POST https://api.appnexus.com/package
(add_package JSON)

Update a package: 
PUT https://api.appnexus.com/package?id=PACKAGE_ID
(modify_package JSON)

View all of your packages: 
GET https://api.appnexus.com/package

View a specific package: 
GET https://api.appnexus.com/package?id=PACKAGE_ID  

Delete a package: 
DELETE https://api.appnexus.com/package?id=PACKAGE_ID

Deleting a package deletes all of its associated deals as well. Campaigns targeting these associated deals will stop serving. The deletions are permanent and cannot be reverted. Although deleted deals continue to be available in reporting, you will no longer have visibility into their specific settings.

Find out which fields you can filter and sort by: 
GET https://api.appnexus.com/package/meta

JSON Fields

Name

Type (Length)

Description

Default

Required on

id

int

The ID of the package.

Auto-generated number

PUT, DELETE

name

string (255) 

The name of the package.

 

 

description

string (65535)

The description of the package. You can use this field to provide buyers additional insight and details about the package.

 

 

active

Boolean

If true, the package is active. If false, buyers cannot generate deals from the package and all associated deals will stop serving.  

true

 

profile_id

int

The ID of the profile associated to the package. You can use a profile to specify publishers, placements, sites, content categories, segments, segment groups, or sizes that need to be involved in the auction in order for the deal to be available to the buyer. For more details, see publisher_targets , placement_targets , content_category_targets , segment_targets , segment_group_targets,   site_targets , and size_targets in the Profile Service .

Any other targeting settings in the associated profile will not be respected.


 

POST

default_ask_price

double

The ask price that will be applied to all deals generated from the package. When a buyer generates a deal, the Deal Service will automatically calculate the floor_price  by subtracting the seller revenue share specified in your AppNexus contract from the value in this field. This is the price shown to the buyer. It is the minimum they must bid in order to compete for the inventory.

You must use the member_ask_price field to set pricing when visibility_type is set to 2. When visibility_type is set to 1, you can use the member_ask_price field to set different pricing for select buyers.

 

POST

default_currency

enum

The ask price currency that will be applied to all deals generated from the package. For a full list of available currencies, use the read-only   Currency Service .

"USD"

 

default_use_deal_floor

Boolean

If true, the default_ask_price will be applied to deals generated from the package. The deal's floor price will override any other floors you may have, i.e., in placements or yield management profiles.

If default_use_deal_floor is false, default_ask_price must be set to 0. In this case, note that although the ask price is shown as 0, no deal floor is actually applied; if you have any other floors (in placements or yield management profiles), they will be applied, or if you do not have any other floors, the standard second-price auction mechanics will apply.

true

 

last_modified

timestamp

The day and time when the package was last modified.

 

 

data_protectedBooleanNot yet supported.false 
allow_creative_add_on_viewBooleanNot yet supported.
false 
allow_creative_add_on_clicktrueNot yet supported.true 
visibility_profile_idintNot yet supported.null 
seller_rankintThe seller's ranking for the package. This controls where the package will appear in the seller's full list of packages in the Console UI. Allowed range: 1 - 65355, where 1 is the highest ranking.100 
size_preferenceenum

Specifies how this package handles private sizes. Private sizes are placement sizes (set in the private_sizes array in the Placement Service) that can be allowed to serve in a package. There are two options:

  • standard: Private sizes are not available for this package.
  • append: Private sizes can be used in addition to the specified placement size.
  
technical_attribute_restrictBoolean

Specifies whether the package is restricted only to the technical attributes listed in the Technical Attributes object.

  • true: Package is restricted only to the listed technical attributes.
  • false: Other technical attributes are also allowed to serve.
true 
seller

object

The name and ID of the seller who is offering the package. For more details, see Seller below.

 

POST

default_deal_type 

object

The deal type that will be applied to all deals generated from the package. For more details, see Deal Type below.

 

 

visibility_typeobject

Defines if the package is visible to all buyers or select buyers. For more details, see Visibility Type below.

  
membersarray of objects

If visibility_type is set to "private", only the members listed in this field will be able to view the package. You can also use this field to define special pricing for select buyers. For more details, see Members below.

  
settingobjectThe type of content included in the package. For more details, see Setting below.   
technical_attributesarray of objects

The technical attributes of creatives that are eligible for the package. For more details, see Technical Attributes below.

  
sizesarray of objectsIf the profile associated with the package has size targets set, you can use this field to expose the specific sizes to buyers. For more details, see Sizes below.   
default_deal_priorityInt

The bidding priority when id in the default_deal_type object = 2/Private Auction.

Possible values: 1 - 20, where 20 is the highest priority.

5 
allowed_media_typesarray of objectsThe media types allowed for the package. To learn more, see Allowed Media Types below.  
allowed_media_subtypesarray of objectsThe media subtypes allowed for the package. To learn more, see Allowed Media Subtypes below.  
media_preferencestring

Specifies how this package handles media types/subtypes. There are two options:

  • standard = use whatever media types are already on the auction (based on the placement settings)
  • append = include the media types on the auction + any private media types set on the placement

If a deal is created from a package, this setting is copied from the package to the deal.

  

Seller

The seller object contains the following fields.

Field

Type

Description

Default

Required On
id intRead-only. The member ID of the seller.Seller's member IDPOST
namestringRead-only. The member name of the seller.Seller's member name 

Default Deal Type

The default_deal_type object contains the following fields. By default, all packages will generate deals with an open auction  deal type.

Field

Type

Description

Default

Required On
id intThe ID representing the type of deal. Possible values: 1 (Open Auction) or 2 (Private Auction). For more information about open and private auctions, see the Deal Service1 
namestringRead-only.  The name of the type of deal. Possible values: "Open Auction" or "Private Auction"."Open Auction" 

Visibility Type

The visibility_type object contains the following fields.

Field

Type

Description

Default

Required On
id int

The ID of the visibility level for your package. Possible values:

  • 1 = console
    A "console" package is visible to all buyers. Any buyer can create a deal from the package. Use the members array to define special pricing for select buyers. For more information, see Members below.
  • 2 = private
    A "private" package is only visible to the buyers specified in the members array. Only those buyers can create a deal from the package. Use the members array to define unique pricing for each of these buyers. For more information, see Members below.
  • 3 = hidden
    A "hidden" package is not visible to any buyers. 

    Hiding a package with associated deals will not affect the associated deals; however b uyers can not generate any new deals from the package.

1 
namestring

Read-only. The name of the visibility level for your package. Possible values: "console", "private", or "hidden".

  

Members

If visibility_type is set to "private", only the buyers listed in this array can view the package. If visibility_type is set to "console", all buyers can view the package but you can define a different ask price for each of the buyers listed in this array. Each member object in this array contains the following fields. 

Field

Type

Description

Default

Required On
id intThe member ID of the buyer.  
namestring

Read-only. The member name of the buyer.

Buyer's member name 
member_use_deal_floorBoolean

If true, the member_ask_price will be applied to deals that the buyer generates from the package. T his value will override any other floors you may have, i.e., in placements or yield management profiles.

The default_ask_price value will never apply to buyers in the members array. You must use the member_ask_price field to define an ask price for buyers listed in the members array.

true 
member_ask_priceint

The ask price that will be applied to deals the buyer generates from the package. When the buyer generates a deal, the Deal From Package Service will automatically calculate the floor_price by subtracting the seller revenue share specified in your AppNexus contract from the value in this field. This is the price shown to the buyer. It is the minimum they must bid in order to compete for the inventory.

If member_use_deal_floor is false, this field must be set to 0. In this case, note that although 0 is shown as the floor price, no deal floor is actually applied; if you have any other floors (in placements or yield management profiles), they will be applied, or if you do not have any other floors, the standard second-price auction mechanics will apply.

  

Setting

This information is used to give buyers a general understanding of the inventory included in the package. The setting object contains the following fields. 

Field

Type

Description

Default

Required On
has_inventoryBooleanSet this field to true if the profile associated with the package has publisher, placement, site, or content category targets set. For more information, see the profile_id field. false 
inventory_descriptionstring

If has_inventory is set to true, use this field to provide a description of the inventory included in the package. Buyers cannot see the specific targets you have set so it is important to provide them with additional insight into the package contents.

  
has_segmentsBoolean

Set this field to true if the profile associated with the package has segment or segment group targets set. For more information, see the profile_id field.

false   
segments_descriptionstring

If has_segments is set to true, use this field to provide a description of the segments included in the package. Buyers cannot see the specific targets you have set so it is important to provide them with additional insight into the package contents.

  
has_sizesBooleanSet this field to true if the profile associated with the package has size targets set. For more information, see the profile_id field. If you want buyers to see the specific sizes you have included, use the sizes field. false   

Sizes

Each object in the sizes array contains the following fields.

FieldTypeDescription
widthstringThe width of the creative.
heightstringThe size of the creative.

Technical Attributes

Each technical_attribute object contains the following fields:

Field

Type

Description

Default

Required On

id intThe ID of the technical attribute that is eligible for the package. You can use the Technical Attribute Service to retrieve technical attribute IDs.  
name stringThe name of the technical attribute that is eligible for the package.   
overrideBoolean

 Set to true to allow a technical attribute to serve for a package even if the ad quality profile would have blocked it.

false 

Allowed Media Types

You can use this array to limit the media type, the general display style of creatives, that can serve on placements that are part of deals made from this package.

Each allowed_media_types object contains the following fields:

Field

Type

Description

Default

Required On

idintThe ID of the media type.  
namestringThe name of the allowed media type, for example "Banner".  
media_type_group_idintThe group ID for the media type.  
uses_sizesenumWhether the media type has size specifications. Possible values:
  • always
  • sometimes
  • never
  
last_modifieddateWhen the allowed_media_type object was last updated.  

Allowed Media Subtypes

You can use this array to limit the media subtype, the specific display style of creatives, that can serve on placements that are part of deals made from this package.

Each allowed_media_subtypes object contains the following fields:

Field

Type

Description

Default

Required On

permitted_sizesarray of objects

The permitted sizes for creatives of the media subtype. See Permitted Sizes below for more details. Note that not all media subtypes have permitted size requirements.

  
native_assetsarray of objects

An array describing constraints on elements of native ads for this media subtype. Elements of a native ad can include the title, body content, and more. The format's constraints could be whether body content is required or recommended, or how long the text may be. For more information, see Native Assets below.

  
idintThe ID of the allowed_media_subtype. PUT and POST on JSON file  
namestring

The name of the allowed_media_subtype.

  
last_modifieddateWhen the allowed_media_subtype array was last modified.  
mediatype_idintThe ID of the media_type.  
media_type_namestringThe name of the media_type.  
media_type_group_idintThe ID of the group for the media type.  

Permitted Sizes

Each permitted_sizes object contains the following fields:

Field

Type

Description

Default

Required On

platform_widthint

The actual rendering width, in pixels, for creatives of this media subtype. This is also the width that appears in reporting.

  
platform_heightintThe actual rendering height, in pixels, for creatives of this media subtype. This is also the height that appears in reporting.  
validate_image_sizebooleanIf true, the image for creatives of this media subtype will be validated against the requirements defined by the following fields in this object:scaling_permittedaspect_ratio_tolerancemin_image_width,max_image_widthmin_image_height, and max_image_height.  
scaling_permittedboolean

If true, the image for creatives of this media subtype must have the same aspect ratio as platform_width / platform_height.

If false, the image for creatives of this media subtype must have a width and height exactly matching platform_width and platform_height.

  
aspect_ratio_tolerancedouble

If validate_image_size and scaling_permitted are both true , the image can deviate from the aspect ratio of platform_width and platform_height by this amount. For example, the aspect ratio for a platform_width and platform_height of 254x133 is 1.19:1. If the aspect_ratio_tolerance is 0.03, an aspect ratio between 1.16:1 and 1.22:1 would be acceptable.

  
min_image_widthintIf validate_image_size is true, the minimum acceptable image width, in pixels, for creatives of this media subtype.  
max_image_widthintIf validate_image_size is true , the maximum acceptable image width, in pixels, for creatives of this media subtype.  
min_image_heightintIf validate_image_size is true , the minimum acceptable image height, in pixels, for creatives of this media subtype.  
max_image_heightintIf validate_image_size is true , the maximum acceptable image height, in pixels, for creatives of this media subtype.  

Native Assets

Each native_assets object contains the following fields:

Field

Type

Description

Default

Required On

native_asset_namestring

The title of the ad.

  
min_text_length int

The minimum length for the text.

  
max_text_length int

The maximum length for the text.

  
requirementenum 

Whether this asset is required by this particular media subtype. This field can contain several levels of "requiredness":

  • "required"
  • "recommended"
  • "optional"
  

Examples

Create a new package for any buyer
Create a new package with custom pricing for selected buyers
Create a new package only visible to selected buyers
Modify a package
View all of your packages
 View a specific package
 Delete a package
  • No labels