openapi: 3.1.0
info:
  title: Deliverect Channel Accounts Checkout 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: Checkout
  description: Checkout operations for the Deliverect Commerce API.
paths:
  /commerce/{accountId}/v2/checkouts:
    post:
      tags:
      - Checkout
      summary: Deliverect Checkout Basket
      description: Creates a checkout session from a basket, leading to a payment intent based on the provided gateway.
      operationId: post_commerce_accountId_checkouts_1
      parameters:
      - name: accountId
        in: path
        schema:
          type: string
          default: 668e4aa170efd23c474b2ad1
        required: true
        description: The accountId value.
        example: 668e4aa170efd23c474b2ad1
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - basket
              - payments
              properties:
                basket:
                  type: object
                  required:
                  - id
                  properties:
                    id:
                      type: string
                      example: 609a1b2c3d4e5f6a7b8c9d0e
                note:
                  type: string
                  example: No salad
                payments:
                  type: array
                  items:
                    properties:
                      type:
                        type: string
                        default: dpay
                        enum:
                        - dpay
                        - third_party
                        - gift_card
                        example: dpay
                      externalId:
                        type: string
                        default: ''
                        description: id of the payment provider
                        example: 609a1b2c3d4e5f6a7b8c9d0e
                      isPrepaid:
                        type: boolean
                        default: 'true'
                        description: indicates whether the order has been paid. For Dpay it should be true.
                        example: 'true'
                      amount:
                        type: integer
                        default: ''
                        description: total amount paid with 2 decimal digits. 800 would correspond to 8 in local currency
                        example: 1250
                      metadata:
                        type: object
                        properties: {}
                    type: object
                    required:
                    - type
                    - externalId
                    - isPrepaid
                    - amount
                order:
                  type: object
                  properties:
                    channelOrderId:
                      type: string
                      description: The full unique ID from the ordering channel, cannot be reused within 48hr after pickup (across all accounts)
                      example: 609a1b2c3d4e5f6a7b8c9d0e
                    channelOrderDisplayId:
                      type: string
                      description: A more human‑readable order reference to provide, usually shorter than the channelOrderId
                      example: 609a1b2c3d4e5f6a7b8c9d0e
                    validationId:
                      type: string
                      example: 609a1b2c3d4e5f6a7b8c9d0e
                    courier:
                      type: string
                      example: string
            examples:
              Deliverect Pay:
                summary: Deliverect Pay
                value:
                  basket:
                    id: '{{commerceBasketId}}'
                  order:
                    channelOrderId: '{{uuid}}'
                    channelOrderDisplayId: DISPLAY-{{uuid}}
                  note: ORDER LEVEL NOTE
                  payments:
                  - type: dpay
                    externalId: 68a4*****0616cad5144
                    isPrepaid: true
                    amount: 900
                    metadata: {}
              Gift Card:
                summary: Gift Card
                value: "{\n    \"basket\": {\n      \"id\": \"{{commerceBasketId}}\"\n    },\n    \"order\": {\n      \"channelOrderId\": \"{{uuid}}\",\n      \"channelOrderDisplayId\": \"DISPLAY-{{uuid}}\"\n    },\n    \"note\": \"ORDER LEVEL NOTE\",\n    \"payments\": [\n      {\n        \"type\": \"gift_card\",\n        \"externalId\": \"{{guid}}\",\n        \"isPrepaid\": true,\n        \"amount\": 900,\n        \"metadata\": {\n          \"giftCardProviderProfileLinkId\": \"68656743e24307aece89862e\",\n          \"giftCardNumber\": \"6000101001050148\",\n          \"giftCardVerificationCode\": \"528811\"\n        }\n      }\n    ]\n  }\n}"
              Third Party:
                summary: Third Party
                value: " {\n    \"basket\": {\n      \"id\": \"{{commerceBasketId}}\"\n    },\n    \"order\": {\n      \"channelOrderId\": \"{{uuid}}\",\n      \"channelOrderDisplayId\": \"DISPLAY-{{uuid}}\"\n    },\n    \"note\": \"ORDER LEVEL NOTE\",\n    \"payments\": [\n      {\n        \"type\": \"third_party\",\n        \"externalId\": \"{{$guid}}\",\n        \"instrumentType\":\"card\",\n        \"isPrepaid\": true,\n        \"amount\": 900,\n        \"metadata\": {}\n      }\n    ]\n  }\n}"
              Multiple Payments:
                summary: Multiple Payments
                value: "{\n    \"basket\": {\n      \"id\": \"{{commerceBasketId}}\"\n    },\n    \"order\": {\n      \"channelOrderId\": \"{{uuid}}\",\n      \"channelOrderDisplayId\": \"{{uuid}}\"\n    },\n    \"note\": \"ORDER LEVEL NOTE\",\n    \"payments\": [\n      {\n        \"type\": \"dpay\",\n        \"externalId\": \"68a4505c7dded0616cad5144\",\n        \"isPrepaid\": false,\n        \"amount\": 300,\n        \"metadata\": {}\n      },\n      {\n        \"type\": \"gift_card\",\n        \"externalId\": \"{{$guid}}\",\n        \"isPrepaid\": true,\n        \"amount\": 300,\n        \"metadata\": {\n          \"giftCardProviderProfileLinkId\": \"68656743e24307aece89862e\",\n          \"giftCardNumber\": \"6000101001050148\",\n          \"giftCardVerificationCode\": \"528811\"\n        }\n      },\n      {\n        \"type\": \"third_party\",\n        \"externalId\": \"{{$guid}}\",\n        \"isPrepaid\": true,\n        \"instrumentType\":\"card\",\n        \"amount\": 300,\n        \"metadata\": {}\n      }\n    ]\n  }\n}"
      responses:
        '200':
          description: '200'
          content:
            application/json:
              examples:
                offline:
                  value:
                    id: 694138133662b46bddf06e70
                    created: '2025-12-16T10:44:35.107000'
                    updated: '2025-12-16T10:44:51.016000+00:00'
                    deleted: false
                    etag: 2e94b59d6155094830af3362502fddc0cd51ef2f
                    accountId: 668cd58b6da5e4cec26f1f35
                    channelLinkId: 6911e9be1531637e9cf80a5f
                    storeId: 6911e9be1531637e9cf80a5f
                    status: open
                    failureReason: null
                    basket:
                      id: 694138103662b46bddf06e6e
                      channel: 10165
                      category:
                        type: restaurant
                      currency: AED
                      taxExclusive: false
                      status: open
                      items:
                      - id: 694138103662b46bddf06e6f
                        menuId: 6882366cf04ece702e6661c8
                        plu: STK-01
                        name: Delicious Steak Frites
                        quantity: 1
                        price: 1500
                        gross: 1500
                        taxes: []
                        net: 1500
                        subItems:
                        - customizationPlu: MOD-01
                          plu: COOK-01
                          name: Rare
                          quantity: 1
                          price: 0
                          subItems: []
                          note: null
                        - customizationPlu: MOD-02
                          plu: SI-01
                          name: Fries
                          quantity: 1
                          price: 0
                          subItems: []
                          note: null
                        discounts: []
                        discountTotal: 0
                        note: ITEM LEVEL NOTE
                      payment:
                        tips: []
                        discountsTotal: 0
                        chargesTotal: 0
                        taxTotal: 0
                        tipTotal: 0
                        subTotal: 1500
                        total: 1500
                      customer:
                        name: John Doe
                        companyName: ACME
                        phoneNumber: '+32474081356'
                        email: john.doe@acme.com
                        externalId: custom_channel_id_12345
                        loyaltyProviderCustomerId: null
                        tin: null
                      fulfillment:
                        type: eatIn
                        spot: TABLE-1
                      taxes: []
                      discounts: []
                      charges:
                        serviceCharge:
                          value: 0
                          taxRate: 0
                          gross: 0
                          tax: 0
                          net: 0
                          type: fixed
                        bagFee:
                          value: 0
                          taxRate: 0
                          gross: 0
                          tax: 0
                          net: 0
                        deliveryFee:
                          value: 0
                          taxRate: 0
                          gross: 0
                          tax: 0
                          net: 0
                        taxTotal: 0
                        netTotal: 0
                        grossTotal: 0
                    payment:
                      id: 694138133662b46bddf06e71
                      gateway: 1
                      status: authorized
                      action:
                        type: offline
                        paid: true
                      metadata: {}
                    order:
                      channelOrderId: 5f6fb9fa-71ad-4758-8118-b9966d950105
                      channelOrderDisplayId: 5f6fb9fa
                      status: null
                redirect:
                  value:
                    id: 6643861d0c1914c93a846b78
                    created: '2024-05-14T15:41:17.518000+00:00'
                    updated: '2024-05-14T15:41:18.449000+00:00'
                    deleted: false
                    etag: f225b232489659ed4dc0f17580f4f0200f4ca3ba
                    accountId: 65c35d109a19b819b7cf78d8
                    storeId: 65eee6a9984a1bc1b9637c59
                    channelLinkId: 65eee6a9984a1bc1b9637c59
                    status: open
                    basket:
                      currency: EUR
                      taxExclusive: false
                      items:
                      - menuId: 62d7f77f64c95193cc29aa91
                        plu: STK-01
                        name: Delicious Steak Frites
                        quantity: 1
                        price: 1500
                        gross: 1500
                        taxes: []
                        net: 1500
                        subItems: []
                        discounts: []
                        discountTotal: 0
                      payment:
                        tips:
                        - amount: 100
                          type: restaurant
                        discountsTotal: 0
                        taxTotal: 0
                        tipTotal: 100
                        total: 1600
                      customer:
                        name: John Doe
                        companyName: ACME
                        phoneNumber: '+3211223344'
                        email: john.doe@acme.com
                        tin: '123456789'
                      fulfillment:
                        type: pickup
                      taxes: []
                      discounts: []
                    payment:
                      id: 62d7f77f64c95193cc29aa91
                      status: pending
                      action:
                        type: redirect
                        url: http://payment.acme.com/1234
                    order: null
              schema:
                type: object
                properties:
                  id:
                    type: string
                    example: 6643861d0c1914c93a846b78
                  created:
                    type: string
                    example: '2024-05-14T15:41:17.518000+00:00'
                  updated:
                    type: string
                    example: '2024-05-14T15:41:18.449000+00:00'
                  deleted:
                    type: boolean
                    example: false
                    default: true
                  etag:
                    type: string
                    example: f225b232489659ed4dc0f17580f4f0200f4ca3ba
                  accountId:
                    type: string
                    example: 65c35d109a19b819b7cf78d8
                  storeId:
                    type: string
                    example: 65eee6a9984a1bc1b9637c59
                  status:
                    type: string
                    example: open
                  basket:
                    type: object
                    properties:
                      currency:
                        type: string
                        example: EUR
                      taxExclusive:
                        type: boolean
                        example: false
                        default: true
                      items:
                        type: array
                        items:
                          type: object
                          properties:
                            menuId:
                              type: string
                              example: 62d7f77f64c95193cc29aa91
                            plu:
                              type: string
                              example: STK-01
                            name:
                              type: string
                              example: Delicious Steak Frites
                            quantity:
                              type: integer
                              example: 1
                              default: 0
                            price:
                              type: integer
                              example: 1500
                              default: 0
                            gross:
                              type: integer
                              example: 1500
                              default: 0
                            taxes:
                              type: array
                            net:
                              type: integer
                              example: 1500
                              default: 0
                            subItems:
                              type: array
                            discounts:
                              type: array
                            discountTotal:
                              type: integer
                              example: 0
                              default: 0
                      payment:
                        type: object
                        properties:
                          tips:
                            type: array
                            items:
                              type: object
                              properties:
                                amount:
                                  type: integer
                                  example: 100
                                  default: 0
                                type:
                                  type: string
                                  example: restaurant
                          discountsTotal:
                            type: integer
                            example: 0
                            default: 0
                          taxTotal:
                            type: integer
                            example: 0
                            default: 0
                          tipTotal:
                            type: integer
                            example: 100
                            default: 0
                          total:
                            type: integer
                            example: 1600
                            default: 0
                      customer:
                        type: object
                        properties:
                          name:
                            type: string
                            example: John Doe
                          companyName:
                            type: string
                            example: ACME
                          phoneNumber:
                            type: string
                            example: '+3211223344'
                          email:
                            type: string
                            example: john.doe@acme.com
                          tin:
                            type: string
                            example: string
                      fulfillment:
                        type: object
                        properties:
                          type:
                            type: string
                            example: pickup
                            enum:
                            - pickup
                            - delivery
                            - dispatch
                      taxes:
                        type: array
                      discounts:
                        type: array
                  payments:
                    type: array
                    items:
                      properties:
                        id:
                          type: string
                          example: 609a1b2c3d4e5f6a7b8c9d0e
                        type:
                          type: string
                          enum:
                          - dpay
                          - third_party
                          - gift_card
                          example: dpay
                        isPrepaid:
                          type: boolean
                          enum:
                          - true
                          - false
                          example: true
                        amount:
                          type: string
                          example: string
                        status:
                          type: string
                          example: confirmed
                      type: object
                  order:
                    type: object
                    properties:
                      channelOrderId:
                        type: string
                        example: 609a1b2c3d4e5f6a7b8c9d0e
                      channelOrderDisplayId:
                        type: string
                        example: 609a1b2c3d4e5f6a7b8c9d0e
        '422':
          description: '422'
          content:
            application/json:
              examples:
                payment_amount_mismatch:
                  value:
                    code: payment_amount_mismatch
                    message: Total of payments does not match basket payment total
                    context:
                      paymentsTotal: 856
                      basketTotal: 854
                  summary: payment_amount_mismatch
              schema:
                type: object
                properties:
                  code:
                    type: string
                    default: ''
                    example: string
                  message:
                    type: string
                    default: ''
                    example: string
                  context:
                    type: object
                    properties:
                      paymentsTotal:
                        type: integer
                        default: ''
                        example: 1250
                      basketTotal:
                        type: integer
                        default: ''
                        example: 1250
                required:
                - code
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /commerce/{accountId}/v2/checkouts/{checkoutId}:
    get:
      tags:
      - Checkout
      summary: Deliverect Get Checkout
      description: Returns a checkout session by ID. This can be used to poll the status of a checkout session providing order placement details.
      operationId: get_commerce_accountId_checkouts_checkoutId_1
      parameters:
      - name: accountId
        in: path
        schema:
          type: string
        required: true
        description: The accountId value.
        example: 5b71c6489f00290d4
      - name: checkoutId
        in: path
        schema:
          type: string
        required: true
        description: The checkoutId value.
        example: 609a1b2c3d4e5f6a7b8c9d0e
      responses:
        '200':
          description: '200'
          content:
            application/json:
              examples:
                completed:
                  value:
                    id: 6643861d0c1914c93a846b78
                    created: '2024-05-14T15:41:17.518000+00:00'
                    updated: '2024-05-14T15:41:18.449000+00:00'
                    deleted: false
                    etag: f225b232489659ed4dc0f17580f4f0200f4ca3ba
                    accountId: 65c35d109a19b819b7cf78d8
                    storeId: 65eee6a9984a1bc1b9637c59
                    channelLinkId: 65eee6a9984a1bc1b9637c59
                    status: completed
                    basket:
                      currency: EUR
                      taxExclusive: false
                      items:
                      - menuId: 62d7f77f64c95193cc29aa91
                        plu: STK-01
                        name: Delicious Steak Frites
                        quantity: 1
                        price: 1500
                        gross: 1500
                        taxes: []
                        net: 1500
                        subItems: []
                        discounts: []
                        discountTotal: 0
                      payment:
                        tips:
                        - amount: 100
                          type: restaurant
                        discountsTotal: 0
                        taxTotal: 0
                        tipTotal: 100
                        total: 1600
                      customer:
                        name: Test
                        companyName: Company LTDA
                        phoneNumber: '12345'
                        email: test@email.com
                        tin: '123456789'
                      fulfillment:
                        type: pickup
                      taxes: []
                      discounts: []
                    payment:
                      id: 62d7f77f64c95193cc29aa91
                      status: authorized
                      action:
                        type: redirect
                        url: http://payment.acme.com/1234
                    order:
                      channelOrderId: 6643861d0c1914c93a846b79
                      channelOrderDisplayId: '01277571'
                pending payment:
                  value:
                    id: 6643861d0c1914c93a846b78
                    created: '2024-05-14T15:41:17.518000+00:00'
                    updated: '2024-05-14T15:41:18.449000+00:00'
                    deleted: false
                    etag: f225b232489659ed4dc0f17580f4f0200f4ca3ba
                    accountId: 65c35d109a19b819b7cf78d8
                    storeId: 65eee6a9984a1bc1b9637c59
                    channelLinkId: 65eee6a9984a1bc1b9637c59
                    status: open
                    basket:
                      currency: EUR
                      taxExclusive: false
                      items:
                      - menuId: 62d7f77f64c95193cc29aa91
                        plu: STK-01
                        name: Delicious Steak Frites
                        quantity: 1
                        price: 1500
                        gross: 1500
                        taxes: []
                        net: 1500
                        subItems: []
                        discounts: []
                        discountTotal: 0
                      payment:
                        tips:
                        - amount: 100
                          type: restaurant
                        discountsTotal: 0
                        taxTotal: 0
                        tipTotal: 100
                        total: 1600
                      customer:
                        name: Test
                        companyName: Company LTDA
                        phoneNumber: '12345'
                        email: test@email.com
                        tin: '123456789'
                      fulfillment:
                        type: pickup
                      taxes: []
                      discounts: []
                    payment:
                      id: 62d7f77f64c95193cc29aa91
                      status: pending
                      action:
                        type: redirect
                        url: http://payment.acme.com/1234
                    order: null
                refused payment:
                  value:
                    id: 6643861d0c1914c93a846b78
                    created: '2024-05-14T15:41:17.518000+00:00'
                    updated: '2024-05-14T15:41:18.449000+00:00'
                    deleted: false
                    etag: f225b232489659ed4dc0f17580f4f0200f4ca3ba
                    accountId: 65c35d109a19b819b7cf78d8
                    storeId: 65eee6a9984a1bc1b9637c59
                    channelLinkId: 65eee6a9984a1bc1b9637c59
                    status: open
                    basket:
                      currency: EUR
                      taxExclusive: false
                      items:
                      - menuId: 62d7f77f64c95193cc29aa91
                        plu: STK-01
                        name: Delicious Steak Frites
                        quantity: 1
                        price: 1500
                        gross: 1500
                        taxes: []
                        net: 1500
                        subItems: []
                        discounts: []
                        discountTotal: 0
                      payment:
                        tips:
                        - amount: 100
                          type: restaurant
                        discountsTotal: 0
                        taxTotal: 0
                        tipTotal: 100
                        total: 1600
                      customer:
                        name: Test
                        companyName: Company LTDA
                        phoneNumber: '12345'
                        email: test@email.com
                        tin: '123456789'
                      fulfillment:
                        type: pickup
                      taxes: []
                      discounts: []
                    payment:
                      id: 62d7f77f64c95193cc29aa91
                      status: refused
                      action:
                        type: redirect
                        url: http://payment.acme.com/1234
                    order: null
                failed payment:
                  value:
                    id: 6643861d0c1914c93a846b78
                    created: '2024-05-14T15:41:17.518000+00:00'
                    updated: '2024-05-14T15:41:18.449000+00:00'
                    deleted: false
                    etag: f225b232489659ed4dc0f17580f4f0200f4ca3ba
                    accountId: 65c35d109a19b819b7cf78d8
                    storeId: 65eee6a9984a1bc1b9637c59
                    channelLinkId: 65eee6a9984a1bc1b9637c59
                    status: failed
                    basket:
                      currency: EUR
                      taxExclusive: false
                      items:
                      - menuId: 62d7f77f64c95193cc29aa91
                        plu: STK-01
                        name: Delicious Steak Frites
                        quantity: 1
                        price: 1500
                        gross: 1500
                        taxes: []
                        net: 1500
                        subItems: []
                        discounts: []
                        discountTotal: 0
                      payment:
                        tips:
                        - amount: 100
                          type: restaurant
                        discountsTotal: 0
                        taxTotal: 0
                        tipTotal: 100
                        total: 1600
                      customer:
                        name: Test
                        companyName: Company LTDA
                        phoneNumber: '12345'
                        email: test@email.com
                        tin: '123456789'
                      fulfillment:
                        type: pickup
                      taxes: []
                      discounts: []
                    payment:
                      id: 62d7f77f64c95193cc29aa91
                      status: failed
                      action: null
                    order: null
              schema:
                oneOf:
                - title: completed
                  type: object
                  properties:
                    id:
                      type: string
                      example: 6643861d0c1914c93a846b78
                    created:
                      type: string
                      example: '2024-05-14T15:41:17.518000+00:00'
                    updated:
                      type: string
                      example: '2024-05-14T15:41:18.449000+00:00'
                    deleted:
                      type: boolean
                      example: false
                      default: true
                    etag:
                      type: string
                      example: f225b232489659ed4dc0f17580f4f0200f4ca3ba
                    accountId:
                      type: string
                      example: 65c35d109a19b819b7cf78d8
                    storeId:
                      type: string
                      example: 65eee6a9984a1bc1b9637c59
                    status:
                      type: string
                      example: completed
                    basket:
                      type: object
                      properties:
                        currency:
                          type: string
                          example: EUR
                        taxExclusive:
                          type: boolean
                          example: false
                          default: true
                        items:
                          type: array
                          items:
                            type: object
                            properties:
                              menuId:
                                type: string
                                example: 62d7f77f64c95193cc29aa91
                              plu:
                                type: string
                        

# --- truncated at 32 KB (49 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/deliverect/refs/heads/main/openapi/deliverect-checkout-api-openapi.yml