Prerequisites
You should have
- an user-account enabled for api access & cart access
- an api-client
- at least one product-record stored in the Hublify PIM
Short facts
The cart stores all relevant data during a customer's shopping session.
The cart-API also handles the business logic related to this process up to the final purchase
This includes
- Products and their prices.
e.g. personalised prices, price scales, availability checks, restrictions for buyable quantities and delivery countries - Handles additional items like
- vouchers (coupons)
- shipping-costs
- payment-costs
- Delivery and billing addresses for the purchase
- Additional customer information to be saved on purchase
- Shipping and Payment selections
incl. additional costs and restrictions based on e.g. countries, weight or total price - Creating an order on purchase for an existing or newly created customer
Creating a new cart
You can already create a new cart-record in advance without the need for any additional data.
Otherwise a cart-record will automatically be created when you add data without providing a cart-id
Important: Remember the cart-id you receive with the first cart-request for a customer,
as you will need it for all follow up calls with this specific cart.
Request
Request URL
https://{your hublify url}/api/eos_10/cart_createRequest parameter
No parameter needed.
Response
If your request was successful, you receive the current status and the hublify ids for this cart.
{
"status": true,
"data": {
"primary_key": "cart_id", // Hublify's primary key for the cart-record
"primary_value": "123", // Hublify ID for this cart-record. Remember this for all follow-up requests
}
}Get the current cart data
Use the previously received cart-id as a filter the retrieve the cart-data
Request
Request URL
https://{your hublify url}/api/eos_10/cart_getRequest parameter
{
"filter": {
"cart_id": 123
},
"fields": [
"cart_id",
"cart_data",
"cart_items"
]
}Minimal Response
If your request was successful, you receive at least the Hublify ID and currency settings for this cart.
{
"status": true,
"data": {
"cart_id": "123", // Hublify ID for this cart-record.
"cart_data": { // any not-item related data (addresses etc. will be saved within cart-data)
"currency": "EUR", // Shop currency
"cart_item_key": 0 // Next (numerical) key in cart-items
},
"cart_items": null,
}
}Standard Response
Once you added additional data to your cart, you will receive details about all the added data.
The data will also be enriched with some additional details for your convenience.
{
"status": true,
"data": {
"cart_id": "123", // Hublify ID for this cart-record.
"cart_data": {
"currency": "EUR", // Shop currency
"cart_item_key": 1, // ID that will be used for the next cart-item
"order": {
"invoice_country": "DE", // ISO-Code for the country of billing address
"deliver_country": "DE", // ISO-Code for the country this should be delivered to
"fk_o_st_id": "1" // Hublify Internal ID for the shippingtype
},
"payment": {
"pys_id": "1" // Hublify Internal ID for the payment-mehod
},
"currency_dsp": "\u20ac" // Display version of the shop-currency (here: €)
},
"cart_items": [
{
"quantity": 1,
"pcode": "PC0001",
"vat_pct": 19,
"xdata": {
"price_scale": null,
"price_data_original": {
"price_single_brutto": 14.56,
"vat_pct": "19.00"
},
"currency_convert_rates": {
"EUR": "1.0000"
}
},
"type": "product", // Type: "product|shipping|payment|coupon|"
"block": 1,
"price_single_brutto": 14.56,
"name": "Example Product 1"
}
],
"cart_total_quantity": 1,
"cart_total_netto": 12.24,
"cart_total_brutto": 14.56,
"cart_prds_quantity": 1,
"cart_prds_netto": 12.24,
"cart_prds_brutto": 14.56,
"summary": {
"prds_pure_virtual": false,
"weight_total": 0,
"vats": {
"19": {
"total_netto": 12.24,
"total_brutto": 14.56,
"total_vat": 2.32,
"items_netto": 12.24,
"items_brutto": 14.56,
"items_vat": 2.32
}
},
"blocks": {
"1": {
"total_netto": 12.24,
"total_brutto": 14.56,
"total_vat": 2.32,
"items_netto": 12.24,
"items_brutto": 14.56,
"items_vat": 2.32
}
},
"items": {
"PC0001": {
"quantity": 1,
"occurrences": 1,
"total_netto": 12.24,
"total_brutto": 14.56,
"total_vat": 2.32
}
},
"type": {
"product": {
"quantity": 1,
"occurrences": 1,
"total_netto": 12.24,
"total_brutto": 14.56,
"total_vat": 2.32
}
},
"order_min_limit_OK": true
},
"checkout": {
"purchase": true,
"msg": null
}
}
}Evaluate the cart
You can evaluate the current cart-data and automatically adjust the selected order-options based on the current cart-content.
This will
- recheck all products for availability and other restrictions set in the PIM. e.g.
- If a product is out of stock and not bookable in advance, it will be removed
- If a product has less than the requested amount in stock, the quantity will be adjusted
- If the min/max-quantity is not met, the quantity will be adjusted
- If the current combination triggers a different price (e.g. different price-scale-level) the price will be adjusted
- adjust shipping costs based on the cart-data (e.g. weight or price limits, country and shipping type settings)
- adjust the selected order-options if the current combination is not available
- select a different shipping type if the previous selection is no longer valid
- select a different payment method if the previous selection is no longer valid
Attention: You should do this at least once before finalizing the purchase so you can inform the customer about any possible adjustments!
Tipp: You can also directly trigger this as part of the other calls, so your cart always reflects all needed adjustments
Request
Request URL
https://{your hublify url}/api/eos_10/cart_evaluateRequest parameter
{
"filter": {
"cart_id": 123
}
}Response
{
"status": true,
"meta": {
"items": {
"PC0001": {
"quantity": 1,
"quantity_final": 1
}
}
},
"data": {
"cart_id": "123", // Hublify ID for this cart-record.
"cart_data": {
"currency": "EUR",
"cart_item_key": 3, // ID that will be used for the next cart-item
"order": {
"invoice_country": "DE", // ISO-Code for the country of billing address
"deliver_country": "DE", // ISO-Code for the country this should be delivered to
"fk_o_st_id": "1" // Hublify Internal ID for the shippingtype
},
"payment": {
"pys_id": "1" // Hublify Internal ID for the payment-mehod
},
"currency_dsp": "\u20ac" // Display version of the shop-currency (here: €)
},
"cart_items": { // List of cart-items
"1": { // Item-ID within the cart. These are needed to update/remove products
"quantity": 1,
"pcode": "PC0001",
"vat_pct": 19,
"xdata": {
"price_scale": null,
"price_data_original": {
"price_single_brutto": 14.56,
"vat_pct": "19.00"
}
},
"type": "product",
"block": 1,
"price_single_brutto": 14.56,
"name": "Example Product 1"
},
"2": {
"pcode": "SHPSTD",
"quantity": 1,
"type": "shipping",
"name": "Standardversand",
"vat_pct": 19,
"price_single_brutto": 3,
"system_item": 1,
"block": "5",
"price_data_original": {
"price_single_brutto": 3,
"vat_pct": 19
}
}
},
"cart_prds_quantity": 1,
"cart_prds_netto": 12.24,
"cart_prds_brutto": 14.56,
"cart_total_quantity": 2,
"cart_total_netto": 14.76,
"cart_total_brutto": 17.56,
"cart_lock": "0",
"cart_prds_lock": "0",
"cart_time_insert": "2021-06-14 16:30:22",
"cart_time_update": "2021-06-14 19:58:15",
"cart_time_out": null,
"cart_time_save": null,
"fk_cart_persid": "0",
"cart_type": "open",
"cart_name": "",
"summary": {
"prds_pure_virtual": false,
"weight_total": 0,
"vats": {
"19": {
"total_netto": 14.76,
"total_brutto": 17.56,
"total_vat": 2.8,
"items_netto": 12.24,
"items_brutto": 14.56,
"items_vat": 2.32
}
},
"blocks": {
"1": {
"total_netto": 12.24,
"total_brutto": 14.56,
"total_vat": 2.32,
"items_netto": 12.24,
"items_brutto": 14.56,
"items_vat": 2.32
},
"5": {
"total_netto": 2.52,
"total_brutto": 3,
"total_vat": 0.48
}
},
"items": {
"PC0001": {
"quantity": 1,
"occurrences": 1,
"total_netto": 12.24,
"total_brutto": 14.56,
"total_vat": 2.32
},
"SHPSTD": {
"quantity": 1,
"occurrences": 1,
"total_netto": 2.52,
"total_brutto": 3,
"total_vat": 0.48
}
},
"type": {
"product": {
"quantity": 1,
"occurrences": 1,
"total_netto": 12.24,
"total_brutto": 14.56,
"total_vat": 2.32
},
"shipping": {
"quantity": 1,
"occurrences": 1,
"total_netto": 2.52,
"total_brutto": 3,
"total_vat": 0.48
}
},
"order_min_limit_OK": true
},
"checkout": {
"purchase": true,
"msg": null
}
}
}Messages & Meta
As part of the result you sometimes get additional messages, that can be used to inform the customer about changes or things he needs to check on. You receive a type ("INFO", "WARNING", "ERROR") and the message itself in form of a translatable string. If available, you could also receive additional params that can be used in your translation to give the customer a more specific message. For adjusted product-quantities you also get additional meta-information to show the difference.
Examples
The previously selected shippingtype does not match the cart-content and was adjusted on evaluation.
{
"msg": [
{
"type": "WARNING",
"i18n": {
"string": "ecs.CART.shippingtype_adjusted",
"params": null
}
}
]
}
The previously selected payment method does not match the cart-content and was adjusted on evaluation.
{
"msg": [
{
"type": "WARNING",
"i18n": {
"string": "ecs.CART.paymode_adjusted",
"params": null
}
}
]
}The requested quantity for a product is not available and was adjusted
{
"meta": {
"items": {
"HFYDEMO": {
"quantity": 5, // the quantity as it was supposed to be
"quantity_final": 4 // the actual quantity after adjustments
}
}
},
"msg": [
{
"type": "WARNING",
"i18n": {
"string": "ecs.CARTITEM.storage_counter_too_low",
"params": {
"pcode": "HFYDEMO",
"name": "Hublify Demo Product",
"quantity": 4
}
}
}
]
}The product is not available anymore
{
"meta": {
"items": {
"HFYDEMO": {
"quantity": 4, // the quantity as it was supposed to be
"quantity_final": 0 // the actual quantity after adjustments
}
}
},
"msg": [
{
"type": "WARNING",
"i18n": {
"string": "ecs.CARTITEM.storage_counter_empty",
"params": {
"pcode": "HFYDEMO",
"name": "Hublify Demo Product"
}
}
}
]
}