openapi: 3.1.0
info:
  title: Deliverect Channel Accounts Jobs API
  description: Integrate ordering channels and marketplaces with Deliverect to create and cancel orders, sync menus, snooze products, update store and courier status, and exchange payment events. Authenticates with OAuth 2.0 machine-to-machine access tokens scoped via genericChannel.
  version: '1.0'
  x-generated-from: documentation
  x-source-url: https://developers.deliverect.com/reference
  x-last-validated: '2026-06-02'
  contact:
    name: Kin Lane
    email: kin@apievangelist.com
  license:
    name: All Rights Reserved
servers:
- url: https://api.deliverect.com
  description: Production
- url: https://api.staging.deliverect.com
  description: Staging
security:
- oauth2: []
tags:
- name: Jobs
  description: Jobs operations for the Deliverect Dispatch API.
paths:
  /validate_job:
    post:
      summary: Deliverect Validate Delivery Job
      description: The initial dispatch notification that a new job is available which needs validated as being deliverable
      operationId: dispatch_validate_job
      responses:
        '200':
          description: '200'
          content:
            application/json:
              examples:
                Can Deliver:
                  value: "{\n  \"jobId\": \"627a6f4c2*****3fbc79a\",\n  \"canDeliver\": true,\n  \"distance\":10,\n  \"pickupTimeETA\": \"2022-05-10T14:47:31.649000Z\",\n  \"deliveryLocations\": [\n    {\n      \"deliveryId\": \"ABC567\",\n      \"orderId\": \"627a6f*****5c09221a9837\",\n      \"deliveryTimeETA\": \"2022-05-10T14:57:31.649000Z\"\n    }\n  ],\n  \"price\": {\n    \"price\": 750,\n    \"taxRate\": 10000\n  }\n}"
                Cannot Deliver:
                  value: "{\n  \"jobId\": \"651******************22a\",\n  \"canDeliver\": false,\n  \"errors\": [\n    {\n      \"deliveryId\": \"J****FI\",\n      \"orderId\": \"651******************215\",\n      \"channelOrderDisplayId\": \"T1***51\",\n      \"reason\": 20,\n      \"description\": \"No drivers available at this time\"\n    }\n    ]\n}"
              schema:
                type: object
                properties:
                  jobId:
                    type: string
                    example: 627a6f4c2*****3fbc79a
                  canDeliver:
                    type: boolean
                    example: true
                    default: true
                  distance:
                    type: integer
                    example: 10
                    default: 0
                  pickupTimeETA:
                    type: string
                    example: '2022-05-10T14:47:31.649000Z'
                  deliveryLocations:
                    type: array
                    items:
                      type: object
                      properties:
                        deliveryId:
                          type: string
                          example: ABC567
                        orderId:
                          type: string
                          example: 627a6f*****5c09221a9837
                        deliveryTimeETA:
                          type: string
                          example: '2022-05-10T14:57:31.649000Z'
                  price:
                    type: object
                    properties:
                      price:
                        type: integer
                        example: 750
                        default: 0
                      taxRate:
                        type: integer
                        example: 10000
                        default: 0
        '400':
          description: '400'
          content:
            text/plain:
              examples:
                Result:
                  value: ''
        '422':
          description: '422'
          content:
            text/plain:
              examples:
                Result:
                  value: ''
      deprecated: false
      tags:
      - Jobs
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /dispatch/create_job:
    post:
      summary: Deliverect Create Delivery Job
      description: Once a delivery job is validated a second webhook event will be sent to confirm the full details
      operationId: dispatch_create_job
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                jobId:
                  type: string
                  example: 609***72e
                account:
                  type: string
                  example: 5f1***131
                pickupTime:
                  type: string
                  format: date-time
                  example: '2021-05-13T13:40:04Z'
                transportType:
                  type: string
                  example: unknown
                driverTip:
                  type: integer
                  example: 500
                pickupLocation:
                  type: object
                  properties:
                    location:
                      type: string
                      example: 606***555
                    name:
                      type: string
                      example: Deliverects Pizza Place
                    remarks:
                      type: string
                      example: please use the backdoor for order pickup
                    street:
                      type: string
                      example: van Ghentlaan
                    streetNumber:
                      type: string
                      example: '3'
                    postalCode:
                      type: string
                      example: 9000 LK
                    city:
                      type: string
                      example: Leusden
                    latitude:
                      type: string
                      example: '52.379189'
                    longitude:
                      type: string
                      example: '4.899431'
                deliveryLocations:
                  type: array
                  items:
                    type: object
                    properties:
                      orderId:
                        type: string
                        example: 609***4dd
                      channelOrderDisplayId:
                        type: string
                        example: MT4YVTPL
                      deliveryTime:
                        type: string
                        format: date-time
                        example: '2021-05-13T13:55:00Z'
                      packageSize:
                        type: string
                        example: medium
                      orderDescription:
                        type: string
                        example: hot food
                      company:
                        type: string
                        example: BrainQuantums
                      name:
                        type: string
                        example: V. Bertels
                      street:
                        type: string
                        example: Refugehof
                      streetNumber:
                        type: string
                        example: '49'
                      postalCode:
                        type: string
                        example: 9001 AB
                      city:
                        type: string
                        example: Leusden
                      phone:
                        type: string
                        example: '+32123456789'
                      phoneAccessCode:
                        type: string
                        example: '342241214'
                      deliveryRemarks:
                        type: string
                        example: Dont ring door bell.
                      latitude:
                        type: string
                        example: '52.379189'
                      longitude:
                        type: string
                        example: '4.899431'
                      payment:
                        type: object
                        properties:
                          orderIsAlreadyPaid:
                            type: boolean
                            example: true
                          amount:
                            type: integer
                            example: 1100
                          paymentType:
                            type: integer
                            example: 0
                ageCheck:
                  type: boolean
                  example: false
            examples:
              dispatch_create_job_request:
                summary: Default dispatch_create_job request
                x-microcks-default: true
                value:
                  jobId: 609***72e
                  account: 5f1***131
                  pickupTime: '2021-05-13T13:40:04Z'
                  transportType: unknown
                  driverTip: 500
                  pickupLocation:
                    location: 606***555
                    name: Deliverects Pizza Place
                    remarks: please use the backdoor for order pickup
                    street: van Ghentlaan
                    streetNumber: '3'
                    postalCode: 9000 LK
                    city: Leusden
                    latitude: '52.379189'
                    longitude: '4.899431'
                  deliveryLocations:
                  - orderId: 609***4dd
                    channelOrderDisplayId: MT4YVTPL
                    deliveryTime: '2021-05-13T13:55:00Z'
                    packageSize: medium
                    orderDescription: hot food
                    company: BrainQuantums
                    name: V. Bertels
                    street: Refugehof
                    streetNumber: '49'
                    postalCode: 9001 AB
                    city: Leusden
                    phone: '+32123456789'
                    phoneAccessCode: '342241214'
                    deliveryRemarks: Dont ring door bell.
                    latitude: '52.379189'
                    longitude: '4.899431'
                    payment:
                      orderIsAlreadyPaid: true
                      amount: 1100
                      paymentType: 0
                  ageCheck: false
      responses:
        '200':
          description: '200'
          content:
            application/json:
              examples:
                Result:
                  value: '{}'
              schema:
                type: object
                properties: {}
        '400':
          description: '400'
          content:
            application/json:
              examples:
                Result:
                  value: '{}'
              schema:
                type: object
                properties: {}
        '422':
          description: '422'
          content:
            application/json:
              examples:
                Result:
                  value: "{\n\t[{\n\t\t“reason”: DeliveryJobErrorReason,\n\t\t“description”: string,\n\t\t“extraDetails”: string\n\t}]\n}"
      deprecated: false
      tags:
      - Jobs
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /dispatch/updateJob:
    post:
      summary: Deliverect Copy of Cancel Delivery Job
      description: A merchant or ordering channel may cancel the order, which in turn will cancel the delivery job
      operationId: dispatch_updatejob
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                _id:
                  type: string
                  example: 5c8fbfd3c6489f00010e50d1
                externalJobId:
                  type: string
                  example: ABC123
                deliveryLocations:
                  type: array
                  items:
                    type: object
                    properties:
                      deliveryId:
                        type: string
                        example: ABC567
                      orderId:
                        type: string
                        example: 5f47a223280a29046404e2af
                      channelOrderDisplayId:
                        type: string
                        example: MT4YVTPL
                      deliveryTime:
                        type: string
                        format: date-time
                        example: '2019-02-20T16:45:00.000000Z'
                      packageSize:
                        type: string
                        example: small
                      orderDescription:
                        type: string
                        example: hot food
                      company:
                        type: string
                        example: BrainQuantums
                      name:
                        type: string
                        example: V. Bertels
                      street:
                        type: string
                        example: Refugehof
                      streetNumber:
                        type: string
                        example: '49'
                      postalCode:
                        type: string
                        example: 9001 AB
                      city:
                        type: string
                        example: Leusden
                      phone:
                        type: string
                        example: '+32123456789'
                      latitude:
                        type: string
                        example: '52.370216'
                      longitude:
                        type: string
                        example: '4.895168'
                      deliveryRemarks:
                        type: string
                        example: please knock 3x, baby is sleeping
                      payment:
                        type: object
                        properties:
                          orderIsAlreadyPaid:
                            type: boolean
                            example: false
                          amount:
                            type: integer
                            example: 1500
                          paymentType:
                            type: integer
                            example: 2
                          paysWith:
                            type: integer
                            example: 2000
            examples:
              dispatch_updatejob_request:
                summary: Default dispatch_updatejob request
                x-microcks-default: true
                value:
                  _id: 5c8fbfd3c6489f00010e50d1
                  externalJobId: ABC123
                  deliveryLocations:
                  - deliveryId: ABC567
                    orderId: 5f47a223280a29046404e2af
                    channelOrderDisplayId: MT4YVTPL
                    deliveryTime: '2019-02-20T16:45:00.000000Z'
                    packageSize: small
                    orderDescription: hot food
                    company: BrainQuantums
                    name: V. Bertels
                    street: Refugehof
                    streetNumber: '49'
                    postalCode: 9001 AB
                    city: Leusden
                    phone: '+32123456789'
                    latitude: '52.370216'
                    longitude: '4.895168'
                    deliveryRemarks: please knock 3x, baby is sleeping
                    payment:
                      orderIsAlreadyPaid: false
                      amount: 1500
                      paymentType: 2
                      paysWith: 2000
                  - orderId: 5f47a484d08f00f30f04e7eb
                    channelOrderDisplayId: 82DE5
                    deliveryTime: '2019-02-20T16:45:00.000000Z'
                    packageSize: large
                    orderDescription: hot food
                    name: C. Landman
                    street: Prinsengracht
                    streetNumber: '198'
                    postalCode: 9101 CG
                    city: Leusden
                    phone: '+3212987654'
                    latitude: '52.370216'
                    longitude: '4.895168'
                    deliveryRemarks: ''
                    payment:
                      orderIsAlreadyPaid: true
                      amount: 1000
                      paymentType: 3
      responses:
        '200':
          description: '200'
          content:
            application/json:
              examples:
                Result:
                  value: '{}'
              schema:
                type: object
                properties: {}
        '400':
          description: '400'
          content:
            application/json:
              examples:
                Result:
                  value: '{}'
              schema:
                type: object
                properties: {}
      deprecated: false
      tags:
      - Jobs
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /dispatch/cancel_job:
    post:
      summary: Deliverect Cancel Delivery Job
      description: A merchant or ordering channel may cancel the order, which in turn will cancel the delivery job
      operationId: dispatch_cancel_job
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                jobId:
                  type: string
                  example: 5c8******************0d1
                account:
                  type: string
                  example: 5be******************e57
                pickupLocation:
                  type: object
                  properties:
                    location:
                      type: string
                      example: 5ea******************4a9
                deliveryLocations:
                  type: array
                  items:
                    type: object
                    properties:
                      orderId:
                        type: string
                        example: 5f4******************2af
                      channelOrderDisplayId:
                        type: string
                        example: MT4YVTPL
                      deliveryId:
                        type: string
                        example: ABC567
                courier:
                  type: object
                  properties:
                    courierId:
                      type: string
                      example: D1234
            examples:
              dispatch_cancel_job_request:
                summary: Default dispatch_cancel_job request
                x-microcks-default: true
                value:
                  jobId: 5c8******************0d1
                  account: 5be******************e57
                  pickupLocation:
                    location: 5ea******************4a9
                  deliveryLocations:
                  - orderId: 5f4******************2af
                    channelOrderDisplayId: MT4YVTPL
                    deliveryId: ABC567
                  courier:
                    courierId: D1234
      responses:
        '200':
          description: '200'
          content:
            application/json:
              examples:
                Result:
                  value: '{}'
              schema:
                type: object
                properties: {}
        '400':
          description: '400'
          content:
            application/json:
              examples:
                Result:
                  value: '{}'
              schema:
                type: object
                properties: {}
      deprecated: false
      tags:
      - Jobs
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 machine-to-machine client-credentials. Exchange client_id/client_secret at POST /oauth/token for a Bearer access_token.
      flows:
        clientCredentials:
          tokenUrl: https://api.deliverect.com/oauth/token
          scopes: {}