Purchase Request is a new API that allows partners to request purchase orders on a merchant's SumUp POS. Once validated by the merchant, an order is created in the SumUp POS system. When compared to Delivery API v2, Purchase Request uses OAuth to authenticate all requests and uses more abstract terminology to describe purchases, which is not specific to restaurants.
Migrating
Authentication
Instead of using the partner_name, restaurant_token and provider_token in the request body to authenticate requests, Purchase Requests 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 Purchase Request, the purchase-request/write scope needs to be included.
Concept mapping
The terminology used in the Delivery API was focused on restaurants. For Purchase Request, the terminology has changed to cover other areas such as retail. We have compiled below a list mapping the terms used in Delivery API to the ones used in Purchase Request. You may also refer to the Glossary for more information.
Delivery API v2
Purchase Request
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.
Option
ItemOptionLine
New name, refers to the options associated to an ItemLine.
MealLine
PackageLine
Meals are now referred to as packages, a more generic term. It refers to a list of items that are bundled together.
MealSubLine
PackageItemLine
Refers to an item contained in the package.
MealOption
PackageItemOptionLine
Refers to an option associated with a PackageItemLine.
Request body attribute mapping
The general structure of the request didn’t change, however, besides the concept name changes mentioned above, there are changes to attributes. First of all, a camelCase is now used instead of snake_case. We have compiled below a table for each schema in Delivery API v2, which maps all changes in attributes when migrating to the corresponding Purchase Request schema.
Delivery API v2 - Request
Purchase Request - Purchase Request
Comments
restaurant_token
-
The store id is now required as a path parameter.
provider_token
-
Removed, the information in the access token is now used to identify partners.
type
purchaseRequestType
This is now required.
external_reference
externalId
store_reference
-
The store id is now required as a path parameter.
display_id
displayName
date
date
pickup_time
pickupTime
total_price
-
Removed.
total_vat
-
Removed.
is_paid
-
Removed. Have been replaced by payments field at the order level.
allow_deny
allowDeny
provider
-
Removed, the information in the access token is now used to identify partners.
consumer
consumer
order
order
-
purchaseRequestType
Delivery API v2 - Consumer
Purchase Request - Consumer
Comments
firstname
firstname
lastname
lastname
phone_number
phoneNumber
email
email
delivery_address
deliveryAddress
billing_address
billingAddress
Delivery API v2 - Address
Purchase Request - Address
Comments
city
city
country
country
street
addressLine1
Street has been split into two address lines.
-
addressLine2
-
state
zip_code
zipCode
comment
comment
Delivery API v2 - Order
Purchase Request - Order
Comments
currency_code
currencyCode
nb_consumers
consumerCount
price
price
vat
tax
comment
comment
meals
packageLines
lines
itemLines
discounts
discounts
-
payments
Replacement of isPaid old field. Array of objects.
