Updating Items

Existing catalog items are updated with the same schema used to create them. Send only the fields you are changing — fields omitted from the payload keep their current values.

PATCH https://openapi.doordash.com/marketplace/api/v2/items

The request body takes a scope object and an items array, exactly as it does on create. Items are matched on merchant_supplied_item_id within the businesses listed in scope.business_ids. See the Catalog Management API Reference for the full field list.

Example

Updating an item's name and marking it organic, leaving every other field untouched:

{
  "scope": {
    "business_ids": ["business-001"]
  },
  "items": [
    {
      "merchant_supplied_item_id": "item-1024",
      "name": "Organic Whole Grain Bread",
      "product_attributes": [
        {
          "attribute_name": "certification_and_production_details",
          "attribute_value": {
            "multi_select_string": ["Organic"]
          }
        }
      ]
    }
  ]
}

Reading the Response

A successful update returns 200 with operation_status: QUEUED:

{
  "operation_id": "759aa941-573a-4737-80df-b95e5bf1c5e2",
  "operation_status": "QUEUED",
  "message": "Request queued."
}

warning

A 200 response does not mean every item was applied. Item-level validation errors are returned as text inside message while the HTTP status stays 200 and operation_status stays QUEUED.

{
  "operation_id": "ab5c2d2f-6bd1-4e5b-bddf-c701ae7287e0",
  "operation_status": "QUEUED",
  "message": "Request queued. Item validation failed with following errors. Items with errors will be skipped.[item[0]: Item categorizations update using PATCH is not supported.]"
}

Errors are keyed by the item's position in the items array — item[0], item[1], and so on. An item flagged this way is skipped in full: every other field sent for that item is dropped with it. Other items in the same request are unaffected and are still processed.

Check message for item[<index>]: on every call, log it alongside the operation_id, and re-send the items that were skipped. An integration that checks only the HTTP status code will lose updates without any error surfacing.

Re-sending the same payload is safe. Each call is queued as a new job with a new operation_id and applies the same values.

What PATCH Cannot Update

item_categorizations cannot be changed with PATCH. The item is skipped with:

[item[0]: Item categorizations update using PATCH is not supported.]

To change an item's category path, send the item through POST instead. POST accepts item_categorizations on an item that already exists, and applies the rest of the payload with it.

Change	Endpoint
Name, description, images, brand, size, traits, product attributes, program eligibility	PATCH
Category path (item_categorizations)	POST

Field Behavior

• Omitted fields are unchanged. Limit the payload to the fields you intend to change; there is no need to re-send the full item definition.

• merchant_supplied_item_id identifies the item and cannot be renamed. Sending a different value creates a new item rather than renaming the existing one. The request succeeds either way, so a typo in the MSID becomes a duplicate SKU with no error.

• PATCH does not check that the item exists. A PATCH against a merchant_supplied_item_id that was never created returns a clean 200. Nothing in the response distinguishes it from a successful update, so verify the MSID before relying on the result.

• Unknown fields fail the whole request. A field that is not part of the item schema returns a 400 and nothing is ingested:

  [Path '/items/0'] Object instance has properties which are not allowed by the schema: ["not_a_real_field"]

• Enum values are closed and case-sensitive. A lowercase program_eligibility value fails the entire request, not just the item that carries it:

  [Path '/items/0/program_eligibility/0'] Instance value ("snap") not found in enum (possible values: ["SNAP","HSA","FSA"])

• Blank strings are rejected per item. "name": "" skips the item with Item name cannot be null or blank.

• null is not accepted for array fields. "images": null returns a 400 with Instance type (null) does not match any allowed primitive type (allowed: ["array"]). Send an array instead.

• product_attributes names and values are not validated. An attribute_name outside the supported list is accepted and silently discarded, so a rename that misses the canonical name looks like a success. See Supported Product Attribute.

Common Updates

• Correcting name or brand_info

• Replacing outdated images

• Adding or changing product_attributes — for example, adding a dietary or certification attribute

• Adding program_eligibility, such as "SNAP"

• Applying or removing the WEIGHTED trait together with weighted_item_info

• Recategorizing an item — use POST rather than PATCH, as described above

Verifying an Update

The Catalog API has no GET endpoint, so an item cannot be read back to confirm what was applied. Two things follow from that:

• The response is the only record of what was accepted. Store the operation_id and the full message for every call. Once the response is discarded there is no way to reconstruct which items were skipped.

• Updates are not immediate. Items are ingested asynchronously — see the Catalog Management overview FAQ for the current ingestion SLA, and confirm results with your DoorDash technical account manager.