DoorDash Marketplace API

openapi: 3.1.0
info:
  title: DoorDash Marketplace API
  description: >-
    The DoorDash Marketplace API allows merchants and third-party providers
    to integrate directly with the DoorDash marketplace for order management,
    menu synchronization, and store operations. It supports receiving orders
    from DoorDash, updating order statuses, and managing menu availability
    in real time. Access is granted through a selective partner program.
  version: '1.0'
  contact:
    name: DoorDash Developer Support
    url: https://developer.doordash.com/en-US/
  termsOfService: https://www.doordash.com/terms/
externalDocs:
  description: DoorDash Marketplace API Documentation
  url: https://developer.doordash.com/en-US/docs/marketplace/overview/about_marketplace/
servers:
- url: https://openapi.doordash.com/marketplace/api/v1
  description: Production Server
tags:
- name: Items
  description: >-
    Manage item availability and 86ing (marking items as unavailable) in
    real time.
- name: Menus
  description: >-
    Create, update, and manage menus for stores on the DoorDash marketplace.
- name: Orders
  description: >-
    Receive, confirm, update, and manage orders placed through the DoorDash
    marketplace.
- name: Stores
  description: >-
    Retrieve store details and manage store status on the marketplace.
security:
- bearerAuth: []
paths:
  /orders/{order_id}:
    patch:
      operationId: updateOrder
      summary: DoorDash Update an Order
      description: >-
        Updates the status of an order, cancels items, adjusts item or option
        quantities, or substitutes items. A separate token may be required
        for patch_order_events operations.
      tags:
      - Orders
      parameters:
      - $ref: '#/components/parameters/OrderId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderUpdate'
            examples:
              UpdateOrderRequestExample:
                summary: Default updateOrder request
                x-microcks-default: true
                value:
                  status: confirmed
                  cancelled_items:
                  - item_id: {}
                    reason: {}
                  substitutions:
                  - original_item_id: {}
                    substitute_item_id: {}
                    substitute_item_name: {}
                    substitute_item_price: {}
      responses:
        '200':
          description: Order updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
              examples:
                UpdateOrder200Example:
                  summary: Default updateOrder 200 response
                  x-microcks-default: true
                  value:
                    id: D-12345
                    external_reference_id: D-12345
                    status: pending
                    store_id: D-12345
                    subtotal: 42
                    tax: 42
                    delivery_fee: 42
                    tip: 42
                    items:
                    - id: {}
                      name: {}
                      quantity: {}
                      price: {}
                      special_instructions: {}
                      options: {}
                    customer:
                      first_name: Acme Pickup Store
                      last_name: Acme Pickup Store
                      phone_number: '+15555551234'
                    delivery_address: 901 Market St, San Francisco, CA 94105
                    special_instructions: Leave at the front desk.
                    created_at: '2026-06-02T14:30:00Z'
                    estimated_pickup_time: '2026-06-02T14:30:00Z'
        '400':
          description: Invalid update parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                UpdateOrder400Example:
                  summary: Default updateOrder 400 response
                  x-microcks-default: true
                  value:
                    message: example
                    code: ABC123
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                UpdateOrder401Example:
                  summary: Default updateOrder 401 response
                  x-microcks-default: true
                  value:
                    message: example
                    code: ABC123
        '404':
          description: Order not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                UpdateOrder404Example:
                  summary: Default updateOrder 404 response
                  x-microcks-default: true
                  value:
                    message: example
                    code: ABC123
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /menus:
    post:
      operationId: createMenu
      summary: DoorDash Create a Menu
      description: >-
        Uploads a complete menu for a store. Menu creation is processed
        asynchronously. A successful response indicates the request was
        received. A webhook notification is sent when processing completes
        or fails.
      tags:
      - Menus
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MenuRequest'
            examples:
              CreateMenuRequestExample:
                summary: Default createMenu request
                x-microcks-default: true
                value:
                  store_id: D-12345
                  categories:
                  - id: {}
                    name: {}
                    description: {}
                    sort_id: {}
                    items: {}
      responses:
        '200':
          description: Menu creation request accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MenuResponse'
              examples:
                CreateMenu200Example:
                  summary: Default createMenu 200 response
                  x-microcks-default: true
                  value:
                    menu_id: D-12345
                    status: received
        '400':
          description: Invalid menu data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                CreateMenu400Example:
                  summary: Default createMenu 400 response
                  x-microcks-default: true
                  value:
                    message: example
                    code: ABC123
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                CreateMenu401Example:
                  summary: Default createMenu 401 response
                  x-microcks-default: true
                  value:
                    message: example
                    code: ABC123
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /menus/{menu_id}:
    patch:
      operationId: updateMenu
      summary: DoorDash Update a Menu
      description: >-
        Updates an existing menu. Uses the same validation as menu creation.
        Processing is asynchronous with webhook notification upon completion.
      tags:
      - Menus
      parameters:
      - $ref: '#/components/parameters/MenuId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MenuRequest'
            examples:
              UpdateMenuRequestExample:
                summary: Default updateMenu request
                x-microcks-default: true
                value:
                  store_id: D-12345
                  categories:
                  - id: {}
                    name: {}
                    description: {}
                    sort_id: {}
                    items: {}
      responses:
        '200':
          description: Menu update request accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MenuResponse'
              examples:
                UpdateMenu200Example:
                  summary: Default updateMenu 200 response
                  x-microcks-default: true
                  value:
                    menu_id: D-12345
                    status: received
        '400':
          description: Invalid menu data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                UpdateMenu400Example:
                  summary: Default updateMenu 400 response
                  x-microcks-default: true
                  value:
                    message: example
                    code: ABC123
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                UpdateMenu401Example:
                  summary: Default updateMenu 401 response
                  x-microcks-default: true
                  value:
                    message: example
                    code: ABC123
        '404':
          description: Menu not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                UpdateMenu404Example:
                  summary: Default updateMenu 404 response
                  x-microcks-default: true
                  value:
                    message: example
                    code: ABC123
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /stores/{merchant_supplied_id}/store_details:
    get:
      operationId: getStoreDetails
      summary: DoorDash Get Store Details
      description: >-
        Retrieves live store-level information for a store that is set up
        on the integration.
      tags:
      - Stores
      parameters:
      - $ref: '#/components/parameters/MerchantSuppliedId'
      responses:
        '200':
          description: Store details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoreDetails'
              examples:
                GetStoreDetails200Example:
                  summary: Default getStoreDetails 200 response
                  x-microcks-default: true
                  value:
                    merchant_supplied_id: D-12345
                    name: Acme Pickup Store
                    address: 901 Market St, San Francisco, CA 94105
                    phone_number: '+15555551234'
                    is_active: true
                    status: open
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                GetStoreDetails401Example:
                  summary: Default getStoreDetails 401 response
                  x-microcks-default: true
                  value:
                    message: example
                    code: ABC123
        '404':
          description: Store not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                GetStoreDetails404Example:
                  summary: Default getStoreDetails 404 response
                  x-microcks-default: true
                  value:
                    message: example
                    code: ABC123
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /stores/{merchant_supplied_id}/menu_details:
    get:
      operationId: getMenuDetails
      summary: DoorDash Get Menu Details for a Store
      description: >-
        Retrieves live menu-level information for a store that is set up
        on the integration.
      tags:
      - Stores
      parameters:
      - $ref: '#/components/parameters/MerchantSuppliedId'
      responses:
        '200':
          description: Menu details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MenuDetails'
              examples:
                GetMenuDetails200Example:
                  summary: Default getMenuDetails 200 response
                  x-microcks-default: true
                  value:
                    store_id: D-12345
                    categories:
                    - id: {}
                      name: {}
                      description: {}
                      sort_id: {}
                      items: {}
                    last_updated: '2026-06-02T14:30:00Z'
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                GetMenuDetails401Example:
                  summary: Default getMenuDetails 401 response
                  x-microcks-default: true
                  value:
                    message: example
                    code: ABC123
        '404':
          description: Store not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                GetMenuDetails404Example:
                  summary: Default getMenuDetails 404 response
                  x-microcks-default: true
                  value:
                    message: example
                    code: ABC123
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /stores/{merchant_supplied_id}/item_status:
    patch:
      operationId: updateItemStatus
      summary: DoorDash Update Item Availability
      description: >-
        Updates the availability status of items and item options for a store.
        Used to 86 items (mark as unavailable) or stock them back in when
        they become available to order.
      tags:
      - Items
      parameters:
      - $ref: '#/components/parameters/MerchantSuppliedId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ItemStatusUpdate'
            examples:
              UpdateItemStatusRequestExample:
                summary: Default updateItemStatus request
                x-microcks-default: true
                value:
                  items:
                  - id: D-12345
                    is_available: true
      responses:
        '200':
          description: Item status updated successfully
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                UpdateItemStatus400Example:
                  summary: Default updateItemStatus 400 response
                  x-microcks-default: true
                  value:
                    message: example
                    code: ABC123
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                UpdateItemStatus401Example:
                  summary: Default updateItemStatus 401 response
                  x-microcks-default: true
                  value:
                    message: example
                    code: ABC123
        '404':
          description: Store not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                UpdateItemStatus404Example:
                  summary: Default updateItemStatus 404 response
                  x-microcks-default: true
                  value:
                    message: example
                    code: ABC123
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /stores/{merchant_supplied_id}/status:
    patch:
      operationId: updateStoreStatus
      summary: DoorDash Update Store Status
      description: >-
        Updates the operational status of a store, such as opening or closing
        the store for orders on the DoorDash marketplace.
      tags:
      - Stores
      parameters:
      - $ref: '#/components/parameters/MerchantSuppliedId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StoreStatusUpdate'
            examples:
              UpdateStoreStatusRequestExample:
                summary: Default updateStoreStatus request
                x-microcks-default: true
                value:
                  status: open
                  reason: example
      responses:
        '200':
          description: Store status updated successfully
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                UpdateStoreStatus400Example:
                  summary: Default updateStoreStatus 400 response
                  x-microcks-default: true
                  value:
                    message: example
                    code: ABC123
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                UpdateStoreStatus401Example:
                  summary: Default updateStoreStatus 401 response
                  x-microcks-default: true
                  value:
                    message: example
                    code: ABC123
        '404':
          description: Store not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                UpdateStoreStatus404Example:
                  summary: Default updateStoreStatus 404 response
                  x-microcks-default: true
                  value:
                    message: example
                    code: ABC123
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        JWT Bearer token for authenticating with the DoorDash Marketplace API.
  parameters:
    OrderId:
      name: order_id
      in: path
      required: true
      description: >-
        The unique DoorDash order identifier.
      schema:
        type: string
    MenuId:
      name: menu_id
      in: path
      required: true
      description: >-
        The unique identifier for the menu.
      schema:
        type: string
    MerchantSuppliedId:
      name: merchant_supplied_id
      in: path
      required: true
      description: >-
        The merchant-supplied identifier for the store.
      schema:
        type: string
  schemas:
    Order:
      type: object
      properties:
        id:
          type: string
          description: >-
            The unique DoorDash order identifier.
          example: D-12345
        external_reference_id:
          type: string
          description: >-
            An external reference ID for the order.
          example: D-12345
        status:
          type: string
          description: >-
            The current status of the order.
          enum:
          - pending
          - confirmed
          - being_prepared
          - ready_for_pickup
          - picked_up
          - delivered
          - cancelled
          example: pending
        store_id:
          type: string
          description: >-
            The merchant-supplied store identifier.
          example: D-12345
        subtotal:
          type: integer
          description: >-
            The order subtotal in cents.
          example: 42
        tax:
          type: integer
          description: >-
            The tax amount in cents.
          example: 42
        delivery_fee:
          type: integer
          description: >-
            The delivery fee in cents.
          example: 42
        tip:
          type: integer
          description: >-
            The tip amount in cents.
          example: 42
        items:
          type: array
          description: >-
            The items in the order.
          items:
            $ref: '#/components/schemas/OrderItem'
        customer:
          $ref: '#/components/schemas/Customer'
        delivery_address:
          type: string
          description: >-
            The delivery address for the order.
          example: 901 Market St, San Francisco, CA 94105
        special_instructions:
          type: string
          description: >-
            Special instructions from the customer.
          example: Leave at the front desk.
        created_at:
          type: string
          format: date-time
          description: >-
            When the order was created.
          example: '2026-06-02T14:30:00Z'
        estimated_pickup_time:
          type: string
          format: date-time
          description: >-
            The estimated time the Dasher will arrive to pick up the order.
          example: '2026-06-02T14:30:00Z'
    OrderUpdate:
      type: object
      properties:
        status:
          type: string
          description: >-
            The updated order status.
          enum:
          - confirmed
          - being_prepared
          - ready_for_pickup
          - cancelled
          example: confirmed
        cancelled_items:
          type: array
          description: >-
            Items to cancel from the order.
          items:
            $ref: '#/components/schemas/CancelledItem'
        substitutions:
          type: array
          description: >-
            Item substitutions for the order.
          items:
            $ref: '#/components/schemas/Substitution'
    OrderItem:
      type: object
      properties:
        id:
          type: string
          description: >-
            The unique item identifier within the order.
          example: D-12345
        name:
          type: string
          description: >-
            The name of the item.
          example: Acme Pickup Store
        quantity:
          type: integer
          description: >-
            The quantity ordered.
          minimum: 1
          example: 1
        price:
          type: integer
          description: >-
            The item price in cents.
          example: 42
        special_instructions:
          type: string
          description: >-
            Special instructions for this item.
          example: Leave at the front desk.
        options:
          type: array
          description: >-
            Selected options for the item.
          items:
            $ref: '#/components/schemas/OrderItemOption'
    OrderItemOption:
      type: object
      properties:
        id:
          type: string
          description: >-
            The unique option identifier.
          example: D-12345
        name:
          type: string
          description: >-
            The option name.
          example: Acme Pickup Store
        quantity:
          type: integer
          description: >-
            The quantity of this option.
          example: 42
        price:
          type: integer
          description: >-
            The option price in cents.
          example: 42
    CancelledItem:
      type: object
      properties:
        item_id:
          type: string
          description: >-
            The ID of the item to cancel.
          example: D-12345
        reason:
          type: string
          description: >-
            The reason for cancellation.
          example: example
    Substitution:
      type: object
      properties:
        original_item_id:
          type: string
          description: >-
            The ID of the original item to substitute.
          example: D-12345
        substitute_item_id:
          type: string
          description: >-
            The ID of the substitute item.
          example: D-12345
        substitute_item_name:
          type: string
          description: >-
            The name of the substitute item.
          example: Acme Pickup Store
        substitute_item_price:
          type: integer
          description: >-
            The price of the substitute item in cents.
          example: 42
    Customer:
      type: object
      properties:
        first_name:
          type: string
          description: >-
            The customer's first name.
          example: Acme Pickup Store
        last_name:
          type: string
          description: >-
            The customer's last name.
          example: Acme Pickup Store
        phone_number:
          type: string
          description: >-
            The customer's phone number.
          example: '+15555551234'
    MenuRequest:
      type: object
      required:
      - store_id
      - categories
      properties:
        store_id:
          type: string
          description: >-
            The merchant-supplied store identifier.
          example: D-12345
        categories:
          type: array
          description: >-
            The menu categories containing items.
          items:
            $ref: '#/components/schemas/MenuCategory'
    MenuCategory:
      type: object
      required:
      - id
      - name
      - items
      properties:
        id:
          type: string
          description: >-
            The unique identifier for this category.
          example: D-12345
        name:
          type: string
          description: >-
            The display name of the category.
          example: Acme Pickup Store
        description:
          type: string
          description: >-
            A description of the category.
          example: Leave at the front desk.
        sort_id:
          type: integer
          description: >-
            The sort order for this category.
          example: 42
        items:
          type: array
          description: >-
            The items in this category.
          items:
            $ref: '#/components/schemas/MenuItem'
    MenuItem:
      type: object
      required:
      - id
      - name
      - price
      properties:
        id:
          type: string
          description: >-
            The merchant-supplied item identifier.
          example: D-12345
        name:
          type: string
          description: >-
            The display name of the item.
          example: Acme Pickup Store
        description:
          type: string
          description: >-
            A description of the item.
          example: Leave at the front desk.
        price:
          type: integer
          description: >-
            The item price in cents.
          example: 42
        image_url:
          type: string
          format: uri
          description: >-
            A URL to an image of the item.
          example: https://example.com/path/abc123
        is_active:
          type: boolean
          description: >-
            Whether the item is currently available for ordering.
          example: true
        sort_id:
          type: integer
          description: >-
            The sort order for this item within its category.
          example: 42
        option_groups:
          type: array
          description: >-
            Option groups (modifiers) for this item.
          items:
            $ref: '#/components/schemas/OptionGroup'
    OptionGroup:
      type: object
      required:
      - id
      - name
      - options
      properties:
        id:
          type: string
          description: >-
            The unique identifier for this option group.
          example: D-12345
        name:
          type: string
          description: >-
            The display name of the option group.
          example: Acme Pickup Store
        min_selections:
          type: integer
          description: >-
            The minimum number of options that must be selected.
          minimum: 0
          example: 0
        max_selections:
          type: integer
          description: >-
            The maximum number of options that can be selected.
          minimum: 1
          example: 1
        options:
          type: array
          description: >-
            The available options in this group.
          items:
            $ref: '#/components/schemas/MenuOption'
    MenuOption:
      type: object
      required:
      - id
      - name
      - price
      properties:
        id:
          type: string
          description: >-
            The unique identifier for this option.
          example: D-12345
        name:
          type: string
          description: >-
            The display name of the option.
          example: Acme Pickup Store
        price:
          type: integer
          description: >-
            The additional price for this option in cents.
          example: 42
        is_active:
          type: boolean
          description: >-
            Whether the option is currently available.
          example: true
    MenuResponse:
      type: object
      properties:
        menu_id:
          type: string
          description: >-
            The unique identifier for the menu request.
          example: D-12345
        status:
          type: string
          description: >-
            The processing status of the menu request.
          enum:
          - received
          - processing
          - completed
          - failed
          example: received
    MenuDetails:
      type: object
      properties:
        store_id:
          type: string
          description: >-
            The merchant-supplied store identifier.
          example: D-12345
        categories:
          type: array
          description: >-
            The menu categories.
          items:
            $ref: '#/components/schemas/MenuCategory'
        last_updated:
          type: string
          format: date-time
          description: >-
            When the menu was last updated.
          example: '2026-06-02T14:30:00Z'
    StoreDetails:
      type: object
      properties:
        merchant_supplied_id:
          type: string
          description: >-
            The merchant-supplied store identifier.
          example: D-12345
        name:
          type: string
          description: >-
            The store name.
          example: Acme Pickup Store
        address:
          type: string
          description: >-
            The store address.
          example: 901 Market St, San Francisco, CA 94105
        phone_number:
          type: string
          description: >-
            The store phone number.
          example: '+15555551234'
        is_active:
          type: boolean
          description: >-
            Whether the store is currently active on DoorDash.
          example: true
        status:
          type: string
          description: >-
            The operational status of the store.
          enum:
          - open
          - closed
          - temporarily_closed
          example: open
    StoreStatusUpdate:
      type: object
      required:
      - status
      properties:
        status:
          type: string
          description: >-
            The new store status.
          enum:
          - open
          - closed
          - temporarily_closed
          example: open
        reason:
          type: string
          description: >-
            The reason for the status change.
          example: example
    I

# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/doordash/refs/heads/main/openapi/doordash-marketplace-openapi.yml