This doc 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 Supported Values

amount

Required field that determines the amount to change the budget or bid. The values of other parameters in the change_spec will determine exactly how this amount is used.

A numeric value, such as 3000 or -50

limit

Optional field that specifies the maximum or minimum budget or bid amount. For example, if we are increasing the budget or bid, this acts as an upper limit. If target_field is present, this specifies a range from the lower bound to the upper bound of 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

Optional field that specifies the unit of the amount value. For example, if the unit is PERCENTAGE, an amount of -50 means -50%. This is required unless target_field is present, in which case this has no meaning.

ACCOUNT_CURRENCY or PERCENTAGE

target_field

Optional field that specifies whether or not we are scaling budgets or bids by a target value. If this is present, amount will be the target value of the target field. We will increase or decrease the budget or bid proportionally based on whether the Ad Set's current value for the target field is lower or higher than the amount.

An Insights field, such as cost_per_mobile_app_install or mobile_app_purchase_roas

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. We will run this rule only 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 we scale the bid daily based on a target cost_per_mobile_app_install value for some Ad Set 123.

We also add a range filter for cost_per_mobile_app_install to introduce a 10% tolerance window. By having this range filter, we won't be making minor proportional changes if our 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 our current value is 4.0, we will increase the bid by 25%, since that is the proportional difference between the target value of 5.0 and the current value. The limit keeps us from increasing bid above 10.0 and decreasing bid below 2.0.