Order API v3 allows partners to access and manage orders of a merchant's SumUp POS. When compared to Order API v2, Order API v3 uses OAuth to authenticate all requests and uses more abstract terminology to describe orders, which is not specific to restaurants.
Migrating
Authentication
Instead of using the restaurant_token and provider_token in the request body to authenticate requests, Order API v3 uses OAuth. More information available here. In short, the provided credentials are used to request an access token from the Auth Server and it needs to be included in every request’s Authorization header (Authorization: Bearer <access token>). When requesting the token to use Order API v3, the order/read and order/write scopes need to be included.
Concept mapping
The terminology used in the Order API v2 was focused on restaurants. For Order API v3, the terminology has changed to cover other areas such as retail. We have compiled below a list mapping the terms used in Order API v2 to the ones used in Order API v3. You may also refer to the Glossary for more information.
Order API v2
Order API v3
Description
Restaurant
Store
Restaurants are now referred to as stores, a more general concept.
Provider
Partner
Providers are now partners. Partners are identified by their OAuth credentials and their information is excluded from the request body.
Line
ItemLine
New name, but still refers to an item.
ExtraLine
ItemOptionLine
New name, refers to the options associated to an ItemLine.
-
PackageLine
Meals are now referred to as packages, a more generic term. It refers to a list of items that are bundled together.
-
PackageItemLine
Refers to an item contained in the package.
-
PackageItemOptionLine
Refers to an option associated with a PackageItemLine.
Customer
Consumer
New name, same concept.
-
Discount
Represents a discount associated with an order, item or package line.
-
Preparation
Represents the preparation of a given item or package.
Request body attribute mapping
The general structures haven't changed, however, besides the concept name changes mentioned above, there are new concepts as well as changes to attributes. First of all, a camelCase approach is now used instead of snake_case. We have compiled below a table for each schema in Order API v2, which maps all changes in attributes when migrating to the corresponding Order API v3.
Order API v2 - Order
Order API v3 - Order
Comments
restaurant_token
-
The store id is now required as a query parameter.
provider_token
-
Removed, the information in the access token is now used to identify partners.
number
-
Removed.
name
displayName
externalId
externalId
status
status
Now it is read only, not necessary on POST.
nbCustomers
guestNumber
openDate
date
Moved inside openingInformations.
tableId
location
waiterId
staff
Moved inside openingInformations.
waiterName
-
type
-
Only Order is supported.
isBooking
-
Booking is not supported by Order API v3.
lines
itemLines
-
packageLines
payments
payments
-
preparations
-
discounts
customer
consumer
-
currencyCode
-
openingInformations
-
partnerName
-
comment
Order API v2 - Customer
Order API v3 - Consumer (Read model)
Comments
id
id
Order creation needs to reference an existing consumer.
