Articles in this section

See more

Create Orders

Avatar
Greg
  • Updated
Follow

Create an Order at a Location. Orders can be for a future time and/or paid. 

POST ~/orders

Headers

Field Type Description
doshii-location-id String

The hashed ID of the location you're targeting. See Hashed Location IDs

Parameters

Field Type Description
order Object

An object containing Order details
  type String

The type of order should be one of the following

type description
(null) Standard POS order.
delivery Order ahead to be delivered to the Consumer
pickup Order ahead to be picked up by the Consumer
dinein Order is for dine-in at the venue
  notesoptional String

Free-text entry for additional order details
  externalOrderRef String

The optional external order reference provided by the Partner when the order was created.
  mealPhaseoptional String

An enumerated string representation of where the Order is in its lifecycle at the venue. Eg: 'ordered', 'mains_served', 'fulfilled', etc...
  manuallyAcceptedoptional Boolean

The order has been verified by a human, pass through "status": "accepted" without external validation. Defaults to false. Certification required to set this property as true
  requiredAtoptional Date

A DateTime in ISO8601 format for when the Order is required. Timezone will default to UTC ("Z") time when not provided. eg. 2017-04-12T20:54:25ZWill be null if not a future Order.
  availableEtaoptional Date

A DateTime in ISO8601 format for when the Order is available for pickup/delivery. Timezone will default to UTC ("Z") time when not provided. eg. 2017-04-12T20:54:25Z Will be null if immediately available.
  checkinIdoptional String

An open checkin that the order should be associated to.
  items Object[]

Array of Product objects.
    name String

The display name of the Product
    quantity String

The quantity ordered. Accepts either String or Integer
    unitPrice String

The price of the Product in cents. Accepts either String or Integer
    totalBeforeSurcounts String

The price of the line item before the Surcounts are applied. Accepts either String or Integer
    totalAfterSurcounts String

The price of the line item after the Surcounts are applied. Accepts either String or Integer
    tagsoptional String[]

Array of strings to help group Products together
    posIdoptional String

The POS id of the Product. When not provided, is treated as a custom/open/generic item by the POS.
    descriptionoptional String

A short description of the Product
    typeoptional String

Either a type of 'single' or 'bundle'. Defaults to 'single'
    includedItemsoptional Object[]

Array of items that are included in a bundle. This property is not accepted unless the order.items.type is 'bundle'.
      name String

The name of the included item
      posId String

The posId of the included item
      quantity String

The quantity of the included item
      unitPrice String

The unitPrice of the included item
      options Object[]

Array of options that can be added to the Product
        posIdoptional String

The POS id of the option
        nameoptional String

The display name of the option
        minoptional String

The minimum number that can be selected (0 for no min)
        maxoptional String

The maximum number that can be selected (0 for no max)
        variantsoptional Object[]

The available Variants for the option
          posIdoptional String

The POS id of the Variant
          nameoptional String

The display name of the Variant
          priceoptional String

The price of the Variant in cents
    surcounts Object[]

Array of Surcount objects.
      nameoptional String

Name of item. Required when order.items.surcounts property is present.
      typeoptional String

Whether this is an 'absolute' or 'percentage' Surcount. Required when order.items.surcounts property is present.
      amountoptional String

The amount to surcharge/discount (positive/negative integer). Required when order.items.surcounts property is present. Accepts either String or Integer
      valueoptional String

The value of the surcounts in cents. Accepts integer or string of integers. This value should be calculated if the Surcount is % based. Required when order.items.surcounts property is present.
      descriptionoptional String

Description of the item.
      posIdoptional String

Id of the item in the POS. Providing this will allow the POS to correctly print and report sales.
    options Object[]

Array of options that can be added to the Product
      nameoptional String

The display name of the option. Required when order.items.optionsproperty is present.
      variantsoptional Object[]

The available Variants for the option. Required when order.items.options property is present.
        nameoptional String

The display name of the Variant. Required when order.items.optionsproperty is present.
        priceoptional String

The price of the Variant in cents. Required when order.items.optionsproperty is present. Accepts either String or Integer
        posIdoptional String

The POS id of the Variant
      posIdoptional String

The POS id of the option
  surcounts Object[]

Array of Surcount objects.
    nameoptional String

Name of item. Required when order.surcounts property is present.
    typeoptional String

Whether this is an 'absolute' or 'percentage' Surcount. Required when order.surcounts property is present.
    amountoptional String

The amount to surcharge/discount (positive/negative integer). Required when order.surcounts property is present.
    valueoptional String

The value of the surcounts in cents. Accepts integer or string of integers. This value should be calculated if the Surcount is % based. Required when order.surcounts property is present.
    descriptionoptional String

Description of item.
    posIdoptional String

Id of the item in the POS
  logoptional Object

An optional object containing additional log properties you might want to store on the order. 
    employeeIdoptional String

A Doshii employeeId for the employee making the action
    employeeNameoptional String

The name of the employee making the action
    employeePosRefoptional String

A POS reference for the employee making the action
    deviceRefoptional String

An internal reference for the device at which the request was made
    deviceNameoptional String

A name for the device at which the request was made
    areaoptional String

The area at which the request was made
consumeroptional Object

An object containing Consumer details. Required when order.type is 'delivery' or 'pickup'.
  name String

The name of the Consumer. Required when order.consumer is provided.
  phone String

The phone number of the Consumer. Required when order.consumer is provided.
  emailoptional String

The email address of the Consumer
  addressoptional Object

The consumer address details. Required when order.type is 'delivery'.
    line1 String

The street number and name. Required when order.type is 'delivery'.
    line2optional String

Apartment/unit/level/suite.
    city String

City. Required when order.type is 'delivery'.
    stateoptional String

State. Required when order.type is 'delivery'.
    postalCodeoptional String

Postal code. Required when order.type is 'delivery'.
    country String

2-character Country Code. Required when order.type is 'delivery'.
    notesoptional String

Free-text entry for order or delivery notes such as "deliver to back door".
transactionsoptional Object[]

An array of Transactions for the Order
  amount String

The amount (in cents) the Transaction is for. Required if the transactions property is present. Accepts either String or Integer
  tipoptional String

Tip amount in cents. Accepts either String or Integer
  prepaidoptional Boolean

Whether the Transaction has already been charged to the Consumer. Must be set and true when declaring a transaction on order creation.
  referenceoptional String

A free-text field for entering external identifiers eg: bank deposit reference no.
  invoiceoptional String

A free-text invoice number. Eg: 'Inv2206-46'.
  methodoptional String

An enumerated list of payment method types, to describe how the payment was made. The supported types are: 'cash', 'visa', 'mastercard', 'amex', 'diners', 'giftcard', 'loyalty', 'crypto', 'credit', 'directdeposit', 'cheque', 'alipay', 'wechatpay', 'zip', 'moto', 'paypal' and 'other'
  surcountsoptional Object[]

Array of Surcount objects. Typically used for payment surcharges (credit card fees, etc). See Surcounts: Surcharges & Discounts for more information on how these work.
    nameoptional String

Name of item. Required when transactions.surcounts property is present.
    typeoptional String

Whether this is an 'absolute' or 'percentage' Surcount. Required when transactions.surcounts property is present.
    amountoptional String

The amount to surcharge/discount (positive/negative integer). Required when transactions.surcounts property is present. Accepts either String or Integer
    valueoptional String

The value of the surcounts in cents. Accepts integer or string of integers. This value should be calculated if the Surcount is % based. Required when transactions.surcounts property is present.
    descriptionoptional String

Description of the surcount.
    posIdoptional String

Id of the item in the POS. Providing this will allow the POS to correctly print and report sales.

Response

Field Type Description
id String

Unique number identifying this resource
checkinId String

Id of the Checkin resource
locationId String

Id of the Location resource
notes String

Free-text entry for additional order details
mealPhase String

An enumerated string representation of where the Order is in its lifecycle at the venue. Eg: 'ordered', 'mains_served', 'fulfilled', etc...
status String

The current state of the Order. Can be one of the following:

state description
pending Order yet to be confirmed by the POS
rejected Order was not accepted by the POS
accepted Order was accepted by the POS
complete Order has been marked as completed by the POS
cancelled Pending Order was cancelled by the Partner
venue_cancelled Accepted Order was cancelled by the Partner or POS

Please note that a complete status does not necessarily mean the order is paid. Use GET orders/:id/transactions to check payment transaction status. See Status and the Order State Machine for more information.
type String

The type of order should be one of the following

type description
(null) Standard POS order.
delivery Order ahead to be delivered to the Consumer
pickup Order ahead to be picked up by the Consumer
dinein Order is for dine-in at the venue
requiredAt String

A DateTime for when the Order is required. Will be null if not a future Order.
availableEta String

An estimated DateTime for when the Order is available for pickup/delivery. Will be null if immediately available.
manuallyAccepted Boolean

The order has been verified by a human, pass through "status": "accepted" without external validation. Defaults to false. 
items Object[]

Array of Product objects.
  uuid String

A UUID for the item. Automatically generated by Doshii.
  posId String

The POS id of the item. Will not be available if the item is a custom/open/generic item.
  name String

The display name of the Product
  quantity String

The quantity ordered. Returns either a String or an Integer
  description String

A short description of the Product
  unitPrice String

The price of the Product in cents. Returns either a String or an Integer
  totalBeforeSurcounts String

The price of the line item before the Surcounts are applied. Returns either a String or an Integer
  totalAfterSurcounts String

The price of the line item after the Surcounts are applied. Returns either a String or an Integer
  tags String[]

Array of strings to help group Products together
  menuDir String[]

An array of strings representing a menu directory. Eg. For a Flat White - ["coffee/hot", "drinks/coffee"] would signify the product exists on the menu under "Coffee" with the submenu being "Hot", and also on the menu under "Drinks" with the submenu "Coffee".
  type String

Either a type of 'single' or 'bundle'. Defaults to 'single' 
  includedItems Object[]

Array of items that are included in a bundle 
    name String

The name of the included item
    posId String

The posId of the included item
    quantity String

The quantity of the included item
    unitPrice String

The unitPrice of the included item
    options Object[]

Array of options that can be added to the Product
      posId String

The POS id of the option
      name String

The display name of the option
      min String

The minimum number that can be selected (0 for no min)
      max String

The maximum number that can be selected (0 for no max)
      variants Object[]

The available Variants for the option
        posId String

The POS id of the Variant
        name String

The display name of the Variant
        price String

The price of the Variant in cents
  surcounts Object[]

Array of Surcount objects.
    posId String

Id of the item in the POS. Providing this will allow the POS to correctly print and report sales.
    rewardId String

Id of the Reward that created this Surcount
    name String

Name of item.
    description String

Description of item.
    type String

Whether this is an 'absolute' or 'percentage' Surcount
    amount String

The amount to surcharge/discount (positive/negative integer). Returns either a String or an Integer
    value String

The value of the surcounts in cents. Accepts integer or string of integers. This value should be calculated if the Surcount is % based. Returns either a String or an Integer
  options Object[]

Array of options that can be added to the Product
    posId String

The POS id of the option
    name String

The display name of the option
    variants Object[]

The available Variants for the option
      posId String

The POS id of the Variant
      name String

The display name of the Variant
      price String

The price of the Variant in cents. Returns either a String or an Integer
unapprovedItems Object[]

Array of Product objects that have a status that is NOT accepted. 
  uuid String

A UUID for the item. Automatically generated by Doshii.
  posId String

The POS id of the Product
  status String

The status of the unapproved item. Must be one of ['pending', 'cancelled', 'voided']
  name String

The display name of the Product
  quantity String

The quantity ordered
  description String

A short description of the Product
  unitPrice String

The price of the Product in cents
  totalBeforeSurcounts String

The price of the line item before the Surcounts are applied
  totalAfterSurcounts String

The price of the line item after the Surcounts are applied
  tags String[]

Array of strings to help group Products together
  type String

Either a type of 'single' or 'bundle'. Defaults to 'single'
  includedItems Object[]

Array of items that are included in a bundle 
    name String

The name of the included item
    posId String

The posId of the included item
    quantity String

The quantity of the included item
    unitPrice String

The unitPrice of the included item
    options Object[]

Array of options that can be added to the Product
      posId String

The POS id of the option
      name String

The display name of the option
      min String

The minimum number that can be selected (0 for no min)
      max String

The maximum number that can be selected (0 for no max)
      variants Object[]

The available Variants for the option
        posId String

The POS id of the Variant
        name String

The display name of the Variant
        price String

The price of the Variant in cents
  surcounts Object[]

Array of Surcount objects.
    posId String

Id of the item in the POS. Providing this will allow the POS to correctly print and report sales.
    rewardId String

Id of the Reward that created this Surcount
    name String

Name of item.
    description String

Description of item.
    amount String

The amount to surcharge/discount (positive/negative integer)
    value String

The value of the surcounts in cents. Accepts integer or string of integers. This value should be calculated if the Surcount is % based.
  options Object[]

Array of options that can be added to the Product
    posId String

The POS id of the option
    name String

The display name of the option
    variants Object[]

The available Variants for the option
      posId String

The POS id of the Variant
      name String

The display name of the Variant
      price String

The price of the Variant in cents
surcounts Object[]

Array of Surcount objects.
  posId String

Id of the item in the POS
  rewardId String

Id of the Reward that created this Surcount
  name String

Name of item.
  description String

Description of item.
  type String

Whether this is an 'absolute' or 'percentage' Surcount
  amount String

The amount to surcharge/discount (positive/negative integer). Returns either a String or an Integer
  value String

The value of the surcounts in cents. Accepts integer or string of integers. This value should be calculated if the Surcount is % based. Returns either a String or an Integer
consumer Object

An object containing any available Consumer details.
  name String

The name of the Consumer
  phone String

The phone number of the Consumer
  email String

The email of the Consumer
address Object

An object containing any available Consumer address details.
    line1 String

The street number and name.
    line2 String

Apartment/unit/level/suite.
    city String

City.
    state String

State.
    postalCode String

Postal code.
    country String

2-character Country Code.
    notes String

Free-text entry for order or delivery notes such as "deliver to back door".
rejectionCode String

The code for a rejection. More information can be found by a GET on /rejection-codes/:rejectionCode. Will not return if not set.
rejectionReason String

The reason defined by the POS as why the order was rejected. Will not return if not set.
externalOrderRef String

The optional external order reference provided by the Partner when the order was created.
updatedAt String

Date when the record is last updated
createdAt String

Date when the record is created
version String

An obfuscated string representation of the version
uri String

URI of the order

Examples

Request: Create immediate pickup order (unpaid)

{
  "consumer":{
    "name":"Tony T",
    "phone":"01234567890"
  },
  "order":{
    "type":"pickup",
    "surcounts": [],
    "log": { 
      "employeeId": "1",
      "employeeName": "Jimmy C",
      "employeePosRef": "432324tgr",
      "deviceRef": "213-iPad",
      "deviceName": "Dining Room iPad 1",
      "area": "Dining Room"
    },
    "items":[{
      "name":"Toasted Sourdough Bread & Eggs",
      "description":"Just ye old classic",
      "unitPrice":"1100",
      "totalBeforeSurcounts":"1100",
      "totalAfterSurcounts":"1100",
      "posId":"toasted_eggs",
      "quantity":1,
      "type": "single", 
      "surcounts": [],
      "options": []
    }]
  }
}

Request: Create immediate pickup order (paid, with discount)

{
  "consumer":{
    "name":"Tony T",
    "phone":"0123456789"
  },
  "transactions":[{
    "reference":"123-456-789",
    "invoice":"CHK200241",
    "method":"loyalty",
    "amount":"585",
    "prepaid":true
  }],
  "order":{
    "type":"pickup",
    "notes":"Extra hot coffee",
    "log": { 
      "employeeId": "1",
      "employeeName": "Jimmy C",
      "employeePosRef": "432324tgr",
      "deviceRef": "213-iPad",
      "deviceName": "Dining Room iPad 1",
      "area": "Dining Room"
    },
    "surcounts":[{
      "name":"Loyalty Discount",
      "posId":"12",
      "amount":"-10",
      "type":"percentage",
      "value":"-65"
    }],
    "items":[{
      "posId":"long_black",
      "name":"Long Black",
      "quantity":1,
      "description":"Made with the finest Novacastrian beans",
      "unitPrice":"300",
      "totalBeforeSurcounts":"300",
      "totalAfterSurcounts":"300",
      "type": "single", 
      "surcounts": [],
      "options": []
    }, {
      "posId":"muffin",
      "name":"Muffin",
      "quantity":1,
      "description":"Sticky bread in a weird shape",
      "unitPrice":"350",
      "totalBeforeSurcounts":"350",
      "totalAfterSurcounts":"350",
      "type": "single", 
      "includedItems": [], 
      "surcounts": [],
      "options": []
    }]
  }
}

Request: Create delayed delivery order (paid, with surcharges)

{
  "consumer":{
    "name":"4",
    "email":"user@test.com",
    "phone":"0415 123 456",
    "address":{
      "line1":"616 St Kilda Road",
      "line2":"Level 8",
      "city":"Melbourne",
      "state":"VIC",
      "postalCode":"3004",
      "country":"AU"
    }
  },
  "transactions": [{
    "reference":"123-456-789",
    "invoice":"INV22627",
    "method":"credit",
    "amount":"2600",
    "prepaid": true
  }],
  "order": {
    "type":"delivery",
    "requiredAt":"2014-09-05T04:12:52.547Z",
    "availableEta":null, 
    "manuallyAccepted": false, 
    "log": { 
      "employeeId": "1",
      "employeeName": "Jimmy C",
      "employeePosRef": "432324tgr",
      "deviceRef": "213-iPad",
      "deviceName": "Dining Room iPad 1",
      "area": "Dining Room",
    },
    "surcounts":[{
      "posId":"13",
      "name":"Delivery fee ($15)",
      "amount":"1500",
      "type":"absolute",
      "value":"1500"
    }],
    "items":[{
      "posId": "pep_pizza",
      "name":"Pepperoni Pizza",
      "quantity": 1,
      "description":"Homemade and spicy",
      "unitPrice":"1100",
      "totalBeforeSurcounts":"1300",
      "totalAfterSurcounts":"1400",
      "type": "single", 
      "options": [{
        "name":"Extra Toppings",
        "posId": "extra_toppings",
        "variants": [{
          "name":"Extra Pepperoni",
          "posId": "extra_pepperoni",
          "price": 200
        }]
      }],
      "surcounts": [{
        "name":"Custom Toppings Fee",
        "amount":"100",
        "type":"absolute",
        "posId": "custom_toppings_fee",
        "value": 100
      }]
    }]
  }
}

Request: Bundled items with discounts:

Addition of a 'type' prop on the order.items level when posting an order to allow bundled items with discounts.

{
  ...
  "order":{
    ...
    "items":[{
      "name":"Family Bundle",
      "description":"Feeds 2 adults, 2 kids",
      "type": "bundle",
      "includedItems": [{
        "name":"2L Coke",
        "description":"Old classic",
        "posId":"2l_coke",
        "quantity":"1",
        "options": []
      }, {
        "name":"Meat Lovers Pizza",
        "description":"Probably not vegan",
        "posId":"meat_lovers",
        "quantity":"2",
        "options": [{
          "name":"Extra Toppings",
          "posId": "extra_toppings",
          "variants": [{
            "name":"Extra Pepperoni",
            "posId": "extra_pepperoni",
            "price": 200
          }]
        }]
      }],
      "unitPrice":"3000",
      "totalBeforeSurcounts":"3200",
      "totalAfterSurcounts":"3200",
      "posId":"fam_deal",
      "quantity":"1",
      "surcounts":[],
      "options": []
    }]
  }
}

Response

{
  "consumer":{
    "name":"4",
    "email":"user@test.com",
    "phone":"0415 123 456",
    "address":{
      "line1":"616 St Kilda Road",
      "line2":"Level 8",
      "city":"Melbourne",
      "state":"VIC",
      "postalCode":"3004",
      "country":"AU"
    }
  },
  "transactions": [{
    "reference":"123-456-789",
    "invoice":"INV22627",
    "method":"amex",
    "amount":"2600",
    "prepaid": true
  }],
  "order": {
    "type":"delivery",
    "requiredAt":"2014-09-05T04:12:52.547Z",
    "availableEta":null, 
    "manuallyAccepted": false, 
    "log": { 
      "employeeId": "1",
      "employeeName": "Jimmy C",
      "employeePosRef": "432324tgr",
      "deviceRef": "213-iPad",
      "deviceName": "Dining Room iPad 1",
      "area": "Dining Room",
    },
    "surcounts":[{
      "posId":"13",
      "name":"Delivery fee ($15)",
      "amount":"1500",
      "type":"absolute",
      "value":"1500"
    }],
    "items":[{
      "posId": "pep_pizza",
      "name":"Pepperoni Pizza",
      "quantity": 1,
      "description":"Homemade and spicy",
      "unitPrice":"1100",
      "totalBeforeSurcounts":"1300",
      "totalAfterSurcounts":"1400",
      "type": "single", 
      "includedItems": null, 
      "options": [{
        "name":"Extra Toppings",
        "posId": "extra_toppings",
        "variants": [{
          "name":"Extra Pepperoni",
          "posId": "extra_pepperoni",
          "price": 200
        }]
      }],
      "surcounts": [{
        "name":"Custom Toppings Fee",
        "amount":"100",
        "type":"absolute",
        "posId": "custom_toppings_fee",
        "value": 100
      }]
    }]
  }
}

 

Related articles

Comments

0 comments

Please sign in to leave a comment.