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: 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'
      responses:
        '200':
          description: Order updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '400':
          description: Invalid update parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Order not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /menus:
    post:
      operationId: createMenu
      summary: 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'
      responses:
        '200':
          description: Menu creation request accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MenuResponse'
        '400':
          description: Invalid menu data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /menus/{menu_id}:
    patch:
      operationId: updateMenu
      summary: 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'
      responses:
        '200':
          description: Menu update request accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MenuResponse'
        '400':
          description: Invalid menu data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Menu not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /stores/{merchant_supplied_id}/store_details:
    get:
      operationId: getStoreDetails
      summary: 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'
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Store not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /stores/{merchant_supplied_id}/menu_details:
    get:
      operationId: getMenuDetails
      summary: 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'
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Store not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /stores/{merchant_supplied_id}/item_status:
    patch:
      operationId: updateItemStatus
      summary: 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'
      responses:
        '200':
          description: Item status updated successfully
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Store not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /stores/{merchant_supplied_id}/status:
    patch:
      operationId: updateStoreStatus
      summary: 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'
      responses:
        '200':
          description: Store status updated successfully
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Store not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
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.
        external_reference_id:
          type: string
          description: >-
            An external reference ID for the order.
        status:
          type: string
          description: >-
            The current status of the order.
          enum:
            - pending
            - confirmed
            - being_prepared
            - ready_for_pickup
            - picked_up
            - delivered
            - cancelled
        store_id:
          type: string
          description: >-
            The merchant-supplied store identifier.
        subtotal:
          type: integer
          description: >-
            The order subtotal in cents.
        tax:
          type: integer
          description: >-
            The tax amount in cents.
        delivery_fee:
          type: integer
          description: >-
            The delivery fee in cents.
        tip:
          type: integer
          description: >-
            The tip amount in cents.
        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.
        special_instructions:
          type: string
          description: >-
            Special instructions from the customer.
        created_at:
          type: string
          format: date-time
          description: >-
            When the order was created.
        estimated_pickup_time:
          type: string
          format: date-time
          description: >-
            The estimated time the Dasher will arrive to pick up the order.
    OrderUpdate:
      type: object
      properties:
        status:
          type: string
          description: >-
            The updated order status.
          enum:
            - confirmed
            - being_prepared
            - ready_for_pickup
            - cancelled
        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.
        name:
          type: string
          description: >-
            The name of the item.
        quantity:
          type: integer
          description: >-
            The quantity ordered.
          minimum: 1
        price:
          type: integer
          description: >-
            The item price in cents.
        special_instructions:
          type: string
          description: >-
            Special instructions for this item.
        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.
        name:
          type: string
          description: >-
            The option name.
        quantity:
          type: integer
          description: >-
            The quantity of this option.
        price:
          type: integer
          description: >-
            The option price in cents.
    CancelledItem:
      type: object
      properties:
        item_id:
          type: string
          description: >-
            The ID of the item to cancel.
        reason:
          type: string
          description: >-
            The reason for cancellation.
    Substitution:
      type: object
      properties:
        original_item_id:
          type: string
          description: >-
            The ID of the original item to substitute.
        substitute_item_id:
          type: string
          description: >-
            The ID of the substitute item.
        substitute_item_name:
          type: string
          description: >-
            The name of the substitute item.
        substitute_item_price:
          type: integer
          description: >-
            The price of the substitute item in cents.
    Customer:
      type: object
      properties:
        first_name:
          type: string
          description: >-
            The customer's first name.
        last_name:
          type: string
          description: >-
            The customer's last name.
        phone_number:
          type: string
          description: >-
            The customer's phone number.
    MenuRequest:
      type: object
      required:
        - store_id
        - categories
      properties:
        store_id:
          type: string
          description: >-
            The merchant-supplied store identifier.
        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.
        name:
          type: string
          description: >-
            The display name of the category.
        description:
          type: string
          description: >-
            A description of the category.
        sort_id:
          type: integer
          description: >-
            The sort order for this category.
        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.
        name:
          type: string
          description: >-
            The display name of the item.
        description:
          type: string
          description: >-
            A description of the item.
        price:
          type: integer
          description: >-
            The item price in cents.
        image_url:
          type: string
          format: uri
          description: >-
            A URL to an image of the item.
        is_active:
          type: boolean
          description: >-
            Whether the item is currently available for ordering.
        sort_id:
          type: integer
          description: >-
            The sort order for this item within its category.
        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.
        name:
          type: string
          description: >-
            The display name of the option group.
        min_selections:
          type: integer
          description: >-
            The minimum number of options that must be selected.
          minimum: 0
        max_selections:
          type: integer
          description: >-
            The maximum number of options that can be selected.
          minimum: 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.
        name:
          type: string
          description: >-
            The display name of the option.
        price:
          type: integer
          description: >-
            The additional price for this option in cents.
        is_active:
          type: boolean
          description: >-
            Whether the option is currently available.
    MenuResponse:
      type: object
      properties:
        menu_id:
          type: string
          description: >-
            The unique identifier for the menu request.
        status:
          type: string
          description: >-
            The processing status of the menu request.
          enum:
            - received
            - processing
            - completed
            - failed
    MenuDetails:
      type: object
      properties:
        store_id:
          type: string
          description: >-
            The merchant-supplied store identifier.
        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.
    StoreDetails:
      type: object
      properties:
        merchant_supplied_id:
          type: string
          description: >-
            The merchant-supplied store identifier.
        name:
          type: string
          description: >-
            The store name.
        address:
          type: string
          description: >-
            The store address.
        phone_number:
          type: string
          description: >-
            The store phone number.
        is_active:
          type: boolean
          description: >-
            Whether the store is currently active on DoorDash.
        status:
          type: string
          description: >-
            The operational status of the store.
          enum:
            - open
            - closed
            - temporarily_closed
    StoreStatusUpdate:
      type: object
      required:
        - status
      properties:
        status:
          type: string
          description: >-
            The new store status.
          enum:
            - open
            - closed
            - temporarily_closed
        reason:
          type: string
          description: >-
            The reason for the status change.
    ItemStatusUpdate:
      type: object
      required:
        - items
      properties:
        items:
          type: array
          description: >-
            The items to update availability for.
          items:
            type: object
            required:
              - id
              - is_available
            properties:
              id:
                type: string
                description: >-
                  The merchant-supplied item identifier.
              is_available:
                type: boolean
                description: >-
                  Whether the item is available for ordering.
    Error:
      type: object
      properties:
        message:
          type: string
          description: >-
            A human-readable error message.
        code:
          type: string
          description: >-
            A machine-readable error code.