**** 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. .. code-block:: javascript { "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 :doc:`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". ======================== ============================================== ============================================== Data ==== ========================== =========================================== ================================================ Field name Type Description ========================== =========================================== ================================================ generated_on Datetime The date and time the bill was generated. product_total :doc:`/objects/amount` The total value of all provided products. service_costs Object The service costs that have to be paid for the provided products. total :doc:`/objects/amount` The total amount the consumer has to pay, before payment costs. products List of :doc:`/objects/product_selection` List of products with a quantity. There is also an optional parent attribute when combo products are used. grand_total :doc:`/objects/amount` The total amount the consumer has to pay. Only included if the payment_method parameter is provided. available_payment_methods List of :doc:`/objects/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 :doc:`/objects/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 :doc:`/objects/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 :doc:`/objects/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 :doc:`/objects/amount` The total amount of the external purchases. needs_payment Boolean Whether the bill requires a payment. donation_amount :doc:`/objects/amount` The amount that the fans donates. Swallowed from the response if the fan decides to not donate anything. ========================== =========================================== ================================================ Link relations ============== * :doc:`place_order ` : POSTing to this resource will place a new order. Embedded resources ================== * :doc:`Product (list) `: Products included in this bill. Example representation ====================== .. code-block:: bash [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 .. code-block:: javascript { "_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": [ // ... ] } } Error handling ============== Validation errors ----------------- Request validation errors return 400 (Bad Request) responses with the validation errors in the error details. .. code-block:: bash HTTP/1.1 400 Bad Request .. code-block:: javascript { "logref": "", "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 ------------------------- .. code-block:: bash HTTP/1.1 400 Bad Request .. code-block:: javascript { "logref": "", "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" .. code-block:: bash HTTP/1.1 400 Bad Request .. code-block:: javascript { "logref": "", "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 ----------------------- .. code-block:: bash HTTP/1.1 400 Bad Request .. code-block:: javascript { "logref": "", "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 ----------------------- .. code-block:: bash HTTP/1.1 400 Bad Request .. code-block:: javascript { "logref": "", "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. .. code-block:: bash HTTP/1.1 400 Bad Request .. code-block:: javascript { "logref": "", "message": "One of the vouchers cannot be used", "_links": { "help": { "href": "http://shopping-api-docs.paylogic.com/documentation/bill.html" } }, "type": "VOUCHER_INVALID" } .. _bill-errors: 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. ================================= =========== ==========================================================================