Run flag deliveries (targeted delivery)

10 min

A targeted delivery is a type of rule for a flag that lets you:

Control who sees your flag.

Gradually increase or roll out the flag to more users.

Roll back the flag if you encounter bugs or other problems.

For information, see Flag deliveries.

Create a targeted delivery (flag delivery)

Prerequisites

Before creating a targeted delivery, complete the following:

Create a flag in your Feature Experimentation project.

Handle user IDs.

Note You should configure a user profile service to ensure consistent user bucketing if you are using a server-side SDK.

If you have not done so yet, implement the Optimizely Feature Experimentation SDK's Decide method in your application's codebase through a flag.

Ensure you are using the following compatible SDK versions:

Swift – v3.3.2 and higher.

Agent – v1.1.0 and higher.

Go – v1.2.0 and higher.

Flutter – v1.0.0-beta or higher.

All other SDKs – v2.0.0 and higher.

See SDK compatibility matrix for details.

With the Feature Experimentation REST API

Use the Update the Ruleset for a Flag in an Environment endpoint to add the rule with the rule's type set to targeted_delivery.

Important For PATCH requests, first GET the current ruleset, merge only the fields you need to change, and then send the PATCH. This helps prevent overwriting existing settings you did not intend to modify.

Endpoints – PATCH https://api.optimizely.com/flags/v1/projects/PROJECT_ID/flags/FLAG_KEY/environments/ENVIRONMENT_KEY/ruleset

Authentication – Include your API key in the Authorization header as a Bearer token. See Generate tokens and use the REST APIs.

Request example

curl --request PATCH \
     --url https://api.optimizely.com/flags/v1/projects/PROJECT_ID/flags/FLAG_KEY/environments/ENVIRONMENT_KEY/ruleset \
     --header 'accept: application/json' \
     --header 'authorization: Bearer TOKEN' \
     --header 'content-type: application/json-patch+json' \
     --data '
[
    {
        "op": "add",
        "path": "/rules/landing_page_targeted_delivery",
        "value": {
            "key": "landing_page_targeted_delivery",
            "name": "Targeted Delivery for the landing page",
            "type": "targeted_delivery",
            "variations": {
                "on": {
                    "key": "on",
                    "name": "on",
                    "percentage_included": 10000
                }
            }
        }
    }
]
'

Response example

{
  "url": "/projects/PROJECT_ID/flags/targeted-delivery-flag/environments/development/ruleset",
  "update_url": "/projects/PROJECT_ID/flags/targeted-delivery-flag/environments/development/ruleset",
  "enable_url": "/projects/PROJECT_ID/flags/targeted-delivery-flag/environments/development/ruleset/enabled",
  "rules": {
    "landing_page_targeted_delivery": {
      "key": "landing_page_targeted_delivery",
      "name": "Targeted Delivery for the landing page",
      "description": "",
      "variations": {
        "on": {
          "key": "on",
          "name": "On",
          "percentage_included": 10000,
          "variation_id": 1500954,
          "id": 6669573
        }
      },
      "baseline_variation_id": null,
      "type": "targeted_delivery",
      "id": 1598837,
      "urn": "rules.flags.optimizely.com::1598837",
      "archived": false,
      "enabled": false,
      "created_time": "2025-09-12T20:14:49.374112Z",
      "updated_time": "2025-09-12T20:14:49.365774Z",
      "audience_conditions": [],
      "audience_ids": [],
      "percentage_included": 10000,
      "metrics": [],
      "allow_list": {},
      "layer_id": 9300001985290,
      "layer_experiment_id": 9300002731002,
      "status": "draft"
    }
  },
  "rule_priorities": [
    "landing_page_targeted_delivery"
  ],
  "id": 1881462,
  "urn": "rulesets.flags.optimizely.com::1881462",
  "archived": false,
  "enabled": false,
  "updated_time": "2025-09-12T20:14:49.432395Z",
  "flag_key": "targeted-delivery-flag",
  "environment_key": "development",
  "environment_name": "Development",
  "environment_id": 761744660106841,
  "default_variation_key": "off",
  "default_variation_name": "Off",
  "revision": 2,
  "status": "draft",
  "role": "admin"
}

See the Update the Ruleset for a Flag in an Environment endpoint reference documentation for information on creating a targeted delivery with the Feature Experimentation API.

With the Feature Experimentation UI

See Run flag deliveries (targeted delivery) in Feature Experimentation in the user documentation.

Run the targeted delivery (flag delivery)

Start your targeted delivery rule and flag (if it is not already running).

With the REST API

Enable the flag by using the Enable the Ruleset for a Flag in an Environment endpoint.

Endpoint – POST https://api.optimizely.com/flags/v1/projects/PROJECT_ID/flags/FLAG_KEY/environments/ENVIRONMENT_KEY/ruleset/enabled

Authentication – Include your API key in the Authorization header as a Bearer token. See Generate tokens and use the REST APIs.

Request example

curl --request POST \
     --url https://api.optimizely.com/flags/v1/projects/PROJECT_ID/flags/FLAG_KEY/environments/ENVIRONMENT_KEY/ruleset/enabled \
     --header 'accept: application/json' \
     --header 'authorization: Bearer TOKEN'

Response example

{
  "url": "/projects/PROJECT_ID/flags/targeted-delivery-flag/environments/development/ruleset",
  "update_url": "/projects/PROJECT_ID/flags/targeted-delivery-flag/environments/development/ruleset",
  "disable_url": "/projects/PROJECT_ID/flags/targeted-delivery-flag/environments/development/ruleset/disabled",
  "rules": {
    "landing_page_targeted_delivery": {
      "key": "landing_page_targeted_delivery",
      "name": "Targeted Delivery for the landing page",
      "description": "",
      "variations": {
        "on": {
          "key": "on",
          "name": "On",
          "percentage_included": 10000,
          "variation_id": 1500954,
          "id": 6669573
        }
      },
      "baseline_variation_id": null,
      "type": "targeted_delivery",
      "id": 1598837,
      "urn": "rules.flags.optimizely.com::1598837",
      "archived": false,
      "enabled": false,
      "created_time": "2025-09-12T20:14:49.374112Z",
      "updated_time": "2025-09-12T20:21:31.718454Z",
      "audience_conditions": [],
      "audience_ids": [],
      "percentage_included": 10000,
      "metrics": [],
      "allow_list": {},
      "layer_id": 9300001985290,
      "layer_experiment_id": 9300002731002,
      "status": "draft"
    }
  },
  "rule_priorities": [],
  "id": 1881462,
  "urn": "rulesets.flags.optimizely.com::1881462",
  "archived": false,
  "enabled": true,
  "updated_time": "2025-09-12T20:21:31.718454Z",
  "flag_key": "targeted-delivery-flag",
  "environment_key": "development",
  "environment_name": "Development",
  "environment_id": 761744660106841,
  "default_variation_key": "off",
  "default_variation_name": "Off",
  "revision": 3,
  "status": "running",
  "role": "admin"
}

Launch your targeted delivery by enabling the rule by using the Update the Ruleset for a Flag in an Environment endpoint and setting the enabled path to true.

Endpoint – PATCH https://api.optimizely.com/flags/v1/projects/PROJECT_ID/flags/FLAG_KEY/environments/ENVIRONMENT_KEY/ruleset

Authentication – Include your API key in the Authorization header as a Bearer token. See Generate tokens and use the REST APIs.

Request example

curl --request PATCH \
     --url https://api.optimizely.com/flags/v1/projects/PROJECT_ID/flags/targeted-delivery-flag/environments/development/ruleset \
     --header 'accept: application/json' \
     --header 'authorization: Bearer TOKEN' \
     --header 'content-type: application/json-patch+json' \
     --data '
[
   {
      "op": "replace",
      "path": "/rules/landing_page_targeted_delivery/enabled",
      "value": true
   }
]
'

Response example

{
  "url": "/projects/PROJECT_ID/flags/targeted-delivery-flag/environments/development/ruleset",
  "update_url": "/projects/PROJECT_ID/flags/targeted-delivery-flag/environments/development/ruleset",
  "disable_url": "/projects/PROJECT_ID/flags/targeted-delivery-flag/environments/development/ruleset/disabled",
  "rules": {
    "landing_page_targeted_delivery": {
      "key": "landing_page_targeted_delivery",
      "name": "Targeted Delivery for the landing page",
      "description": "",
      "variations": {
        "on": {
          "key": "on",
          "name": "On",
          "percentage_included": 10000,
          "variation_id": 1500954,
          "id": 6669615
        }
      },
      "baseline_variation_id": null,
      "type": "targeted_delivery",
      "id": 1598837,
      "urn": "rules.flags.optimizely.com::1598837",
      "archived": false,
      "enabled": true,
      "created_time": "2025-09-12T20:14:49.374112Z",
      "updated_time": "2025-09-12T20:26:05.310167Z",
      "audience_conditions": [],
      "audience_ids": [],
      "percentage_included": 10000,
      "metrics": [],
      "allow_list": {},
      "layer_id": 9300001985290,
      "layer_experiment_id": 9300002731002,
      "status": "running"
    }
  },
  "rule_priorities": [
    "landing_page_targeted_delivery"
  ],
  "id": 1881462,
  "urn": "rulesets.flags.optimizely.com::1881462",
  "archived": false,
  "enabled": true,
  "updated_time": "2025-09-12T20:26:05.381855Z",
  "flag_key": "targeted-delivery-flag",
  "environment_key": "development",
  "environment_name": "Development",
  "environment_id": 761744660106841,
  "default_variation_key": "off",
  "default_variation_name": "Off",
  "revision": 4,
  "status": "running",
  "role": "admin"
}

With the Feature Experimentation UI

See Run flag deliveries (targeted delivery) in Feature Experimentation in the user documentation.

Implement the delivery

After you implement your flag, no further implementation is required for the delivery. Optimizely Feature Experimentation uses the decide call you created when you implemented the feature flag to decide if a user qualifies for the delivery rule or not and which variation they receive.

Note A user evaluates against all the rules in a ruleset in order before being bucketed into a given rule's variation. See interactions between flag rules.

Deliveries are used to launch features, so no decision events show up on the results page. To measure the impact of a flag and track metrics on your results page, create an experiment, such as an A/B test, instead of a targeted delivery.

Important Before running an experiment and delivery rule for the same flag at the same time, you must understand how flag rules interact.