Articles in this section

See more

Create &/or Update Order

Avatar
Greg
  • Updated
Follow

Create or Update an Order with it's POS id.

All successful responses from this endpoint will be the same as from GET /orders/:pos-id.

PUT ~/orders/:pos-id

Headers

Field Type Description
Authorization String

Bearer authentication token prefixed with Bearer and a space. See Authentication for more information.
Content-Type String

Request content type, must be 'application/json'
vendor String

The POS vendor name retrieved from Doshii dashboard
doshii-terminal-id  String 

The hashed Id of a POS Terminal registered within Doshii via the Create POS Terminal endpoint

Parameters

Field Type Description
:pos-id String

The POS id of the Order to create or update
order Object

An object containing Order details
  status String

The status of the order. "accepted" or "cancelled" permitted from "pending" state. See Status and the Order State Machine for more information.
  versionoptional String

The order version hash. See Order Version Hash. The version is only required when performing an update.
  manuallyAcceptedoptional Boolean

The order has been verified by a human, pass through "status": "accepted" without external validation. Defaults to false.
  rejectionCodeoptional String

The rejection code applicable. List of codes can be found at GET /rejection-codes/:rejectionCode. Do not set unless updating to "status": "rejected".
  rejectionReasonoptional String

The reason for rejecting the order. Do not set unless updating to "status": "rejected".
  notesoptional String

Free-text entry for additional order details
  mealPhaseoptional String

An enumerated list of phases describing the lifecycle of an order at a venue.

phase description
ordered Initial order has been placed
delayed Order has been delayed
appetiser_preparing The appetisers are currently being prepared
entree_preparing The entrees are being prepared
main_preparing The main course is being prepared
dessert_preparing The desserts are being prepared
appetiser_prepared The appetisers have been prepared and ready to serve to customer
entree_prepared The entrees have been prepared and ready to serve to customer
main_prepared The main course has been prepared and ready to serve to customer 
dessert_prepared The desserts have been prepared and ready to serve to customer 
appetiser_served The appetisers have been served
entree_served The entrees have been served
main_served The mains have been served
dessert_served The desserts have been served
billed The bill has been prepared and provided to customer
fulfilled The order has been fulfilled 
  typeoptional 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
  requiredAtoptional String

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

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

A DateTime for when the Order was created in the POS.
  items Object[]

Array of Product objects.
    uuidoptional String

A UUID for the item. This value must be unique for the order. If not supplied, a value will be automatically generated by Doshii.
    posIdoptional String

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

The display name of the Product
    quantity String

The quantity ordered
    descriptionoptional 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
    tagsoptional String[]

Array of strings to help group Products together
    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 required when the item type is bundle.
      name String

The name of the included item
      posIdoptional 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
        name String

The display name of the option
        variants Object[]

The available Variants for the option. This property is required, however can contain an empty list.
          posIdoptional 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. This property is required, however can be an empty array.
      posIdoptional String

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

Name of surcount.
      descriptionoptional String

Description of item.
      type String

Whether this is an 'absolute' or 'percentage' Surcount
      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 have been selected with the item. This property is required, however can be an empty array.
      posIdoptional String

The POS id of the option
      name String

The display name of the option
      variants Object[]

The selected Variants for the option
        posIdoptional String

The POS id of the Variant
        name String

The display name of the Variant
        price String

The price of the Variant in cents
  unapprovedItemsoptional Object[]

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

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

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

The display name of the Product
    status String

The status of the unapproved item. If the unapproved item is accepted, it would be moved to the items property and removed from this list.

 

type description
pending The unapproved item is yet to be processed by the POS
cancelled The unapproved item was cancelled by the Partner App
rejected The unapproved item was rejected by the POS
voided The unapproved item was voided by the POS
    quantity String

The quantity ordered
    descriptionoptional 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
    tagsoptional String[]

Array of strings to help group Products together
    typeoptional String

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

Array of items that are included in a bundle
      name String

The name of the included item
      posIdoptional 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
        name String

The display name of the option
        variants Object[]

The selected Variants for the option. This property is required, however can be an empty array if no options are selected.
          posIdoptional 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. This property is required, however can be an empty array if no surcounts have been applied.
      posIdoptional String

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

Name of item.
      descriptionoptional String

Description of item.
      type String

Whether this is an 'absolute' or 'percentage' Surcount
      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.
    optionsoptional Object[]

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

The POS id of the option
      name String

The display name of the option
      variants Object[]

The available Variants for the option. This property is required, however the value can be an empty array if there are no variants selected.
        posIdoptional String

The POS id of the Variant
        name String

The display name of the Variant
        priceoptional String

The price of the Variant in cents
  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
  surcounts Object[]

Array of Surcount objects. This property is required, however it may contain an empty list if there are no surcounts applied to the order.
    posIdoptional String

Id of the item in the POS
    name String

Name of item.
    descriptionoptional String

Description of item.
    type String

Whether this is an 'absolute' or 'percentage' Surcount
    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.
checkinoptional Object

An object containing Checkin details.
  tableNamesoptional String

Array of table names used in the checkin.
  coversoptional String

Number of covers
  consumeroptional String

An object containing Consumer details.
    nameoptional String

The name of the consumer
    phoneoptional String

The phone of the consumer
    emailoptional String

The email of the consumer
    addressoptional String

An object containing Consumer Address details.
      line1optional String

The street number and name.
      cityoptional String

city.
      stateoptional String

state.
      postalCodeoptional String

Postal code.
      countryoptional String

2-character Country Code.
consumeroptional Object

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

The name of the Consumer
  phoneoptional String

The phone number of the Consumer
  emailoptional String

The email address of the consumer
  addressoptional String

An object containing Consumer Address details.
    line1optional String

The street number and name.
    cityoptional String

City.
    stateoptional String

State.
    postalCodeoptional String

Postal code.
    countryoptional String

2-character Country Code.
    notesoptional String

Free-text entry for notes about the Consumer's address such as "leave at back door".
transactionsoptional Object[]

An array of Transactions for the Order
  doshiiIdoptional String

The ID of an existing transaction to link to. If the transaction is new and created as part of this order then this property should not be supplied. If the doshiiId is supplied, the transaction status and version properties are required. 
  statusoptional String

The current payment status. Default is "complete". See Status and the Transaction State Machine for more information. This is required if the doshiiId property is supplied.
  versionoptional  String

An obfuscated string representation of the transaction version. This property is required when doshiiId is supplied.
  amount String

The amount (in cents) the Transaction is for. If the doshiiId property is supplied then the amount is not allowed.
  method String

An enumerated value describing how the payment was made. The supported types are: 'cash', 'visa', 'mastercard', 'amex', 'diners', 'giftcard', 'loyalty', 'crypto', 'credit', 'directdeposit', 'cheque', 'alipay', 'wechatpay', 'zip', 'moto' and 'other'
  referenceoptional String

A free-text reference, representing an internal payment ID.
  invoiceoptional String

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

Response

Field Type Description
id String

Unique number identifying this resource
locationId String

Id of the Location resource
checkinId String

Id of the Checkin resource
manuallyAccepted Boolean

The order has been verified by a human, pass through "status": "accepted" without external validation. Defaults to false.
mealPhase String

The current stage of the lifecylce that the order is in at the venue. Eg: 'ordered', 'main_served', 'billed'
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

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
notes String

Free-text entry for order or delivery notes such as "deliver to back door".
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.
items Object[]

Array of Product objects.
  posId String

The POS id of the Product
  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
unapprovedItems Object[]

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

The POS id of the Product
  name String

The display name of the Product
  quantity String

The quantity ordered
  status String

The status of the unapproved item
  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
consumer String

An object containing Consumer details.
  name String

The name of the consumer
  phone String

The phone of the consumer
  email String

The email of the consumer
  address String

An object containing Consumer Address details.
    line1 String

The street number and name.
    city String

City.
    state String

State.
    postalCode String

Postal code.
    country String

2-character Country Code.
    notes String

Free-text entry for consumer's address notes such as "Leave at back door".
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.
  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.
checkin Object

An object containing Checkin details.
  id String

The checkin ID
  tableNames String

Array of table names used in the checkin.
  covers String

Number of covers
  updatedAt String

Checkin last update date
  createdAt String

Checkin creation date
  uri String

URI of the Checkin
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.
preorderBookingId String

The ID of the booking that this pre-order is associated to (See POST /bookings/:booking-id/preorders). Will not return if not a pre-order.
posCreatedAt String

Date when the order is created in the POS
posTerminalId String

A hashed ID of the POS terminal that is associated to this order. Will not return if not set.
updatedAt String

Order last update date
createdAt String

Order creation date
version String

An obfuscated string representation of the version
uri String

URI of the order
transactionsUri String

URI of the Transactions associated with the order

Examples

Response

HTTP/1.1 200 OK
{
  "id": "1634",
  "status": "accepted",
  "phase": "ordered",
  "manuallyAccepted": false, 
  "checkinId": "3",
  "locationId": "Xuy8K3a0",
  "notes":"Well done toast",
  "requiredAt":null,
  "availableEta":null, 
  "surcounts": [],
  "items": [
    {
      "uuid":"43g25532h235-f34f23f34f34-f3432g23g32",
      "posId":"lol12",
      "name":"Toasted Sourdough Bread & Eggs",
      "quantity":1,
      "description":"Just ye old classic",
      "unitPrice":"1100",
      "totalBeforeSurcounts":"1100",
      "totalAfterSurcounts":"1100",
      "type": "single", 
      "includedItems": [], 
      "surcounts": [],
      "options": []
    }
  ],
 "unapprovedItems": [
   {
      "uuid":"32f342f3-f34f23f34f34-f3432g23g32",
      "name":"Coke",
      "status":"pending",
      "description":"classic cola",
      "unitPrice":"450",
      "posId":"rwqed1",
      "quantity":1,
      "type": "single", 
      "includedItems": [], 
      "surcounts": [],
      "options": []
    }
  ],
  "consumer":{
    "name": "Tony Tamplin",
    "phone":"0121211212",
    "email":"t@mail.com",
    "address":{
      "line1":"St Kilda Rd",
      "line2":"Level 6, 616 St Kilda Rd"
      "city":"Melbourne"
      "state":"VIC"
      "postalCode":"3180"
      "country":"AU"
    }
  },
  "updatedAt": "2018-03-18T04:58:38.485Z",
  "createdAt": "2018-03-18T04:58:38.485Z",
  "posCreatedAt": "2018-03-18T04:58:37.485Z",
  "version":"iwgjr2NJ014",
  "uri": "https://sandbox.doshii.co/pos/v3/orders/1634",
  "transactionsUri": "https://sandbox.doshii.co/pos/v3/orders/1634/transactions"
}

Examples

Request: Initial Creation

{
  "order": {
    "phase":"ordered"
    "manuallyAccepted": false,
    "posCreatedAt": "2018-03-18T04:58:38.485Z",
    "surcounts": [],
    "items":[{
      "uuid":"32f342f3-f34f23f34f34-f3432g23g32",
      "posId":"toasted_bread",
      "name":"Toasted Sourdough Bread & Eggs",
      "quantity":"1",
      "description":"Just ye old classic",
      "unitPrice":"1100",
      "totalBeforeSurcounts":"1100",
      "totalAfterSurcounts":"1100",
      "type": "single", 
      "includedItems": [], 
      "surcounts": [],
      "options": []
    }],
  }
}

Request: Update Status

{
  "order": {
    "phase":"ordered",
    "status":"accepted",
    "manuallyAccepted": false,
    "surcounts": [],
    "items":[{
      "uuid":"32f342f3-f34f23f34f34-f3432g23g32",
      "posId":"toasted_bread",
      "name":"Toasted Sourdough Bread & Eggs",
      "quantity":"1",
      "description":"Just ye old classic",
      "unitPrice":"1100",
      "totalBeforeSurcounts":"1100",
      "totalAfterSurcounts":"1100",
      "surcounts": [],
      "options": []
    }],
    "version":"j3y5aaKIe"
}

Request: Update with a rejected item

{
  "order": {
    "phase":"ordered",
    "status":"accepted",
    "manuallyAccepted": false,
    "surcounts": [],
    "items":[{
      "uuid":"32f342f3-f34f23f34f34-f3432g23g32",
      "posId":"toasted_bread",
      "name":"Toasted Sourdough Bread & Eggs",
      "quantity":"1",
      "description":"Just ye old classic",
      "unitPrice":"1100",
      "totalBeforeSurcounts":"1100",
      "totalAfterSurcounts":"1100",
      "surcounts": [],
      "options": []
    }],
    "unapprovedItems":[{ 
      "uuid":"32f342f3-d3213fas36-f3432g23g32",
      "posId":"coke1",
      "status":"rejected",
      "name":"Small Coke",
      "quantity":"1",
      "description":"classic cola",
      "unitPrice":"300",
      "totalBeforeSurcounts":"300",
      "totalAfterSurcounts":"300",
      "surcounts": [],
      "options": []
    }],
    "version":"j3y5aaKIe"
}

Request: Create an order with a consumer

{
  "consumer":{
     "name": "Tony Tamplin",
     "phone":"0121211212",
     "email":"t@mail.com",
     "address":{
       "line1":"St Kilda Rd",
       "line2":"Level 6, 616 St Kilda Rd"
       "city":"Melbourne"
       "state":"VIC"
       "postalCode":"3180"
       "country":"AU"
     }
  },
  "order": {
    "phase":"ordered",
    "manuallyAccepted": false,
    "posCreatedAt": "2018-03-18T04:58:38.485Z",
    "surcounts": [],
    "items":[{
      "uuid":"32f342f3-f34f23f34f34-f3432g23g32",
      "posId":"toasted_bread",
      "name":"Toasted Sourdough Bread & Eggs",
      "quantity":"1",
      "description":"Just ye old classic",
      "unitPrice":"1100",
      "totalBeforeSurcounts":"1100",
      "totalAfterSurcounts":"1100",
      "surcounts": [],
      "options": []
    }],
  }
}

Request: Create an order with a check-in

{
  "checkin": {
    "ref":"1000",
    "tableNames": ["table1"],
    "covers": "2",
    "consumer":{
       "name": "Tony Tamplin",
       "phone":"0121211212",
       "email":"t@mail.com",
       "address":{
         "line1":"St Kilda Rd",
         "line2":"Level 6, 616 St Kilda Rd"
         "city":"Melbourne"
         "state":"VIC"
         "postalCode":"3180"
         "country":"AU"
       }
    }
  },
  "order": {
    "phase":"ordered",
    "status":"accepted",
    "manuallyAccepted": false,
    "posCreatedAt": "2018-03-18T04:58:38.485Z",
    "surcounts": [],
    "items":[{
      "uuid":"32f342f3-f34f23f34f34-f3432g23g32",
      "posId":"toasted_bread",
      "name":"Toasted Sourdough Bread & Eggs",
      "quantity":"1",
      "description":"Just ye old classic",
      "unitPrice":"1100",
      "totalBeforeSurcounts":"1100",
      "totalAfterSurcounts":"1100",
      "surcounts": [],
      "options": []
    }],
    "version":"j3y5aaKIe"
  }
}

Response

{
  "id": "1634",
  "status": "accepted",
  "phase": "ordered",
  "manuallyAccepted": false, 
  "checkinId": "3",
  "locationId": "Xuy8K3a0",
  "notes":"Well done toast",
  "requiredAt":null,
  "availableEta":null, 
  "surcounts": [],
  "items": [
    {
      "uuid":"43g25532h235-f34f23f34f34-f3432g23g32",
      "posId":"lol12",
      "name":"Toasted Sourdough Bread & Eggs",
      "quantity":1,
      "description":"Just ye old classic",
      "unitPrice":"1100",
      "totalBeforeSurcounts":"1100",
      "totalAfterSurcounts":"1100",
      "type": "single", 
      "includedItems": [], 
      "surcounts": [],
      "options": []
    }
  ],
 "unapprovedItems": [
   {
      "uuid":"32f342f3-f34f23f34f34-f3432g23g32",
      "name":"Coke",
      "status":"pending",
      "description":"classic cola",
      "unitPrice":"450",
      "posId":"rwqed1",
      "quantity":1,
      "type": "single", 
      "includedItems": [], 
      "surcounts": [],
      "options": []
    }
  ],
  "consumer":{
    "name": "Tony Tamplin",
    "phone":"0121211212",
    "email":"t@mail.com",
    "address":{
      "line1":"St Kilda Rd",
      "line2":"Level 6, 616 St Kilda Rd"
      "city":"Melbourne"
      "state":"VIC"
      "postalCode":"3180"
      "country":"AU"
    }
  },
  "updatedAt": "2018-03-18T04:58:38.485Z",
  "createdAt": "2018-03-18T04:58:38.485Z",
  "posCreatedAt": "2018-03-18T04:58:37.485Z",
  "version":"iwgjr2NJ014",
  "uri": "https://sandbox.doshii.co/pos/v3/orders/1634",
  "transactionsUri": "https://sandbox.doshii.co/pos/v3/orders/1634/transactions"
}

 

Related articles

Comments

0 comments

Please sign in to leave a comment.