Akinon Release Notes (11/10/2025) are now live! Click here to learn what's new.
Docs Portal

Basket

Get Current Basket

get

This method retrieves the current basket for the active session, including all items, pricing, and applied discounts.

The endpoint automatically:

  • Removes unavailable products from the basket

  • Applies all eligible promotional offers

  • Calculates total amounts and discounts

  • Returns detailed item information with stock and pricing

Unavailable Product Handling:

  • Products that are inactive, deleted, or have insufficient stock are automatically removed

  • Removed products are listed in unavailable_basket_products field

  • Each unavailable product entry includes: pk, name, and unavailable_quantity

  • Basket cache is invalidated when products are removed

  • Promotional offers are recalculated without the removed items

Configuration Dependencies:

  • IS_MARKETPLACE: When enabled, includes datasource and extra pricing/stock details

  • Response structure adapts based on marketplace configuration

Use Cases:

  • Display shopping cart page

  • Load basket data for checkout process

  • Validate basket contents before order placement

  • Show current basket state in any view

  • Detect and notify users about removed products

Authorizations
Header parameters
X-CookiestringOptional

Use X-Cookie header instead of Cookie header in "try out" section. Use Cookie header while testing in postman or other tools. Some commerce applications may support 'sesionid' instead of 'osessionid'.

Example: osessionid=abc123
Responses
200

Successfully retrieved basket details

application/json
get
/basket/
200

Successfully retrieved basket details

Add Product to Basket

post

This method adds a product to the basket with the specified quantity.

The quantity is added to any existing quantity for the same product. For example, if the basket already contains 2 units of a product and you POST with quantity 3, the basket will then contain 5 units.

IMPORTANT: Attribute-Based Item Differentiation

  • Basket items with different attribute values are treated as separate basket items

  • Even if they are the same product (same product ID), different attributes create distinct basket items

  • Example: Product #789 with gift_note: "Happy Birthday" and Product #789 with gift_note: "Congratulations" will be 2 separate basket items

  • This applies to any custom attributes (gift notes, personalization, form data, etc.)

  • Each unique combination of product ID + attributes creates a new basket item

  • To update an existing item's quantity, you must match all its attributes exactly

Validation Rules:

  • Product must be active (is_active = true)

  • Product type cannot be product_meta or grouped (not purchasable)

  • Bundle products must have is_form_required = true

  • Required form fields must be provided in attributes

  • Sub-items must be in product's extra_product_sku attribute list (for miscellaneous/offer types)

  • Attributes size must not exceed BASKET_ITEM_ATTRIBUTES_MAX_LENGTH_KB limit

Service Conditions (Applied During Add):

  • basket_user_max_quantity: Enforces per-user quantity limits

    • Checks product's BASKET_PRODUCT_USER_MAX_QUANTITY_ATTRIBUTE

    • Includes orders from last 24 hours (configurable via BASKET_PRODUCT_USER_MAX_QUANTITY_GAP_HOUR)

    • Prevents single user from exceeding purchase limits

  • basket_item_max_count: Enforces total basket quantity limit

    • Total quantity across all items cannot exceed BASKET_MAX_ITEM_COUNT (default: 80)

  • bundle_type_compatibility_condition: Validates bundle compatibility

    • Checks product's bundle_type attribute against existing basket items

    • Prevents incompatible bundle types per BUNDLE_TYPE_CONFIGURATION

  • extra_product_quantity_condition: Validates quantity changes for items with sub-items

    • Prevents quantity modification of parent items that have sub-items (extra products) attached

    • User must remove sub-items before changing parent quantity

Configuration Dependencies:

  • IS_MARKETPLACE = true: Datasource field becomes required

  • BASKET_ITEM_ATTRIBUTES_MAX_LENGTH_KB: Controls max attributes size (default 10KB)

  • OFFER_MISCELLANEOUS_ATTRIBUTE_KEY: Validates miscellaneous sub-items

  • BASKET_SERVICE_CONDITIONS: List of condition functions to apply

  • BASKET_MAX_ITEM_COUNT: Total quantity limit (default: 80)

Namespace Behavior:

  • If namespace provided, stores it in user session

  • Switches active basket context to specified namespace

  • Creates new basket if namespace doesn't exist

  • Namespace validators applied per BASKET_NAMESPACE_VALIDATORS:

    • NullNamespaceValidator: Rejects None namespace (allows null for backwards compatibility)

    • ActiveBasketCountValidator: Limits active baskets per user (default: 5)

    • NamespaceDataSourceValidator: Validates namespace matches active datasource slug

    • DefaultNamespaceValidator: Prevents literal string "null" as namespace

  • Failed namespace validation returns 400 error with validation messages

After adding:

  • The system validates stock availability

  • Promotional offers are automatically applied

  • Complete basket state is returned with updated totals

Use Cases:

  • Add to cart functionality from product pages

  • Quick add from product listings

  • Add products with customization options

  • Bulk add operations with sub-items

Authorizations
csrftokenstringRequired

CSRF token for state-changing requests (POST/PUT/PATCH/DELETE)

Header parameters
X-CookiestringOptional

Use X-Cookie header instead of Cookie header in "try out" section. Use Cookie header while testing in postman or other tools. Some commerce applications may support 'sesionid' instead of 'osessionid'.

Example: osessionid=abc123
Body
productintegerRequired

Product ID to add to basket

Example: 789
quantitynumberRequired

Quantity to add (will be added to existing quantity)

Example: 2
attributesobjectOptional

Custom attributes for the basket item (gift notes, form data, etc.)

Example: {"gift_note":"Happy Birthday!"}
datasourceintegerOptional

Datasource/seller ID (required for marketplace)

Example: 10
namespacestringOptional

Basket namespace to use

Example: main
Responses
200

Product successfully added to basket

application/json
post
/basket/

Set Product Quantity in Basket

put

This method sets a specific quantity for a product in the basket.

Unlike POST (which adds to existing quantity), PUT replaces the entire quantity. For example, if the basket contains 5 units and you PUT with quantity 2, the basket will then contain exactly 2 units.

Special behavior:

  • Setting quantity to 0 removes the item from the basket

  • If the product doesn't exist in basket, it will be added

  • Existing attributes are preserved unless explicitly updated

Features:

  • Set exact quantity for products

  • Support for custom attributes and form data

  • Handle sub-items with the main product

  • Datasource/seller specification for marketplace

  • Namespace support for multiple baskets

Validation Rules:

  • Same validation as POST (product active, type restrictions, form requirements)

  • Product type cannot be product_meta or grouped

  • Bundle products require form data in attributes

  • Sub-items must match product's extra_product_sku configuration

  • Attributes size limit applies (BASKET_ITEM_ATTRIBUTES_MAX_LENGTH_KB)

Configuration Dependencies:

  • IS_MARKETPLACE = true: Datasource field becomes required

  • BASKET_ITEM_ATTRIBUTES_MAX_LENGTH_KB: Max attributes size validation

  • OFFER_MISCELLANEOUS_ATTRIBUTE_KEY: Sub-item validation key

Namespace Behavior:

  • Namespace parameter updates session basket context

  • Switches to specified namespace basket

  • Same namespace validation as POST (see POST endpoint for validator details)

After setting:

  • Stock validation is performed

  • Promotional offers are recalculated

  • Complete basket state is returned

Use Cases:

  • Update quantity from cart page input fields

  • Replace item quantities in bulk operations

  • Remove items by setting quantity to 0

  • Synchronize basket with external systems

Authorizations
csrftokenstringRequired

CSRF token for state-changing requests (POST/PUT/PATCH/DELETE)

Header parameters
X-CookiestringOptional

Use X-Cookie header instead of Cookie header in "try out" section. Use Cookie header while testing in postman or other tools. Some commerce applications may support 'sesionid' instead of 'osessionid'.

Example: osessionid=abc123
Body
productintegerRequired

Product ID to set in basket

Example: 789
quantitynumberRequired

Quantity to set (replaces existing quantity, 0 removes item)

Example: 3
attributesobjectOptional

Custom attributes for the basket item

datasourceintegerOptional

Datasource/seller ID (required for marketplace)

Example: 10
namespacestringOptional

Basket namespace to use

Example: main
Responses
200

Quantity successfully set

application/json
put
/basket/

Clear All Items from Basket

delete

This method removes all items from the basket, effectively clearing the entire cart.

Important:

  • The basket itself is NOT deleted, only its items

  • The basket remains active and can be used for new additions

  • All applied voucher codes are preserved

  • Promotional offers are recalculated (resulting in empty offers)

After clearing:

  • Basket will have zero items

  • Total amounts will be zero

  • Basket structure and metadata remain intact

  • Empty basket object is returned

Use Cases:

  • "Clear cart" functionality

  • Start fresh shopping session

  • Clean up abandoned baskets

  • Cancel current shopping process

  • Testing and development scenarios

Authorizations
csrftokenstringRequired

CSRF token for state-changing requests (POST/PUT/PATCH/DELETE)

Header parameters
X-CookiestringOptional

Use X-Cookie header instead of Cookie header in "try out" section. Use Cookie header while testing in postman or other tools. Some commerce applications may support 'sesionid' instead of 'osessionid'.

Example: osessionid=abc123
Responses
200

All items successfully removed from basket

application/json
delete
/basket/
200

All items successfully removed from basket

Apply or Remove Voucher Code

patch

This method applies a voucher/coupon code to the basket or removes an existing one.

The system supports three types of voucher codes:

  • Voucher codes: Single-use promotional codes

  • Coupon codes: Multi-use promotional codes

  • Bulk voucher codes: Pre-generated code pools

  • External offer codes: Codes from external promotional systems (no validation)

Features:

  • Apply voucher code with automatic validation

  • Remove currently applied voucher code

  • Support for external promotional codes

  • Automatic offer recalculation after code application

  • Detailed error messages for invalid or expired codes

Request Parameters:

  • voucher_code: Standard voucher/coupon code (validated)

  • external_offer_code: External code (not validated, stored directly)

  • remove_voucher_code = true: Removes current voucher (no validation)

Validation checks (for voucher_code only):

  • Code exists and is active

  • Code hasn't been used before (for single-use codes)

  • User meets eligibility requirements

  • Basket contents qualify for the offer

  • Code hasn't expired

  • Code usage limits not exceeded

External Offer Codes:

  • No validation performed (validate_voucher = false)

  • Code stored directly in basket

  • Useful for codes from external promotional systems

  • System attempts to apply matching offers if available

Rate Limiting:

  • PATCH method has rate limiting enabled (CustomScopedRateThrottle)

  • Scope: basket

  • Prevents brute-force code guessing attacks

After applying:

  • Promotional offers are recalculated

  • Discounts are applied if eligible

  • Updated basket with discounts is returned

  • Returns 400 if code invalid/expired

  • Returns 429 if rate limit exceeded

Use Cases:

  • Apply promotional codes during checkout

  • Remove incorrectly applied codes

  • Test promotional code validity

  • Apply partner or affiliate codes

  • Integrate with external promotional systems

Authorizations
csrftokenstringRequired

CSRF token for state-changing requests (POST/PUT/PATCH/DELETE)

Header parameters
X-CookiestringOptional

Use X-Cookie header instead of Cookie header in "try out" section. Use Cookie header while testing in postman or other tools. Some commerce applications may support 'sesionid' instead of 'osessionid'.

Example: osessionid=abc123
Body
voucher_codestringOptional

Voucher code to apply

Example: SAVE10
remove_voucher_codebooleanOptional

Set to true to remove current voucher code

Example: false
external_offer_codestringOptional

External offer code (alternative to voucher_code)

Example: EXT-PROMO-2023
Responses
200

Voucher code successfully applied or removed

application/json
patch
/basket/

Get Mini Basket Summary

get

This method retrieves a minimal summary of the current basket.

Returns only essential information needed for quick display scenarios such as cart indicators in headers, navigation menus, or mobile interfaces.

Features:

  • Lightweight response with minimal data

  • Fast response time for frequent polling

  • No promotional calculations performed

  • No item details included

Returned data:

  • Basket ID (pk)

  • Total quantity of items

Use Cases:

  • Shopping cart icon with item count in header

  • Quick basket status checks without full details

  • Mobile app navigation elements

  • Real-time basket quantity updates

  • Performance-critical scenarios where full basket data isn't needed

Authorizations
Header parameters
X-CookiestringOptional

Use X-Cookie header instead of Cookie header in "try out" section. Use Cookie header while testing in postman or other tools. Some commerce applications may support 'sesionid' instead of 'osessionid'.

Example: osessionid=abc123
Responses
200

Successfully retrieved mini basket summary

application/json
get
/basket/mini/
200

Successfully retrieved mini basket summary

Update Basket Item Attributes

patch

This method updates custom attributes for a specific basket item without changing the product or quantity.

Attributes are custom fields that can be attached to basket items, such as:

  • Gift notes or messages

  • Personalization data

  • Customization options

  • Special instructions

  • Custom form fields

Features:

  • Update specific basket item by ID

  • Merge new attributes with existing ones

  • Remove attributes by setting them to empty string

  • Option to apply same attributes to all items of the same product

  • Automatic gift note validation (removes empty or whitespace-only notes)

Validation Rules:

  • Basket item with specified ID must exist in current basket

  • Attributes field is required (cannot be null)

  • Attributes must not exceed BASKET_ITEM_ATTRIBUTES_MAX_LENGTH_KB limit

  • Gift notes with only whitespace are automatically removed

  • Product field must match the basket item's product

Behavior:

  • Attributes are merged, not replaced (existing attributes preserved)

  • To remove an attribute, set it to empty string: {"gift_note": ""}

  • Gift notes with only whitespace are automatically removed

  • Setting is_all: true applies attributes to all basket items with same product

  • Returns 400 if basket item not found in current basket

Configuration Dependencies:

  • BASKET_ITEM_ATTRIBUTES_MAX_LENGTH_KB: Maximum size limit (default 10KB)

  • Exceeding this limit returns validation error

After updating:

  • Promotional offers are recalculated

  • Complete basket state is returned

  • Updated attributes are immediately visible

  • Changes apply to specified item(s) only

Use Cases:

  • Add/update gift messages from cart page

  • Update personalization options

  • Modify custom form field values

  • Add special delivery instructions

  • Bulk update attributes for multiple items of same product

Authorizations
csrftokenstringRequired

CSRF token for state-changing requests (POST/PUT/PATCH/DELETE)

Header parameters
X-CookiestringOptional

Use X-Cookie header instead of Cookie header in "try out" section. Use Cookie header while testing in postman or other tools. Some commerce applications may support 'sesionid' instead of 'osessionid'.

Example: osessionid=abc123
Body
idintegerRequired

Basket item ID to update

Example: 456
attributesobjectRequired

Attributes to update (merged with existing attributes)

Example: {"gift_note":"Updated message"}
is_allbooleanOptional

Apply to all items with same product (default false)

Example: false
Responses
200

Attributes successfully updated

application/json
patch
/basket_items/
PreviousBasket Validators (Checkout Validation)NextMulti Basket

Last updated

Was this helpful?