Submit a request
 
PRODUCT
Privacy Policy |  AAS Advertising Policy | Terms of Use
Cookie Preference
✖

Amazon Ad Server will be sunset in Q4 2024, please visit this page (AAS offboarding information) for offboarding support resources and sunset FAQs. Details shared on that page represent the most up to date information in the Help Center, if you find disparate information in other resources please default to the information in the AAS offboarding information page accordingly.

Please note that on October 1, 2024, the ability to create new campaigns, placements, and tag managers will be disabled.

Follow
Last Update:
  viewable by end users
  editable by agents

Related Entities

Endpoints Using the rootContainer Object

Parent Objects

rootContainer Object Definition

Note

Note: The Required column includes the following values:

  • Required: The field must be included in the POST call.

  • Read-only: The field is received in the GET call and required in the PUT call. It is not required in the POST call. You cannot edit this field.

  • Optional: If the field was received in the GET call, include it in the PUT call. This field is editable.

  • Internal: (For Amazon Ad Server (AAS) internal use) If the field was received in the GET call, include it in the PUT call.

Name

Description

Type

Required

Notes

type

String

Read-only

RootContainer

id

ID of the delivery group.

Integer

Read-only

relationsBag

Holds hierarchy entities (parent/children).

relationsBag Object

Read-only

version

Internal.

Integer

Read-only

childRotationType

Rotation type of subcontainers.

String

Required

subContainers

List of all base ad containers attached to this delivery group.

subContainers Object

Optional

childOptimizationMetric

Metric towards which the automatic optimization engine optimizes when the selected rotation method for a delivery group is automatic optimization.

String

Required

childConversionTagId

ID of the conversion tag towards which to optimize when the selected optimization metric is conversions.

Integer

Required

childConversionTagName

Name of the tag towards which the automatic optimization engine is optimizing.

String

Optional

Object JSON Example

Example
 "rootContainer": {
                "type": "RootContainer",
                "id": null,
                "relationsBag": null,
                "version": null,
                "childRotationType": "EvenDistribution",
                "subContainers": [
                    {
                        "type": "DeliveryGroupAd",
                        "id": 1073786333,
                        "rotationSetting": {
                            "type": "EvenDistribution",
                            "enabled": true,
                            "rotationType": "EvenDistribution",
                            "weight": 100
                        },
                        "masterAdId": 1074034054,
                        "name": "Moran1511201666419",
                        "adName": null
                    }
                ],
                "childOptimizationMetric": null,
                "childConversionTagId": null,
                "childConversionTagName": null
            },

relationsBag Object

This object enables you to view the parent object of an object, for example, the account ID and name of an advertiser. This saves time because you do not need to call another call to get these details.

relationsBag Object Definition

Note

Note: The Required column includes the following values:

  • Required: The field must be included in the POST call.

  • Read-only: The field is received in the GET call and required in the PUT call. It is not required in the POST call. You cannot edit this field.

  • Optional: If the field was received in the GET call, include it in the PUT call. This field is editable.

  • Internal: (For Amazon Ad Server (AAS) internal use) If the field was received in the GET call, include it in the PUT call.

Name

Description

Type

Required

Notes

parents

This is an object of the entities that are related to this object, and depends on the object type.For example, a campaign will include "account", "advertiser", and "brand" data.

An advertiser will only include the "account".

Parents Object

Read-only

children

Includes the count of the related entities.

Children Object

Read-only

creativeAccountContact

Internal.

Boolean

Read-only

Object JSON Example

Example
"relationsBag": {
        "parents": {
                "account": {
                        "id": 16674,
                        "name": "[TEST] migrated account",
                        "internal": true
                },
                "advertiser": null,
                "brand": null,
                "campaign": null,
                "site": null
        },
        "children": {
                "advertisers": {
                        "count": 0
                },
                "brands": {
                        "count": 1
                },
                "campaigns": {
                        "count": 231
                },
                "users": {
                        "count": 0
                }
        },
        "creativeAccountContact": false
},

Parents Object

Parents Object Definition

Name

Description

Type

Required

Notes

account

Parent account of current entity (if applicable).

Object

Read-Only

Example:

{
 "id": 1072241834,
 "name": "testing account",
 "internal": false
 }

advertiser

Parent advertiser of current entity (if applicable).

Object

Read-Only

Example:

{
 "id": 1073741822,
 "name": "AAA"
 }

brand

Parent brand of current entity (if applicable).

Object

Read-Only

Example:

 {
 "id": 1073741833,
 "name": "BBB"
 }

campaign

Parent campaign of current entity (if applicable).

Object

Read-Only

Example:

 {
 "id": 1073741831,
 "name": "ccc"
 }

site

Parent site of current entity (if applicable).

Object

Read-Only

Example:

 {
 "id": 1073741853,
 "name": "ddd"
 }
Object JSON Example
Example
"parents": {
        "account": {
                "id": 1072241834,
                "name": "testing account",
                "internal": false
        },
        "advertiser": {
                "id": 1073741822,
                "name": "AAA"
        },
        "brand": {
                "id": 1073741833,
                "name": "BBB"
        },
        "campaign": null,
        "site": null
},

Children Object

Children Object Definition

Name

Description

Type

Required

Notes

advertisers

Contains the count of child advertisers (if applicable).

Object

Read-Only

brands

Contains the count of child brands (if applicable).

Object

Read-Only

campaigns

Contains the count of child campaigns (if applicable).

Object

Read-Only

users

Contains the count of child users (if applicable).

Object

Read-Only
Object JSON Example
Example
"children": {
        "advertisers": {
                "count": 0
        },
        "brands": {
                "count": 1
        },
        "campaigns": {
                "count": 231
        },
        "users": {
                "count": 0
        }
}

subContainers Object

subContainers Object Definition

Note

Note: The Required column includes the following values:

  • Required: The field must be included in the POST call.

  • Read-only: The field is received in the GET call and required in the PUT call. It is not required in the POST call. You cannot edit this field.

  • Optional: If the field was received in the GET call, include it in the PUT call. This field is editable.

  • Internal: (For Amazon Ad Server (AAS) internal use) If the field was received in the GET call, include it in the PUT call.

Name

Description

Type

Required

Notes

type

Type of object.

String

Read-only

subContainers

id

ID of the delivery group.

Integer

Read-only

rotationSetting

Rotation type.

rotationSetting Object

Required

masterAdId

Master ad ID for the delivery group ad.

Long

Required

name

Name of the ad.

String

Read-only

adName

Deprecated.

Deprecated

Deprecated

Object JSON Example

Example
 "rootContainer": {
                "type": "RootContainer",
                "id": null,
                "relationsBag": null,
                "version": null,
                "childRotationType": "EvenDistribution",
                "subContainers": [
                    {
                        "type": "DeliveryGroupAd",
                        "id": 1073786333,
                        "rotationSetting": {
                            "type": "EvenDistribution",
                            "enabled": true,
                            "rotationType": "EvenDistribution",
                            "weight": 100
                        },
                        "masterAdId": 1074034054,
                        "name": "Name",
                        "adName": null
                    }
                ],
                "childOptimizationMetric": null,
                "childConversionTagId": null,
                "childConversionTagName": null
            },

rotationSetting Object

rotationSetting Object Definition

Note

Note: The Required column includes the following values:

  • Required: The field must be included in the POST call.

  • Read-only: The field is received in the GET call and required in the PUT call. It is not required in the POST call. You cannot edit this field.

  • Optional: If the field was received in the GET call, include it in the PUT call. This field is editable.

  • Internal: (For Amazon Ad Server (AAS) internal use) If the field was received in the GET call, include it in the PUT call.

Name

Description

Type

Required

Notes

type

Type of object.

String

Read-only

rotationSetting

enabled

Status of the ad.

Boolean

Required

rotationType

Type of rotation.

String

Required
View values

  • EvenDistribution

  • Weighted

  • TimeBased

  • Sequence

  • AdvancedSequence

datesAccordingToPlacements

Determines if a date range is specified for the placement.

Boolean

Required

Inherited from placement = true

startDate

Serving start date for the delivery group.

String

Required

Applicable only for time-based rotation.

endDate

Serving end date for the delivery group.

String

Required

Applicable only for time-based rotation.

dateRanges

Internal.

Internal

Internal

serveOnSpecificDaysAndHours

Settings for a range of hours.

Boolean

Required

Select true if you are using hours-based.

hoursPerDay

Cron expression that defines the days, in hours, in which the delivery group will be served.

hoursPerDay Object

Required
Object JSON Example
Example
...
"subContainers": [{
        "type": "DeliveryGroupAd",
        "id": 1073786333,
        "rotationSetting": {
            "type": "TimeBased",
            "enabled": true,
            "rotationType": "TimeBased",
            "datesAccordingToPlacements": true,
            "startDate": null,
            "endDate": null,
            "dateRanges": [{
                "type": "APIDateRange",
                "startDate": 1577232000000,
                "endDate": 1577404799999
            }],
            "serveOnSpecificDaysAndHours": false,
            "hoursPerDay": null
        },
...

hoursPerDay Object

hoursPerDay Object Definition

Note

Note: The Required column includes the following values:

  • Required: The field must be included in the POST call.

  • Read-only: The field is received in the GET call and required in the PUT call. It is not required in the POST call. You cannot edit this field.

  • Optional: If the field was received in the GET call, include it in the PUT call. This field is editable.

  • Internal: (For Amazon Ad Server (AAS) internal use) If the field was received in the GET call, include it in the PUT call.

NAME

DESCRIPTION

TYPE

REQUIRED

NOTES

hoursPerDay

Defines the days, in hours, in which the delivery group will be served.

Cron expression

Required
Object JSON Example
Example
"hoursPerDay": ["* * 0-23 ? * 2", "* * 0-5 ? * 3", "* * 0-23 ? * 4", "* * 7-23 ? * 5", "* * 0-23 ? * 6"]
About Cron Expressions

Cron is a time-based job scheduler; the cron expression defines the entire setup in one single expression. In Amazon Ad Server (AAS), we use cron jobs in time-based serving to determine which hours and days of the week to serve creatives.

Building Cron Expressions
Cron Expression Structure

The cron expression has a defined structure. You define the different time parameters, and each parameter is separated by a space.

The structure is as follows:

<second> <minute> <hour> <day-of-month> <month> <day-of-week> <year>

Special Characters in Cron Expressions

Special characters in cron expressions include the following:

  • * (all): Specifies all of the values for a specific set. For example, setting * in the hours field means an ad serves each hour during a 24 hour period.

  • ? (any): Specifies any value for a specific set, and applies only to <Day-of-month> and <Day-of-week>.

  • - (range): Specifies a range of values. For example, setting 2 - 4 in the hour field, means the creative serves at 02:00 a.m., 03:00 a.m., and 04:00 a.m.

Note

Note: Set each day with a separate cron expression. For example, if you want to serve an ad on Friday and Saturday, between 02:00 a.m. - 03:00 a.m., add two cron expressions (comma separated) to the HoursPerDay object.

"hoursPerDay": ["* * 2-3 ? * 6", "* * 2-3 ? * 7"]
Object Fields and Values

The following table describes the object fields and values for cron expressions.

Note

Note: Currently, Amazon Ad Server (AAS) only supports six-character cron expressions.

Name

Required

Values

Notes

second

Yes

*

Not supported

minute

Yes

*

Not supported

hour

Yes

Any number between 0 and 23. For a range, use “-“.

Example

  • 0 = midnight – 01:00 a.m.

  • 1 = 01:00 a.m. – 02:00 a.m.

day-of-month

Yes

?

Not supported

month

Yes

*

Not supported. To specify a month, set a start date and end date under Rotation Setting object.

day-of-week

Yes

Any number between 1 and 7.

  • Sunday = 1

  • Monday = 2

  • Tuesday = 3

  • Wednesday = 4

  • Thursday = 5

  • Friday = 6

  • Saturday = 7

year

Yes

*

Not supported. Serves according to the specified start date and end date under Rotation Setting object.
Cron Expression Examples

  • Serving for weekdays (Monday – Friday), each hour during a 24 hour period

    "hoursPerDay":
["* * 0-23 ? * 2", "* * 0-23 ? * 3", "* * 0-23 ? * 4", "* * 0-23 ? * 5", "* * 0-23 ? * 6"]

  • Serving for weekends (Friday - Saturday), from 08:00 a.m. to 08:00 p.m.

    hoursPerDay: ["* * 8-19 ? * 7", "* * 8-19 ? * 1"]

  • Serving for only one hour, Sunday 08:00 a.m. - 09:00 a.m.

     "hoursPerDay": ["* * 8 ? * 1"]
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments