Ad Rules Change Spec

This page discusses the change_spec in more detail, specifically on how to construct the execution option and how to use the more advanced features.

The change_spec is used for execution types such as CHANGE_BUDGET and CHANGE_BID, and contains the following parameters: amount, limit, unit, target_field.

Field	Description
`amount`	Required. Determines the amount to change the budget or bid. The values of other parameters in the `change_spec` determine exactly how this amount is used. Supported Values: A numeric value, such as `3000` or `-50`
`limit`	Optional. Specifies the maximum or minimum budget or bid amount. For example, if budget or bid are being increased, this number acts as an upper limit. If `target_field` is present, this specifies a range from the lower bound to the upper bound of values. Supported Values: Currency, such as `5000` to represent $50 USD, or for `target_field`, a range of currencies such as `[4000, 6000]` to represent $40 to $60 USD.
`unit`	Required, unless `target_field` is present. Specifies the unit of the `amount` value. For example, if the unit is `PERCENTAGE`, an `amount` of `-50` means `-50%`. Supported Values: `ACCOUNT_CURRENCY` or `PERCENTAGE`
`target_field`	Optional. Specifies whether or not to scale budgets or bids by a target value. If this is present, `amount` is the target value of the target field. Budget or bid are increased or decreased proportionally, based on whether the ad set's current value for the target field is lower or higher than the `amount`. Supported Values: An Insights field, such as `cost_per_mobile_app_install` or `mobile_app_purchase_roas`

Examples

Here's an example of a CHANGE_BUDGET rule that decreases budgets by 30% for all under-performing ad sets, where we define under-performing as stably having a high lifetime frequency. This rule only runs at midnight on Tuesdays and Fridays.

curl \
-F 'name=Test Change Budget Rule' \
-F 'schedule_spec={
     "schedule_type": "CUSTOM",
     "schedule": [
       {
          "start_minute": 0,
         "days": [2, 5]
       }
     ]
   }' \
-F 'evaluation_spec={
     "evaluation_type": "SCHEDULE",
     "filters": [
       {
         "field": "entity_type",
         "value": "ADSET",
         "operator": "EQUAL"
       },
       {
         "field": "time_preset",
         "value": "LIFETIME",
         "operator": "EQUAL"
       },
       {
         "field": "impressions",
         "value": 8000,
         "operator": "GREATER_THAN"
       },
       {
         "field": "frequency",
         "value": 5.0,
         "operator": "GREATER_THAN"
       }
     ]
   }' \
-F 'execution_spec={
     "execution_type": "CHANGE_BUDGET",
     "execution_options": [
       {
         "field": "change_spec",
         "value": {
           "amount": -30,
           "unit": "PERCENTAGE"
         },
         "operator": "EQUAL"
       },
     ]
   }' \
-F "access_token=<ACCESS_TOKEN>" \
https://graph.facebook.com/<VERSION>/<AD_ACCOUNT_ID>/adrules_library

Here's another example, where the bid is scaled daily based on a target cost_per_mobile_app_install value for ad set 123.

We also add a range filter for cost_per_mobile_app_install to introduce a 10% tolerance window. By having this, minor proportional changes are not done, if current value is close enough to the target value.

curl \
-F 'name=Test Change Bid Rule' \
-F 'schedule_spec={
     "schedule_type": "DAILY"
   }' \
-F 'evaluation_spec={
     "evaluation_type": "SCHEDULE",
     "filters": [
       {
         "field": "id",
         "value": [123],
         "operator": "IN"
       },
       {
         "field": "time_preset",
         "value": "LIFETIME",
         "operator": "EQUAL"
       },
       {
         "field": "mobile_app_install",
         "value": 100,
         "operator": "GREATER_THAN"
       },
       {
         "field": "cost_per_mobile_app_install",
         "value": [4.5, 5.5],
         "operator": "NOT_IN_RANGE"
       }
     ]
   }' \
-F 'execution_spec={
     "execution_type": "CHANGE_BID",
     "execution_options": [
       {
         "field": "change_spec",
         "value": {
           "amount": 5.0,
           "limit": [2.0, 10.0],
           "target_field": "cost_per_mobile_app_install"
         },
         "operator": "EQUAL"
       },
     ]
   }' \
-F "access_token=<ACCESS_TOKEN>" \
https://graph.facebook.com/<VERSION>/<AD_ACCOUNT_ID>/adrules_library

For example, if current value is 4.0, the bid is increased by 25%, since that is the proportional difference between the target value of 5.0 and the current value.

The limit keeps the bid from increasing above 10.0 and decreasing below 2.0.