Skip to content

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.

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)

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.

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
]
}

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.

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.

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.

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.

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)

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.

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.

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.

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