Storefront

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.

Vouchers

Voucher codes can influence the product choices, alter sales period, change min/max per order limitations, provide discounts etc.

Categories

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 a storefront

  • GET: Get a storefront representation of product choices.

Accepted query parameters

Parameter Type Description
event Event URI of the event.
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.

Data

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 unit_price and total of items.
min_per_order Integer Min total quantity of selected products per order.
max_per_order Integer Max total quantity of selected products per order.

Embedded resources

  • 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.

Example representation

[GET] https://shopping-api.paylogic.com/storefront?event=https://shopping-api.paylogic.com/events/123
{

    "_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=http%3A%2F%2F127.0.0.1%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"}
                    }
                }
            ],
            "name": null,  // When configured: {"nl": "Categorienaam", "en": "Category name", etc.}
            "description": null,
            "color": "#000000",
            "background_color": "#ffffff",
            "featured": false
        }
    ],
    "generated_on": "2016-10-17T13:02:16Z",
    "country": "NL",
    "should_display_service_costs": 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": {
            // ...
        }
    }

}

Service costs and the 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 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.

Captcha

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.

Error handling

Validation errors

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"
}

Voucher code is invalid

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 types

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.