Package service

Article
03/05/2024

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.

REST API

HTTP Method	Endpoint	Description
`POST`	`https://api.appnexus.com/package` (`add_package` JSON)	Add a new package.
`PUT`	`https://api.appnexus.com/package?id=PACKAGE_ID` (`modify_package` JSON)	Update a package.
`GET`	`https://api.appnexus.com/package`	View all of your packages.
`GET`	`https://api.appnexus.com/package?id=PACKAGE_ID`	View a specific package.
`DELETE`	`https://api.appnexus.com/package?id=PACKAGE_ID`	Delete a package. CAUTION: 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.
`GET`	`https://api.appnexus.com/package/meta`	Find out which fields you can filter and sort by.

JSON fields

Name	Type (Length)	Description
`id`	int	The ID of the package. Default: Auto-generated number Required On: `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. Default: `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. CAUTION: Any other targeting settings in the associated profile will not be respected. Required On: `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 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. Note: 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. Required On: `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. Default: `"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. Note: 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. Default: `true`
`last_modified`	timestamp	The day and time when the package was last modified.
`data_protected`	Boolean	Not yet supported. Default: `false`
`allow_creative_add_on_view`	Boolean	Not yet supported. Default: `false`
`allow_creative_add_on_click`	true	Not yet supported. Default: `true`
`visibility_profile_id`	int	Not yet supported. Default: `null`
`seller_rank`	int	The seller's ranking for the package. This controls where the package will appear in the seller's full list of packages in the UI. Allowed range: `1` - `65355`, where `1` is the highest ranking. Default: `100`
`size_preference`	enum	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_restrict`	Boolean	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. Default: `true`
`seller`	object	The name and ID of the seller who is offering the package. For more details, see Seller below. Required On: `POST`
`default_deal_type`	object	The deal type that will be applied to all deals generated from the package. For more details, see Default Deal Type below.
`visibility_type`	object	Defines if the package is visible to all buyers or select buyers. For more details, see Visibility Type below.
`members`	array 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.
`setting`	object	The type of content included in the package. For more details, see Setting below.
`technical_attributes`	array of objects	The technical attributes of creatives that are eligible for the package. For more details, see Technical Attributes below.
`sizes`	array of objects	If 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_priority`	Int	The bidding priority when `id` in the `default_deal_type` object = `2`/Private Auction. Possible values: `1` - `20`, where `20` is the highest priority. Default: `5`
`allowed_media_types`	array of objects	The media types allowed for the package. To learn more, see Allowed Media Types below.
`allowed_media_subtypes`	array of objects	The media subtypes allowed for the package. To learn more, see Allowed Media Subtypes below.
`media_preference`	string	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
`id`	int	Read-only. The member ID of the seller. Default: Seller's member ID Required On: `POST`
`name`	string	Read-only. The member name of the seller. Default: 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
`id`	int	The 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 Service. Default: `1`
`name`	string	Read-only. The name of the type of deal. Possible values: `"Open Auction"` or `"Private Auction"`. Default: `"Open Auction"`

Visibility type

The visibility_type object contains the following fields.

Field	Type	Description
`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. Note: Hiding a package with associated deals will not affect the associated deals; however buyers can not generate any new deals from the package. Default: `1`
`name`	string	Read-only. The name of the visibility level for your package. Possible values: - `"console"` - `"private"` - `"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
`id`	int	The member ID of the buyer.
`name`	string	Read-only. The member name of the buyer. Default: Buyer's member name
`member_use_deal_floor`	Boolean	If `true`, the `member_ask_price` will be applied to deals that the buyer generates from the package. This value will override any other floors you may have, i.e., in placements or yield management profiles. CAUTION: 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. Default: `true`
`member_ask_price`	int	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 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. Note: 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
`has_inventory`	Boolean	Set 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. Default: `false`
`inventory_description`	string	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_segments`	Boolean	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. Default: `false`
`segments_description`	string	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_sizes`	Boolean	Set 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. Default: `false`

Sizes

Each object in the sizes array contains the following fields.

Field	Type	Description
`width`	string	The width of the creative.
`height`	string	The size of the creative.

Technical attributes

Each technical_attribute object contains the following fields:

Field	Type	Description
`id`	int	The ID of the technical attribute that is eligible for the package. You can use the Technical Attribute Service to retrieve technical attribute IDs.
`name`	string	The name of the technical attribute that is eligible for the package.
`override`	Boolean	Set to `true` to allow a technical attribute to serve for a package even if the ad quality profile would have blocked it. Default: `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
`id`	int	The ID of the media type.
`name`	string	The name of the allowed media type, for example `"Banner"`.
`media_type_group_id`	int	The group ID for the media type.
`uses_sizes`	enum	Whether the media type has size specifications. Possible values: - `always` - `sometimes` - `never`
`last_modified`	date	When 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
`permitted_sizes`	array of objects	The permitted sizes for creatives of the media subtype. See Permitted Sizes below for more details. Note: Not all media subtypes have permitted size requirements.
`native_assets`	array 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.
`id`	int	The ID of the `allowed_media_subtype`. `PUT` and `POST` on JSON file
`name`	string	The name of the `allowed_media_subtype`.
`last_modified`	date	When the `allowed_media_subtype` array was last modified.
`mediatype_id`	int	The ID of the `media_type`.
`media_type_name`	string	The name of the `media_type`.
`media_type_group_id`	int	The ID of the group for the media type.

Permitted sizes

Each permitted_sizes object contains the following fields:

Field	Type	Description
`platform_width`	int	The actual rendering width, in pixels, for creatives of this media subtype. This is also the width that appears in reporting.
`platform_height`	int	The actual rendering height, in pixels, for creatives of this media subtype. This is also the height that appears in reporting.
`validate_image_size`	boolean	If `true`, the image for creatives of this media subtype will be validated against the requirements defined by the following fields in this object: `scaling_permitted`, `aspect_ratio_tolerance`, `min_image_width`, `max_image_width`, `min_image_height`, and `max_image_height`.
`scaling_permitted`	boolean	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_tolerance`	double	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_width`	int	If `validate_image_size` is `true`, the minimum acceptable image width, in pixels, for creatives of this media subtype.
`max_image_width`	int	If `validate_image_size` is `true`, the maximum acceptable image width, in pixels, for creatives of this media subtype.
`min_image_height`	int	If `validate_image_size` is `true`, the minimum acceptable image height, in pixels, for creatives of this media subtype.
`max_image_height`	int	If `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
`native_asset_name`	string	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.
`requirement`	enum	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

$ cat add_package

{
 "package":
  { "name" : "Package 1",
    "seller" : {
        "id" : 5555
        },
    "profile_id" : 555540,
    "default_ask_price" : "1.00"
  }
}

$ curl -b cookies -c cookies -X POST -d @add_package.json "https://api.appnexus.com/package"

{
    "response": {
        "status": "OK",
        "count": 1,
        "package": {
            "id": 109,
            "name": "Package 1",
            "description": null,
            "active": true,
            "profile_id": 555540,
            "default_ask_price": 1,
            "default_currency": "USD",
            "default_use_deal_floor": true,
            "last_modified": "2014-07-16 20:53:03",
            "seller": {
                "id": 5555,
                "name": "Seller 1"
            },
            "default_deal_type": {
                "id": 1,
                "name": "Open Auction"
            },
            "visibility_type": {
                "id": 1,
                "name": "console"
            },
            "members": null,
            "setting": null,
            "technical_attributes": null,
            "sizes": null
        }
    }
}

Create a new package with custom pricing for selected buyers

In this example, we create a new package that is visible to all buyers with a price of $3.00. For a few select buyers we set custom pricing below $3.00.

$ cat add_package_custom_pricing

{
 "package":
  { "name" : "Package 2",
    "seller" : {
        "id" : 5555
        },
    "profile_id" : 555540,
    "default_ask_price" : "1.00",
    "members" : [
          {
            "id": 5524,
            "member_use_deal_floor": true,
            "member_ask_price": 2.15,
            "name": "Buyer 1"
          },
          {
            "id": 5561,
            "member_use_deal_floor": true,
            "member_ask_price": 2.25,
            "name": "Buyer 2"
          }
        ]
  }
}

$ curl -b cookies -c cookies -X POST -d @add_package_custom_pricing.json "https://api.appnexus.com/package"

{
  "response": {
    "status": "OK",
    "count": 1,
    "package": {
      "id": 128,
      "name": "Package 2",
      "description": null,
      "active": true,
      "profile_id": 555540,
      "default_ask_price": 3,
      "default_currency": "USD",
      "default_use_deal_floor": true,
      "last_modified": "2014-08-19 20:55:15",
      "seller": {
        "id": 5555,
        "name": "Seller 1"
      },
      "default_deal_type": {
        "id": 1,
        "name": "Open Auction"
      },
      "visibility_type": {
        "id": 1,
        "name": "console"
      },
      "members": [
        {
          "id": 5524,
          "member_use_deal_floor": true,
          "member_ask_price": 2.15,
          "name": "Buyer 1"
        },
        {
          "id": 5561,
          "member_use_deal_floor": true,
          "member_ask_price": 2.25,
          "name": "Buyer 2"
        }
      ],
      "setting": null,
      "technical_attributes": null,
      "sizes": null
    }
  }
}

Create a new package only visible to selected buyers

In this example, we create a new package that is only visible to two buyers. We have set a different ask price for each buyer.

$ cat add_package_specific_buyer

{
 "package":
  { "name" : "Package 2",
    "seller" : {
        "id" : 5555
        },
    "profile_id" : 555540,
    "default_ask_price" : "3.00",
    "visibility_type" : {
        "id" : 2
    },
    "members" : [
          {
            "id": 5524,
            "member_use_deal_floor": true,
            "member_ask_price": 2.15,
            "name": "Buyer 1"
          },
          {
            "id": 5561,
            "member_use_deal_floor": true,
            "member_ask_price": 2.25,
            "name": "Buyer 2"
          }
        ]
  }
}

$ curl -b cookies -c cookies -X POST -d @add_package_specific_buyer.json "https://api.appnexus.com/package"

{
  "response": {
    "status": "OK",
    "count": 1,
    "package": {
      "id": 128,
      "name": "Package 2",
      "description": null,
      "active": true,
      "profile_id": 555540,
      "default_ask_price": 1,
      "default_currency": "USD",
      "default_use_deal_floor": true,
      "last_modified": "2014-08-19 20:55:15",
      "seller": {
        "id": 5555,
        "name": "Seller 1"
      },
      "default_deal_type": {
        "id": 1,
        "name": "Open Auction"
      },
      "visibility_type": {
        "id": 2,
        "name": "private"
      },
      "members": [
        {
          "id": 5524,
          "member_use_deal_floor": true,
          "member_ask_price": 2.15,
          "name": "Buyer 1"
        },
        {
          "id": 5561,
          "member_use_deal_floor": true,
          "member_ask_price": 2.25,
          "name": "Buyer 2"
        }
      ],
      "setting": null,
      "technical_attributes": null,
      "sizes": null
    }
  }
}

Modify a package

In this example, we update the name of the package.

$ cat modify_package

{
 "package":
  { "name" : "Updated Package 1"
  }
}

$ curl -b cookies -c cookies -X PUT -d @modify_package.json "https://api.appnexus.com/package?id=109

{
  "response": {
    "status": "OK",
    "count": 1,
    "package": {
      "id": 109,
      "name": "Updated Package 1",
      "description": null,
      "active": true,
      "profile_id": 555540,
      "default_ask_price": 1,
      "default_currency": "USD",
      "default_use_deal_floor": true,
      "last_modified": "2014-07-21 17:14:16",
      "seller": {
        "id": 5555,
        "name": "Tyroo Media Pvt. Ltd."
      },
      "default_deal_type": {
        "id": 1,
        "name": "Open Auction"
      },
      "visibility_type": {
        "id": 1,
        "name": "console"
      },
      "members": null,
      "setting": null,
      "technical_attributes": null,
      "sizes": null
    }
  }
}

View all of your packages

$ curl -b cookies -c cookies "https://api.appnexus.com/package"

{
  "response": {
    "status": "OK",
    "count": 2,
    "packages": [
      {
        "id": 108,
        "name": null,
        "description": null,
        "active": true,
        "profile_id": 555540,
        "default_ask_price": 1,
        "default_currency": "USD",
        "default_use_deal_floor": true,
        "last_modified": "2014-07-16 20:49:30",
        "seller": {
          "id": 5555,
          "name": "Tyroo Media Pvt. Ltd."
        },
        "default_deal_type": {
          "id": 1,
          "name": "Open Auction"
        },
      "visibility_type": {
        "id": 1,
        "name": "console"
      },
      "members": null,
      "setting": null,
      "sizes": null
      },
      {
        "id": 109,
        "name": "Updated Package 1",
        "description": null,
        "active": true,
        "profile_id": 555540,
        "default_ask_price": 1,
        "default_currency": "USD",
        "default_use_deal_floor": true,
        "last_modified": "2014-07-21 17:14:16",
        "seller": {
          "id": 5555,
          "name": "Tyroo Media Pvt. Ltd."
        },
        "default_deal_type": {
          "id": 1,
          "name": "Open Auction"
        },
      "visibility_type": {
        "id": 1,
        "name": "console"
      },
      "members": null,
      "setting": null,
      "technical_attributes": null,
      "sizes": null
      }
    ]
  }
}

View a specific package

$ curl -b cookies -c cookies "https://api.appnexus.com/package?id=109"

{
  "response": {
    "status": "OK",
    "count": 1,
    "package": {
      "id": 109,
      "name": "Updated Package 1",
      "description": null,
      "active": true,
      "profile_id": 555540,
      "default_ask_price": 1,
      "default_currency": "USD",
      "default_use_deal_floor": true,
      "last_modified": "2014-07-21 17:14:16",
      "seller": {
        "id": 5555,
        "name": "Tyroo Media Pvt. Ltd."
      },
      "default_deal_type": {
        "id": 1,
        "name": "Open Auction"
      },
      "visibility_type": {
        "id": 1,
        "name": "console"
      },
      "members": null,
      "setting": null,
      "technical_attributes": null,
      "sizes": null
    }
  }
}

Delete a package

$ curl -b cookies -c cookies -DELETE "https://api.appnexus.com/package?id=109"

{
  "response": {
    "status": "OK",
    "count": 1
  }
}

Share via