Set up Inventory Pull

Overview

As part of the integration workflow, partners can implement an endpoint that allows DoorDash to pull and replace all StoreItems sold in a store location. This effectively refreshes the item availability and pricing visible to Customers shopping on DoorDash.

The response from this endpoint should match BatchAddOrUpdateStoreItemRequest request model.

Partners can trigger the job creating a StoreItem pull job by POST /api/v2/jobs with CreateJob request by using one of the two job types:

• "PULL_STORE_ITEMS" - if you can return all items in one pull call for one store
• "PULL_STORE_ITEMS_WITH_PAGINATION" - if cannot return all items in a single pull and need to use a paginated version

The job parameters in CreateJobRequest should match CreatePullStoreItemsJobParameters.

Note: When the pull job runs, DoorDash replaces the store's existing inventory record with the response from your endpoint. This is not a differential update — your response must contain every item (active and inactive) for the store.

Get Started

---

Step 1: Set up Endpoint Specification to Pull StoreItem

The set up of the endpoint is:

GET /{merchant_pull_endpoint}/{store_location_id}

or, for paginated flow:

GET /{merchant_pull_endpoint}/{store_location_id}?page_num={page_number}

store_location_id is the unique Merchant Supplied ID that is configured for that store location. The endpoint will deliver the full inventory for 1 single location at a time. page_number is the page of the data that needs to be fetched. Data will be fetched page by page if using the paginated flow.

Currently we support static tokens and Oauth authentication mechanisms when calling Pull Store Item endpoint. If DoorDash needs to authenticate with your endpoint using Oauth, please share the oauth endpoint with Technical Account Manager to register in DoorDash.

Endpoint requirements

• The endpoint must be available over HTTPS.
• It must return all active and inactive items for the store, either in one response or paginated.
• It must be capable of handling high concurrency, since DoorDash may pull many stores in parallel.
• Paginated responses must include a meta object with pagination details (see Step 2).

Step 2: Ensure that storeItems.json response from endpoint has the correct format

As mentioned above, the StoreItem Pull request must return the response that matches BatchAddOrUpdateStoreItemRequest request model

Note: The response should contain all StoreItems in a store. DoorDash will replace all StoreItem attributes of the store with the ones from the json response when calling the pull job endpoint.

All prices are represented in cents (e.g., 1099 = $10.99).

Sample response expected from endpoint:

{
  "items": [
    
    {
      "merchant_supplied_item_id": "1",
      "item_availability": "ACTIVE",
      "price_info": {
        "base_price": 1099,
        "sale_price": 999,
      }
    }, 
    {
      "merchant_supplied_item_id": "2",
      "item_availability": "INACTIVE",
      "price_info": {
        "base_price": 599,
        "sale_price": 599,
      }
    }
    .
    .
    .
    {
      "merchant_supplied_item_id": "10000",
      "item_availability": "ACTIVE",
      "price_info": {
        "base_price": 499,
        "sale_price": 499,
      }
    }, 
  ]
}

If you are using the paginated pull flow, expect additional response in the "meta" fields:

{
  "meta":
    
    {
      "current_page": "1",
      "page_size": "500", //number of items on the page
      "total_page": "100" //total number of pages
    }
}

Field Reference

Field	Type	Required	Description
merchant_supplied_item_id	string	Yes	The item's unique ID in your system. Must match the merchant_supplied_item_id in your catalog.
item_availability	string	Yes	ACTIVE or INACTIVE. Determines whether the item appears to customers.
price_info.base_price	integer	Yes	Base price in cents.
price_info.sale_price	integer	Optional	Promotional or discounted price in cents.
meta	object	Conditional	Required only for paginated responses. See pagination example above.

Step 3: Enroll your endpoint in the Developer Portal

Once the endpoint is ready, enroll it using the Developer Portal:

1. Navigate to the Developer Portal

2. Navigate to your Marketplace integration

3. Navigate to the "Webhook subscriptions" section

4. Click "Configure endpoint"

5. Select the appropriate provider type

6. For "Event", select "Full Inventory Pull"

7. Enter the URL

   • Enter the base URL and %s to indicate where in the URL the store ID should be passed: https://{merchant_pull_endpoint}/%s. DoorDash will send through the partner_store_id in place of %s each time a request is made. Your endpoint must accept that URL parameter and return the inventory data only for the store specified.

8. Enter the authentication token (if needed)

   • Currently we support static tokens and Oauth authentication mechanisms when calling Pull endpoints.

Step 4: Trigger StoreItem Pull by creating pull Job

You can trigger a StoreItem pull by POST /api/v2/jobs with CreateJob request and job parameters in CreateJobRequest should match CreatePullStoreItemsJobParameters. The CreateJob request can accept only 1 location. To pull inventory for multiple locations, you will make multiple requests to the /api/v2/jobs endpoint, one for each location.

Following is a sample CreateJob request to trigger StoreItem pull without pagination

{
  "job_type": "PULL_STORE_ITEMS",
  "job_parameters": {
    "store_location_id": "100",
    "pull_mode": "REPLACE"
  }
}

Sample CreateJob request to trigger StoreItem pull with pagination

{
  "job_type": "PULL_STORE_ITEMS_WITH_PAGINATION",
  "job_parameters": {
    "store_location_id": "100",
    "pull_mode": "REPLACE"
  }
}

Notes

• Each store requires its own job — submit one CreateJob request per store_location_id.
• pull_mode must always be "REPLACE". DoorDash replaces all existing inventory for the store with the response from your endpoint.
• Use PULL_STORE_ITEMS_WITH_PAGINATION only if your endpoint supports paged results.
• Monitor job execution and status in the Developer Portal under Event Logs.

Success Response

A successful trigger or completed pull returns:

{
  "operation_id": "string",
  "operation_status": "SUCCESS",
  "message": "string"
}

operation_status will be one of:

Status	Meaning
QUEUED	The job has been accepted and is waiting to run.
IN_PROGRESS	DoorDash is actively pulling inventory from your endpoint.
SUCCESS	All items in the response were ingested successfully.
FAILED	The job failed before any items were ingested. Inspect message for the cause.
PARTIAL_SUCCESS	The job ran but some items were rejected (typically item-level validation errors). Review the Developer Portal Event Logs for the per-item details.

Error Handling

When triggering or servicing a Store Item Pull, inspect both the HTTP status and the response body. Success responses confirm job creation or data acceptance; errors indicate authentication, schema, or rate-limiting issues.

HTTP Status	Code	Message	Recommended Action
400	validation_error	One or more request values couldn't be validated.	Verify schema and ensure required fields like store_location_id are included.
401	authentication_error	The [exp] is in the past; the JWT is expired.	Generate a new JWT and retry.
403	authorization_error	Authorization error — credentials invalid or insufficient.	Confirm correct API credentials and permissions.
404	unknown_store_id	The specified store was not found.	Check that store_location_id matches a valid store.
422	request_rate_limited	Request rate limit exceeded.	Throttle or retry with backoff.
429	request_rate_limited	Too many requests in a short time.	Reduce request frequency and retry later.
500	service_fault	Internal service failure, please try again later.	Retry after a short delay; contact your DoorDash TAM if the problem persists.

Best Practices

• Keep your endpoint performant and highly available — DoorDash may call it at any time.
• Ensure all merchant_supplied_item_id values match the IDs in your catalog.
• Represent prices as integers in cents — no decimals or currency symbols.
• Mark temporarily unavailable items as "INACTIVE" rather than removing them from the response. Items omitted from a REPLACE pull are removed from the store's inventory.
• Trigger only one pull job per store at a time.
• Test your endpoint using the Developer Portal's trigger tooling before promoting to production.
• Monitor job results for FAILED or PARTIAL_SUCCESS statuses and correct any item-level errors promptly.

Next Steps

To ensure that StoreItem Pull is working as expected, please reach out to support via Developer Portal or your Technical Account Manager (if applicable) to test StoreItem Pull.

---

Modified: 5/8/2026