Bill

The bill resource allows you to generate a bill for a collection of products which is created and stored on the client side. This bill will state what the order consumer will have to pay in total, including all applicable fees, and will give you your options for payment and shipping methods.

Please note that the bill resource is merely a snapshot of all costs and prices, which is only accurate at the time it is generated. Because configurations could change in between generating the bill and placing an order, there is no guarantee that this is exactly what the order consumer will be charged for after placing the order. This should be made clear to the consumer during the ordering process.

Generate a bill

  • POST: Generate a bill for a collection of products or tickets.

Bill can be generated by posting the same format of the payload that is used to create orders. This is a convenient way to use the same data structures on the client side.

{
    "products": [
        {"product": "https://shopping-api.paylogic.com/products/0c2019503cd666fb35c5a3dbd7bafe86", "quantity": 2}
    ],
    "consumer": {"country": "NL"}
}

Get a bill (deprecated)

  • GET: Compute bill for a collection of products.

Accepted query parameters

Parameter Type Description
products List of Product with quantity A list of product URIs and a quantity for that product. A product URI and its quantity are separated by a comma, while different products are separated by an ampersand. Example: “products=/products/123,2&products=/products/456,4”.
payment_method String The payment method for which a bill should be generated.
shipping_method String The shipping method for which a bill should be generated
country String(ISO 3166-1) The country of the consumer for whom the bill should be generated. This is required to include payment method options.
external_purchase_amount String The total amount of the external purchases in the format CURRENCYAMOUNT. Example: “EUR350.75”.

Data

Field name Type Description
generated_on Datetime The date and time the bill was generated.
product_total Amount The total value of all provided products.
service_costs Object The service costs that have to be paid for the provided products.
total Amount The total amount the consumer has to pay, before payment costs.
products List of Product selection List of products with a quantity. There is also an optional parent attribute when combo products are used.
grand_total Amount The total amount the consumer has to pay. Only included if the payment_method parameter is provided.
available_payment_methods List of Payment method A list of payment methods that can be chosen. If the consumer’s country is not provided as a query parameter this will be an empty list.
available_shipping_methods List of Shipping method List of shipping methods that can be chosen. When placing the order it is always possible to select no shipping method if the shipping is handled by the client. If the consumer’s country is included we will also show non-digital shipping methods (if available).
payment_method Payment method If the payment_method GET parameter is provided, this will contain a payment method object with the details of the specified payment method. If it is not provided, this field will be empty.
shipping_method Shipping method If the shipping_method GET parameter is provided, this will contain a shipping method object with the details of the specified shipping method. If it is not provided, this field will be empty.
external_purchase_amount Amount The total amount of the external purchases.
needs_payment Boolean Whether the bill requires a payment.

Embedded resources

None.

Example representation

[GET] https://shopping-api.paylogic.com/bill?products=https://shopping-api.paylogic.com/products/123,3&products=https://shopping-api.paylogic.com/products/456,1&country=NL
{
    "_links": {
        "self": {
            "href": "https://shopping-api.paylogic.com/bill?products=https://shopping-api.paylogic.com/products/123,3&products=https://shopping-api.paylogic.com/products/456,1&country=NL"
        },
        "curies": [
            {
                "name": "shop",
                "href": "https://shopping-api-docs.paylogic.com/documentation/{rel}.html",
                "templated": true,
                "type": "text/html"
            }
        ],
        "profile": {
            "href": "https://shopping-api-docs.paylogic.com/documentation/bill.html",
            "type": "text/html"
        },
        "shop:place_order": {
            "href": "https://shopping-api.paylogic.com/orders"
        }
    },
    "generated_on": "2014-04-01T10:23:54Z",
    "product_total": {
        "amount": 13.50,
        "currency": "EUR"
    },
    "service_costs": {
        "amount": 1.50,  // Deprecated
        "currency": "EUR",  // Deprecated
        "total": {"amount": 1.50, "currency": "EUR"},
        "per_order": {"amount": 0.50, "currency": "EUR"},
        "per_product": [
            {
                "product": "https://shopping-api.paylogic.com/products/12365478654238976585643567854323",
                "amount": {"amount": 0.90, "currency": "EUR"}
            },
            {
                "product": "https://shopping-api.paylogic.com/products/456ghtr45tg678fe5rf456yhgbvsw3lh",
                "amount": {"amount": 0.05, "currency": "EUR"}
            },
            {
                "product": "https://shopping-api.paylogic.com/products/267arnr45tg984rd5rf456opshwks0ol",
                "amount": {"amount": 0.05, "currency": "EUR"}
            }
        ]
    },
    "total": {
        "amount": 16.50,
        "currency": "EUR"
    },
    "products": [
        {
            "product": "https://shopping-api.paylogic.com/products/12365478654238976585643567854323",
            "quantity": 3,
            "unit_price": {"currency": "EUR", "amount": "5.45"},
            "total": {"currency": "EUR", "amount": "16.35"}
        },
        {
            "product": "https://shopping-api.paylogic.com/products/456ghtr45tg678fe5rf456yhgbvsw3lh",
            "quantity": 1,
            "unit_price": {"currency": "EUR", "amount": "1.00"},
            "total": {"currency": "EUR", "amount": "1.00"}
        },
        {
            "parent": "https://shopping-api.paylogic.com/products/456ghtr45tg678fe5rf456yhgbvsw3lh",
            "product": "https://shopping-api.paylogic.com/products/267arnr45tg984rd5rf456opshwks0ol",
            "quantity": 1,
            "unit_price": {"currency": "EUR", "amount": "1.23"},
            "total": {"currency": "EUR", "amount": "1.23"}
        }
    ],
    "available_payment_methods": [
        {
            "uid": "ghr57d5h3gd162fb35c5a3db57ghrydg",
            "name": {"en": "iDeal", "nl": "", "de": "", "fr": "", "es": "", "pt": "", "tr": "", "ru": ""},
            "image": "https://static.paylogic.com/ideal.jpg",
            "costs": {
                "amount": 1.00,
                "currency": "EUR"
            },
            "required_consumer_fields": ["first_name", "last_name", "email", "country"]
        },
        {
            "uid": "g49vhq85jzg05jzhero58359vhqox5us",
            "name": {"en": "PayPal", "nl": "", "de": "", "fr": "", "es": "", "pt": "", "tr": "", "ru": ""},
            "image": "https://static.paylogic.com/paypal.jpg",
            "costs": {
                "amount": 0.85,
                "currency": "EUR"
            },
            "required_consumer_fields": [
                "first_name",
                "last_name",
                "email",
                "date_of_birth",
                "gender",
                "address",
                "postal_code",
                "city",
                "country"
            ]
        }
    ],
    "available_shipping_methods": [
        {
            "uid": "87a5quvndhe162fb357alt872705zr2j",
            "name": {"en": "Eticket", "nl": "", "de": "", "fr": "", "es": "", "pt": "", "tr": "", "ru": ""},
            "costs": {
                "amount": 0.60,
                "currency": "EUR"
            },
            "required_consumer_fields": ["first_name", "last_name", "email", "country"]
        {
            "uid": "850bhq3kehe05hal48cal68gherucr2j",
            "name": "name": {"en": "Postal", "nl": "", "de": "", "fr": "", "es": "", "pt": "", "tr": "", "ru": ""},
            "costs": {
                "amount": 2.50,
                "currency": "EUR"
            },
            "required_consumer_fields": [
                "first_name",
                "last_name",
                "email",
                "date_of_birth",
                "gender",
                "address",
                "postal_code",
                "city",
                "country"
            ]
        }
    ],
    "payment_method": {
        "uid": "ghr57d5h3gd162fb35c5a3db57ghrydg",
        "name": {"en": "iDeal", "nl": "", "de": "", "fr": "", "es": "", "pt": "", "tr": "", "ru": ""},
        "image": "https://static.paylogic.com/ideal.jpg",
        "costs": {
            "amount": 1.00,
            "currency": "EUR"
        },
        "required_consumer_fields": ["first_name", "last_name", "email", "country"]
    },
    "shipping_method": {
        "uid": "87a5quvndhe162fb357alt872705zr2j",
        "name": {"en": "Eticket", "nl": "", "de": "", "fr": "", "es": "", "pt": "", "tr": "", "ru": ""},
        "costs": {
            "amount": 0.60,
            "currency": "EUR"
        },
        "required_consumer_fields": ["first_name", "last_name", "email", "country"]
    },
    "external_purchase_amount": {
        "amount": "350.75",
        "currency": "EUR"
    },
    "needs_payment": true
}

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/bill.html"
        }
    },
    "type": "BAD_REQUEST",
    "details": {
        "errors": [
            {"attr": "products", "error": "To compute a bill, please provide one or more products with quantities."}
        ]
    }
}

Invalid products provided

HTTP/1.1 400 Bad Request
{
    "logref": "<UID>",
    "message": "One or more of the products you provided doesn't exist. Please make sure to use the correct format, and only use the URI's exposed by the API.",
    "_links": {
        "help": {
            "href": "http://shopping-api-docs.paylogic.com/documentation/bill.html"
        }
    },
    "type": "BAD_REQUEST"
}

Invalid country for payment method or unknown payment method

For example, “country=BR&payment_method=ideal”

HTTP/1.1 400 Bad Request
{
    "logref": "<UID>",
    "message": "This payment method cannot be used for a consumer in this country. Please select another payment method from the list of available payment methods.",
    "_links": {
        "help": {
            "href": "http://shopping-api-docs.paylogic.com/documentation/bill.html"
        }
    },
    "type": "PAYMENT_METHOD_NOT_APPLICABLE"
}

Invalid shipping method

HTTP/1.1 400 Bad Request
{
    "logref": "<UID>",
    "message": "This shipping method cannot be used for a consumer in this country. Please select another shipping method from the list of available shipping methods.",
    "_links": {
        "help": {
            "href": "http://shopping-api-docs.paylogic.com/documentation/bill.html"
        }
    },
    "type": "SHIPPING_METHOD_NOT_APPLICABLE"
}

Incompatible currencies

HTTP/1.1 400 Bad Request
{
    "logref": "<UID>",
    "message": "The external purchase amount should use the correct currency: EUR",
    "_links": {
        "help": {
            "href": "http://shopping-api-docs.paylogic.com/documentation/bill.html"
        }
    },
    "type": "BAD_REQUEST"
}

Voucher code is invalid

This error is returned when 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/bill.html"
        }
    },
    "type": "VOUCHER_INVALID"
}

Error types

Error type codes can be used to dispatch the errors on the client side. These errors are related to the bill and order creation.

Type HTTP code Description
FORBIDDEN 403 Forbidden.
NOT_FOUND 404 Not found.
BAD_REQUEST 400 Bad request.
MULTIPLE_EVENTS 400 You are trying to create an order with products from multiple events. This is not allowed. Please only select products from a single event.
NON_SEPARATELY_SALEABLE_PRODUCT 400 All products selected are not separately saleable. Please select an additional product that is separately saleable.
NOT_ON_SALE 400 One of the selected products is not on sale.
PRODUCT_NOT_AVAILABLE 400 One of the selected products is not available. Please GET a representation of the product(s) to view the latest status.
INSUFFICIENT_PRODUCTS 400 The number of selected products is lower than allowed by the configuration of the product and its event. Please GET a representation of the event and the product(s) to see what is allowed.
MAX_PER_ORDER_EXCEEDED 400 The number of selected products is higher than allowed by the configuration of the product and its event. Please GET a representation of the event and the product(s) to see what is allowed.
PAYMENT_METHOD_NOT_APPLICABLE 400 This payment method cannot be used for a consumer in this country. Please select another payment method from the list of available payment methods.
SHIPPING_METHOD_NOT_APPLICABLE 400 This shipping method cannot be used for a consumer in this country. Please select another shipping method from the list of available shipping methods.
VOUCHER_INVALID 400 Voucher code is invalid.