Place order¶
The place order call is executed when an OpenApp user confirms an order and payment has been initiated.
This is visible as step 9 in the sequence diagram:
sequenceDiagram
autonumber
actor User
participant OpenApp
participant Merchant
Merchant->>User: show OpenApp widget
User->>User: scan widget
User->>+OpenApp: load basket
OpenApp->>+Merchant: retrieve basket
Merchant->>-OpenApp: send basket
OpenApp->>-User: send basket
User->>+OpenApp: confirm
OpenApp->>OpenApp: validate payment
OpenApp->>+Merchant: place order
Merchant->>-OpenApp: confirm
OpenApp->>-User: confirmRequest¶
In this case, OpenApp will execute a HTTP POST to the to the endpoint configured in the control panel, with order information in the request body.
So if you configured the value https://shop.example.com/api/openapp/order, the request executed by OpenApp will be:
In the POST body, OpenApp will add all data required to complete the order in the webshop. The actual data depends on the delivery method specified by the user.
The oaOrderId uniquely identifies an order. If an order is placed and OpenApp does not receive a response soon enough it may retry so it is important that the webshop implements the place order endpoint in an idempotent manner.
APM delivery¶
In the example request below the user has selected a delivery into an APM locker. The required information for that is which locker location is selected as well as the information to contact the user for sending him a code to open the locker.
Place order request schema v1
{
"description": "The data for an order placed through OpenApp.",
"title": "MerchantPlaceOrder#",
"additionalProperties": false,
"type": "object",
"properties": {
"oaOrderId": {
"description": "The unique ID of the order generated by OpenApp.",
"maxLength": 36,
"type": "string",
"title": "oaOrderId"
},
"basket": {
"$ref": "#/definitions/OpenPayOrderBasket",
"description": "The shopping basket",
"title": "basket"
},
"deliveryDetails": {
"$ref": "#/definitions/DeliveryDetails",
"description": "The details of delivery",
"title": "deliveryDetails"
},
"billingDetails": {
"description": "The details of invoice",
"$ref": "#/definitions/BillingDetails",
"title": "billingDetails"
},
"paymentDetails": {
"$ref": "#/definitions/PlaceOrderAmount",
"description": "The details of the payment",
"title": "paymentDetails"
},
"consents": {
"description": "The consents which the user agreed to",
"type": "array",
"items": {
"$ref": "#/definitions/OrderConsent"
},
"title": "consents"
}
},
"required": [
"basket",
"consents",
"deliveryDetails",
"oaOrderId",
"paymentDetails"
],
"definitions": {
"OpenPayOrderBasket": {
"title": "OpenPayOrderBasket",
"type": "object",
"properties": {
"id": {
"description": "The id of the shopping basket which is purchased",
"maxLength": 36,
"type": "string",
"title": "id"
},
"price": {
"$ref": "#/definitions/PlaceOrderPrice",
"description": "The basket price information",
"title": "price"
},
"products": {
"description": "The basket products",
"type": "array",
"items": {
"$ref": "#/definitions/BaseProduct"
},
"title": "products"
},
"loggedUser": {
"description": "The id of the user in the merchant store (if known)",
"type": "string",
"title": "loggedUser"
}
},
"required": [
"id",
"price",
"products"
]
},
"PlaceOrderPrice": {
"description": "The basket price information",
"title": "PlaceOrderPrice",
"type": "object",
"properties": {
"deliveryCost": {
"description": "The delivery cost. Price is expressed as the number (integer) of 1/100s of the price.",
"minimum": 0,
"type": "integer",
"title": "deliveryCost"
},
"currency": {
"type": "string",
"title": "currency"
},
"basketValue": {
"description": "The price of the basket. Price is expressed as the number (integer) of 1/100s of the price.",
"minimum": 0,
"type": "integer",
"title": "basketValue"
},
"discounts": {
"description": "Applied discounts",
"type": "array",
"items": {
"$ref": "#/definitions/BasketPriceDiscount"
},
"title": "discounts"
}
},
"required": [
"basketValue",
"currency",
"deliveryCost",
"discounts"
]
},
"BasketPriceDiscount": {
"title": "BasketPriceDiscount",
"type": "object",
"properties": {
"code": {
"description": "The discount code.",
"maxLength": 36,
"type": "string",
"title": "code"
},
"value": {
"description": "The value of the discount. Value is expressed as the number (integer) of 1/100s of the currency.",
"minimum": 0,
"type": "integer",
"title": "value"
},
"error": {
"description": "The error code of the discount",
"enum": [
"EXPIRED",
"INVALID",
"NOT_APPLICABLE",
"USED"
],
"type": "string",
"title": "error"
}
},
"required": [
"code",
"value"
]
},
"BaseProduct": {
"title": "BaseProduct",
"type": "object",
"properties": {
"ean": {
"description": "The ean (or other barcode on the product). Specifying this allows the user to search in his order history by scanning the barcode to do a re-purchase.",
"maxLength": 36,
"type": "string",
"title": "ean"
},
"id": {
"description": "The unique ID of the product.",
"maxLength": 36,
"type": "string",
"title": "id"
},
"quantity": {
"description": "The number of items in the purchase.",
"minimum": 0,
"type": "integer",
"title": "quantity"
},
"unitPrice": {
"description": "The price of a single product. Price is expressed as the number (integer) of 1/100s of the price.",
"type": "integer",
"title": "unitPrice"
},
"linePrice": {
"description": "The price of the products. Price is expressed as the number (integer) of 1/100s of the price.",
"type": "integer",
"title": "linePrice"
}
},
"required": [
"id",
"linePrice",
"quantity",
"unitPrice"
]
},
"DeliveryDetails": {
"title": "DeliveryDetails",
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"description": "Delivery to a pickup point",
"type": "string",
"enum": [
"PICKUP"
],
"title": "type"
},
"subType": {
"$ref": "#/definitions/CheckoutDeliverySubtype",
"description": "The type of pickup point",
"title": "subType"
},
"method": {
"$ref": "#/definitions/MerchantDeliveryOptions",
"description": "The method",
"title": "method"
},
"name": {
"description": "The name of the pickup point",
"type": "string",
"title": "name"
},
"id": {
"description": "The code of the pickup point",
"type": "string",
"title": "id"
},
"lat": {
"description": "The lattitude of the pickup point",
"type": "number",
"title": "lat"
},
"lng": {
"description": "The longitude of the pickup point",
"type": "number",
"title": "lng"
},
"street": {
"description": "The street",
"type": "string",
"title": "street"
},
"streetNo": {
"description": "The number on the street",
"type": "string",
"title": "streetNo"
},
"apartmentNo": {
"description": "The appartment number",
"type": "string",
"title": "apartmentNo"
},
"postalCode": {
"description": "The postal code",
"type": "string",
"title": "postalCode"
},
"city": {
"description": "The city",
"type": "string",
"title": "city"
},
"country": {
"description": "The country",
"type": "string",
"enum": [
"PL"
],
"title": "country"
},
"phoneNumber": {
"description": "The phone number",
"type": "string",
"title": "phoneNumber"
},
"email": {
"description": "The email address",
"type": "string",
"title": "email"
}
},
"required": [
"city",
"country",
"email",
"id",
"method",
"name",
"postalCode",
"street",
"subType",
"type"
]
},
{
"type": "object",
"properties": {
"type": {
"description": "Delivery by courier",
"type": "string",
"enum": [
"COURIER"
],
"title": "type"
},
"method": {
"$ref": "#/definitions/MerchantDeliveryOptions",
"title": "method"
},
"street": {
"description": "The street",
"type": "string",
"title": "street"
},
"streetNo": {
"description": "The number on the street",
"type": "string",
"title": "streetNo"
},
"apartmentNo": {
"description": "The appartment number",
"type": "string",
"title": "apartmentNo"
},
"postalCode": {
"description": "The postal code",
"type": "string",
"title": "postalCode"
},
"city": {
"description": "The city",
"type": "string",
"title": "city"
},
"country": {
"description": "The country",
"type": "string",
"enum": [
"PL"
],
"title": "country"
},
"notes": {
"description": "Additional notes",
"type": "string",
"title": "notes"
},
"firstName": {
"description": "The first name",
"type": "string",
"title": "firstName"
},
"lastName": {
"description": "The last name",
"type": "string",
"title": "lastName"
},
"phoneNumber": {
"description": "The phone number",
"type": "string",
"title": "phoneNumber"
},
"companyName": {
"description": "The company name",
"type": "string",
"title": "companyName"
},
"email": {
"description": "The email address",
"type": "string",
"title": "email"
}
},
"required": [
"city",
"country",
"email",
"firstName",
"lastName",
"method",
"notes",
"phoneNumber",
"postalCode",
"street",
"streetNo",
"type"
]
},
{
"type": "object",
"properties": {
"type": {
"description": "Electronic delivery",
"type": "string",
"enum": [
"ELECTRONIC"
],
"title": "type"
},
"method": {
"$ref": "#/definitions/MerchantDeliveryOptions",
"title": "method"
},
"email": {
"description": "The email address",
"type": "string",
"title": "email"
}
},
"required": [
"email",
"method",
"type"
]
}
]
},
"CheckoutDeliverySubtype": {
"title": "CheckoutDeliverySubtype",
"enum": [
"APM",
"PICKUP_POINT",
"SHOP"
],
"type": "string"
},
"MerchantDeliveryOptions": {
"title": "MerchantDeliveryOptions",
"enum": [
"DHL_COURIER",
"DHL_PICKUP",
"DPD_COURIER",
"DPD_PICKUP",
"ELECTRONIC",
"FEDEX_COURIER",
"GEIS_COURIER",
"GLS_COURIER",
"INPOST_APM",
"INPOST_COURIER",
"INSTORE_PICKUP",
"ORLEN_APM",
"POCZTA_POLSKA_APM",
"POCZTEX_COURIER",
"UPS_COURIER"
],
"type": "string"
},
"BillingDetails": {
"title": "BillingDetails",
"type": "object",
"properties": {
"companyName": {
"description": "The name of the comapny for the invoice",
"type": "string",
"title": "companyName"
},
"taxId": {
"description": "The tax number",
"type": "string",
"title": "taxId"
},
"firstName": {
"description": "The first name",
"type": "string",
"title": "firstName"
},
"lastName": {
"description": "The last name",
"type": "string",
"title": "lastName"
},
"country": {
"description": "The country",
"type": "string",
"title": "country"
},
"city": {
"description": "The city",
"type": "string",
"title": "city"
},
"postalCode": {
"description": "The postal code",
"type": "string",
"title": "postalCode"
},
"street": {
"description": "The street",
"type": "string",
"title": "street"
},
"streetNo": {
"description": "The number on the street",
"type": "string",
"title": "streetNo"
},
"apartmentNo": {
"description": "The appartment number",
"type": "string",
"title": "apartmentNo"
},
"notes": {
"description": "Additional notes",
"type": "string",
"title": "notes"
}
},
"required": [
"city",
"country",
"notes",
"postalCode",
"street",
"streetNo"
]
},
"PlaceOrderAmount": {
"title": "PlaceOrderAmount",
"type": "object",
"properties": {
"amount": {
"description": "The total price for the order. Price is expressed as the number (integer) of 1/100s of the price.",
"minimum": 0,
"type": "integer",
"title": "amount"
},
"currency": {
"description": "The currency",
"maxLength": 3,
"type": "string",
"title": "currency"
}
},
"required": [
"amount",
"currency"
]
},
"OrderConsent": {
"title": "OrderConsent",
"type": "object",
"properties": {
"id": {
"description": "The ID of the consent as defined in the merchant panel",
"type": "string",
"title": "id"
},
"version": {
"description": "The version of the consent",
"type": "number",
"title": "version"
}
},
"required": [
"id",
"version"
]
}
},
"$schema": "http://json-schema.org/draft-07/schema#"
}
The user has not requested any invoice, so that information is missing from the data. The user is further using the anonimization features of OpenApp to hide his email address from the merchant. The merchant can still email the user since the email address provided by OpenApp will be forwarded, but the real identity of the user is not disclosed. As can be seen from the product list, the product had an original proce of PLN 70.00 and were discounted to PLN 60.00. Then a discount code with a value of PLM 10.00 was applied to the whole order, so the total price of the order is PLN 110.00.
Electronic delivery¶
If the user has selected electronic delivery the required information is the email address:
Place order request schema v1
{
"description": "The data for an order placed through OpenApp.",
"title": "MerchantPlaceOrder#",
"additionalProperties": false,
"type": "object",
"properties": {
"oaOrderId": {
"description": "The unique ID of the order generated by OpenApp.",
"maxLength": 36,
"type": "string",
"title": "oaOrderId"
},
"basket": {
"$ref": "#/definitions/OpenPayOrderBasket",
"description": "The shopping basket",
"title": "basket"
},
"deliveryDetails": {
"$ref": "#/definitions/DeliveryDetails",
"description": "The details of delivery",
"title": "deliveryDetails"
},
"billingDetails": {
"description": "The details of invoice",
"$ref": "#/definitions/BillingDetails",
"title": "billingDetails"
},
"paymentDetails": {
"$ref": "#/definitions/PlaceOrderAmount",
"description": "The details of the payment",
"title": "paymentDetails"
},
"consents": {
"description": "The consents which the user agreed to",
"type": "array",
"items": {
"$ref": "#/definitions/OrderConsent"
},
"title": "consents"
}
},
"required": [
"basket",
"consents",
"deliveryDetails",
"oaOrderId",
"paymentDetails"
],
"definitions": {
"OpenPayOrderBasket": {
"title": "OpenPayOrderBasket",
"type": "object",
"properties": {
"id": {
"description": "The id of the shopping basket which is purchased",
"maxLength": 36,
"type": "string",
"title": "id"
},
"price": {
"$ref": "#/definitions/PlaceOrderPrice",
"description": "The basket price information",
"title": "price"
},
"products": {
"description": "The basket products",
"type": "array",
"items": {
"$ref": "#/definitions/BaseProduct"
},
"title": "products"
},
"loggedUser": {
"description": "The id of the user in the merchant store (if known)",
"type": "string",
"title": "loggedUser"
}
},
"required": [
"id",
"price",
"products"
]
},
"PlaceOrderPrice": {
"description": "The basket price information",
"title": "PlaceOrderPrice",
"type": "object",
"properties": {
"deliveryCost": {
"description": "The delivery cost. Price is expressed as the number (integer) of 1/100s of the price.",
"minimum": 0,
"type": "integer",
"title": "deliveryCost"
},
"currency": {
"type": "string",
"title": "currency"
},
"basketValue": {
"description": "The price of the basket. Price is expressed as the number (integer) of 1/100s of the price.",
"minimum": 0,
"type": "integer",
"title": "basketValue"
},
"discounts": {
"description": "Applied discounts",
"type": "array",
"items": {
"$ref": "#/definitions/BasketPriceDiscount"
},
"title": "discounts"
}
},
"required": [
"basketValue",
"currency",
"deliveryCost",
"discounts"
]
},
"BasketPriceDiscount": {
"title": "BasketPriceDiscount",
"type": "object",
"properties": {
"code": {
"description": "The discount code.",
"maxLength": 36,
"type": "string",
"title": "code"
},
"value": {
"description": "The value of the discount. Value is expressed as the number (integer) of 1/100s of the currency.",
"minimum": 0,
"type": "integer",
"title": "value"
},
"error": {
"description": "The error code of the discount",
"enum": [
"EXPIRED",
"INVALID",
"NOT_APPLICABLE",
"USED"
],
"type": "string",
"title": "error"
}
},
"required": [
"code",
"value"
]
},
"BaseProduct": {
"title": "BaseProduct",
"type": "object",
"properties": {
"ean": {
"description": "The ean (or other barcode on the product). Specifying this allows the user to search in his order history by scanning the barcode to do a re-purchase.",
"maxLength": 36,
"type": "string",
"title": "ean"
},
"id": {
"description": "The unique ID of the product.",
"maxLength": 36,
"type": "string",
"title": "id"
},
"quantity": {
"description": "The number of items in the purchase.",
"minimum": 0,
"type": "integer",
"title": "quantity"
},
"unitPrice": {
"description": "The price of a single product. Price is expressed as the number (integer) of 1/100s of the price.",
"type": "integer",
"title": "unitPrice"
},
"linePrice": {
"description": "The price of the products. Price is expressed as the number (integer) of 1/100s of the price.",
"type": "integer",
"title": "linePrice"
}
},
"required": [
"id",
"linePrice",
"quantity",
"unitPrice"
]
},
"DeliveryDetails": {
"title": "DeliveryDetails",
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"description": "Delivery to a pickup point",
"type": "string",
"enum": [
"PICKUP"
],
"title": "type"
},
"subType": {
"$ref": "#/definitions/CheckoutDeliverySubtype",
"description": "The type of pickup point",
"title": "subType"
},
"method": {
"$ref": "#/definitions/MerchantDeliveryOptions",
"description": "The method",
"title": "method"
},
"name": {
"description": "The name of the pickup point",
"type": "string",
"title": "name"
},
"id": {
"description": "The code of the pickup point",
"type": "string",
"title": "id"
},
"lat": {
"description": "The lattitude of the pickup point",
"type": "number",
"title": "lat"
},
"lng": {
"description": "The longitude of the pickup point",
"type": "number",
"title": "lng"
},
"street": {
"description": "The street",
"type": "string",
"title": "street"
},
"streetNo": {
"description": "The number on the street",
"type": "string",
"title": "streetNo"
},
"apartmentNo": {
"description": "The appartment number",
"type": "string",
"title": "apartmentNo"
},
"postalCode": {
"description": "The postal code",
"type": "string",
"title": "postalCode"
},
"city": {
"description": "The city",
"type": "string",
"title": "city"
},
"country": {
"description": "The country",
"type": "string",
"enum": [
"PL"
],
"title": "country"
},
"phoneNumber": {
"description": "The phone number",
"type": "string",
"title": "phoneNumber"
},
"email": {
"description": "The email address",
"type": "string",
"title": "email"
}
},
"required": [
"city",
"country",
"email",
"id",
"method",
"name",
"postalCode",
"street",
"subType",
"type"
]
},
{
"type": "object",
"properties": {
"type": {
"description": "Delivery by courier",
"type": "string",
"enum": [
"COURIER"
],
"title": "type"
},
"method": {
"$ref": "#/definitions/MerchantDeliveryOptions",
"title": "method"
},
"street": {
"description": "The street",
"type": "string",
"title": "street"
},
"streetNo": {
"description": "The number on the street",
"type": "string",
"title": "streetNo"
},
"apartmentNo": {
"description": "The appartment number",
"type": "string",
"title": "apartmentNo"
},
"postalCode": {
"description": "The postal code",
"type": "string",
"title": "postalCode"
},
"city": {
"description": "The city",
"type": "string",
"title": "city"
},
"country": {
"description": "The country",
"type": "string",
"enum": [
"PL"
],
"title": "country"
},
"notes": {
"description": "Additional notes",
"type": "string",
"title": "notes"
},
"firstName": {
"description": "The first name",
"type": "string",
"title": "firstName"
},
"lastName": {
"description": "The last name",
"type": "string",
"title": "lastName"
},
"phoneNumber": {
"description": "The phone number",
"type": "string",
"title": "phoneNumber"
},
"companyName": {
"description": "The company name",
"type": "string",
"title": "companyName"
},
"email": {
"description": "The email address",
"type": "string",
"title": "email"
}
},
"required": [
"city",
"country",
"email",
"firstName",
"lastName",
"method",
"notes",
"phoneNumber",
"postalCode",
"street",
"streetNo",
"type"
]
},
{
"type": "object",
"properties": {
"type": {
"description": "Electronic delivery",
"type": "string",
"enum": [
"ELECTRONIC"
],
"title": "type"
},
"method": {
"$ref": "#/definitions/MerchantDeliveryOptions",
"title": "method"
},
"email": {
"description": "The email address",
"type": "string",
"title": "email"
}
},
"required": [
"email",
"method",
"type"
]
}
]
},
"CheckoutDeliverySubtype": {
"title": "CheckoutDeliverySubtype",
"enum": [
"APM",
"PICKUP_POINT",
"SHOP"
],
"type": "string"
},
"MerchantDeliveryOptions": {
"title": "MerchantDeliveryOptions",
"enum": [
"DHL_COURIER",
"DHL_PICKUP",
"DPD_COURIER",
"DPD_PICKUP",
"ELECTRONIC",
"FEDEX_COURIER",
"GEIS_COURIER",
"GLS_COURIER",
"INPOST_APM",
"INPOST_COURIER",
"INSTORE_PICKUP",
"ORLEN_APM",
"POCZTA_POLSKA_APM",
"POCZTEX_COURIER",
"UPS_COURIER"
],
"type": "string"
},
"BillingDetails": {
"title": "BillingDetails",
"type": "object",
"properties": {
"companyName": {
"description": "The name of the comapny for the invoice",
"type": "string",
"title": "companyName"
},
"taxId": {
"description": "The tax number",
"type": "string",
"title": "taxId"
},
"firstName": {
"description": "The first name",
"type": "string",
"title": "firstName"
},
"lastName": {
"description": "The last name",
"type": "string",
"title": "lastName"
},
"country": {
"description": "The country",
"type": "string",
"title": "country"
},
"city": {
"description": "The city",
"type": "string",
"title": "city"
},
"postalCode": {
"description": "The postal code",
"type": "string",
"title": "postalCode"
},
"street": {
"description": "The street",
"type": "string",
"title": "street"
},
"streetNo": {
"description": "The number on the street",
"type": "string",
"title": "streetNo"
},
"apartmentNo": {
"description": "The appartment number",
"type": "string",
"title": "apartmentNo"
},
"notes": {
"description": "Additional notes",
"type": "string",
"title": "notes"
}
},
"required": [
"city",
"country",
"notes",
"postalCode",
"street",
"streetNo"
]
},
"PlaceOrderAmount": {
"title": "PlaceOrderAmount",
"type": "object",
"properties": {
"amount": {
"description": "The total price for the order. Price is expressed as the number (integer) of 1/100s of the price.",
"minimum": 0,
"type": "integer",
"title": "amount"
},
"currency": {
"description": "The currency",
"maxLength": 3,
"type": "string",
"title": "currency"
}
},
"required": [
"amount",
"currency"
]
},
"OrderConsent": {
"title": "OrderConsent",
"type": "object",
"properties": {
"id": {
"description": "The ID of the consent as defined in the merchant panel",
"type": "string",
"title": "id"
},
"version": {
"description": "The version of the consent",
"type": "number",
"title": "version"
}
},
"required": [
"id",
"version"
]
}
},
"$schema": "http://json-schema.org/draft-07/schema#"
}
The user has ordered 1 item of PLN 60.00. Since there was no discount appplied, the product list only has a unitPrice and a linePrice, and no previousUnitPrice or previousLinePrice. Of note is that the user has given consent to receive email marketing messages, but not to receive SMS marketing messages.
In store pickup¶
If the user has selected in store pickup, delivery details will contain the delivery address enriched with pointId of pickup point seleted by user in app:
Place order request schema v1
{
"description": "The data for an order placed through OpenApp.",
"title": "MerchantPlaceOrder#",
"additionalProperties": false,
"type": "object",
"properties": {
"oaOrderId": {
"description": "The unique ID of the order generated by OpenApp.",
"maxLength": 36,
"type": "string",
"title": "oaOrderId"
},
"basket": {
"$ref": "#/definitions/OpenPayOrderBasket",
"description": "The shopping basket",
"title": "basket"
},
"deliveryDetails": {
"$ref": "#/definitions/DeliveryDetails",
"description": "The details of delivery",
"title": "deliveryDetails"
},
"billingDetails": {
"description": "The details of invoice",
"$ref": "#/definitions/BillingDetails",
"title": "billingDetails"
},
"paymentDetails": {
"$ref": "#/definitions/PlaceOrderAmount",
"description": "The details of the payment",
"title": "paymentDetails"
},
"consents": {
"description": "The consents which the user agreed to",
"type": "array",
"items": {
"$ref": "#/definitions/OrderConsent"
},
"title": "consents"
}
},
"required": [
"basket",
"consents",
"deliveryDetails",
"oaOrderId",
"paymentDetails"
],
"definitions": {
"OpenPayOrderBasket": {
"title": "OpenPayOrderBasket",
"type": "object",
"properties": {
"id": {
"description": "The id of the shopping basket which is purchased",
"maxLength": 36,
"type": "string",
"title": "id"
},
"price": {
"$ref": "#/definitions/PlaceOrderPrice",
"description": "The basket price information",
"title": "price"
},
"products": {
"description": "The basket products",
"type": "array",
"items": {
"$ref": "#/definitions/BaseProduct"
},
"title": "products"
},
"loggedUser": {
"description": "The id of the user in the merchant store (if known)",
"type": "string",
"title": "loggedUser"
}
},
"required": [
"id",
"price",
"products"
]
},
"PlaceOrderPrice": {
"description": "The basket price information",
"title": "PlaceOrderPrice",
"type": "object",
"properties": {
"deliveryCost": {
"description": "The delivery cost. Price is expressed as the number (integer) of 1/100s of the price.",
"minimum": 0,
"type": "integer",
"title": "deliveryCost"
},
"currency": {
"type": "string",
"title": "currency"
},
"basketValue": {
"description": "The price of the basket. Price is expressed as the number (integer) of 1/100s of the price.",
"minimum": 0,
"type": "integer",
"title": "basketValue"
},
"discounts": {
"description": "Applied discounts",
"type": "array",
"items": {
"$ref": "#/definitions/BasketPriceDiscount"
},
"title": "discounts"
}
},
"required": [
"basketValue",
"currency",
"deliveryCost",
"discounts"
]
},
"BasketPriceDiscount": {
"title": "BasketPriceDiscount",
"type": "object",
"properties": {
"code": {
"description": "The discount code.",
"maxLength": 36,
"type": "string",
"title": "code"
},
"value": {
"description": "The value of the discount. Value is expressed as the number (integer) of 1/100s of the currency.",
"minimum": 0,
"type": "integer",
"title": "value"
},
"error": {
"description": "The error code of the discount",
"enum": [
"EXPIRED",
"INVALID",
"NOT_APPLICABLE",
"USED"
],
"type": "string",
"title": "error"
}
},
"required": [
"code",
"value"
]
},
"BaseProduct": {
"title": "BaseProduct",
"type": "object",
"properties": {
"ean": {
"description": "The ean (or other barcode on the product). Specifying this allows the user to search in his order history by scanning the barcode to do a re-purchase.",
"maxLength": 36,
"type": "string",
"title": "ean"
},
"id": {
"description": "The unique ID of the product.",
"maxLength": 36,
"type": "string",
"title": "id"
},
"quantity": {
"description": "The number of items in the purchase.",
"minimum": 0,
"type": "integer",
"title": "quantity"
},
"unitPrice": {
"description": "The price of a single product. Price is expressed as the number (integer) of 1/100s of the price.",
"type": "integer",
"title": "unitPrice"
},
"linePrice": {
"description": "The price of the products. Price is expressed as the number (integer) of 1/100s of the price.",
"type": "integer",
"title": "linePrice"
}
},
"required": [
"id",
"linePrice",
"quantity",
"unitPrice"
]
},
"DeliveryDetails": {
"title": "DeliveryDetails",
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"description": "Delivery to a pickup point",
"type": "string",
"enum": [
"PICKUP"
],
"title": "type"
},
"subType": {
"$ref": "#/definitions/CheckoutDeliverySubtype",
"description": "The type of pickup point",
"title": "subType"
},
"method": {
"$ref": "#/definitions/MerchantDeliveryOptions",
"description": "The method",
"title": "method"
},
"name": {
"description": "The name of the pickup point",
"type": "string",
"title": "name"
},
"id": {
"description": "The code of the pickup point",
"type": "string",
"title": "id"
},
"lat": {
"description": "The lattitude of the pickup point",
"type": "number",
"title": "lat"
},
"lng": {
"description": "The longitude of the pickup point",
"type": "number",
"title": "lng"
},
"street": {
"description": "The street",
"type": "string",
"title": "street"
},
"streetNo": {
"description": "The number on the street",
"type": "string",
"title": "streetNo"
},
"apartmentNo": {
"description": "The appartment number",
"type": "string",
"title": "apartmentNo"
},
"postalCode": {
"description": "The postal code",
"type": "string",
"title": "postalCode"
},
"city": {
"description": "The city",
"type": "string",
"title": "city"
},
"country": {
"description": "The country",
"type": "string",
"enum": [
"PL"
],
"title": "country"
},
"phoneNumber": {
"description": "The phone number",
"type": "string",
"title": "phoneNumber"
},
"email": {
"description": "The email address",
"type": "string",
"title": "email"
}
},
"required": [
"city",
"country",
"email",
"id",
"method",
"name",
"postalCode",
"street",
"subType",
"type"
]
},
{
"type": "object",
"properties": {
"type": {
"description": "Delivery by courier",
"type": "string",
"enum": [
"COURIER"
],
"title": "type"
},
"method": {
"$ref": "#/definitions/MerchantDeliveryOptions",
"title": "method"
},
"street": {
"description": "The street",
"type": "string",
"title": "street"
},
"streetNo": {
"description": "The number on the street",
"type": "string",
"title": "streetNo"
},
"apartmentNo": {
"description": "The appartment number",
"type": "string",
"title": "apartmentNo"
},
"postalCode": {
"description": "The postal code",
"type": "string",
"title": "postalCode"
},
"city": {
"description": "The city",
"type": "string",
"title": "city"
},
"country": {
"description": "The country",
"type": "string",
"enum": [
"PL"
],
"title": "country"
},
"notes": {
"description": "Additional notes",
"type": "string",
"title": "notes"
},
"firstName": {
"description": "The first name",
"type": "string",
"title": "firstName"
},
"lastName": {
"description": "The last name",
"type": "string",
"title": "lastName"
},
"phoneNumber": {
"description": "The phone number",
"type": "string",
"title": "phoneNumber"
},
"companyName": {
"description": "The company name",
"type": "string",
"title": "companyName"
},
"email": {
"description": "The email address",
"type": "string",
"title": "email"
}
},
"required": [
"city",
"country",
"email",
"firstName",
"lastName",
"method",
"notes",
"phoneNumber",
"postalCode",
"street",
"streetNo",
"type"
]
},
{
"type": "object",
"properties": {
"type": {
"description": "Electronic delivery",
"type": "string",
"enum": [
"ELECTRONIC"
],
"title": "type"
},
"method": {
"$ref": "#/definitions/MerchantDeliveryOptions",
"title": "method"
},
"email": {
"description": "The email address",
"type": "string",
"title": "email"
}
},
"required": [
"email",
"method",
"type"
]
}
]
},
"CheckoutDeliverySubtype": {
"title": "CheckoutDeliverySubtype",
"enum": [
"APM",
"PICKUP_POINT",
"SHOP"
],
"type": "string"
},
"MerchantDeliveryOptions": {
"title": "MerchantDeliveryOptions",
"enum": [
"DHL_COURIER",
"DHL_PICKUP",
"DPD_COURIER",
"DPD_PICKUP",
"ELECTRONIC",
"FEDEX_COURIER",
"GEIS_COURIER",
"GLS_COURIER",
"INPOST_APM",
"INPOST_COURIER",
"INSTORE_PICKUP",
"ORLEN_APM",
"POCZTA_POLSKA_APM",
"POCZTEX_COURIER",
"UPS_COURIER"
],
"type": "string"
},
"BillingDetails": {
"title": "BillingDetails",
"type": "object",
"properties": {
"companyName": {
"description": "The name of the comapny for the invoice",
"type": "string",
"title": "companyName"
},
"taxId": {
"description": "The tax number",
"type": "string",
"title": "taxId"
},
"firstName": {
"description": "The first name",
"type": "string",
"title": "firstName"
},
"lastName": {
"description": "The last name",
"type": "string",
"title": "lastName"
},
"country": {
"description": "The country",
"type": "string",
"title": "country"
},
"city": {
"description": "The city",
"type": "string",
"title": "city"
},
"postalCode": {
"description": "The postal code",
"type": "string",
"title": "postalCode"
},
"street": {
"description": "The street",
"type": "string",
"title": "street"
},
"streetNo": {
"description": "The number on the street",
"type": "string",
"title": "streetNo"
},
"apartmentNo": {
"description": "The appartment number",
"type": "string",
"title": "apartmentNo"
},
"notes": {
"description": "Additional notes",
"type": "string",
"title": "notes"
}
},
"required": [
"city",
"country",
"notes",
"postalCode",
"street",
"streetNo"
]
},
"PlaceOrderAmount": {
"title": "PlaceOrderAmount",
"type": "object",
"properties": {
"amount": {
"description": "The total price for the order. Price is expressed as the number (integer) of 1/100s of the price.",
"minimum": 0,
"type": "integer",
"title": "amount"
},
"currency": {
"description": "The currency",
"maxLength": 3,
"type": "string",
"title": "currency"
}
},
"required": [
"amount",
"currency"
]
},
"OrderConsent": {
"title": "OrderConsent",
"type": "object",
"properties": {
"id": {
"description": "The ID of the consent as defined in the merchant panel",
"type": "string",
"title": "id"
},
"version": {
"description": "The version of the consent",
"type": "number",
"title": "version"
}
},
"required": [
"id",
"version"
]
}
},
"$schema": "http://json-schema.org/draft-07/schema#"
}
Courier delivery¶
If the user has selected courier delivery the delivery details will contain the delivery address:
Place order request schema v1
{
"description": "The data for an order placed through OpenApp.",
"title": "MerchantPlaceOrder#",
"additionalProperties": false,
"type": "object",
"properties": {
"oaOrderId": {
"description": "The unique ID of the order generated by OpenApp.",
"maxLength": 36,
"type": "string",
"title": "oaOrderId"
},
"basket": {
"$ref": "#/definitions/OpenPayOrderBasket",
"description": "The shopping basket",
"title": "basket"
},
"deliveryDetails": {
"$ref": "#/definitions/DeliveryDetails",
"description": "The details of delivery",
"title": "deliveryDetails"
},
"billingDetails": {
"description": "The details of invoice",
"$ref": "#/definitions/BillingDetails",
"title": "billingDetails"
},
"paymentDetails": {
"$ref": "#/definitions/PlaceOrderAmount",
"description": "The details of the payment",
"title": "paymentDetails"
},
"consents": {
"description": "The consents which the user agreed to",
"type": "array",
"items": {
"$ref": "#/definitions/OrderConsent"
},
"title": "consents"
}
},
"required": [
"basket",
"consents",
"deliveryDetails",
"oaOrderId",
"paymentDetails"
],
"definitions": {
"OpenPayOrderBasket": {
"title": "OpenPayOrderBasket",
"type": "object",
"properties": {
"id": {
"description": "The id of the shopping basket which is purchased",
"maxLength": 36,
"type": "string",
"title": "id"
},
"price": {
"$ref": "#/definitions/PlaceOrderPrice",
"description": "The basket price information",
"title": "price"
},
"products": {
"description": "The basket products",
"type": "array",
"items": {
"$ref": "#/definitions/BaseProduct"
},
"title": "products"
},
"loggedUser": {
"description": "The id of the user in the merchant store (if known)",
"type": "string",
"title": "loggedUser"
}
},
"required": [
"id",
"price",
"products"
]
},
"PlaceOrderPrice": {
"description": "The basket price information",
"title": "PlaceOrderPrice",
"type": "object",
"properties": {
"deliveryCost": {
"description": "The delivery cost. Price is expressed as the number (integer) of 1/100s of the price.",
"minimum": 0,
"type": "integer",
"title": "deliveryCost"
},
"currency": {
"type": "string",
"title": "currency"
},
"basketValue": {
"description": "The price of the basket. Price is expressed as the number (integer) of 1/100s of the price.",
"minimum": 0,
"type": "integer",
"title": "basketValue"
},
"discounts": {
"description": "Applied discounts",
"type": "array",
"items": {
"$ref": "#/definitions/BasketPriceDiscount"
},
"title": "discounts"
}
},
"required": [
"basketValue",
"currency",
"deliveryCost",
"discounts"
]
},
"BasketPriceDiscount": {
"title": "BasketPriceDiscount",
"type": "object",
"properties": {
"code": {
"description": "The discount code.",
"maxLength": 36,
"type": "string",
"title": "code"
},
"value": {
"description": "The value of the discount. Value is expressed as the number (integer) of 1/100s of the currency.",
"minimum": 0,
"type": "integer",
"title": "value"
},
"error": {
"description": "The error code of the discount",
"enum": [
"EXPIRED",
"INVALID",
"NOT_APPLICABLE",
"USED"
],
"type": "string",
"title": "error"
}
},
"required": [
"code",
"value"
]
},
"BaseProduct": {
"title": "BaseProduct",
"type": "object",
"properties": {
"ean": {
"description": "The ean (or other barcode on the product). Specifying this allows the user to search in his order history by scanning the barcode to do a re-purchase.",
"maxLength": 36,
"type": "string",
"title": "ean"
},
"id": {
"description": "The unique ID of the product.",
"maxLength": 36,
"type": "string",
"title": "id"
},
"quantity": {
"description": "The number of items in the purchase.",
"minimum": 0,
"type": "integer",
"title": "quantity"
},
"unitPrice": {
"description": "The price of a single product. Price is expressed as the number (integer) of 1/100s of the price.",
"type": "integer",
"title": "unitPrice"
},
"linePrice": {
"description": "The price of the products. Price is expressed as the number (integer) of 1/100s of the price.",
"type": "integer",
"title": "linePrice"
}
},
"required": [
"id",
"linePrice",
"quantity",
"unitPrice"
]
},
"DeliveryDetails": {
"title": "DeliveryDetails",
"anyOf": [
{
"type": "object",
"properties": {
"type": {
"description": "Delivery to a pickup point",
"type": "string",
"enum": [
"PICKUP"
],
"title": "type"
},
"subType": {
"$ref": "#/definitions/CheckoutDeliverySubtype",
"description": "The type of pickup point",
"title": "subType"
},
"method": {
"$ref": "#/definitions/MerchantDeliveryOptions",
"description": "The method",
"title": "method"
},
"name": {
"description": "The name of the pickup point",
"type": "string",
"title": "name"
},
"id": {
"description": "The code of the pickup point",
"type": "string",
"title": "id"
},
"lat": {
"description": "The lattitude of the pickup point",
"type": "number",
"title": "lat"
},
"lng": {
"description": "The longitude of the pickup point",
"type": "number",
"title": "lng"
},
"street": {
"description": "The street",
"type": "string",
"title": "street"
},
"streetNo": {
"description": "The number on the street",
"type": "string",
"title": "streetNo"
},
"apartmentNo": {
"description": "The appartment number",
"type": "string",
"title": "apartmentNo"
},
"postalCode": {
"description": "The postal code",
"type": "string",
"title": "postalCode"
},
"city": {
"description": "The city",
"type": "string",
"title": "city"
},
"country": {
"description": "The country",
"type": "string",
"enum": [
"PL"
],
"title": "country"
},
"phoneNumber": {
"description": "The phone number",
"type": "string",
"title": "phoneNumber"
},
"email": {
"description": "The email address",
"type": "string",
"title": "email"
}
},
"required": [
"city",
"country",
"email",
"id",
"method",
"name",
"postalCode",
"street",
"subType",
"type"
]
},
{
"type": "object",
"properties": {
"type": {
"description": "Delivery by courier",
"type": "string",
"enum": [
"COURIER"
],
"title": "type"
},
"method": {
"$ref": "#/definitions/MerchantDeliveryOptions",
"title": "method"
},
"street": {
"description": "The street",
"type": "string",
"title": "street"
},
"streetNo": {
"description": "The number on the street",
"type": "string",
"title": "streetNo"
},
"apartmentNo": {
"description": "The appartment number",
"type": "string",
"title": "apartmentNo"
},
"postalCode": {
"description": "The postal code",
"type": "string",
"title": "postalCode"
},
"city": {
"description": "The city",
"type": "string",
"title": "city"
},
"country": {
"description": "The country",
"type": "string",
"enum": [
"PL"
],
"title": "country"
},
"notes": {
"description": "Additional notes",
"type": "string",
"title": "notes"
},
"firstName": {
"description": "The first name",
"type": "string",
"title": "firstName"
},
"lastName": {
"description": "The last name",
"type": "string",
"title": "lastName"
},
"phoneNumber": {
"description": "The phone number",
"type": "string",
"title": "phoneNumber"
},
"companyName": {
"description": "The company name",
"type": "string",
"title": "companyName"
},
"email": {
"description": "The email address",
"type": "string",
"title": "email"
}
},
"required": [
"city",
"country",
"email",
"firstName",
"lastName",
"method",
"notes",
"phoneNumber",
"postalCode",
"street",
"streetNo",
"type"
]
},
{
"type": "object",
"properties": {
"type": {
"description": "Electronic delivery",
"type": "string",
"enum": [
"ELECTRONIC"
],
"title": "type"
},
"method": {
"$ref": "#/definitions/MerchantDeliveryOptions",
"title": "method"
},
"email": {
"description": "The email address",
"type": "string",
"title": "email"
}
},
"required": [
"email",
"method",
"type"
]
}
]
},
"CheckoutDeliverySubtype": {
"title": "CheckoutDeliverySubtype",
"enum": [
"APM",
"PICKUP_POINT",
"SHOP"
],
"type": "string"
},
"MerchantDeliveryOptions": {
"title": "MerchantDeliveryOptions",
"enum": [
"DHL_COURIER",
"DHL_PICKUP",
"DPD_COURIER",
"DPD_PICKUP",
"ELECTRONIC",
"FEDEX_COURIER",
"GEIS_COURIER",
"GLS_COURIER",
"INPOST_APM",
"INPOST_COURIER",
"INSTORE_PICKUP",
"ORLEN_APM",
"POCZTA_POLSKA_APM",
"POCZTEX_COURIER",
"UPS_COURIER"
],
"type": "string"
},
"BillingDetails": {
"title": "BillingDetails",
"type": "object",
"properties": {
"companyName": {
"description": "The name of the comapny for the invoice",
"type": "string",
"title": "companyName"
},
"taxId": {
"description": "The tax number",
"type": "string",
"title": "taxId"
},
"firstName": {
"description": "The first name",
"type": "string",
"title": "firstName"
},
"lastName": {
"description": "The last name",
"type": "string",
"title": "lastName"
},
"country": {
"description": "The country",
"type": "string",
"title": "country"
},
"city": {
"description": "The city",
"type": "string",
"title": "city"
},
"postalCode": {
"description": "The postal code",
"type": "string",
"title": "postalCode"
},
"street": {
"description": "The street",
"type": "string",
"title": "street"
},
"streetNo": {
"description": "The number on the street",
"type": "string",
"title": "streetNo"
},
"apartmentNo": {
"description": "The appartment number",
"type": "string",
"title": "apartmentNo"
},
"notes": {
"description": "Additional notes",
"type": "string",
"title": "notes"
}
},
"required": [
"city",
"country",
"notes",
"postalCode",
"street",
"streetNo"
]
},
"PlaceOrderAmount": {
"title": "PlaceOrderAmount",
"type": "object",
"properties": {
"amount": {
"description": "The total price for the order. Price is expressed as the number (integer) of 1/100s of the price.",
"minimum": 0,
"type": "integer",
"title": "amount"
},
"currency": {
"description": "The currency",
"maxLength": 3,
"type": "string",
"title": "currency"
}
},
"required": [
"amount",
"currency"
]
},
"OrderConsent": {
"title": "OrderConsent",
"type": "object",
"properties": {
"id": {
"description": "The ID of the consent as defined in the merchant panel",
"type": "string",
"title": "id"
},
"version": {
"description": "The version of the consent",
"type": "number",
"title": "version"
}
},
"required": [
"id",
"version"
]
}
},
"$schema": "http://json-schema.org/draft-07/schema#"
}
As courier delivery is not free, an additional fee of PLN 9.95 is added to the total price of the purchase.
Response¶
In reponse, the website should send the order confirmation.
| Place order response | |
|---|---|
Place order response schema v1
{
"additionalProperties": false,
"type": "object",
"properties": {
"shopOrderId": {
"description": "The unique ID of the order.",
"maxLength": 36,
"type": "string",
"title": "shopOrderId"
},
"oaOrderId": {
"description": "The ID of the order as generated by OpenApp. Mandatory in case of an asynchronous connection through a queue in order to correlate the placed order with the response.",
"maxLength": 36,
"type": "string",
"title": "oaOrderId"
},
"returnPolicy": {
"$ref": "#/definitions/OrderReturnPolicy",
"description": "The policy for returning the order",
"title": "returnPolicy"
},
"shipments": {
"description": "The shipments for the order",
"type": "array",
"items": {
"$ref": "#/definitions/OrderShipmentMulti"
},
"title": "shipments"
}
},
"required": [
"returnPolicy",
"shopOrderId"
],
"definitions": {
"OrderReturnPolicy": {
"title": "OrderReturnPolicy",
"type": "object",
"properties": {
"maxReturnDays": {
"description": "The length of the allowed return period for the order.",
"minimum": 0,
"type": "integer",
"title": "maxReturnDays"
}
},
"required": [
"maxReturnDays"
]
},
"OrderShipmentMulti": {
"additionalProperties": false,
"title": "OrderShipmentMulti",
"type": "object",
"properties": {
"shipmentId": {
"description": "The id of the shipment",
"maxLength": 64,
"type": "string",
"title": "shipmentId"
},
"status": {
"$ref": "#/definitions/StoreDeliveryStatus",
"description": "The status of the shipment",
"title": "status"
},
"notes": {
"description": "Optional merchant notes on the shipment",
"maxLength": 64,
"type": "string",
"title": "notes"
},
"products": {
"description": "The products which will be in this shipment",
"type": "array",
"items": {
"$ref": "#/definitions/OrderShipmentProduct"
},
"title": "products"
},
"timing": {
"description": "The estimation of the delivery time, i.e. 'next business day' or 'July 18th'.",
"maxLength": 40,
"type": "string",
"title": "timing"
},
"operator": {
"description": "The operator of the shipment",
"maxLength": 64,
"type": "string",
"title": "operator"
},
"trackingCode": {
"description": "The tracking code.",
"maxLength": 64,
"type": "string",
"title": "trackingCode"
},
"trackingUrl": {
"description": "The tracking URL.",
"maxLength": 255,
"type": "string",
"title": "trackingUrl"
}
},
"required": [
"shipmentId",
"status"
]
},
"StoreDeliveryStatus": {
"title": "StoreDeliveryStatus",
"enum": [
"CANCELLED_MERCHANT",
"DELIVERED",
"FULFILLED",
"IN_DELIVERY",
"ORDERED",
"READY_FOR_PICKUP",
"SHIPPED"
],
"type": "string"
},
"OrderShipmentProduct": {
"additionalProperties": false,
"title": "OrderShipmentProduct",
"type": "object",
"properties": {
"id": {
"description": "The unique ID of the product.",
"maxLength": 36,
"type": "string",
"title": "id"
},
"quantity": {
"description": "The number of items in the purchase.",
"minimum": 0,
"type": "integer",
"title": "quantity"
}
},
"required": [
"id",
"quantity"
]
}
},
"$schema": "http://json-schema.org/draft-07/schema#"
}
The merchant website should answer within 8 seconds.
This example is an example of a simple basket. For a complete description of the basket response see the basket JSON schema.