Cart API
The cart holds the products a visitor picks in the store, in the visitor’s browser session, until a signed-in client checks out and the order and its invoice are made. See Store and order form. The Cart module is not on the staff group Permissions tab, so its admin calls pass the module check only for Super Administrators.
Only Super Administrators can make admin calls of this module: it has no card on the staff group’s Permissions tab. See Authentication.
Admin calls
Section titled “Admin calls”get_list
Section titled “get_list”POST /api/admin/cart/get_list
Lists every shopping cart in the database (open carts of visitors and clients).
Permission: No permission of its own (Super Administrators, see above)
| Parameter | Type | Description |
|---|---|---|
page |
integer | Page number, from 1. Default 1. |
per_page |
integer | Rows per page, 1 to 500. Default 100. |
Returns: A paged list. Each row is a cart as in get. The list has no set order.
POST /api/admin/cart/get
Returns one shopping cart with its items and totals.
Permission: No permission of its own (Super Administrators, see above)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The cart id. |
Returns: promocode (the code applied, or null), auto_promo (an automatic promotion’s code, or null), promo_recurring, discount, subtotal, total, currency (as in the currency get), subscribable and items. Each item has id, product_id, form_id, title, type, quantity, unit, price, setup_price, discount, discount_price, discount_setup, total, recurring_price, recurring_discount, promo_line, addon_due, prorata_day and the item’s order options.
Errors:
- Shopping cart not found (code 9999)
batch_expire
Section titled “batch_expire”POST /api/admin/cart/batch_expire
Deletes the carts created more than 7 days ago, with their items, as cron does.
Permission: No permission of its own (Super Administrators, see above)
No parameters.
Returns: true.
Client calls
Section titled “Client calls”checkout (client)
Section titled “checkout (client)”POST /api/client/cart/checkout
Checks out the signed-in client’s session cart: the orders and their invoice are made and the cart is emptied.
| Parameter | Type | Description |
|---|---|---|
gateway_id |
integer | The payment method for the invoice; it must be offered for the cart’s currency. |
Returns: gateway_id, invoice_hash (the unpaid invoice to pay, or null when nothing is due), order_id (the main order) and orders (all order ids). A held order (a fraud or network check, or an ID document needed) also has held: true and id_document. A free order may have redirect: the page where the client sets up a saved payment method.
Errors:
- Cannot checkout an empty cart (code 9999)
- Selected currency EUR does not match your profile currency USD. Please change cart currency to continue. (code 9999)
- Payment method not found (code 813)
- You have already used this promo code. Please remove the promo code and checkout again. (code 9874)
- Promo code cannot be applied to your account (code 9999)
- Unable to complete order. One or more selected products are out of stock. (code 9999)
- The store is not available. (code 9999) when the store is closed to this client
- Rate limit exceeded. Please try again later. (code 429)
Limited to 15 calls an hour per IP address. Authorized users of the account need the Place new orders permission. Fires onBeforeClientCheckout and onAfterClientOrderCreate.
Example
Request parameters:
{ "gateway_id": 2}result:
{ "gateway_id": 2, "invoice_hash": "a1b2c3d4e5f60718293a4b5c6d7e8f90", "order_id": 15, "orders": [ 15, 16 ]}Guest calls
Section titled “Guest calls”get (guest)
Section titled “get (guest)”POST /api/guest/cart/get
Returns the visitor’s session cart (an empty one is made when there is none).
No parameters.
Returns: The cart, as in the admin get.
count (guest)
Section titled “count (guest)”POST /api/guest/cart/count
How many items are in the visitor’s session cart. It never makes a cart.
No parameters.
Returns: The number of items.
reset (guest)
Section titled “reset (guest)”POST /api/guest/cart/reset
Empties the visitor’s session cart and removes its promo code.
No parameters.
Returns: true.
Needs the browser session’s CSRF token (CSRFToken, or the X-CSRF-TOKEN header), a POST request and the portal’s own origin.
set_currency (guest)
Section titled “set_currency (guest)”POST /api/guest/cart/set_currency
Changes the currency of the visitor’s session cart.
| Parameter | Type | Description |
|---|---|---|
currency |
string, required | A currency code the portal has. |
Returns: true.
Errors:
- Currency not found (code 9999)
A signed-in client whose profile has a currency always orders in it: the cart switches back. Needs the browser session’s CSRF token, a POST request and the portal’s own origin.
get_currency (guest)
Section titled “get_currency (guest)”POST /api/guest/cart/get_currency
The currency of the visitor’s session cart, or the default currency.
No parameters.
Returns: The currency, as in the currency get.
Errors:
- No currency available (code 9999)
apply_promo (guest)
Section titled “apply_promo (guest)”POST /api/guest/cart/apply_promo
Applies a promo code to the visitor’s session cart.
| Parameter | Type | Description |
|---|---|---|
promocode |
string, required | The promo code. |
Returns: true.
Errors:
- The promo code has expired or does not exist (code 9999)
- Promo code cannot be applied to your account (code 9999)
- Add products to your cart before applying promo code (code 9999)
- The store is not available. (code 9999) when the store is closed to this visitor
- Rate limit exceeded. Please try again later. (code 429)
Limited to 10 calls an hour per IP address. Needs the browser session’s CSRF token, a POST request and the portal’s own origin.
remove_promo (guest)
Section titled “remove_promo (guest)”POST /api/guest/cart/remove_promo
Removes the promo code from the visitor’s session cart.
No parameters.
Returns: true.
Needs the browser session’s CSRF token, a POST request and the portal’s own origin.
remove_item (guest)
Section titled “remove_item (guest)”POST /api/guest/cart/remove_item
Removes an item from the visitor’s session cart, with the add-ons that came with it.
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The cart item id (items[].id of get). |
Returns: true.
Errors:
- Product not found (code 9999)
Needs the browser session’s CSRF token, a POST request and the portal’s own origin.
add_item (guest)
Section titled “add_item (guest)”POST /api/guest/cart/add_item
Adds a product to the visitor’s session cart. By default the cart is emptied first.
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | An active product id (not an add-on). |
period |
string | The billing period code, such as 1M or 1Y. Required for products with recurring prices. |
quantity |
integer | How many. Default 1. |
multiple |
boolean | Keep what is already in the cart. Default false: the cart is emptied first. |
addons |
array | Add-ons of this product to add with it. |
domain |
object | The domain registered or transferred with a hosting product. |
* |
mixed | Any other keys are the product’s order options: the fields its product type takes (such as a domain’s name for a domain product) and the answers to its order form. Unknown keys are dropped. |
Returns: true.
Errors:
- Product not found (code 9999)
- Addon products cannot be added separately. (code 9999)
- Period parameter not passed (code 9999)
- Selected billing period is invalid (code 9999)
- This domain is already in the cart. (code 9999)
- This item is currently out of stock (code 9999)
- The store is not available. (code 9999) when the store is closed to this visitor
Needs the browser session’s CSRF token, a POST request and the portal’s own origin. Fires onBeforeProductAddedToCart and onAfterProductAddedToCart.
Example
Request parameters:
{ "id": 3, "period": "1Y", "multiple": true}result:
true
