--- title: Run flag deliveries (targeted delivery) slug: feature-experimentation/docs/run-flag-deliveries docTags: createdAt: 2026-08-05T20:39:57.000Z --- 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](docId\:rQ6XFXI9Pk9rQOZw57zeb). ## Create a targeted delivery (flag delivery) ### Prerequisites Before creating a targeted delivery, complete the following: 1. [Create a flag](docId\:eH-UMm_rOn_GdGDGLV6__) in your Feature Experimentation project. 2. [Handle user IDs](docId\:j0PPoMJWYbz04K76EKLUI). :::hint{type="info"} **Note** You should configure a [user profile service](docId:0mbVhcaiWJm6M96ZohwI-) to ensure consistent user bucketing if you are using a server-side SDK. ::: 3. If you have not done so yet, [implement the Optimizely Feature Experimentation SDK's Decide method](docId\:R0KSPrSRYev0Q6jXL27QK) in your application's codebase through a [flag](docId\:eH-UMm_rOn_GdGDGLV6__). 4. 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](docId:2shbZfPCkPAZ0mlZpL1TU) for details. ### With the Feature Experimentation REST API Use the [Update the Ruleset for a Flag in an Environment](docId\:wpUSoZjCEhG6L1zPVvfhf) endpoint to add the rule with the rule's `type` set to `targeted_delivery`. :::hint{type="warning"} **Important** For `PATCH` requests, first [\`GET the current ruleset\`](docId\:TxxX0KcGkrO_cG331nADs), 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](docId\:pQfa5KPTbmy6crey-nsrd). **Request example** ```curl 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** ```json { "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](docId\:wpUSoZjCEhG6L1zPVvfhf) 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](docId:_BjMxuGwwlVrhkNcx2kzm) 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 1. Enable the flag by using the [Enable the Ruleset for a Flag in an Environment](docId:3EqUxeVRs0Ew1Pbe6yCII) 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](docId\:pQfa5KPTbmy6crey-nsrd). - **Request example** ```curl 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' ``` :::Paragraph{listStyleType="disc" indent="2"} **Response example** ::: ```json { "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" } ``` 2. Launch your targeted delivery by enabling the rule by using the [Update the Ruleset for a Flag in an Environment](docId\:wpUSoZjCEhG6L1zPVvfhf) endpoint and setting the `enabled` path to `true`. :::hint{type="warning"} **Important** For `PATCH` requests, first [\`GET the current ruleset\`](docId\:TxxX0KcGkrO_cG331nADs), 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. ::: :::Paragraph{listStyleType="disc" indent="2"} **Endpoint** – `PATCH https://api.optimizely.com/flags/v1/projects/PROJECT_ID/flags/FLAG_KEY/environments/ENVIRONMENT_KEY/ruleset` ::: :::Paragraph{listStyleType="disc" indent="2"} **Authentication** – Include your API key in the `Authorization` header as a Bearer token. See [Generate tokens and use the REST APIs](docId\:pQfa5KPTbmy6crey-nsrd). ::: :::Paragraph{listStyleType="disc" indent="2"} **Request example** ::: ```curl 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 } ] ' ``` :::Paragraph{listStyleType="disc" indent="2"} **Response example** ::: ```json { "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](docId:_BjMxuGwwlVrhkNcx2kzm) 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\`](docId\:Mq8a-0tyTzM32HEt362lj) you created when you [implemented the feature flag](docId\:eH-UMm_rOn_GdGDGLV6__) to decide if a user qualifies for the delivery rule or not and which variation they receive. :::hint{type="info"} **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](docId:_4OpAAw99L5HVhT-OCJTW). ::: Deliveries are used to launch features, so no [decision events](docId\:SzVcfUMHk3IKycnEjgjbq) show up on the [results page](docId:_K6n7h_MZ8b0xn6yWPrrq). To measure the impact of a flag and track metrics on your results page, create an experiment, such as an [A/B test](docId:8pnfCv-sR37goLcxTtCPv), instead of a targeted delivery. :::hint{type="warning"} **Important** Before running an experiment and delivery rule for the **same flag** at the **same time**, you must understand how [flag rules interact](docId:_4OpAAw99L5HVhT-OCJTW). :::