openapi: 3.2.0
info:
  title: Storefront V1 API Specification Order API
  version: 1.0.0
  contact:
    name: Storefront API Support
    email: storefront-api-support@doordash.com
  description: Endpoints for order resources
servers:
- url: https://openapi.doordash.com
  variables: {}
security:
- BearerAuth: []
tags:
- name: Order
  description: Endpoints for order resources
paths:
  /storefront/api/v1/orders/order_session:
    post:
      tags:
      - Order
      summary: Create storefront order session from external cart
      operationId: CreateStorefrontOrderSessionFromExternalCartId
      requestBody:
        description: request body which should contain menu ids, menu item ids and other relevant details needed in external cart.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StorefrontOrderSessionRequest'
      responses:
        '200':
          description: Successfully created order session
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StorefrontOrderSessionResponse'
        '400':
          description: Request Validation Failed
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationFieldError'
        '401':
          description: Request not authenticated
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationError'
        '403':
          description: Operation not authorized
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationError'
        '404':
          description: Request resources not found
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoreMenuResourceNotFoundError'
        '429':
          description: Rate limited
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitedError'
        '500':
          description: Internal service failure, please try again later
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalError'
  /storefront/api/v1/orders/order_session_to_cart:
    post:
      tags:
      - Order
      summary: Create cart from order session
      operationId: CreateCartFromOrderSession
      requestBody:
        description: Internal use only. request body which should contain all the relevant details needed to create cart from order session.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StorefrontCreateCartFromOrderSessionRequest'
      responses:
        '200':
          description: Successfully created order session
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StorefrontCreateCartFromOrderSessionResponse'
        '400':
          description: Bad Request
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '422':
          description: Request Entity Too Large
        '429':
          description: Request is rate limited
        '500':
          description: Internal Server Error
  /storefront/api/v1/orders/order_history:
    post:
      tags:
      - Order
      summary: Get order history of a consumer
      operationId: getOrderHistory
      requestBody:
        description: request body which should contain user's identification details.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoyaltyUserSessionRequest'
      responses:
        '200':
          description: Successfully retrieved order history
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetStorefrontOrderHistoryResponse'
        '400':
          description: Bad Request
        '403':
          description: Forbidden
        '422':
          description: Request Entity Too Large
        '429':
          description: Request is rate limited
        '500':
          description: Internal Server Error
  /storefront/api/v1/orders/order_status:
    post:
      tags:
      - Order
      summary: Get order status given a order id
      operationId: getOrderStatus
      requestBody:
        description: request body which should integration id, type and order id.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetStorefrontOrderStatusRequest'
      responses:
        '200':
          description: Successfully retrieved order status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetStorefrontOrderStatusResponse'
        '400':
          description: Bad Request
        '403':
          description: Forbidden
        '422':
          description: Request Entity Too Large
        '429':
          description: Request is rate limited
        '500':
          description: Internal Server Error
components:
  schemas:
    UpdatedAt:
      type: string
      pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(.[0-9]{3,})?Z$
      description: UTC Timestamp in ISO-8601 format
      example: 2018-08-22T17:20:28Z or 2018-08-22T17:20:28.123Z
    IntegrationType:
      type: string
      enum:
      - BUSINESS
      - BUSINESS_GROUP
      - STORE
      example: store
      default: business
      description: Type of the integration id
    Order:
      type: object
      required:
      - order_id
      - fulfillment_type
      - created_at
      - updated_at
      - order_status
      properties:
        order_id:
          type: string
          description: unique id for this order
        tracking_url:
          type: string
          description: tracking url for this order if available
        eta:
          type: integer
          description: eta in minutes
        fulfillment_type:
          $ref: '#/components/schemas/FulfillmentType'
        created_at:
          $ref: '#/components/schemas/CreatedAt'
        updated_at:
          $ref: '#/components/schemas/UpdatedAt'
        order_status:
          $ref: '#/components/schemas/OrderStatus'
        help_url:
          type: string
          description: help url for this order if available
    StorefrontCreateCartFromOrderSessionResponse:
      type: object
      required:
      - cart_id
      properties:
        cart_id:
          $ref: '#/components/schemas/CartId'
    InternalError:
      x-error: true
      title: InternalError
      type: object
      description: Internal errors that occur during the api call.
      required:
      - code
      - message
      properties:
        code:
          type: string
          enum:
          - internal_service_error
        message:
          type: string
          example: Internal Service Error.
    DeliveryDetails:
      type: object
      properties:
        address:
          $ref: '#/components/schemas/Address'
        delivery_option:
          $ref: '#/components/schemas/DeliveryOption'
        delivery_instruction:
          type: string
          description: Delivery instructions if any.
      required:
      - address
    StorefrontCreateCartFromOrderSessionRequest:
      type: object
      required:
      - integration_id
      - integration_type
      - order_session_id
      - consumer_id
      - session_id
      properties:
        integration_id:
          $ref: '#/components/schemas/IntegrationId'
        integration_type:
          $ref: '#/components/schemas/IntegrationType'
        order_session_id:
          type: string
        session_id:
          $ref: '#/components/schemas/SessionId'
        consumer_id:
          $ref: '#/components/schemas/ConsumerId'
        should_delete_existing_carts:
          $ref: '#/components/schemas/ShouldDeleteExistingCarts'
    GetStorefrontOrderStatusRequest:
      type: object
      required:
      - integration_id
      - integration_type
      - order_id
      properties:
        integration_id:
          $ref: '#/components/schemas/IntegrationId'
        integration_type:
          $ref: '#/components/schemas/IntegrationType'
        order_id:
          type: string
          description: unique id for this order
    StoreMenuResourceNotFoundError:
      x-error: true
      title: StoreMenuResourceNotFoundError
      type: object
      description: The response returned when requested resource is not found/available.
      required:
      - code
      - message
      properties:
        code:
          type: string
          enum:
          - not_found
        message:
          type: string
          example: Failed to fetch store menus for store 123.
    ConsumerId:
      type: string
      pattern: ^([1-9][0-9]*)$
      description: Unique ID for a doordash consumer.
      example: '123'
    DeliveryOption:
      type: string
      description: one of two options which user can chose for delivery, leave at my door or hand it to me
      enum:
      - hand_it_to_me
      - leave_at_my_door
      default: leave_at_my_door
      example: leave_at_my_door
    RateLimitedError:
      x-error: true
      title: RateLimitedError
      type: object
      description: Rate limited.
      required:
      - code
      - message
      properties:
        code:
          type: string
          enum:
          - rate_limit_error
        message:
          type: string
          example: Developer account endpoint rate limit exceeded.
    ExternalCartItemExtra:
      type: object
      required:
      - id
      - quantity
      - price
      properties:
        id:
          type: string
          description: The id of this instance
        quantity:
          type: integer
          description: quantity for this item
        price:
          $ref: '#/components/schemas/Price'
        options:
          type: array
          items:
            $ref: '#/components/schemas/ExternalCartItem'
    GetStorefrontOrderStatusResponse:
      type: object
      title: GetStorefrontOrderStatusResponse
      description: order status for an order id.
      required:
      - order
      properties:
        order:
          $ref: '#/components/schemas/Order'
    Address:
      type: object
      properties:
        address_id:
          type: string
          pattern: ^([1-9][0-9]*)$
          example: '1234567'
        apartment_number:
          type: string
          example: '123'
      required:
      - address_id
    Price:
      type: object
      required:
      - value
      - currency
      properties:
        value:
          type: integer
          description: Price of this instance in minor units
          example: 399
        currency:
          type: string
          description: ISO 4217 - currency codes
          example: USD
    AuthenticationError:
      x-error: true
      type: object
      description: Authorization error, available credentials don't match requested operation
      required:
      - code
      - message
      properties:
        code:
          type: string
          enum:
          - authentication_error
        message:
          type: string
          example: Request does not contain a JWT.
    ExternalCartItem:
      type: object
      required:
      - id
      - quantity
      - price
      properties:
        id:
          type: string
          description: The id of this instance
        quantity:
          type: integer
          description: quantity for this item
        price:
          $ref: '#/components/schemas/Price'
        special_instructions:
          type: string
        extras:
          type: array
          items:
            $ref: '#/components/schemas/ExternalCartItemExtra'
    GetStorefrontOrderHistoryResponse:
      type: object
      title: GetStorefrontOrderHistoryResponse
      description: List of past orders of a user.
      required:
      - orders
      properties:
        orders:
          type: array
          items:
            $ref: '#/components/schemas/Order'
    SessionId:
      type: string
      description: id of the application session
    ValidationFieldError:
      x-error: true
      title: ValidationFieldError
      type: object
      description: The response returned when validation for field errors are encountered.
      required:
      - code
      - message
      - field_errors
      properties:
        code:
          type: string
          enum:
          - validation_error
        message:
          type: string
          example: Request validation failed.
        errors:
          type: string
          example: Missing business/store id.
    OrderStatus:
      type: string
      enum:
      - unspecified
      - order_placed
      - delivery_created
      - order_completed
      - order_cancelled
      - store_confirmed_order
      - store_confirmed_ready_for_pickup
      - dasher_confirmed_assignment
      - dasher_arriving_at_store
      - dasher_confirmed_at_store
      - dasher_arriving_at_consumer
      - dasher_confirmed_at_consumer
      - order_picked_up
      example: order_placed
    IntegrationId:
      type: string
      pattern: ^([1-9][0-9]*)$
      description: Unique ID for the business, business group or store.
      example: '987654'
    FulfillmentType:
      type: string
      enum:
      - delivery
      - pickup
      example: pickup
    LoyaltyUserSessionRequest:
      type: object
      properties:
        session_id:
          $ref: '#/components/schemas/SessionId'
        integration_id:
          $ref: '#/components/schemas/IntegrationId'
        integration_type:
          $ref: '#/components/schemas/IntegrationType'
      required:
      - session_id
      - integration_id
      - integration_type
    AuthorizationError:
      x-error: true
      type: object
      description: Authorization error, available credentials don't match requested operation
      required:
      - code
      - message
      properties:
        code:
          type: string
          enum:
          - authorization_error
        message:
          type: string
          example: You are not authorized to perform this action.
    StorefrontOrderSessionRequest:
      type: object
      required:
      - store_id
      - menu_id
      - fulfillment_type
      - items
      properties:
        store_id:
          type: string
        menu_id:
          type: string
        fulfillment_type:
          $ref: '#/components/schemas/FulfillmentType'
        items:
          type: array
          items:
            $ref: '#/components/schemas/ExternalCartItem'
        delivery_details:
          $ref: '#/components/schemas/DeliveryDetails'
        scheduled_time:
          type: string
          pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(.[0-9]{3,})?Z$
          description: UTC Timestamp in ISO-8601 format
          example: 2018-08-22T17:20:28Z or 2018-08-22T17:20:28.123Z
    ShouldDeleteExistingCarts:
      type: boolean
      default: true
    CreatedAt:
      type: string
      pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(.[0-9]{3,})?Z$
      description: UTC Timestamp in ISO-8601 format
      example: 2018-08-22T17:20:28Z or 2018-08-22T17:20:28.123Z
    CartId:
      type: string
      description: id of the cart.
    StorefrontOrderSessionResponse:
      type: object
      required:
      - order_session_id
      - checkout_url
      properties:
        order_session_id:
          type: string
        checkout_url:
          type: string
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer