The storefront resource represents categorized product choices for a specific event at any one moment in time. Products are grouped in categories with respect to sales business rules like sales periods, priority groups, sold out settings etc.
Voucher codes can influence the product choices, alter sales period, change min/max per order limitations, provide discounts etc.
Product category is a group of items with a specific name. If a product does not belong to a configured category then a default category is used and the name is null.
GET: Get a storefront representation of product choices.
Parameter |
Type |
Description |
|---|---|---|
event |
URI of the event. |
|
sale |
Link |
URI of the sale. |
basket |
Link |
URI of the basket. This can be used as alternative for the sale URI. |
currency |
String (ISO 4217) |
Optional currency code (See Amount). |
vouchers |
List of Strings |
Optional list of voucher codes. |
cache_allowed |
Boolean |
Optional bool whether the storefront can be cached. Defaults to true. |
country |
String(ISO 3166-1) |
Optional country of the consumer for whom the storefront should be generated. Defaults to event location or detected by the IP address of the consumer. |
Field name |
Type |
Description |
|---|---|---|
generated_on |
Datetime |
The date and time the storefront was generated. |
categories |
List |
List of product item categories. |
country |
String(ISO 3166-1) |
Country of the consumer for whom the storefront is generated. |
should_display_service_costs |
Boolean |
Should the price include service costs and other unavoidable costs be displayed. Affects the |
uses_vouchers |
Boolean |
Whether this storefront uses vouchers |
min_per_order |
Integer |
Min total quantity of selected products per order. |
max_per_order |
Integer |
Max total quantity of selected products per order. |
Event: Event available at this storefront.
Product (list): Products available at this storefront, embedded here for ease of use.
Bill: The bill generated for the cheapest product selection. Contains the minimal shipping and payment costs.
[GET] https://shopping-api.paylogic.com/storefront?event=https%3A%2F%2Fshopping-api.paylogic.com%2Fevents%2F6eeda079963c4060899309f26a6dec2f
{
"_links": {
"curies": [{"href": "https://shopping-api-docs.paylogic.com/documentation/{rel}.html", "name": "shop", "templated": true, "type": "text/html"}],
"profile": {"href": "https://shopping-api-docs.paylogic.com/documentation/storefront.html", "type": "text/html"},
"self": {"href": "https://shopping-api.paylogic.com/storefront?event=https%3A%2F%2Fshopping-api.paylogic.com%2Fevents%2F6eeda079963c4060899309f26a6dec2f"}
},
"categories": [
{
"items": [
{
"is_sold_out": false,
"max_quantity": 10,
"min_quantity": 0,
"product": "https://shopping-api.paylogic.com/products/1252932c11924914bdeba0218727a81d",
"combo": [
{
"product": "https://shopping-api.paylogic.com/products/c136f2d9add9493ba5ca51ae48f4340e",
"unit_price": {"amount": "0.00", "currency": "EUR"},
"price_breakdown": {
"unit_price_including_service_costs": {"amount": "0.00", "currency": "EUR"},
"unit_price_excluding_service_costs": {"amount": "0.00", "currency": "EUR"},
"unit_price_service_costs": {"amount": "0.00", "currency": "EUR"},
"total_including_service_costs": {"amount": "0.00", "currency": "EUR"},
"total_excluding_service_costs": {"amount": "0.00", "currency": "EUR"},
"total_service_costs": {"amount": "0.00", "currency": "EUR"}
}
}
],
"unit_price": {"amount": "1.20", "currency": "EUR"},
"total": {"amount": "1.20", "currency": "EUR"},
"price_breakdown": {
"unit_price_including_service_costs": {"amount": "1.20", "currency": "EUR"},
"unit_price_excluding_service_costs": {"amount": "1.10", "currency": "EUR"},
"unit_price_service_costs": {"amount": "0.10", "currency": "EUR"},
"total_including_service_costs": {"amount": "1.20", "currency": "EUR"},
"total_excluding_service_costs": {"amount": "1.10", "currency": "EUR"},
"total_service_costs": {"amount": "0.10", "currency": "EUR"}
},
"custom_fees": [
{
"uid": "50dbc921d8c547fdb300406841088079",
"label": {
"de":"",
"en":"test",
"es":"",
"fr":"",
"nl":"",
"pt":""
},
"amount": {
"amount": "10.36",
"currency": "EUR"
}
}
],
"available_in_secondary_sale": false
}
],
"name": null, // When configured: {"nl": "Categorienaam", "en": "Category name", etc.}
"description": null,
}
],
"generated_on": "2016-10-17T13:02:16Z",
"country": "NL",
"should_display_service_costs": true,
"uses_vouchers": true,
"min_per_order": 1,
"max_per_order": 4,
"captcha": {
"provider": "reCAPTCHA",
"public_key": "6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI"
},
"_embedded": {
"shop:event": {
// ...
},
"shop:product": [
{
// ...
"price": {"amount": "1.10", "currency": "EUR"}
}
],
"shop:cheapest_bill": {
// ...
}
}
}
In some countries it is required to display all unavoidable costs per product included into the unit price and other fees for booking, shipping and payment are displayed at the very beginning of the purchasing flow.
The should_display_service_costs property is indicating that requirement. It depends on the country that is supplied (or detected) unless configured in the system to be always on.
The item unit_price and the total are modal and depend on that value. They may include the service costs per product.
There is a detailed price_breakdown (see Price breakdown) as well that represents all the price
components for the custom representation of the storefront items.
Storefront response embeds the bill for the cheapest selection of products when possible (shop:cheapest_bill). This bill is to indicate the minimal shipping and payment costs when no products are yet selected by a consumer.
Applications may use rate-limiting protection for the order creation. In this case the captcha provider and the public key is exposed in the storefront. Captcha has to be resolved by the consumer and the response can be optionally supplied to the order POST payload. If the response is not supplied when captcha is enabled then strict rate-limiting will be applied to order creation.
Request validation errors return 400 (Bad Request) responses with the validation errors in the error details.
HTTP/1.1 400 Bad Request
{
"logref": "<UID>",
"message": "Bad request.",
"_links": {
"help": {
"href": "http://shopping-api-docs.paylogic.com/documentation/storefront.html"
}
},
"type": "BAD_REQUEST"
}
This error is returned when a voucher code cannot be used, if it is not valid or already used in other orders.
HTTP/1.1 400 Bad Request
{
"logref": "<UID>",
"message": "One of the vouchers cannot be used",
"_links": {
"help": {
"href": "http://shopping-api-docs.paylogic.com/documentation/storefront.html"
}
},
"type": "VOUCHER_INVALID"
}
Error type codes can be used to dispatch the errors on the client side.
Type |
HTTP code |
Description |
|---|---|---|
FORBIDDEN |
403 |
Forbidden. |
NOT_FOUND |
404 |
Not found. |
BAD_REQUEST |
400 |
Bad request. |
VOUCHER_INVALID |
400 |
Voucher code is invalid. |