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.
now Datetime Optional datetime to generate the storefront.

Data

Field name Type Description
generated_on Datetime The date and time the storefront was generated.
categories List List of product item categories.
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.

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"}
                        }
                    ],
                    "unit_price": {"amount": "1.20", "currency": "EUR"},
                    "total": {"amount": "1.20", "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",
    "min_per_order": 1,
    "max_per_order": 4,
    "_embedded": {
        "shop:event": {
            // ...
        },
        "shop:product": [
            {
                // ...
            }
        ]
    },

}

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.