openapi: 3.2.0
info:
  description: API to manage item catalog, inventory, pricing and other attributes.
  version: '2.0'
  title: Doordash Item management API Specification Promotion…
  x-logo:
    url: https://cdn.doordash.com/static/img/merchant/logo-red@3x.png
    backgroundColor: '#FFFFFF'
    altText: Doordash Marketplace
    href: https://developer.doordash.com/
servers:
- url: https://openapi.doordash.com/marketplace
tags:
- name: PromotionManagementEndpoints
  x-displayName: Promotion Management Endpoints
  description: Endpoints for promotion management
paths:
  /api/v2/promotions/stores/{store_location_id}:
    post:
      tags:
      - PromotionManagementEndpoints
      summary: Create new promotion for store
      operationId: createPromotion
      parameters:
      - name: store_location_id
        in: path
        description: location ID of store
        required: true
        schema:
          type: string
          format: string
      responses:
        '202':
          description: Accepted
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncOperationResponse'
        '400':
          description: Request Validation Failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationFieldError'
        '401':
          description: Request unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        '422':
          description: Request Entity Too Large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestNotProcessError'
        '429':
          description: Request is rate limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestRateLimitedError'
        '500':
          description: Internal service failure, please try again later
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/server_fault'
      requestBody:
        description: create new promotion
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Promotion'
    patch:
      tags:
      - PromotionManagementEndpoints
      summary: Update promotions in store
      operationId: updatePromotions
      parameters:
      - name: store_location_id
        in: path
        description: location ID of store to be updated
        required: true
        schema:
          type: string
          format: string
      responses:
        '202':
          description: Accepted
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncOperationResponse'
        '400':
          description: Request Validation Failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationFieldError'
        '401':
          description: Request unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationError'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        '422':
          description: Request Entity Too Large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestNotProcessError'
        '429':
          description: Request is rate limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestRateLimitedError'
        '500':
          description: Internal service failure, please try again later
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/server_fault'
      requestBody:
        description: update promotions in store
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Promotion'
components:
  schemas:
    RequestRateLimitedError:
      x-error: true
      type: object
      description: Request was rate limited.
      required:
      - code
      - message
      properties:
        code:
          type: string
          enum:
          - request_rate_limited
        message:
          type: string
          example: Request was rate limited. You may be calling the API too much in a short time.
    AsyncOperationResponse:
      type: object
      properties:
        operation_id:
          type: string
        operation_status:
          type: string
          enum:
          - QUEUED
          - IN_PROGRESS
          - SUCCESS
          - FAILED
          - PARTIAL_SUCCESS
        message:
          type: string
    AuthenticationError:
      x-error: true
      type: object
      description: 'Authentication error: the token provided with the request doesn''t work for the requested operation'
      required:
      - code
      - message
      properties:
        code:
          type: string
          enum:
          - authentication_error
          default: authentication_error
        message:
          type: string
          example: The [exp] is in the past; the JWT is expired
          default: The [exp] is in the past; the JWT is expired
    Promotion:
      title: Promotion
      description: Promotion to be managed by doordash.
      properties:
        promotion_id:
          type: string
          description: 'Promotion Id to identify a promotion uniquely with a Mx. Required. '
        promotion_type:
          type: string
          description: Promotion types
          enum:
          - BUY_X_FOR_Y
          - BUY_X_SAVE_Y
          - BUY_X_GET_Y_Z_PERCENT_OFF
        funding_source:
          type: string
          description: Funding source type
          enum:
          - MERCHANT
          - CPG
        purchase_criteria:
          type: object
          description: Purchase criteria to redeem this promotion
          properties:
            purchase_items:
              description: List of MSIDs that need to be purchased to redeem this promotion
              type: array
              items:
                type: string
            purchase_quantity:
              type: integer
              description: The number required for purchasing to redeem this promotion
        redemption_limit:
          type: object
          description: Purchase criteria to redeem this promotion
          properties:
            limit_per_order:
              type: integer
              description: The maximum number of times this promotion can be redeemed per order, default to 3
        discount_options:
          type: object
          description: Purchase criteria to redeem this promotion
          properties:
            discount_total_price:
              type: number
              description: The total price in cents for this promotion after discount if promotion type is BUY_X_FOR_Y
            discount_price_off:
              type: number
              description: The discount price in cents when applying this promotion if promotion type is BUY_X_SAVE_Y
            discount_percentage:
              type: number
              description: The percentage of discount when applying this promotion if promotion type is BUY_X_GET_Y_Z_PERCENT_OFF
            discount_quantity:
              type: number
              description: The discount quantity when applying this promotion if promotion type is BUY_X_GET_Y_Z_PERCENT_OFF
        promotion_options:
          type: object
          description: The options to represent for what and how a promotion can be defined
          properties:
            promotion_conditions:
              type: array
              description: The conditional options that can be configured for a promotion. For example, MIX_AND_MATCH indicate that the supplied purchase items can be used in a Mix-and-Match deal.
              items:
                type: string
                enum:
                - MIX_AND_MATCH
        start_time:
          type: string
          format: yyyy-MM-ddTHH:mm:ssXXX
          description: required, start time of the promotion with local timezone, example 2024-04-03T10:15:30Z https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html#ISO_ZONED_DATE_TIME
        end_time:
          type: string
          format: yyyy-MM-ddTHH:mm:ssXXX
          description: required, end time of the promotion with local timezone https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html#ISO_ZONED_DATE_TIME
    RequestNotProcessError:
      x-error: true
      type: object
      description: Request was not process.
      required:
      - code
      - message
      properties:
        code:
          type: string
          enum:
          - request_rate_limited
        message:
          type: string
          example: Request was not process. Request entity may be too large.
    ValidationFieldError:
      x-error: true
      title: ValidationFieldError
      type: object
      description: One or more request values couldn't be validated.
      required:
      - code
      - message
      - field_errors
      properties:
        code:
          type: string
          enum:
          - validation_error
        message:
          type: string
          description: One or more request values couldn't be validated.
          example: One or more request values couldn't be validated.
        field_errors:
          type: array
          description: The list of fields whose values couldn't be validated. See more [error examples](https://developer.doordash.com/en-US/docs/drive/reference/errors)
          items:
            $ref: '#/components/schemas/FieldError'
          readOnly: true
    NotFoundError:
      x-error: true
      type: object
      description: Request entity was not found.
      required:
      - code
      - message
      properties:
        code:
          type: string
          enum:
          - unknown_business_id
        message:
          type: string
          example: Entity was not found
    FieldError:
      title: FieldError
      type: object
      description: A field whose value couldn't be validated.
      required:
      - field
      - error
      properties:
        field:
          type: string
          description: Name of the field whose value couldn't be validated.
          example: pickup_phone_number
        error:
          type: string
          description: The error that was encountered when validating the field's value.
          example: Invalid phone number format
    server_fault:
      x-error: true
      type: object
      description: Internal service failure, please try again later.
      required:
      - code
      - message
      properties:
        code:
          type: string
          enum:
          - service_fault
          default: service_fault
        message:
          type: string
          example: Internal service failure, please try again later.
          default: Internal service failure, please try again later.
    AuthorizationError:
      x-error: true
      type: object
      description: 'Authorization error: the credentials provided with the request don''t work for the requested operation'
      required:
      - code
      - message
      properties:
        code:
          type: string
          enum:
          - authorization_error
          default: authorization_error
        message:
          type: string
          example: 'Authorization error: the credentials provided with the request don''t work for the requested operation'
          default: 'Authorization error: the credentials provided with the request don''t work for the requested operation'