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.
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: Compute bill for a collection of products.
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”. |
donation_amount |
String |
The amount to be donated in the format CURRENCYAMOUNT. Example: “EUR1.50”. |
Field name |
Type |
Description |
|---|---|---|
generated_on |
Datetime |
The date and time the bill was generated. |
product_total |
The total value of all provided products. |
|
service_costs |
Object |
The service costs that have to be paid for the provided products. |
total |
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 |
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 |
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 |
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 |
The total amount of the external purchases. |
|
needs_payment |
Boolean |
Whether the bill requires a payment. |
donation_amount |
The amount that the fans donates. Swallowed from the response if the fan decides to not donate anything. |
place_order : POSTing to this resource will place a new order.
Product (list): Products included in this bill.
[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"}
}
],
"custom_fees": [
{
"uid": "3c406cc077f247a190b2e0978c3f9aa0",
"amount": {
"amount": "2.00",
"currency": "EUR"
},
"unit_price": {
"amount": "1.00",
"currency": "EUR"
},
"label": {
"en": "Custom fee",
"nl": "",
"de": "",
"es": "",
"fr": "",
"pt": ""
},
"quantity": 2
}
],
"total_excluding_custom_fees": {"amount": 14.50, "currency": "EUR"}
},
"total": {
"amount": 16.50,
"currency": "EUR"
},
"donation_amount": {
"amount": 1.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"
},
"pickup_location": null,
"required_consumer_fields": ["first_name", "last_name", "email", "country"]
},
{
"uid": "82a5quvndhe161fb357alt872705zr2k",
"name": {"en": "Pickup", "nl": "", "de": "", "fr": "", "es": "", "pt": "", "tr": "", "ru": ""},
"costs": {
"amount": 0.60,
"currency": "EUR"
},
"pickup_location": "1760 John Summit Apt. 896, 71026, Escobarton, United States of America",
"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"
},
"pickup_location": null,
"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"
},
"pickup_location": null,
"required_consumer_fields": ["first_name", "last_name", "email", "country"]
},
"external_purchase_amount": {
"amount": "350.75",
"currency": "EUR"
},
"needs_payment": true,
"_embedded": {
"shop:product": [
// ...
]
}
}
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."}
]
}
}
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"
}
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"
}
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"
}
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"
}
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 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. |