How to Utilize Modifiers with the Pull Job Management API

---

The Pull Job Management API lets items on the Retail UI carry modifiers, so partners can offer customizable hot and prepared foods — such as build your own bowls, sandwiches, and customized drinks — alongside their standard retail catalog.

note

New to inventory pulls? Start with Set up Inventory Pull before configuring modifiers, since every modifier update flows through a pull job.

Prerequisites

To configure modifiers, you'll need:

• An existing test store with a catalog.
• The ability to perform inventory updates through the pull job management process.
• A heads-up to your DoorDash technical account manager that you intend to implement modifiers, plus confirmation that your store is configured correctly.

Endpoints used

Modifiers touch three endpoints across the integration flow:

Step	Endpoint	Purpose
Configure items	batchAddStoreItem	Define items and their modifiers to the provided specification.
Trigger pull	Pull Job Management	Refresh DoorDash inventory, including modifier items.
Activate / suspend	PUT Item and Item Option	Directly activate or suspend items and options using the V1 endpoints.

Getting started

Step 1: Configure items with modifiers

Configure items with modifiers according to the batch add store item specification.

Step 2: Trigger a pull job

Initiate a pull job to update DoorDash's inventory, including the modifier items.

Step 3: Configure V1 activation endpoints

Set up the item and item option activation endpoints to manage these resources.

Modifier group fields

Each entry in the extras array defines a modifier group. The following fields are supported:

Field	Type	Required	Description
name	string	Yes	Display name of the modifier group (e.g., "Choose a Size").
merchant_supplied_id	string	Yes	Internal ID for the extra group.
description	string	No	Consumer-facing description of the modifier group.
availability	string	No	"ACTIVE" (default) or "INACTIVE".
sort_id	integer	No	Determines display order. Lower values appear first.
min_num_options	integer	No	Minimum number of distinct options that must be selected.
max_num_options	integer	No	Maximum number of distinct options allowed.
num_free_options	integer	No	Number of options offered for free before surcharges apply.
min_option_choice_quantity	integer	No	Minimum quantity for any single option.
max_option_choice_quantity	integer	No	Maximum quantity for any single option.
min_aggregate_options_quantity	integer	No	Minimum total quantity across all selected options.
max_aggregate_options_quantity	integer	No	Maximum total quantity across all selected options.
options	array	Yes	List of individual Option objects within this group.

Example: basic extra with two options

"extras": [
  {
    "name": "Choose a Size",
    "merchant_supplied_id": "size-001",
    "min_num_options": 1,
    "max_num_options": 1,
    "options": [
      {
        "merchant_supplied_item_id": "size-small",
        "name": "Small",
        "price_info": { "base_price": 0 },
        "default": true,
        "sort_id": 1
      },
      {
        "merchant_supplied_item_id": "size-large",
        "name": "Large",
        "price_info": { "base_price": 200 },
        "sort_id": 2
      }
    ]
  }
]

Example: extra with quantity selector

"extras": [
  {
    "name": "Toppings",
    "merchant_supplied_id": "toppings-001",
    "min_aggregate_options_quantity": 0,
    "max_aggregate_options_quantity": 5,
    "options": [
      {
        "merchant_supplied_item_id": "topping-pepperoni",
        "name": "Pepperoni",
        "price_info": { "base_price": 100 },
        "sort_id": 1
      },
      {
        "merchant_supplied_item_id": "topping-mushroom",
        "name": "Mushroom",
        "price_info": { "base_price": 75 },
        "sort_id": 2
      }
    ]
  }
]

Verify your integration

To confirm modifiers are working end to end:

• Confirm the pull job processed successfully through the Developer Portal event logs.
• Open your test store and confirm modifiers display on the intended items.
• Place a test order to validate modifier functionality.
• Deactivate and reactivate items and options using the PUT Item and Item Option endpoints to confirm activation works as expected.

Frequently asked questions

How can I update attributes for items with modifiers?

The Pull Job endpoint is the only way to add, delete, or update attributes for items with modifiers — including parent items as well as extras and options.

Can I directly activate or suspend modifiers or the parent item?

Yes. The OpenAPI PUT Item and Item Option endpoint can activate or suspend items and modifiers (extras/options) when you need direct control.

What happens if I send a POST/PATCH request to the Inventory/Pricing endpoint for an item with modifiers?

If a request contains an item with modifiers, the entire request fails — none of the items in the request are updated. Always route modifier changes through the Pull Job endpoint.

Next steps

Guide	Description
Set up Inventory Pull	Stand up the pull endpoint that powers every modifier update.
Inventory/Pricing Overview	Understand how per-store inventory and pricing work.
Item & Store Status	Activate or suspend items and options directly.