Tyro Payments Orders API

openapi: 3.2.0
info:
  title: Ordering API for App Partners Orders API
  version: '1.0'
  contact: {}
  description: This is the API for Apps looking to implement Ordering on Tyro Connect
servers:
- url: https://api.tyro.com/connect
  description: Production
tags:
- name: Orders
paths:
  /orders:
    post:
      summary: New Order
      operationId: create-order
      responses:
        '201':
          description: Created order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/existing-order'
              examples:
                Create order response:
                  $ref: '#/components/examples/create-order-response'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/bad-request-validation-errors-response'
                - $ref: '#/components/schemas/bad-request-single-error-response'
              examples:
                Validation errors:
                  value:
                    message: Request validation failed
                    errors:
                    - segment: body
                      path: items
                      message: '"items" is required'
                    error: '"items" is required'
                Same order id but different content:
                  value:
                    error: Order with the same id but different content already exists
        '401':
          description: Invalid access token
        '403':
          description: Insufficient permissions to create an order
      description: "This endpoint is for creating an order that Tyro Connect will deliver to a POS.\n\n Make sure you create the order in one of the following statuses:\n - `CREATED` - the order has been created but not approved by the merchant.\n - `ACCEPTED` - the order has already been approved by the merchant (eg. via a separate app available to them).\n\nMaking identical requests with the same `orderId` and content **does not** create a new order. In this case, it returns the previously created order's details.\nThis means every new order must have a different `orderId`.\n"
      security:
      - JWT: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/new-order'
            examples:
              New Order:
                value:
                  locationId: tc-merchant-2000
                  origin:
                    orderId: 2f8922fb-235f-40c6-af9a-3d6b46ce9635
                    orderReference: Order for Tom
                  items:
                  - id: unique-item-id
                    sku: sku-known-to-the-pos
                    description: Amazing cheese burger
                    unitPrice:
                      currency: AUD
                      amount: 2000
                    discounts:
                    - currency: AUD
                      amount: 1000
                      description: Half price cheese burgers on the first of the month
                    modifiers:
                    - id: uuid-3636-101
                      sku: '634'
                      description: Bacon
                      unitPrice:
                        amount: 0
                      quantity: 1
                    allergens:
                    - description: Fish
                    - description: Nuts
                    quantity: 1
                  discounts:
                  - currency: AUD
                    amount: 200
                    description: Student discount
                  surcharges:
                  - currency: AUD
                    amount: 200
                    description: Public Holiday
                  - currency: AUD
                    amount: 200
                    description: Plastic take away containers
                  tip:
                    currency: AUD
                    amount: 150
                  total:
                    currency: AUD
                    amount: 1350
                  table:
                    id: B1
                    section: Bar
                  status: CREATED
                  customers:
                  - firstName: Daniel
                  - firstName: Elizabeth
                  fulfilment:
                    type: PICK_UP
                  paymentStatus: CLOSED
              Order with modifiers:
                value:
                  locationId: tc-location-1001
                  origin:
                    orderId: order-1001
                    orderReference: Order for Tom
                  status: ACCEPTED
                  notes: Please hurry, I am hungry.
                  items:
                  - id: uuid-101
                    sku: '101'
                    description: Chicken Burger
                    modifiers:
                    - id: uuid-3636-101
                      sku: '634'
                      description: Cheese
                      quantity: 1
                      unitPrice:
                        amount: 0
                        currency: AUD
                    - id: uuid-3636-202
                      sku: '699'
                      description: Bacon
                      quantity: 1
                      unitPrice:
                        amount: 200
                        currency: AUD
                      discounts:
                      - amount: 100
                        currency: AUD
                        description: Half Price Bacon Day
                    - id: uuid-3636-303
                      sku: '673'
                      description: No Tomato
                      quantity: 1
                      unitPrice:
                        amount: 0
                        currency: AUD
                    quantity: 2
                    unitPrice:
                      amount: 1500
                      currency: AUD
                    discounts:
                    - amount: 150
                      currency: AUD
                      description: 10% Off Burgers on Tuesday
                  - id: uuid-202
                    sku: '213'
                    description: Large Fries
                    quantity: 1
                    unitPrice:
                      amount: 450
                      currency: AUD
                    discounts:
                    - amount: 100
                      currency: AUD
                      description: Combo Price
                  - id: uuid-303
                    sku: '5343'
                    description: Small Cola
                    quantity: 1
                    unitPrice:
                      amount: 250
                      currency: AUD
                  discounts:
                  - amount: 836
                    currency: AUD
                    description: 20% Loyalty Reward
                  surcharges:
                  - amount: 380
                    currency: AUD
                    description: Public Holiday
                  - amount: 300
                    currency: AUD
                    description: Corkage
                  total:
                    amount: 3344
                    currency: AUD
                  table:
                    id: B1
                  customers:
                  - firstName: Daniel
                  fulfilment:
                    type: PICK_UP
                  paymentStatus: CLOSED
              Order with discounts and notes:
                value:
                  locationId: tc-location-1001
                  origin:
                    orderId: 123321821308-5729
                    orderReference: '5729'
                  status: CREATED
                  items:
                  - id: '1'
                    sku: '12345262829'
                    unitPrice:
                      amount: 900
                      currency: AUD
                    modifiers:
                    - id: '1'
                      sku: '12345262832'
                      unitPrice:
                        amount: 0
                        currency: AUD
                      modifiers: []
                      quantity: 1
                      description: No pickles
                    quantity: 2
                    description: Chicken Burger
                  discounts:
                  - amount: 1800
                    currency: AUD
                    description: Order remake - Restaurant's fault.
                  total:
                    amount: 0
                    currency: AUD
                  notes: Order remake - Restaurant's fault. No pickles. I'm allergic
                  fulfilment:
                    type: DELIVERY
                  paymentStatus: CLOSED
              Order with different modifiers:
                value:
                  locationId: tc-location-1001
                  origin:
                    orderId: order-some-id
                    orderReference: Order for Jason's Family
                  status: CREATED
                  items:
                  - id: uuid-201
                    sku: '2001'
                    description: Cheeseburger
                    modifiers:
                    - id: uuid-3636-201
                      sku: '1111'
                      description: Extra patty
                      quantity: 2
                      unitPrice:
                        amount: 150
                        currency: AUD
                    - id: uuid-3636-203
                      sku: '2222'
                      description: No Tomato
                      quantity: 1
                      unitPrice:
                        amount: 0
                        currency: AUD
                    quantity: 2
                    unitPrice:
                      amount: 1000
                      currency: AUD
                    discounts:
                    - amount: 100
                      currency: AUD
                      description: 10% Off Burgers on Tuesday
                    - amount: 100
                      currency: AUD
                      description: Triple Patty promotion
                  - id: uuid-202
                    sku: '2001'
                    description: Cheeseburger
                    modifiers:
                    - id: uuid-3636-201
                      sku: '1111'
                      description: Extra patty
                      quantity: 1
                      unitPrice:
                        amount: 150
                        currency: AUD
                    - id: uuid-3636-203
                      sku: '2222'
                      description: No Tomato
                      quantity: 1
                      unitPrice:
                        amount: 0
                        currency: AUD
                    quantity: 1
                    unitPrice:
                      amount: 1000
                      currency: AUD
                    discounts:
                    - amount: 100
                      currency: AUD
                      description: 10% Off Burgers on Tuesday
                  - id: uuid-203
                    sku: '2001'
                    description: Cheeseburger
                    modifiers:
                    - id: uuid-3636-203
                      sku: '2222'
                      description: No Tomato
                      quantity: 1
                      unitPrice:
                        amount: 0
                        currency: AUD
                    quantity: 1
                    unitPrice:
                      amount: 1000
                      currency: AUD
                    discounts:
                    - amount: 100
                      currency: AUD
                      description: 10% Off Burgers on Tuesday
                  total:
                    amount: 4150
                    currency: AUD
                  table:
                    id: '16'
                    section: Patio
                  customers:
                  - firstName: Jason
                  fulfilment:
                    type: DINE_IN
                  paymentStatus: CLOSED
        description: ''
      parameters:
      - $ref: '#/components/parameters/header-bearer-token'
      tags:
      - Orders
  /orders/{orderId}:
    parameters:
    - name: orderId
      in: path
      description: ID of order to retrieve
      required: true
      schema:
        type: string
    get:
      responses:
        '200':
          description: The order response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get-order'
              examples:
                Get Order:
                  value:
                    id: order-identifier-in-tyro-connect
                    locationId: tc-merchant-2000
                    origin:
                      orderId: 2f8922fb-235f-40c6-af9a-3d6b46ce9635
                      orderReference: Order for Tom
                      name: Charlie's Preorder App
                    items:
                    - id: unique-item-id
                      sku: sku-known-to-the-pos
                      description: Amazing cheese burger
                      unitPrice:
                        currency: AUD
                        amount: 2000
                      discounts:
                      - currency: AUD
                        amount: 1000
                        description: Half price cheese burgers on the first of the month
                      modifiers:
                      - id: uuid-3636-101
                        sku: '634'
                        description: Bacon
                        unitPrice:
                          amount: 0
                        quantity: 1
                      allergens:
                      - description: Fish
                      - description: Nuts
                      quantity: 1
                    discounts:
                    - currency: AUD
                      amount: 200
                      description: Student discount
                    surcharges:
                    - currency: AUD
                      amount: 200
                      description: Public Holiday
                    - currency: AUD
                      amount: 200
                      description: Plastic take away containers
                    tip:
                      currency: AUD
                      amount: 150
                    total:
                      currency: AUD
                      amount: 1350
                    table:
                      id: B1
                      section: Bar
                    status: ACCEPTED
                    customers:
                    - firstName: Daniel
                    - firstName: Elizabeth
                    fulfilment:
                      type: PICK_UP
                    paymentStatus: CLOSED
        '403':
          description: Insufficient permissions to view an order
        '404':
          description: Order id not found
      description: This endpoint is for fetching the details of an order.
      parameters:
      - name: orderId
        in: path
        description: ID of order to retrieve
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/header-bearer-token'
      operationId: get-order
      summary: Get Order
      security:
      - JWT: []
      tags:
      - Orders
    patch:
      operationId: update-order
      responses:
        '204':
          description: No body content. Order updated successfully
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bad-request-validation-errors-response'
        '401':
          description: Invalid or missing access token
        '403':
          description: Insufficient permissions to edit an order's status
        '404':
          description: Order id not found
          content:
            application/json:
              examples:
                Order not found:
                  value:
                    error: Order cannot be found.
        '409':
          description: Conflict when updating order status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/order-update-status-conflict'
              examples:
                Rejected to Cancelled:
                  value:
                    error: Order status conflict. Order status REJECTED cannot be updated to CANCELLED_BY_CUSTOMER.
        '500':
          description: Internal server error
      description: "In order to provide more information about the status changes to the order, you can send the following statuses:\n - `CANCELLED_BY_CUSTOMER` - customer has cancelled the order.\n - `FULFILLED` - The order was completed successfully.\n"
      requestBody:
        content:
          application/merge-patch+json:
            schema:
              description: The new status of an order.
              type: object
              title: Update Order
              properties:
                status:
                  type: string
                  enum:
                  - CANCELLED_BY_CUSTOMER
                  - FULFILLED
                reason:
                  type: string
                  description: Required only when status is `CANCELLED_BY_CUSTOMER. An empty string will be considered as invalid`
              required:
              - status
            examples:
              FULFILLED:
                value:
                  status: FULFILLED
              CANCELLED_BY_CUSTOMER:
                value:
                  status: CANCELLED_BY_CUSTOMER
                  reason: Customer changed their mind.
        description: ''
      summary: Update Order
      parameters:
      - $ref: '#/components/parameters/header-bearer-token'
      - name: orderId
        in: path
        description: Identifier of the order that needs to be updated
        required: true
        schema:
          type: string
      security:
      - JWT: []
      tags:
      - Orders
components:
  schemas:
    bad-request-single-error-response:
      title: Single error
      properties:
        error:
          type: string
          description: Error message
    order-item:
      type: object
      title: Order Item
      description: This object represents an item within a food order.
      properties:
        id:
          type: string
          description: 'An id unique to the order, representing the item within the overall order.

            order, i.e. 2 of the same items will have unique ids.'
        unitPrice:
          description: The basic price of a single item in cents excluding discounts (if any).
          allOf:
          - $ref: '#/components/schemas/money'
        discounts:
          title: Money with Itemisation
          type: array
          description: Each entry in the discounts array will apply to each single item - it represents unit discounts (eg. if the quantity of this object is defined as 2 and the discounts array contains one $1 entry, each of the 2 items should be discounted by $1). item.total = (item.unitPrice + item.modifiersTotal - item.discounts) * item.quantity
          items:
            $ref: '#/components/schemas/money-positive-with-description'
        modifiers:
          type: array
          description: A list of modifications to be made to the parent item. Each entry in this array will apply to each single item - it represents unit modifiers (eg. if the quantity of this object is defined as 2 and the modifiers array contains one $1 entry, each of the 2 items should be modified by $1). item.total = (item.unitPrice + item.modifiersTotal - item.discounts) * item.quantity'
          items:
            $ref: '#/components/schemas/order-item'
        allergens:
          description: Allergens that need to be removed from the parent item.
          type: array
          items:
            type: object
            properties:
              description:
                type: string
                description: Fish Nuts etc
        sku:
          type: string
          description: Id of the item that is aligned with the ID of the item in the POS.
        description:
          type: string
          description: A human readable description of the item that can be used to resolve mismatches between the app and the POS.
        quantity:
          type: integer
          minimum: 0
          description: The number of units of this item required to fulfil the order. Please note that items with different modifiers or surcharges should be split into separate item objects.
        notes:
          type: string
          description: An instruction or message about this order item.
      required:
      - id
      - unitPrice
      - sku
      - description
      - quantity
    existing-order:
      title: Existing Order
      allOf:
      - $ref: '#/components/schemas/new-order'
      - type: object
        properties:
          id:
            type: string
            description: This is the Tyro Connect system order Id. It uniquely identifies the order.
          origin:
            type: object
            properties:
              name:
                type: string
                description: This will be your name. It is mostly used by POS's to identify where an order came from
      description: This is the representation of the order as provided by Tyro Connect.
    get-order:
      title: Get order
      allOf:
      - $ref: '#/components/schemas/existing-order'
      - properties:
          statusInfo:
            type: string
            enum:
            - AUTO_REJECTED_BY_TIMEOUT
            description: This field provides additional information about the status of an order
    money:
      title: Money
      type: object
      properties:
        amount:
          type: integer
          description: This is the amount in smallest currency unit. e.g 12520 (in cents) is $125.20
          example: 12520
        currency:
          type: string
          default: AUD
          enum:
          - AUD
          - EUR
          - NZD
          - GBP
          - USD
          example: AUD
      required:
      - amount
      - currency
    bad-request-validation-errors-response:
      title: List of errors
      type: object
      properties:
        message:
          type: string
          description: General error message
        errors:
          type: array
          description: List of errors for further information about the error
          items:
            type: object
            properties:
              segment:
                type: string
                description: Location in the request where the error occured
              path:
                type: string
                description: Path of where the error occurred
              message:
                type: string
                description: Error message
        error:
          type: string
          description: Error message
    new-order:
      title: New Order
      type: object
      description: This is the representation of the order that was provided by a food ordering app.
      properties:
        origin:
          type: object
          description: Contains information about the food ordering partner that created the order.
          required:
          - orderId
          - orderReference
          properties:
            orderId:
              type: string
              maxLength: 50
              description: An identifier that has been generated by the origin. This can be used for reconciliation of orders in the app partner’s system.
            orderReference:
              type: string
              description: Reference for the order. You should use it to facilitate the communication between the merchant and the eater during fulfillment by providing a short code that allows the order to be easily identifiable.
        locationId:
          type: string
          maxLength: 50
          description: The id of the location as specified by the Tyro Connect system.
        status:
          type: string
          description: The current status of the order. When created, order status must be `CREATED` or `ACCEPTED`.
          default: CREATED
          enum:
          - CREATED
          - ACCEPTED
          - REJECTED
          - BEING_PREPARED
          - READY
          - OUT_FOR_DELIVERY
          - CANCELLED_BY_MERCHANT
          - CANCELLED_BY_CUSTOMER
          - FULFILLED
        notes:
          type: string
          description: A free text field with instructions from the customer to the merchant.
        items:
          type: array
          description: A list of all the items in the order.
          items:
            $ref: '#/components/schemas/order-item'
        table:
          type: object
          description: This object is optional, and if present will only have information about table and section.
          properties:
            id:
              type: string
            section:
              type: string
        customers:
          type: array
          description: The object only has a single field firstName.
          items:
            type: object
            properties:
              firstName:
                type: string
        discounts:
          type: array
          description: Each entry in the discounts array will apply to the whole order and is included in the order total value.
          items:
            $ref: '#/components/schemas/money-positive-with-description'
        surcharges:
          type: array
          description: Each entry in the surcharges array will apply to the whole order and is included in the order total value.
          items:
            $ref: '#/components/schemas/money-positive-with-description'
        total:
          description: The order total is calculated as order.total = (item.unitPrice + item.modifiersTotal - item.discounts) * item.quantity + order.surcharges - order.discounts + order.tip. Please note that TyroConnect does not enforce this calculation to allow flexibility while creating an order.
          allOf:
          - $ref: '#/components/schemas/money-positive'
        tip:
          description: This value will apply to the whole order and is included in the order total value.
          allOf:
          - $ref: '#/components/schemas/money-positive'
        fulfilment:
          type: object
          description: Details about how the customers expect to receive the order.
          required:
          - type
          properties:
            type:
              type: string
              description: Type of fulfilment the customer expects
              enum:
              - PICK_UP
              - DINE_IN
              - DELIVERY
        paymentStatus:
          type: string
          description: Current payment status of the order. Can be either `OPEN` or `CLOSED`. `OPEN` payment status is only applicable for orders with fulfilment type of `DINE_IN`.
          default: CLOSED
      required:
      - origin
      - locationId
      - status
      - items
      - total
      - fulfilment
    order-update-status-conflict:
      title: Order conflict status
      properties:
        error:
          type: string
          description: Error message
    money-positive:
      title: Money Positive Amount
      type: object
      properties:
        amount:
          type: integer
          description: This is the amount in smallest currency unit. e.g 12520 (in cents) is $125.20
          example: 12520
          minimum: 0
        currency:
          type: string
          default: AUD
          enum:
          - AUD
          - EUR
          - NZD
          - GBP
          - USD
          example: AUD
      required:
      - amount
      - currency
    money-positive-with-description:
      title: Money Positive Amount With Description
      allOf:
      - $ref: '#/components/schemas/money-positive'
      - type: object
        properties:
          description:
            type: string
            description: A description of what this amount of money represents
            example: Tuesday Happy Hour Discount
  parameters:
    header-bearer-token:
      schema:
        type: string
        default: Bearer {$$.env.access_token}
      in: header
      name: Authorization
      required: true
  examples:
    create-order-response:
      value:
        id: order-identifier-in-tyro-connect
        locationId: tc-merchant-2000
        origin:
          orderId: 2f8922fb-235f-40c6-af9a-3d6b46ce9635
          orderReference: Order for Tom
          name: Charlie's Preorder App
        items:
        - id: unique-item-id
          sku: sku-known-to-the-pos
          description: Amazing cheese burger
          unitPrice:
            currency: AUD
            amount: 2000
          discounts:
          - currency: AUD
            amount: 1000
            description: Half price cheese burgers on the first of the month
          modifiers:
          - id: uuid-3636-101
            sku: '634'
            description: Bacon
            unitPrice:
              amount: 0
            quantity: 1
          allergens:
          - description: Fish
          - description: Nuts
          quantity: 1
        discounts:
        - currency: AUD
          amount: 200
          description: Student discount
        surcharges:
        - currency: AUD
          amount: 200
          description: Public Holiday
        - currency: AUD
          amount: 200
          description: Plastic take away containers
        tip:
          currency: AUD
          amount: 150
        total:
          currency: AUD
          amount: 1350
        table:
          id: B1
          section: Bar
        status: CREATED
        customers:
        - firstName: Daniel
        - firstName: Elizabeth
        fulfilment:
          type: PICK_UP
        paymentStatus: CLOSED
  securitySchemes:
    JWT:
      type: openIdConnect
      openIdConnectUrl: https://auth.connect.tyro.com/.well-known/openid-configuration