Bevz Pick a Delivery Service for Onboarding API

openapi: 3.2.0
info:
  title: Bevz Integrator Service Pick a Delivery Service for Onboarding API
  contact:
    name: API Support
    email: tech@bevz.com
  description: '# Introduction


    Welcome to the Bevz Integrator Service API documentation.


    The Bevz Integrator Service empowers our partners—including integrators and third-party POS providers—to seamlessly manage stores and related operations through a secure, scalable, and high-performance REST API platform.


    ## Who is this documentation for?


    This documentation is designed for integrators and third-party POS systems looking to leverage the Bevz SaaS platform to automate and streamline store management, menu operations, and more.


    ## Key Features


    By integrating with the Bevz platform, you gain access to:


    - **Rapid Store Onboarding:** Effortlessly provision and deprovision stores using our dedicated APIs.

    - **Menu Management:** Upload, update, and synchronize store menus programmatically.

    - **User & Access Management:** Manage integrator admin users and developer access for your organization.

    - **Order Processing:** Receive and process orders in real time via webhooks and API endpoints.

    - **Reporting & Analytics:** (Coming Soon) Access comprehensive reporting tools to monitor and optimize your operations.


    Explore the following sections to get started, review API endpoints, and discover best practices for a successful integration with Bevz.

    '
  version: 1.12.0
servers:
- url: https://api.bevz.com/integrator-service
  description: Production server
- url: https://sandbox-api.bevz.com/integrator-service
  description: Sandbox server
tags:
- name: Pick a Delivery Service for Onboarding API
  description: 'This document outlines the integration flow for onboarding new DoorDash and Grubhub stores through the [Delivery Services Onboarding API](#tag/Pick-a-Delivery-Service-for-Onboarding-API/operation/onboard).


    ## DoorDash Onboarding


    ### Overview

    Onboarding a store to DoorDash is an asynchronous process initiated by Bevz via a webhook. Once the POS sends a request to the [Delivery Services Onboarding API](#tag/Pick-a-Delivery-Service-for-Onboarding-API/operation/onboard), DoorDash processes the information, performs necessary checks, and notifies Bevz of the outcome through a webhook.


    ### Process Flow

    1. **Initiate Onboarding Request**

    - The POS sends a request to the Delivery Services Onboarding API with all required store and sensitive information.

    - Refer to the [Delivery Services Onboarding API](#tag/Pick-a-Delivery-Service-for-Onboarding-API/operation/onboard) for required fields.

    2. **DoorDash Processing**

    - DoorDash attempts to map the store using the provided details, requests approval from the merchant, and performs internal checks such as menu QA and business admin verification.

    3. **Receive Webhook Notification**

    - Once DoorDash completes processing, they send a webhook notification to Bevz indicating the onboarding status (e.g., approved, pending, rejected) and any relevant details or next steps.

    4. **Finalize Onboarding**

    - The integration is activated once all requirements and approvals are met. If issues arise (e.g., missing hours, menu errors, compliance problems), DoorDash notifies the merchant and Bevz for resolution.



    ## Grubhub Onboarding


    ### Overview

    The onboarding process enables POS systems to initiate a Grubhub store onboarding request via the [Delivery Services Onboarding API](#tag/Pick-a-Delivery-Service-for-Onboarding-API/operation/onboard). Bevz provides an auto-populated onboarding form, which the POS can present to the store. After submission, a Grubhub representative contacts the store to complete setup.


    ### Process Flow

    1. **Initiate Onboarding Request**

    - The POS sends a request to the Delivery Services Onboarding API.

    - This request contains the required store information (e.g., store details, sensitive data).

    2. **Generate Onboarding Link**

    - Bevz responds with a unique onboarding link.

    - This link points to a form that is pre-filled with store data provided in step 1.

    3. **Customer Completes Form**

    - The POS system embeds or redirects the store to the generated onboarding link.

    - The store reviews and completes the form.

    4. **Grubhub Representative Follows Up**

    - Once the store submits the form, the information is sent to Grubhub.

    - A Grubhub representative contacts the store to finalize onboarding and assist with setup.

    '
paths:
  /integrators/{integrator_id}/stores/{store_id}/onboard-delivery-services:
    post:
      tags:
      - Pick a Delivery Service for Onboarding API
      operationId: onboard
      summary: Delivery Services Onboarding API
      description: 'The Delivery Services Onboarding API allows you to onboard your store to DoorDash or Grubhub and manage related integration operations.


        Use this endpoint to configure service-specific settings, such as commission rates, menu sync options, and enable/disable status for each delivery service.

        '
      parameters:
      - name: integrator_id
        in: path
        required: true
        schema:
          type: integer
          format: int64
        description: Unique identifier for the integrator.
      - name: store_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Unique identifier for the store.
      - name: Authorization
        in: header
        required: true
        schema:
          type: string
        description: "JWT token for authenticating API requests.  \n"
        example: Bearer yourJWTtoken
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeliverySettings'
      responses:
        '200':
          description: Successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      link:
                        type: string
                        description: Grubhub jotform link with prefilled store information (grubhub only).
              examples:
                doordash:
                  summary: DoorDash
                  value:
                    message: Successfully onboarded DoorDash delivery service
                grubhub:
                  summary: Grubhub
                  value:
                    message: Your application to Grubhub was successfully submitted. Grubhub Representative will reach out to you to help get started with Grubhub.
                    link: https://grubhub.jotform.com/231635658468872?storeName=Bevz+Test+Store
        '400':
          description: Bad request! Please check your input.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  errors:
                    type: array
                    items:
                      type: string
              examples:
                doordash_inventory:
                  summary: DoorDash - Not enough inventory
                  value:
                    message: Bad request! Please check your input.
                    errors:
                    - Store must have at least 500 items in its inventory or menu. Please add more items to proceed
                doordash_hours:
                  summary: DoorDash - Store hours not set
                  value:
                    message: Bad request! Please check your input.
                    errors:
                    - Store has no Store Hours set. Please set your hours to proceed (Settings > Store Info > Add Store Hours)
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  errors:
                    type: array
              examples:
                Integrator unauthorized to perform this action!:
                  value:
                    message: Unauthorized request! Please check your permission.
                    errors:
                    - Integrator unauthorized to perform this action!
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: User is not authorized to access this resource with an explicit deny
components:
  schemas:
    DeliverySettings:
      type: object
      required:
      - deliveryService
      discriminator:
        propertyName: deliveryService
        mapping:
          DOORDASH: '#/components/schemas/DeliverySettingsDD'
          GRUBHUB: '#/components/schemas/DeliverySettingsGH'
      properties:
        deliveryService:
          type: string
          description: DOORDASH | GRUBHUB
x-tagGroups:
- name: getting started
  tags:
  - Introduction
  - What is this documentation for?
  - Getting Started
- name: guides
  tags:
  - Preparing Your Store
  - Using Webhooks
  - Uploading store menu
  - Receiving and processing order
- name: apis
  tags:
  - Integrators
  - integrator_users
  - Stores
  - Store Products
  - Lotto Scratcher Games
  - Order
- name: Delivery Services Onboarding
  tags:
  - Pick a Delivery Service for Onboarding API
  - Uber Eats Onboarding API Workflow
- name: webhooks
  tags:
  - Webhooks
- name: models
  tags:
  - models
- name: faqs
  tags:
  - faq
- name: changelog
  tags:
  - Changelog