# Basket

## Get Current Basket

> 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

```json
{"openapi":"3.0.3","info":{"title":"Basket API","version":"1.0.0"},"servers":[{"description":"Server base URL for basket operations","url":"https://{commerce_url}/baskets","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL"}}}],"security":[{"commerceSessionAuth":[]}],"components":{"securitySchemes":{},"parameters":{"CookieHeader":{"name":"X-Cookie","in":"header","description":"Use X-Cookie header instead of Cookie header in \"try out\" section.\nUse Cookie header while testing in postman or other tools.\nSome commerce applications may support 'sesionid' instead of 'osessionid'.","required":false,"schema":{"type":"string"}}},"schemas":{"BasketResponse":{"type":"object","properties":{"basket":{"$ref":"#/components/schemas/Basket"}}},"Basket":{"type":"object","properties":{"pk":{"type":"integer","description":"Basket unique identifier"},"namespace":{"type":"string","nullable":true,"description":"Basket namespace for logical separation"},"basketitem_set":{"type":"array","items":{"$ref":"#/components/schemas/BasketItem"},"description":"List of basket items"},"total_quantity":{"type":"integer","description":"Total quantity of all items in basket"},"total_amount":{"type":"string","description":"Total amount after all discounts"},"total_discount_amount":{"type":"string","description":"Total discount amount applied to basket"},"total_product_amount":{"type":"string","description":"Total product amount before discounts"},"discounts":{"type":"array","items":{"$ref":"#/components/schemas/Discount"},"description":"List of applied discounts"},"upsell_details":{"type":"array","items":{"$ref":"#/components/schemas/UpsellDetail"},"description":"Upsell messages for offers that almost qualified"},"voucher_code":{"type":"string","nullable":true,"description":"Applied voucher code"},"created_date":{"type":"string","format":"date-time","description":"Basket creation timestamp"},"modified_date":{"type":"string","format":"date-time","description":"Last modification timestamp"},"segment":{"$ref":"#/components/schemas/Segment"},"unavailable_basket_products":{"type":"array","items":{"$ref":"#/components/schemas/UnavailableProduct"},"description":"Products that were removed due to unavailability"}}},"BasketItem":{"type":"object","properties":{"id":{"type":"integer","description":"Basket item unique identifier"},"product":{"$ref":"#/components/schemas/ProductDetail"},"quantity":{"type":"number","multipleOf":0.01,"description":"Quantity of the product"},"unit_price":{"type":"string","description":"Unit price of the product (before discounts)"},"price":{"type":"string","description":"Current unit price (same as unit_price)"},"retail_price":{"type":"string","description":"Retail price of the product"},"discounted_price":{"type":"string","description":"Unit price after discounts"},"tax_rate":{"type":"string","description":"Tax rate applied (as decimal)"},"currency_type":{"$ref":"#/components/schemas/CurrencyTypeEnum"},"total_amount":{"type":"string","description":"Total amount for this item (quantity × discounted_price)"},"discount_amount":{"type":"string","description":"Total discount amount for this item"},"stock":{"type":"integer","description":"Available stock for this product"},"attributes":{"type":"object","description":"Custom attributes for the basket item (gift notes, etc.)","nullable":true},"attributes_kwargs":{"type":"object","description":"Formatted attributes for display","nullable":true},"shipping_discount":{"$ref":"#/components/schemas/ShippingDiscount"},"offer_badges":{"type":"array","items":{"$ref":"#/components/schemas/Discount"},"description":"List of offer badges applied to this item"},"image":{"type":"string","nullable":true,"description":"Primary image for the item"},"parent":{"type":"integer","nullable":true,"description":"Parent basket item ID (for sub-items)"},"datasource":{"$ref":"#/components/schemas/DataSource"},"extra_product_stock_detailed":{"type":"object","nullable":true,"description":"Extra product stock details (marketplace)"},"extra_product_price_detailed":{"type":"object","nullable":true,"description":"Extra product price details (marketplace)"}}},"ProductDetail":{"type":"object","properties":{"pk":{"type":"integer","description":"Product unique identifier"},"sku":{"type":"string","description":"Stock Keeping Unit"},"name":{"type":"string","description":"Product name"},"base_code":{"type":"string","description":"Product base code"},"product_type":{"$ref":"#/components/schemas/ProductTypeEnum"},"productimage_set":{"type":"array","items":{"type":"object","properties":{"image":{"type":"string","description":"Product image URL"}}},"description":"Product images"},"attributes":{"type":"object","description":"Product attributes and metadata"},"is_active":{"type":"boolean","description":"Product active status"},"attribute_set":{"type":"integer","nullable":true,"description":"Attribute set ID"}}},"ProductTypeEnum":{"type":"string","description":"Type of product that determines its behavior and structure.\n\nProduct type definitions:\n* `simple` (0) - Standard standalone product with single SKU\n* `bundle` (2) - Bundle product requiring form completion with chapters and attributes\n* `grouped` (3) - Grouped product that contains multiple related products\n* `product_meta` (1) - Meta product used for organizational purposes (not purchasable)\n* `miscellaneous` (4) - Special miscellaneous product (e.g., gift wrap, services)\n* `offer` (5) - Special offer product that may contain promotional items\n* `pre_product` (-1) - Pre-release or pre-order product\n* `pre_miscellaneous` (-2) - Pre-release miscellaneous product\n\n**Important notes:**\n* `product_meta` and `grouped` types cannot be added to basket directly\n* `bundle` type requires form completion with chapter data\n* `miscellaneous` and `offer` types are typically used as sub-items","enum":["-1","0","1","2","3","-2","4","5"]},"CurrencyTypeEnum":{"type":"string","description":"Currency type using ISO 4217 currency codes.\n\nSupported currencies:\n* `try` - Turkish Lira (TRY)\n* `eur` - Euro (EUR)\n* `usd` - US Dollar (USD)\n* `gbp` - British Pound Sterling (GBP)\n* `egp` - Egyptian Pound (EGP)\n* `mad` - Moroccan Dirham (MAD)\n* `pln` - Polish Zloty (PLN)\n* `sar` - Saudi Riyal (SAR)\n* `ron` - Romanian Leu (RON)\n* `uah` - Ukrainian Hryvnia (UAH)\n* `czk` - Czech Koruna (CZK)\n* `huf` - Hungarian Forint (HUF)\n* `rub` - Russian Ruble (RUB)\n* `bgn` - Bulgarian Lev (BGN)\n* `iqd` - Iraqi Dinar (IQD)\n* `kwd` - Kuwaiti Dinar (KWD)\n* `bhd` - Bahraini Dinar (BHD)\n* `omr` - Omani Rial (OMR)\n* `qar` - Qatari Riyal (QAR)\n* `aed` - UAE Dirham (AED)\n* `ngn` - Nigerian Naira (NGN)\n* `inr` - Indian Rupee (INR)\n* `lei` - Moldovan Leu (LEI)\n* `kzt` - Kazakhstani Tenge (KZT)\n* `jod` - Jordanian Dinar (JOD)\n* `rsd` - Serbian Dinar (RSD)","enum":["try","eur","usd","gbp","egp","mad","pln","sar","ron","uah","czk","huf","rub","bgn","iqd","kwd","bhd","omr","qar","aed","ngn","inr","lei","kzt","jod","rsd"]},"ShippingDiscount":{"type":"object","properties":{"description":{"type":"string","nullable":true,"description":"Shipping discount description"},"discount":{"type":"string","description":"Shipping discount amount"},"affects":{"$ref":"#/components/schemas/ApplicationResultTypeEnum"}}},"ApplicationResultTypeEnum":{"type":"string","description":"Type of discount application result that determines what the discount affects.\n\nApplication types:\n* `basket` - Discount applied to basket items (reduces product prices)\n* `shipping` - Discount applied to shipping costs (free or reduced shipping)\n* `post_order` - Discount applied after order completion (cashback, loyalty points)\n* `sample_product` - Free sample product added to basket as promotional item\n\n**Usage in responses:**\n* Basket discounts reduce the total_amount\n* Shipping discounts appear in shipping_discount field on items\n* Sample products appear as separate basket items with special pricing\n* Post-order benefits are tracked separately for future application","enum":["basket","shipping","post_order","sample_product"]},"Discount":{"type":"object","properties":{"description":{"type":"string","description":"Description of the discount"},"discount":{"type":"string","description":"Discount amount"},"affects":{"$ref":"#/components/schemas/ApplicationResultTypeEnum"}}},"DataSource":{"type":"object","properties":{"pk":{"type":"integer","description":"Datasource unique identifier"},"name":{"type":"string","description":"Datasource/seller name"},"erp_code":{"type":"string","nullable":true,"description":"ERP code for the datasource"}}},"UpsellDetail":{"type":"object","properties":{"message":{"type":"string","description":"Upsell message for failed offer"},"params":{"type":"object","description":"Parameters for the upsell message"}}},"Segment":{"type":"object","properties":{"pk":{"type":"integer","nullable":true,"description":"Segment primary key"},"price_list":{"type":"integer","nullable":true,"description":"Price list ID for the segment"},"stock_list":{"type":"integer","nullable":true,"description":"Stock list ID for the segment"}}},"UnavailableProduct":{"type":"object","properties":{"pk":{"type":"integer","description":"Product ID"},"name":{"type":"string","description":"Product name"},"unavailable_quantity":{"type":"number","description":"Quantity that was removed due to unavailability"}}}}},"paths":{"/basket/":{"get":{"summary":"Get Current Basket","description":"This method retrieves the current basket for the active session, including all items, pricing, and applied discounts.\n\nThe endpoint automatically:\n* Removes unavailable products from the basket\n* Applies all eligible promotional offers\n* Calculates total amounts and discounts\n* Returns detailed item information with stock and pricing\n\n**Unavailable Product Handling:**\n* Products that are inactive, deleted, or have insufficient stock are automatically removed\n* Removed products are listed in `unavailable_basket_products` field\n* Each unavailable product entry includes: pk, name, and unavailable_quantity\n* Basket cache is invalidated when products are removed\n* Promotional offers are recalculated without the removed items\n\n**Configuration Dependencies:**\n* `IS_MARKETPLACE`: When enabled, includes datasource and extra pricing/stock details\n* Response structure adapts based on marketplace configuration\n\n**Use Cases:**\n* Display shopping cart page\n* Load basket data for checkout process\n* Validate basket contents before order placement\n* Show current basket state in any view\n* Detect and notify users about removed products","operationId":"get_basket","parameters":[{"$ref":"#/components/parameters/CookieHeader"}],"responses":{"200":{"description":"Successfully retrieved basket details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BasketResponse"}}}}},"tags":["basket"]}}}}
```

## Add Product to Basket

> 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

```json
{"openapi":"3.0.3","info":{"title":"Basket API","version":"1.0.0"},"servers":[{"description":"Server base URL for basket operations","url":"https://{commerce_url}/baskets","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL"}}}],"security":[{"commerceSessionAuth":[],"csrfCookie":[]}],"components":{"securitySchemes":{},"parameters":{"CookieHeader":{"name":"X-Cookie","in":"header","description":"Use X-Cookie header instead of Cookie header in \"try out\" section.\nUse Cookie header while testing in postman or other tools.\nSome commerce applications may support 'sesionid' instead of 'osessionid'.","required":false,"schema":{"type":"string"}}},"schemas":{"AddProductRequest":{"type":"object","required":["product","quantity"],"properties":{"product":{"type":"integer","description":"Product ID to add to basket"},"quantity":{"type":"number","multipleOf":0.01,"minimum":0,"description":"Quantity to add (will be added to existing quantity)"},"attributes":{"type":"object","description":"Custom attributes for the basket item (gift notes, form data, etc.)"},"datasource":{"type":"integer","description":"Datasource/seller ID (required for marketplace)"},"sub_items":{"type":"array","items":{"$ref":"#/components/schemas/AddProductRequest"},"description":"Sub-items to add with the main product (extra products)"},"namespace":{"type":"string","description":"Basket namespace to use"}}},"BasketResponse":{"type":"object","properties":{"basket":{"$ref":"#/components/schemas/Basket"}}},"Basket":{"type":"object","properties":{"pk":{"type":"integer","description":"Basket unique identifier"},"namespace":{"type":"string","nullable":true,"description":"Basket namespace for logical separation"},"basketitem_set":{"type":"array","items":{"$ref":"#/components/schemas/BasketItem"},"description":"List of basket items"},"total_quantity":{"type":"integer","description":"Total quantity of all items in basket"},"total_amount":{"type":"string","description":"Total amount after all discounts"},"total_discount_amount":{"type":"string","description":"Total discount amount applied to basket"},"total_product_amount":{"type":"string","description":"Total product amount before discounts"},"discounts":{"type":"array","items":{"$ref":"#/components/schemas/Discount"},"description":"List of applied discounts"},"upsell_details":{"type":"array","items":{"$ref":"#/components/schemas/UpsellDetail"},"description":"Upsell messages for offers that almost qualified"},"voucher_code":{"type":"string","nullable":true,"description":"Applied voucher code"},"created_date":{"type":"string","format":"date-time","description":"Basket creation timestamp"},"modified_date":{"type":"string","format":"date-time","description":"Last modification timestamp"},"segment":{"$ref":"#/components/schemas/Segment"},"unavailable_basket_products":{"type":"array","items":{"$ref":"#/components/schemas/UnavailableProduct"},"description":"Products that were removed due to unavailability"}}},"BasketItem":{"type":"object","properties":{"id":{"type":"integer","description":"Basket item unique identifier"},"product":{"$ref":"#/components/schemas/ProductDetail"},"quantity":{"type":"number","multipleOf":0.01,"description":"Quantity of the product"},"unit_price":{"type":"string","description":"Unit price of the product (before discounts)"},"price":{"type":"string","description":"Current unit price (same as unit_price)"},"retail_price":{"type":"string","description":"Retail price of the product"},"discounted_price":{"type":"string","description":"Unit price after discounts"},"tax_rate":{"type":"string","description":"Tax rate applied (as decimal)"},"currency_type":{"$ref":"#/components/schemas/CurrencyTypeEnum"},"total_amount":{"type":"string","description":"Total amount for this item (quantity × discounted_price)"},"discount_amount":{"type":"string","description":"Total discount amount for this item"},"stock":{"type":"integer","description":"Available stock for this product"},"attributes":{"type":"object","description":"Custom attributes for the basket item (gift notes, etc.)","nullable":true},"attributes_kwargs":{"type":"object","description":"Formatted attributes for display","nullable":true},"shipping_discount":{"$ref":"#/components/schemas/ShippingDiscount"},"offer_badges":{"type":"array","items":{"$ref":"#/components/schemas/Discount"},"description":"List of offer badges applied to this item"},"image":{"type":"string","nullable":true,"description":"Primary image for the item"},"parent":{"type":"integer","nullable":true,"description":"Parent basket item ID (for sub-items)"},"datasource":{"$ref":"#/components/schemas/DataSource"},"extra_product_stock_detailed":{"type":"object","nullable":true,"description":"Extra product stock details (marketplace)"},"extra_product_price_detailed":{"type":"object","nullable":true,"description":"Extra product price details (marketplace)"}}},"ProductDetail":{"type":"object","properties":{"pk":{"type":"integer","description":"Product unique identifier"},"sku":{"type":"string","description":"Stock Keeping Unit"},"name":{"type":"string","description":"Product name"},"base_code":{"type":"string","description":"Product base code"},"product_type":{"$ref":"#/components/schemas/ProductTypeEnum"},"productimage_set":{"type":"array","items":{"type":"object","properties":{"image":{"type":"string","description":"Product image URL"}}},"description":"Product images"},"attributes":{"type":"object","description":"Product attributes and metadata"},"is_active":{"type":"boolean","description":"Product active status"},"attribute_set":{"type":"integer","nullable":true,"description":"Attribute set ID"}}},"ProductTypeEnum":{"type":"string","description":"Type of product that determines its behavior and structure.\n\nProduct type definitions:\n* `simple` (0) - Standard standalone product with single SKU\n* `bundle` (2) - Bundle product requiring form completion with chapters and attributes\n* `grouped` (3) - Grouped product that contains multiple related products\n* `product_meta` (1) - Meta product used for organizational purposes (not purchasable)\n* `miscellaneous` (4) - Special miscellaneous product (e.g., gift wrap, services)\n* `offer` (5) - Special offer product that may contain promotional items\n* `pre_product` (-1) - Pre-release or pre-order product\n* `pre_miscellaneous` (-2) - Pre-release miscellaneous product\n\n**Important notes:**\n* `product_meta` and `grouped` types cannot be added to basket directly\n* `bundle` type requires form completion with chapter data\n* `miscellaneous` and `offer` types are typically used as sub-items","enum":["-1","0","1","2","3","-2","4","5"]},"CurrencyTypeEnum":{"type":"string","description":"Currency type using ISO 4217 currency codes.\n\nSupported currencies:\n* `try` - Turkish Lira (TRY)\n* `eur` - Euro (EUR)\n* `usd` - US Dollar (USD)\n* `gbp` - British Pound Sterling (GBP)\n* `egp` - Egyptian Pound (EGP)\n* `mad` - Moroccan Dirham (MAD)\n* `pln` - Polish Zloty (PLN)\n* `sar` - Saudi Riyal (SAR)\n* `ron` - Romanian Leu (RON)\n* `uah` - Ukrainian Hryvnia (UAH)\n* `czk` - Czech Koruna (CZK)\n* `huf` - Hungarian Forint (HUF)\n* `rub` - Russian Ruble (RUB)\n* `bgn` - Bulgarian Lev (BGN)\n* `iqd` - Iraqi Dinar (IQD)\n* `kwd` - Kuwaiti Dinar (KWD)\n* `bhd` - Bahraini Dinar (BHD)\n* `omr` - Omani Rial (OMR)\n* `qar` - Qatari Riyal (QAR)\n* `aed` - UAE Dirham (AED)\n* `ngn` - Nigerian Naira (NGN)\n* `inr` - Indian Rupee (INR)\n* `lei` - Moldovan Leu (LEI)\n* `kzt` - Kazakhstani Tenge (KZT)\n* `jod` - Jordanian Dinar (JOD)\n* `rsd` - Serbian Dinar (RSD)","enum":["try","eur","usd","gbp","egp","mad","pln","sar","ron","uah","czk","huf","rub","bgn","iqd","kwd","bhd","omr","qar","aed","ngn","inr","lei","kzt","jod","rsd"]},"ShippingDiscount":{"type":"object","properties":{"description":{"type":"string","nullable":true,"description":"Shipping discount description"},"discount":{"type":"string","description":"Shipping discount amount"},"affects":{"$ref":"#/components/schemas/ApplicationResultTypeEnum"}}},"ApplicationResultTypeEnum":{"type":"string","description":"Type of discount application result that determines what the discount affects.\n\nApplication types:\n* `basket` - Discount applied to basket items (reduces product prices)\n* `shipping` - Discount applied to shipping costs (free or reduced shipping)\n* `post_order` - Discount applied after order completion (cashback, loyalty points)\n* `sample_product` - Free sample product added to basket as promotional item\n\n**Usage in responses:**\n* Basket discounts reduce the total_amount\n* Shipping discounts appear in shipping_discount field on items\n* Sample products appear as separate basket items with special pricing\n* Post-order benefits are tracked separately for future application","enum":["basket","shipping","post_order","sample_product"]},"Discount":{"type":"object","properties":{"description":{"type":"string","description":"Description of the discount"},"discount":{"type":"string","description":"Discount amount"},"affects":{"$ref":"#/components/schemas/ApplicationResultTypeEnum"}}},"DataSource":{"type":"object","properties":{"pk":{"type":"integer","description":"Datasource unique identifier"},"name":{"type":"string","description":"Datasource/seller name"},"erp_code":{"type":"string","nullable":true,"description":"ERP code for the datasource"}}},"UpsellDetail":{"type":"object","properties":{"message":{"type":"string","description":"Upsell message for failed offer"},"params":{"type":"object","description":"Parameters for the upsell message"}}},"Segment":{"type":"object","properties":{"pk":{"type":"integer","nullable":true,"description":"Segment primary key"},"price_list":{"type":"integer","nullable":true,"description":"Price list ID for the segment"},"stock_list":{"type":"integer","nullable":true,"description":"Stock list ID for the segment"}}},"UnavailableProduct":{"type":"object","properties":{"pk":{"type":"integer","description":"Product ID"},"name":{"type":"string","description":"Product name"},"unavailable_quantity":{"type":"number","description":"Quantity that was removed due to unavailability"}}},"ErrorResponse":{"type":"object","properties":{"detail":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Field-specific validation errors"}}}}},"paths":{"/basket/":{"post":{"summary":"Add Product to Basket","parameters":[{"$ref":"#/components/parameters/CookieHeader"}],"description":"This method adds a product to the basket with the specified quantity.\n\nThe quantity is **added** to any existing quantity for the same product.\nFor example, if the basket already contains 2 units of a product and you POST\nwith quantity 3, the basket will then contain 5 units.\n\n**IMPORTANT: Attribute-Based Item Differentiation**\n* Basket items with **different attribute values** are treated as **separate basket items**\n* Even if they are the same product (same product ID), different attributes create distinct basket items\n* Example: Product #789 with `gift_note: \"Happy Birthday\"` and Product #789 with `gift_note: \"Congratulations\"` will be 2 separate basket items\n* This applies to any custom attributes (gift notes, personalization, form data, etc.)\n* Each unique combination of product ID + attributes creates a new basket item\n* To update an existing item's quantity, you must match all its attributes exactly\n\n**Validation Rules:**\n* Product must be active (`is_active = true`)\n* Product type cannot be `product_meta` or `grouped` (not purchasable)\n* Bundle products must have `is_form_required = true`\n* Required form fields must be provided in attributes\n* Sub-items must be in product's `extra_product_sku` attribute list (for miscellaneous/offer types)\n* Attributes size must not exceed `BASKET_ITEM_ATTRIBUTES_MAX_LENGTH_KB` limit\n\n**Service Conditions (Applied During Add):**\n* `basket_user_max_quantity`: Enforces per-user quantity limits\n  - Checks product's `BASKET_PRODUCT_USER_MAX_QUANTITY_ATTRIBUTE`\n  - Includes orders from last 24 hours (configurable via `BASKET_PRODUCT_USER_MAX_QUANTITY_GAP_HOUR`)\n  - Prevents single user from exceeding purchase limits\n* `basket_item_max_count`: Enforces total basket quantity limit\n  - Total quantity across all items cannot exceed `BASKET_MAX_ITEM_COUNT` (default: 80)\n* `bundle_type_compatibility_condition`: Validates bundle compatibility\n  - Checks product's `bundle_type` attribute against existing basket items\n  - Prevents incompatible bundle types per `BUNDLE_TYPE_CONFIGURATION`\n* `extra_product_quantity_condition`: Validates quantity changes for items with sub-items\n  - Prevents quantity modification of parent items that have sub-items (extra products) attached\n  - User must remove sub-items before changing parent quantity\n\n**Configuration Dependencies:**\n* `IS_MARKETPLACE = true`: Datasource field becomes **required**\n* `BASKET_ITEM_ATTRIBUTES_MAX_LENGTH_KB`: Controls max attributes size (default 10KB)\n* `OFFER_MISCELLANEOUS_ATTRIBUTE_KEY`: Validates miscellaneous sub-items\n* `BASKET_SERVICE_CONDITIONS`: List of condition functions to apply\n* `BASKET_MAX_ITEM_COUNT`: Total quantity limit (default: 80)\n\n**Namespace Behavior:**\n* If namespace provided, stores it in user session\n* Switches active basket context to specified namespace\n* Creates new basket if namespace doesn't exist\n* Namespace validators applied per `BASKET_NAMESPACE_VALIDATORS`:\n  - `NullNamespaceValidator`: Rejects None namespace (allows null for backwards compatibility)\n  - `ActiveBasketCountValidator`: Limits active baskets per user (default: 5)\n  - `NamespaceDataSourceValidator`: Validates namespace matches active datasource slug\n  - `DefaultNamespaceValidator`: Prevents literal string \"null\" as namespace\n* Failed namespace validation returns 400 error with validation messages\n\n**After adding:**\n* The system validates stock availability\n* Promotional offers are automatically applied\n* Complete basket state is returned with updated totals\n\n**Use Cases:**\n* Add to cart functionality from product pages\n* Quick add from product listings\n* Add products with customization options\n* Bulk add operations with sub-items","operationId":"add_product_to_basket","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddProductRequest"}}}},"responses":{"200":{"description":"Product successfully added to basket","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BasketResponse"}}}},"400":{"description":"Validation error (invalid product, insufficient stock, etc.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["basket"]}}}}
```

## Set Product Quantity in Basket

> 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

```json
{"openapi":"3.0.3","info":{"title":"Basket API","version":"1.0.0"},"servers":[{"description":"Server base URL for basket operations","url":"https://{commerce_url}/baskets","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL"}}}],"security":[{"commerceSessionAuth":[],"csrfCookie":[]}],"components":{"securitySchemes":{},"parameters":{"CookieHeader":{"name":"X-Cookie","in":"header","description":"Use X-Cookie header instead of Cookie header in \"try out\" section.\nUse Cookie header while testing in postman or other tools.\nSome commerce applications may support 'sesionid' instead of 'osessionid'.","required":false,"schema":{"type":"string"}}},"schemas":{"SetProductRequest":{"type":"object","required":["product","quantity"],"properties":{"product":{"type":"integer","description":"Product ID to set in basket"},"quantity":{"type":"number","multipleOf":0.01,"minimum":0,"description":"Quantity to set (replaces existing quantity, 0 removes item)"},"attributes":{"type":"object","description":"Custom attributes for the basket item"},"datasource":{"type":"integer","description":"Datasource/seller ID (required for marketplace)"},"sub_items":{"type":"array","items":{"$ref":"#/components/schemas/AddProductRequest"},"description":"Sub-items to set with the main product"},"namespace":{"type":"string","description":"Basket namespace to use"}}},"AddProductRequest":{"type":"object","required":["product","quantity"],"properties":{"product":{"type":"integer","description":"Product ID to add to basket"},"quantity":{"type":"number","multipleOf":0.01,"minimum":0,"description":"Quantity to add (will be added to existing quantity)"},"attributes":{"type":"object","description":"Custom attributes for the basket item (gift notes, form data, etc.)"},"datasource":{"type":"integer","description":"Datasource/seller ID (required for marketplace)"},"sub_items":{"type":"array","items":{"$ref":"#/components/schemas/AddProductRequest"},"description":"Sub-items to add with the main product (extra products)"},"namespace":{"type":"string","description":"Basket namespace to use"}}},"BasketResponse":{"type":"object","properties":{"basket":{"$ref":"#/components/schemas/Basket"}}},"Basket":{"type":"object","properties":{"pk":{"type":"integer","description":"Basket unique identifier"},"namespace":{"type":"string","nullable":true,"description":"Basket namespace for logical separation"},"basketitem_set":{"type":"array","items":{"$ref":"#/components/schemas/BasketItem"},"description":"List of basket items"},"total_quantity":{"type":"integer","description":"Total quantity of all items in basket"},"total_amount":{"type":"string","description":"Total amount after all discounts"},"total_discount_amount":{"type":"string","description":"Total discount amount applied to basket"},"total_product_amount":{"type":"string","description":"Total product amount before discounts"},"discounts":{"type":"array","items":{"$ref":"#/components/schemas/Discount"},"description":"List of applied discounts"},"upsell_details":{"type":"array","items":{"$ref":"#/components/schemas/UpsellDetail"},"description":"Upsell messages for offers that almost qualified"},"voucher_code":{"type":"string","nullable":true,"description":"Applied voucher code"},"created_date":{"type":"string","format":"date-time","description":"Basket creation timestamp"},"modified_date":{"type":"string","format":"date-time","description":"Last modification timestamp"},"segment":{"$ref":"#/components/schemas/Segment"},"unavailable_basket_products":{"type":"array","items":{"$ref":"#/components/schemas/UnavailableProduct"},"description":"Products that were removed due to unavailability"}}},"BasketItem":{"type":"object","properties":{"id":{"type":"integer","description":"Basket item unique identifier"},"product":{"$ref":"#/components/schemas/ProductDetail"},"quantity":{"type":"number","multipleOf":0.01,"description":"Quantity of the product"},"unit_price":{"type":"string","description":"Unit price of the product (before discounts)"},"price":{"type":"string","description":"Current unit price (same as unit_price)"},"retail_price":{"type":"string","description":"Retail price of the product"},"discounted_price":{"type":"string","description":"Unit price after discounts"},"tax_rate":{"type":"string","description":"Tax rate applied (as decimal)"},"currency_type":{"$ref":"#/components/schemas/CurrencyTypeEnum"},"total_amount":{"type":"string","description":"Total amount for this item (quantity × discounted_price)"},"discount_amount":{"type":"string","description":"Total discount amount for this item"},"stock":{"type":"integer","description":"Available stock for this product"},"attributes":{"type":"object","description":"Custom attributes for the basket item (gift notes, etc.)","nullable":true},"attributes_kwargs":{"type":"object","description":"Formatted attributes for display","nullable":true},"shipping_discount":{"$ref":"#/components/schemas/ShippingDiscount"},"offer_badges":{"type":"array","items":{"$ref":"#/components/schemas/Discount"},"description":"List of offer badges applied to this item"},"image":{"type":"string","nullable":true,"description":"Primary image for the item"},"parent":{"type":"integer","nullable":true,"description":"Parent basket item ID (for sub-items)"},"datasource":{"$ref":"#/components/schemas/DataSource"},"extra_product_stock_detailed":{"type":"object","nullable":true,"description":"Extra product stock details (marketplace)"},"extra_product_price_detailed":{"type":"object","nullable":true,"description":"Extra product price details (marketplace)"}}},"ProductDetail":{"type":"object","properties":{"pk":{"type":"integer","description":"Product unique identifier"},"sku":{"type":"string","description":"Stock Keeping Unit"},"name":{"type":"string","description":"Product name"},"base_code":{"type":"string","description":"Product base code"},"product_type":{"$ref":"#/components/schemas/ProductTypeEnum"},"productimage_set":{"type":"array","items":{"type":"object","properties":{"image":{"type":"string","description":"Product image URL"}}},"description":"Product images"},"attributes":{"type":"object","description":"Product attributes and metadata"},"is_active":{"type":"boolean","description":"Product active status"},"attribute_set":{"type":"integer","nullable":true,"description":"Attribute set ID"}}},"ProductTypeEnum":{"type":"string","description":"Type of product that determines its behavior and structure.\n\nProduct type definitions:\n* `simple` (0) - Standard standalone product with single SKU\n* `bundle` (2) - Bundle product requiring form completion with chapters and attributes\n* `grouped` (3) - Grouped product that contains multiple related products\n* `product_meta` (1) - Meta product used for organizational purposes (not purchasable)\n* `miscellaneous` (4) - Special miscellaneous product (e.g., gift wrap, services)\n* `offer` (5) - Special offer product that may contain promotional items\n* `pre_product` (-1) - Pre-release or pre-order product\n* `pre_miscellaneous` (-2) - Pre-release miscellaneous product\n\n**Important notes:**\n* `product_meta` and `grouped` types cannot be added to basket directly\n* `bundle` type requires form completion with chapter data\n* `miscellaneous` and `offer` types are typically used as sub-items","enum":["-1","0","1","2","3","-2","4","5"]},"CurrencyTypeEnum":{"type":"string","description":"Currency type using ISO 4217 currency codes.\n\nSupported currencies:\n* `try` - Turkish Lira (TRY)\n* `eur` - Euro (EUR)\n* `usd` - US Dollar (USD)\n* `gbp` - British Pound Sterling (GBP)\n* `egp` - Egyptian Pound (EGP)\n* `mad` - Moroccan Dirham (MAD)\n* `pln` - Polish Zloty (PLN)\n* `sar` - Saudi Riyal (SAR)\n* `ron` - Romanian Leu (RON)\n* `uah` - Ukrainian Hryvnia (UAH)\n* `czk` - Czech Koruna (CZK)\n* `huf` - Hungarian Forint (HUF)\n* `rub` - Russian Ruble (RUB)\n* `bgn` - Bulgarian Lev (BGN)\n* `iqd` - Iraqi Dinar (IQD)\n* `kwd` - Kuwaiti Dinar (KWD)\n* `bhd` - Bahraini Dinar (BHD)\n* `omr` - Omani Rial (OMR)\n* `qar` - Qatari Riyal (QAR)\n* `aed` - UAE Dirham (AED)\n* `ngn` - Nigerian Naira (NGN)\n* `inr` - Indian Rupee (INR)\n* `lei` - Moldovan Leu (LEI)\n* `kzt` - Kazakhstani Tenge (KZT)\n* `jod` - Jordanian Dinar (JOD)\n* `rsd` - Serbian Dinar (RSD)","enum":["try","eur","usd","gbp","egp","mad","pln","sar","ron","uah","czk","huf","rub","bgn","iqd","kwd","bhd","omr","qar","aed","ngn","inr","lei","kzt","jod","rsd"]},"ShippingDiscount":{"type":"object","properties":{"description":{"type":"string","nullable":true,"description":"Shipping discount description"},"discount":{"type":"string","description":"Shipping discount amount"},"affects":{"$ref":"#/components/schemas/ApplicationResultTypeEnum"}}},"ApplicationResultTypeEnum":{"type":"string","description":"Type of discount application result that determines what the discount affects.\n\nApplication types:\n* `basket` - Discount applied to basket items (reduces product prices)\n* `shipping` - Discount applied to shipping costs (free or reduced shipping)\n* `post_order` - Discount applied after order completion (cashback, loyalty points)\n* `sample_product` - Free sample product added to basket as promotional item\n\n**Usage in responses:**\n* Basket discounts reduce the total_amount\n* Shipping discounts appear in shipping_discount field on items\n* Sample products appear as separate basket items with special pricing\n* Post-order benefits are tracked separately for future application","enum":["basket","shipping","post_order","sample_product"]},"Discount":{"type":"object","properties":{"description":{"type":"string","description":"Description of the discount"},"discount":{"type":"string","description":"Discount amount"},"affects":{"$ref":"#/components/schemas/ApplicationResultTypeEnum"}}},"DataSource":{"type":"object","properties":{"pk":{"type":"integer","description":"Datasource unique identifier"},"name":{"type":"string","description":"Datasource/seller name"},"erp_code":{"type":"string","nullable":true,"description":"ERP code for the datasource"}}},"UpsellDetail":{"type":"object","properties":{"message":{"type":"string","description":"Upsell message for failed offer"},"params":{"type":"object","description":"Parameters for the upsell message"}}},"Segment":{"type":"object","properties":{"pk":{"type":"integer","nullable":true,"description":"Segment primary key"},"price_list":{"type":"integer","nullable":true,"description":"Price list ID for the segment"},"stock_list":{"type":"integer","nullable":true,"description":"Stock list ID for the segment"}}},"UnavailableProduct":{"type":"object","properties":{"pk":{"type":"integer","description":"Product ID"},"name":{"type":"string","description":"Product name"},"unavailable_quantity":{"type":"number","description":"Quantity that was removed due to unavailability"}}},"ErrorResponse":{"type":"object","properties":{"detail":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Field-specific validation errors"}}}}},"paths":{"/basket/":{"put":{"summary":"Set Product Quantity in Basket","parameters":[{"$ref":"#/components/parameters/CookieHeader"}],"description":"This method sets a specific quantity for a product in the basket.\n\nUnlike POST (which adds to existing quantity), PUT **replaces** the entire quantity.\nFor example, if the basket contains 5 units and you PUT with quantity 2,\nthe basket will then contain exactly 2 units.\n\n**Special behavior:**\n* Setting quantity to 0 removes the item from the basket\n* If the product doesn't exist in basket, it will be added\n* Existing attributes are preserved unless explicitly updated\n\n**Features:**\n* Set exact quantity for products\n* Support for custom attributes and form data\n* Handle sub-items with the main product\n* Datasource/seller specification for marketplace\n* Namespace support for multiple baskets\n\n**Validation Rules:**\n* Same validation as POST (product active, type restrictions, form requirements)\n* Product type cannot be `product_meta` or `grouped`\n* Bundle products require form data in attributes\n* Sub-items must match product's `extra_product_sku` configuration\n* Attributes size limit applies (`BASKET_ITEM_ATTRIBUTES_MAX_LENGTH_KB`)\n\n**Configuration Dependencies:**\n* `IS_MARKETPLACE = true`: Datasource field becomes **required**\n* `BASKET_ITEM_ATTRIBUTES_MAX_LENGTH_KB`: Max attributes size validation\n* `OFFER_MISCELLANEOUS_ATTRIBUTE_KEY`: Sub-item validation key\n\n**Namespace Behavior:**\n* Namespace parameter updates session basket context\n* Switches to specified namespace basket\n* Same namespace validation as POST (see POST endpoint for validator details)\n\n**After setting:**\n* Stock validation is performed\n* Promotional offers are recalculated\n* Complete basket state is returned\n\n**Use Cases:**\n* Update quantity from cart page input fields\n* Replace item quantities in bulk operations\n* Remove items by setting quantity to 0\n* Synchronize basket with external systems","operationId":"set_product_quantity","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetProductRequest"}}}},"responses":{"200":{"description":"Quantity successfully set","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BasketResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["basket"]}}}}
```

## Clear All Items from Basket

> 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

```json
{"openapi":"3.0.3","info":{"title":"Basket API","version":"1.0.0"},"servers":[{"description":"Server base URL for basket operations","url":"https://{commerce_url}/baskets","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL"}}}],"security":[{"commerceSessionAuth":[],"csrfCookie":[]}],"components":{"securitySchemes":{},"parameters":{"CookieHeader":{"name":"X-Cookie","in":"header","description":"Use X-Cookie header instead of Cookie header in \"try out\" section.\nUse Cookie header while testing in postman or other tools.\nSome commerce applications may support 'sesionid' instead of 'osessionid'.","required":false,"schema":{"type":"string"}}},"schemas":{"BasketResponse":{"type":"object","properties":{"basket":{"$ref":"#/components/schemas/Basket"}}},"Basket":{"type":"object","properties":{"pk":{"type":"integer","description":"Basket unique identifier"},"namespace":{"type":"string","nullable":true,"description":"Basket namespace for logical separation"},"basketitem_set":{"type":"array","items":{"$ref":"#/components/schemas/BasketItem"},"description":"List of basket items"},"total_quantity":{"type":"integer","description":"Total quantity of all items in basket"},"total_amount":{"type":"string","description":"Total amount after all discounts"},"total_discount_amount":{"type":"string","description":"Total discount amount applied to basket"},"total_product_amount":{"type":"string","description":"Total product amount before discounts"},"discounts":{"type":"array","items":{"$ref":"#/components/schemas/Discount"},"description":"List of applied discounts"},"upsell_details":{"type":"array","items":{"$ref":"#/components/schemas/UpsellDetail"},"description":"Upsell messages for offers that almost qualified"},"voucher_code":{"type":"string","nullable":true,"description":"Applied voucher code"},"created_date":{"type":"string","format":"date-time","description":"Basket creation timestamp"},"modified_date":{"type":"string","format":"date-time","description":"Last modification timestamp"},"segment":{"$ref":"#/components/schemas/Segment"},"unavailable_basket_products":{"type":"array","items":{"$ref":"#/components/schemas/UnavailableProduct"},"description":"Products that were removed due to unavailability"}}},"BasketItem":{"type":"object","properties":{"id":{"type":"integer","description":"Basket item unique identifier"},"product":{"$ref":"#/components/schemas/ProductDetail"},"quantity":{"type":"number","multipleOf":0.01,"description":"Quantity of the product"},"unit_price":{"type":"string","description":"Unit price of the product (before discounts)"},"price":{"type":"string","description":"Current unit price (same as unit_price)"},"retail_price":{"type":"string","description":"Retail price of the product"},"discounted_price":{"type":"string","description":"Unit price after discounts"},"tax_rate":{"type":"string","description":"Tax rate applied (as decimal)"},"currency_type":{"$ref":"#/components/schemas/CurrencyTypeEnum"},"total_amount":{"type":"string","description":"Total amount for this item (quantity × discounted_price)"},"discount_amount":{"type":"string","description":"Total discount amount for this item"},"stock":{"type":"integer","description":"Available stock for this product"},"attributes":{"type":"object","description":"Custom attributes for the basket item (gift notes, etc.)","nullable":true},"attributes_kwargs":{"type":"object","description":"Formatted attributes for display","nullable":true},"shipping_discount":{"$ref":"#/components/schemas/ShippingDiscount"},"offer_badges":{"type":"array","items":{"$ref":"#/components/schemas/Discount"},"description":"List of offer badges applied to this item"},"image":{"type":"string","nullable":true,"description":"Primary image for the item"},"parent":{"type":"integer","nullable":true,"description":"Parent basket item ID (for sub-items)"},"datasource":{"$ref":"#/components/schemas/DataSource"},"extra_product_stock_detailed":{"type":"object","nullable":true,"description":"Extra product stock details (marketplace)"},"extra_product_price_detailed":{"type":"object","nullable":true,"description":"Extra product price details (marketplace)"}}},"ProductDetail":{"type":"object","properties":{"pk":{"type":"integer","description":"Product unique identifier"},"sku":{"type":"string","description":"Stock Keeping Unit"},"name":{"type":"string","description":"Product name"},"base_code":{"type":"string","description":"Product base code"},"product_type":{"$ref":"#/components/schemas/ProductTypeEnum"},"productimage_set":{"type":"array","items":{"type":"object","properties":{"image":{"type":"string","description":"Product image URL"}}},"description":"Product images"},"attributes":{"type":"object","description":"Product attributes and metadata"},"is_active":{"type":"boolean","description":"Product active status"},"attribute_set":{"type":"integer","nullable":true,"description":"Attribute set ID"}}},"ProductTypeEnum":{"type":"string","description":"Type of product that determines its behavior and structure.\n\nProduct type definitions:\n* `simple` (0) - Standard standalone product with single SKU\n* `bundle` (2) - Bundle product requiring form completion with chapters and attributes\n* `grouped` (3) - Grouped product that contains multiple related products\n* `product_meta` (1) - Meta product used for organizational purposes (not purchasable)\n* `miscellaneous` (4) - Special miscellaneous product (e.g., gift wrap, services)\n* `offer` (5) - Special offer product that may contain promotional items\n* `pre_product` (-1) - Pre-release or pre-order product\n* `pre_miscellaneous` (-2) - Pre-release miscellaneous product\n\n**Important notes:**\n* `product_meta` and `grouped` types cannot be added to basket directly\n* `bundle` type requires form completion with chapter data\n* `miscellaneous` and `offer` types are typically used as sub-items","enum":["-1","0","1","2","3","-2","4","5"]},"CurrencyTypeEnum":{"type":"string","description":"Currency type using ISO 4217 currency codes.\n\nSupported currencies:\n* `try` - Turkish Lira (TRY)\n* `eur` - Euro (EUR)\n* `usd` - US Dollar (USD)\n* `gbp` - British Pound Sterling (GBP)\n* `egp` - Egyptian Pound (EGP)\n* `mad` - Moroccan Dirham (MAD)\n* `pln` - Polish Zloty (PLN)\n* `sar` - Saudi Riyal (SAR)\n* `ron` - Romanian Leu (RON)\n* `uah` - Ukrainian Hryvnia (UAH)\n* `czk` - Czech Koruna (CZK)\n* `huf` - Hungarian Forint (HUF)\n* `rub` - Russian Ruble (RUB)\n* `bgn` - Bulgarian Lev (BGN)\n* `iqd` - Iraqi Dinar (IQD)\n* `kwd` - Kuwaiti Dinar (KWD)\n* `bhd` - Bahraini Dinar (BHD)\n* `omr` - Omani Rial (OMR)\n* `qar` - Qatari Riyal (QAR)\n* `aed` - UAE Dirham (AED)\n* `ngn` - Nigerian Naira (NGN)\n* `inr` - Indian Rupee (INR)\n* `lei` - Moldovan Leu (LEI)\n* `kzt` - Kazakhstani Tenge (KZT)\n* `jod` - Jordanian Dinar (JOD)\n* `rsd` - Serbian Dinar (RSD)","enum":["try","eur","usd","gbp","egp","mad","pln","sar","ron","uah","czk","huf","rub","bgn","iqd","kwd","bhd","omr","qar","aed","ngn","inr","lei","kzt","jod","rsd"]},"ShippingDiscount":{"type":"object","properties":{"description":{"type":"string","nullable":true,"description":"Shipping discount description"},"discount":{"type":"string","description":"Shipping discount amount"},"affects":{"$ref":"#/components/schemas/ApplicationResultTypeEnum"}}},"ApplicationResultTypeEnum":{"type":"string","description":"Type of discount application result that determines what the discount affects.\n\nApplication types:\n* `basket` - Discount applied to basket items (reduces product prices)\n* `shipping` - Discount applied to shipping costs (free or reduced shipping)\n* `post_order` - Discount applied after order completion (cashback, loyalty points)\n* `sample_product` - Free sample product added to basket as promotional item\n\n**Usage in responses:**\n* Basket discounts reduce the total_amount\n* Shipping discounts appear in shipping_discount field on items\n* Sample products appear as separate basket items with special pricing\n* Post-order benefits are tracked separately for future application","enum":["basket","shipping","post_order","sample_product"]},"Discount":{"type":"object","properties":{"description":{"type":"string","description":"Description of the discount"},"discount":{"type":"string","description":"Discount amount"},"affects":{"$ref":"#/components/schemas/ApplicationResultTypeEnum"}}},"DataSource":{"type":"object","properties":{"pk":{"type":"integer","description":"Datasource unique identifier"},"name":{"type":"string","description":"Datasource/seller name"},"erp_code":{"type":"string","nullable":true,"description":"ERP code for the datasource"}}},"UpsellDetail":{"type":"object","properties":{"message":{"type":"string","description":"Upsell message for failed offer"},"params":{"type":"object","description":"Parameters for the upsell message"}}},"Segment":{"type":"object","properties":{"pk":{"type":"integer","nullable":true,"description":"Segment primary key"},"price_list":{"type":"integer","nullable":true,"description":"Price list ID for the segment"},"stock_list":{"type":"integer","nullable":true,"description":"Stock list ID for the segment"}}},"UnavailableProduct":{"type":"object","properties":{"pk":{"type":"integer","description":"Product ID"},"name":{"type":"string","description":"Product name"},"unavailable_quantity":{"type":"number","description":"Quantity that was removed due to unavailability"}}}}},"paths":{"/basket/":{"delete":{"summary":"Clear All Items from Basket","parameters":[{"$ref":"#/components/parameters/CookieHeader"}],"description":"This method removes all items from the basket, effectively clearing the entire cart.\n\n**Important:**\n* The basket itself is NOT deleted, only its items\n* The basket remains active and can be used for new additions\n* All applied voucher codes are preserved\n* Promotional offers are recalculated (resulting in empty offers)\n\n**After clearing:**\n* Basket will have zero items\n* Total amounts will be zero\n* Basket structure and metadata remain intact\n* Empty basket object is returned\n\n**Use Cases:**\n* \"Clear cart\" functionality\n* Start fresh shopping session\n* Clean up abandoned baskets\n* Cancel current shopping process\n* Testing and development scenarios","operationId":"clear_basket","responses":{"200":{"description":"All items successfully removed from basket","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BasketResponse"}}}}},"tags":["basket"]}}}}
```

## Apply or Remove Voucher Code

> 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

```json
{"openapi":"3.0.3","info":{"title":"Basket API","version":"1.0.0"},"servers":[{"description":"Server base URL for basket operations","url":"https://{commerce_url}/baskets","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL"}}}],"security":[{"commerceSessionAuth":[],"csrfCookie":[]}],"components":{"securitySchemes":{},"parameters":{"CookieHeader":{"name":"X-Cookie","in":"header","description":"Use X-Cookie header instead of Cookie header in \"try out\" section.\nUse Cookie header while testing in postman or other tools.\nSome commerce applications may support 'sesionid' instead of 'osessionid'.","required":false,"schema":{"type":"string"}}},"schemas":{"UpdateVoucherRequest":{"type":"object","properties":{"voucher_code":{"type":"string","description":"Voucher code to apply"},"remove_voucher_code":{"type":"boolean","description":"Set to true to remove current voucher code"},"external_offer_code":{"type":"string","description":"External offer code (alternative to voucher_code)"}}},"BasketResponse":{"type":"object","properties":{"basket":{"$ref":"#/components/schemas/Basket"}}},"Basket":{"type":"object","properties":{"pk":{"type":"integer","description":"Basket unique identifier"},"namespace":{"type":"string","nullable":true,"description":"Basket namespace for logical separation"},"basketitem_set":{"type":"array","items":{"$ref":"#/components/schemas/BasketItem"},"description":"List of basket items"},"total_quantity":{"type":"integer","description":"Total quantity of all items in basket"},"total_amount":{"type":"string","description":"Total amount after all discounts"},"total_discount_amount":{"type":"string","description":"Total discount amount applied to basket"},"total_product_amount":{"type":"string","description":"Total product amount before discounts"},"discounts":{"type":"array","items":{"$ref":"#/components/schemas/Discount"},"description":"List of applied discounts"},"upsell_details":{"type":"array","items":{"$ref":"#/components/schemas/UpsellDetail"},"description":"Upsell messages for offers that almost qualified"},"voucher_code":{"type":"string","nullable":true,"description":"Applied voucher code"},"created_date":{"type":"string","format":"date-time","description":"Basket creation timestamp"},"modified_date":{"type":"string","format":"date-time","description":"Last modification timestamp"},"segment":{"$ref":"#/components/schemas/Segment"},"unavailable_basket_products":{"type":"array","items":{"$ref":"#/components/schemas/UnavailableProduct"},"description":"Products that were removed due to unavailability"}}},"BasketItem":{"type":"object","properties":{"id":{"type":"integer","description":"Basket item unique identifier"},"product":{"$ref":"#/components/schemas/ProductDetail"},"quantity":{"type":"number","multipleOf":0.01,"description":"Quantity of the product"},"unit_price":{"type":"string","description":"Unit price of the product (before discounts)"},"price":{"type":"string","description":"Current unit price (same as unit_price)"},"retail_price":{"type":"string","description":"Retail price of the product"},"discounted_price":{"type":"string","description":"Unit price after discounts"},"tax_rate":{"type":"string","description":"Tax rate applied (as decimal)"},"currency_type":{"$ref":"#/components/schemas/CurrencyTypeEnum"},"total_amount":{"type":"string","description":"Total amount for this item (quantity × discounted_price)"},"discount_amount":{"type":"string","description":"Total discount amount for this item"},"stock":{"type":"integer","description":"Available stock for this product"},"attributes":{"type":"object","description":"Custom attributes for the basket item (gift notes, etc.)","nullable":true},"attributes_kwargs":{"type":"object","description":"Formatted attributes for display","nullable":true},"shipping_discount":{"$ref":"#/components/schemas/ShippingDiscount"},"offer_badges":{"type":"array","items":{"$ref":"#/components/schemas/Discount"},"description":"List of offer badges applied to this item"},"image":{"type":"string","nullable":true,"description":"Primary image for the item"},"parent":{"type":"integer","nullable":true,"description":"Parent basket item ID (for sub-items)"},"datasource":{"$ref":"#/components/schemas/DataSource"},"extra_product_stock_detailed":{"type":"object","nullable":true,"description":"Extra product stock details (marketplace)"},"extra_product_price_detailed":{"type":"object","nullable":true,"description":"Extra product price details (marketplace)"}}},"ProductDetail":{"type":"object","properties":{"pk":{"type":"integer","description":"Product unique identifier"},"sku":{"type":"string","description":"Stock Keeping Unit"},"name":{"type":"string","description":"Product name"},"base_code":{"type":"string","description":"Product base code"},"product_type":{"$ref":"#/components/schemas/ProductTypeEnum"},"productimage_set":{"type":"array","items":{"type":"object","properties":{"image":{"type":"string","description":"Product image URL"}}},"description":"Product images"},"attributes":{"type":"object","description":"Product attributes and metadata"},"is_active":{"type":"boolean","description":"Product active status"},"attribute_set":{"type":"integer","nullable":true,"description":"Attribute set ID"}}},"ProductTypeEnum":{"type":"string","description":"Type of product that determines its behavior and structure.\n\nProduct type definitions:\n* `simple` (0) - Standard standalone product with single SKU\n* `bundle` (2) - Bundle product requiring form completion with chapters and attributes\n* `grouped` (3) - Grouped product that contains multiple related products\n* `product_meta` (1) - Meta product used for organizational purposes (not purchasable)\n* `miscellaneous` (4) - Special miscellaneous product (e.g., gift wrap, services)\n* `offer` (5) - Special offer product that may contain promotional items\n* `pre_product` (-1) - Pre-release or pre-order product\n* `pre_miscellaneous` (-2) - Pre-release miscellaneous product\n\n**Important notes:**\n* `product_meta` and `grouped` types cannot be added to basket directly\n* `bundle` type requires form completion with chapter data\n* `miscellaneous` and `offer` types are typically used as sub-items","enum":["-1","0","1","2","3","-2","4","5"]},"CurrencyTypeEnum":{"type":"string","description":"Currency type using ISO 4217 currency codes.\n\nSupported currencies:\n* `try` - Turkish Lira (TRY)\n* `eur` - Euro (EUR)\n* `usd` - US Dollar (USD)\n* `gbp` - British Pound Sterling (GBP)\n* `egp` - Egyptian Pound (EGP)\n* `mad` - Moroccan Dirham (MAD)\n* `pln` - Polish Zloty (PLN)\n* `sar` - Saudi Riyal (SAR)\n* `ron` - Romanian Leu (RON)\n* `uah` - Ukrainian Hryvnia (UAH)\n* `czk` - Czech Koruna (CZK)\n* `huf` - Hungarian Forint (HUF)\n* `rub` - Russian Ruble (RUB)\n* `bgn` - Bulgarian Lev (BGN)\n* `iqd` - Iraqi Dinar (IQD)\n* `kwd` - Kuwaiti Dinar (KWD)\n* `bhd` - Bahraini Dinar (BHD)\n* `omr` - Omani Rial (OMR)\n* `qar` - Qatari Riyal (QAR)\n* `aed` - UAE Dirham (AED)\n* `ngn` - Nigerian Naira (NGN)\n* `inr` - Indian Rupee (INR)\n* `lei` - Moldovan Leu (LEI)\n* `kzt` - Kazakhstani Tenge (KZT)\n* `jod` - Jordanian Dinar (JOD)\n* `rsd` - Serbian Dinar (RSD)","enum":["try","eur","usd","gbp","egp","mad","pln","sar","ron","uah","czk","huf","rub","bgn","iqd","kwd","bhd","omr","qar","aed","ngn","inr","lei","kzt","jod","rsd"]},"ShippingDiscount":{"type":"object","properties":{"description":{"type":"string","nullable":true,"description":"Shipping discount description"},"discount":{"type":"string","description":"Shipping discount amount"},"affects":{"$ref":"#/components/schemas/ApplicationResultTypeEnum"}}},"ApplicationResultTypeEnum":{"type":"string","description":"Type of discount application result that determines what the discount affects.\n\nApplication types:\n* `basket` - Discount applied to basket items (reduces product prices)\n* `shipping` - Discount applied to shipping costs (free or reduced shipping)\n* `post_order` - Discount applied after order completion (cashback, loyalty points)\n* `sample_product` - Free sample product added to basket as promotional item\n\n**Usage in responses:**\n* Basket discounts reduce the total_amount\n* Shipping discounts appear in shipping_discount field on items\n* Sample products appear as separate basket items with special pricing\n* Post-order benefits are tracked separately for future application","enum":["basket","shipping","post_order","sample_product"]},"Discount":{"type":"object","properties":{"description":{"type":"string","description":"Description of the discount"},"discount":{"type":"string","description":"Discount amount"},"affects":{"$ref":"#/components/schemas/ApplicationResultTypeEnum"}}},"DataSource":{"type":"object","properties":{"pk":{"type":"integer","description":"Datasource unique identifier"},"name":{"type":"string","description":"Datasource/seller name"},"erp_code":{"type":"string","nullable":true,"description":"ERP code for the datasource"}}},"UpsellDetail":{"type":"object","properties":{"message":{"type":"string","description":"Upsell message for failed offer"},"params":{"type":"object","description":"Parameters for the upsell message"}}},"Segment":{"type":"object","properties":{"pk":{"type":"integer","nullable":true,"description":"Segment primary key"},"price_list":{"type":"integer","nullable":true,"description":"Price list ID for the segment"},"stock_list":{"type":"integer","nullable":true,"description":"Stock list ID for the segment"}}},"UnavailableProduct":{"type":"object","properties":{"pk":{"type":"integer","description":"Product ID"},"name":{"type":"string","description":"Product name"},"unavailable_quantity":{"type":"number","description":"Quantity that was removed due to unavailability"}}},"ErrorResponse":{"type":"object","properties":{"detail":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Field-specific validation errors"}}}}},"paths":{"/basket/":{"patch":{"summary":"Apply or Remove Voucher Code","parameters":[{"$ref":"#/components/parameters/CookieHeader"}],"description":"This method applies a voucher/coupon code to the basket or removes an existing one.\n\nThe system supports three types of voucher codes:\n* **Voucher codes**: Single-use promotional codes\n* **Coupon codes**: Multi-use promotional codes\n* **Bulk voucher codes**: Pre-generated code pools\n* **External offer codes**: Codes from external promotional systems (no validation)\n\n**Features:**\n* Apply voucher code with automatic validation\n* Remove currently applied voucher code\n* Support for external promotional codes\n* Automatic offer recalculation after code application\n* Detailed error messages for invalid or expired codes\n\n**Request Parameters:**\n* `voucher_code`: Standard voucher/coupon code (validated)\n* `external_offer_code`: External code (not validated, stored directly)\n* `remove_voucher_code = true`: Removes current voucher (no validation)\n\n**Validation checks (for voucher_code only):**\n* Code exists and is active\n* Code hasn't been used before (for single-use codes)\n* User meets eligibility requirements\n* Basket contents qualify for the offer\n* Code hasn't expired\n* Code usage limits not exceeded\n\n**External Offer Codes:**\n* No validation performed (`validate_voucher = false`)\n* Code stored directly in basket\n* Useful for codes from external promotional systems\n* System attempts to apply matching offers if available\n\n**Rate Limiting:**\n* PATCH method has rate limiting enabled (`CustomScopedRateThrottle`)\n* Scope: `basket`\n* Prevents brute-force code guessing attacks\n\n**After applying:**\n* Promotional offers are recalculated\n* Discounts are applied if eligible\n* Updated basket with discounts is returned\n* Returns 400 if code invalid/expired\n* Returns 429 if rate limit exceeded\n\n**Use Cases:**\n* Apply promotional codes during checkout\n* Remove incorrectly applied codes\n* Test promotional code validity\n* Apply partner or affiliate codes\n* Integrate with external promotional systems","operationId":"update_voucher_code","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateVoucherRequest"}}}},"responses":{"200":{"description":"Voucher code successfully applied or removed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BasketResponse"}}}},"400":{"description":"Invalid or expired voucher code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["basket"]}}}}
```

## Get Mini Basket Summary

> 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

```json
{"openapi":"3.0.3","info":{"title":"Basket API","version":"1.0.0"},"servers":[{"description":"Server base URL for basket operations","url":"https://{commerce_url}/baskets","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL"}}}],"security":[{"commerceSessionAuth":[]}],"components":{"securitySchemes":{},"parameters":{"CookieHeader":{"name":"X-Cookie","in":"header","description":"Use X-Cookie header instead of Cookie header in \"try out\" section.\nUse Cookie header while testing in postman or other tools.\nSome commerce applications may support 'sesionid' instead of 'osessionid'.","required":false,"schema":{"type":"string"}}},"schemas":{"MiniBasket":{"type":"object","properties":{"pk":{"type":"integer","description":"Basket unique identifier"},"total_quantity":{"type":"integer","description":"Total quantity of items in basket"}}}}},"paths":{"/basket/mini/":{"get":{"summary":"Get Mini Basket Summary","parameters":[{"$ref":"#/components/parameters/CookieHeader"}],"description":"This method retrieves a minimal summary of the current basket.\n\nReturns only essential information needed for quick display scenarios\nsuch as cart indicators in headers, navigation menus, or mobile interfaces.\n\n**Features:**\n* Lightweight response with minimal data\n* Fast response time for frequent polling\n* No promotional calculations performed\n* No item details included\n\n**Returned data:**\n* Basket ID (pk)\n* Total quantity of items\n\n**Use Cases:**\n* Shopping cart icon with item count in header\n* Quick basket status checks without full details\n* Mobile app navigation elements\n* Real-time basket quantity updates\n* Performance-critical scenarios where full basket data isn't needed","operationId":"get_mini_basket","responses":{"200":{"description":"Successfully retrieved mini basket summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MiniBasket"}}}}},"tags":["basket"]}}}}
```

## Update Basket Item Attributes

> 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

```json
{"openapi":"3.0.3","info":{"title":"Basket API","version":"1.0.0"},"servers":[{"description":"Server base URL for basket operations","url":"https://{commerce_url}/baskets","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL"}}}],"security":[{"commerceSessionAuth":[],"csrfCookie":[]}],"components":{"securitySchemes":{},"parameters":{"CookieHeader":{"name":"X-Cookie","in":"header","description":"Use X-Cookie header instead of Cookie header in \"try out\" section.\nUse Cookie header while testing in postman or other tools.\nSome commerce applications may support 'sesionid' instead of 'osessionid'.","required":false,"schema":{"type":"string"}}},"schemas":{"UpdateItemAttributesRequest":{"type":"object","required":["id","attributes"],"properties":{"id":{"type":"integer","description":"Basket item ID to update"},"attributes":{"type":"object","description":"Attributes to update (merged with existing attributes)"},"is_all":{"type":"boolean","description":"Apply to all items with same product (default false)"}}},"BasketResponse":{"type":"object","properties":{"basket":{"$ref":"#/components/schemas/Basket"}}},"Basket":{"type":"object","properties":{"pk":{"type":"integer","description":"Basket unique identifier"},"namespace":{"type":"string","nullable":true,"description":"Basket namespace for logical separation"},"basketitem_set":{"type":"array","items":{"$ref":"#/components/schemas/BasketItem"},"description":"List of basket items"},"total_quantity":{"type":"integer","description":"Total quantity of all items in basket"},"total_amount":{"type":"string","description":"Total amount after all discounts"},"total_discount_amount":{"type":"string","description":"Total discount amount applied to basket"},"total_product_amount":{"type":"string","description":"Total product amount before discounts"},"discounts":{"type":"array","items":{"$ref":"#/components/schemas/Discount"},"description":"List of applied discounts"},"upsell_details":{"type":"array","items":{"$ref":"#/components/schemas/UpsellDetail"},"description":"Upsell messages for offers that almost qualified"},"voucher_code":{"type":"string","nullable":true,"description":"Applied voucher code"},"created_date":{"type":"string","format":"date-time","description":"Basket creation timestamp"},"modified_date":{"type":"string","format":"date-time","description":"Last modification timestamp"},"segment":{"$ref":"#/components/schemas/Segment"},"unavailable_basket_products":{"type":"array","items":{"$ref":"#/components/schemas/UnavailableProduct"},"description":"Products that were removed due to unavailability"}}},"BasketItem":{"type":"object","properties":{"id":{"type":"integer","description":"Basket item unique identifier"},"product":{"$ref":"#/components/schemas/ProductDetail"},"quantity":{"type":"number","multipleOf":0.01,"description":"Quantity of the product"},"unit_price":{"type":"string","description":"Unit price of the product (before discounts)"},"price":{"type":"string","description":"Current unit price (same as unit_price)"},"retail_price":{"type":"string","description":"Retail price of the product"},"discounted_price":{"type":"string","description":"Unit price after discounts"},"tax_rate":{"type":"string","description":"Tax rate applied (as decimal)"},"currency_type":{"$ref":"#/components/schemas/CurrencyTypeEnum"},"total_amount":{"type":"string","description":"Total amount for this item (quantity × discounted_price)"},"discount_amount":{"type":"string","description":"Total discount amount for this item"},"stock":{"type":"integer","description":"Available stock for this product"},"attributes":{"type":"object","description":"Custom attributes for the basket item (gift notes, etc.)","nullable":true},"attributes_kwargs":{"type":"object","description":"Formatted attributes for display","nullable":true},"shipping_discount":{"$ref":"#/components/schemas/ShippingDiscount"},"offer_badges":{"type":"array","items":{"$ref":"#/components/schemas/Discount"},"description":"List of offer badges applied to this item"},"image":{"type":"string","nullable":true,"description":"Primary image for the item"},"parent":{"type":"integer","nullable":true,"description":"Parent basket item ID (for sub-items)"},"datasource":{"$ref":"#/components/schemas/DataSource"},"extra_product_stock_detailed":{"type":"object","nullable":true,"description":"Extra product stock details (marketplace)"},"extra_product_price_detailed":{"type":"object","nullable":true,"description":"Extra product price details (marketplace)"}}},"ProductDetail":{"type":"object","properties":{"pk":{"type":"integer","description":"Product unique identifier"},"sku":{"type":"string","description":"Stock Keeping Unit"},"name":{"type":"string","description":"Product name"},"base_code":{"type":"string","description":"Product base code"},"product_type":{"$ref":"#/components/schemas/ProductTypeEnum"},"productimage_set":{"type":"array","items":{"type":"object","properties":{"image":{"type":"string","description":"Product image URL"}}},"description":"Product images"},"attributes":{"type":"object","description":"Product attributes and metadata"},"is_active":{"type":"boolean","description":"Product active status"},"attribute_set":{"type":"integer","nullable":true,"description":"Attribute set ID"}}},"ProductTypeEnum":{"type":"string","description":"Type of product that determines its behavior and structure.\n\nProduct type definitions:\n* `simple` (0) - Standard standalone product with single SKU\n* `bundle` (2) - Bundle product requiring form completion with chapters and attributes\n* `grouped` (3) - Grouped product that contains multiple related products\n* `product_meta` (1) - Meta product used for organizational purposes (not purchasable)\n* `miscellaneous` (4) - Special miscellaneous product (e.g., gift wrap, services)\n* `offer` (5) - Special offer product that may contain promotional items\n* `pre_product` (-1) - Pre-release or pre-order product\n* `pre_miscellaneous` (-2) - Pre-release miscellaneous product\n\n**Important notes:**\n* `product_meta` and `grouped` types cannot be added to basket directly\n* `bundle` type requires form completion with chapter data\n* `miscellaneous` and `offer` types are typically used as sub-items","enum":["-1","0","1","2","3","-2","4","5"]},"CurrencyTypeEnum":{"type":"string","description":"Currency type using ISO 4217 currency codes.\n\nSupported currencies:\n* `try` - Turkish Lira (TRY)\n* `eur` - Euro (EUR)\n* `usd` - US Dollar (USD)\n* `gbp` - British Pound Sterling (GBP)\n* `egp` - Egyptian Pound (EGP)\n* `mad` - Moroccan Dirham (MAD)\n* `pln` - Polish Zloty (PLN)\n* `sar` - Saudi Riyal (SAR)\n* `ron` - Romanian Leu (RON)\n* `uah` - Ukrainian Hryvnia (UAH)\n* `czk` - Czech Koruna (CZK)\n* `huf` - Hungarian Forint (HUF)\n* `rub` - Russian Ruble (RUB)\n* `bgn` - Bulgarian Lev (BGN)\n* `iqd` - Iraqi Dinar (IQD)\n* `kwd` - Kuwaiti Dinar (KWD)\n* `bhd` - Bahraini Dinar (BHD)\n* `omr` - Omani Rial (OMR)\n* `qar` - Qatari Riyal (QAR)\n* `aed` - UAE Dirham (AED)\n* `ngn` - Nigerian Naira (NGN)\n* `inr` - Indian Rupee (INR)\n* `lei` - Moldovan Leu (LEI)\n* `kzt` - Kazakhstani Tenge (KZT)\n* `jod` - Jordanian Dinar (JOD)\n* `rsd` - Serbian Dinar (RSD)","enum":["try","eur","usd","gbp","egp","mad","pln","sar","ron","uah","czk","huf","rub","bgn","iqd","kwd","bhd","omr","qar","aed","ngn","inr","lei","kzt","jod","rsd"]},"ShippingDiscount":{"type":"object","properties":{"description":{"type":"string","nullable":true,"description":"Shipping discount description"},"discount":{"type":"string","description":"Shipping discount amount"},"affects":{"$ref":"#/components/schemas/ApplicationResultTypeEnum"}}},"ApplicationResultTypeEnum":{"type":"string","description":"Type of discount application result that determines what the discount affects.\n\nApplication types:\n* `basket` - Discount applied to basket items (reduces product prices)\n* `shipping` - Discount applied to shipping costs (free or reduced shipping)\n* `post_order` - Discount applied after order completion (cashback, loyalty points)\n* `sample_product` - Free sample product added to basket as promotional item\n\n**Usage in responses:**\n* Basket discounts reduce the total_amount\n* Shipping discounts appear in shipping_discount field on items\n* Sample products appear as separate basket items with special pricing\n* Post-order benefits are tracked separately for future application","enum":["basket","shipping","post_order","sample_product"]},"Discount":{"type":"object","properties":{"description":{"type":"string","description":"Description of the discount"},"discount":{"type":"string","description":"Discount amount"},"affects":{"$ref":"#/components/schemas/ApplicationResultTypeEnum"}}},"DataSource":{"type":"object","properties":{"pk":{"type":"integer","description":"Datasource unique identifier"},"name":{"type":"string","description":"Datasource/seller name"},"erp_code":{"type":"string","nullable":true,"description":"ERP code for the datasource"}}},"UpsellDetail":{"type":"object","properties":{"message":{"type":"string","description":"Upsell message for failed offer"},"params":{"type":"object","description":"Parameters for the upsell message"}}},"Segment":{"type":"object","properties":{"pk":{"type":"integer","nullable":true,"description":"Segment primary key"},"price_list":{"type":"integer","nullable":true,"description":"Price list ID for the segment"},"stock_list":{"type":"integer","nullable":true,"description":"Stock list ID for the segment"}}},"UnavailableProduct":{"type":"object","properties":{"pk":{"type":"integer","description":"Product ID"},"name":{"type":"string","description":"Product name"},"unavailable_quantity":{"type":"number","description":"Quantity that was removed due to unavailability"}}},"ErrorResponse":{"type":"object","properties":{"detail":{"type":"string","description":"Error message"},"errors":{"type":"object","description":"Field-specific validation errors"}}}}},"paths":{"/basket_items/":{"patch":{"summary":"Update Basket Item Attributes","parameters":[{"$ref":"#/components/parameters/CookieHeader"}],"description":"This method updates custom attributes for a specific basket item without changing the product or quantity.\n\nAttributes are custom fields that can be attached to basket items, such as:\n* Gift notes or messages\n* Personalization data\n* Customization options\n* Special instructions\n* Custom form fields\n\n**Features:**\n* Update specific basket item by ID\n* Merge new attributes with existing ones\n* Remove attributes by setting them to empty string\n* Option to apply same attributes to all items of the same product\n* Automatic gift note validation (removes empty or whitespace-only notes)\n\n**Validation Rules:**\n* Basket item with specified ID must exist in current basket\n* Attributes field is required (cannot be null)\n* Attributes must not exceed `BASKET_ITEM_ATTRIBUTES_MAX_LENGTH_KB` limit\n* Gift notes with only whitespace are automatically removed\n* Product field must match the basket item's product\n\n**Behavior:**\n* Attributes are **merged**, not replaced (existing attributes preserved)\n* To remove an attribute, set it to empty string: `{\"gift_note\": \"\"}`\n* Gift notes with only whitespace are automatically removed\n* Setting `is_all: true` applies attributes to all basket items with same product\n* Returns 400 if basket item not found in current basket\n\n**Configuration Dependencies:**\n* `BASKET_ITEM_ATTRIBUTES_MAX_LENGTH_KB`: Maximum size limit (default 10KB)\n* Exceeding this limit returns validation error\n\n**After updating:**\n* Promotional offers are recalculated\n* Complete basket state is returned\n* Updated attributes are immediately visible\n* Changes apply to specified item(s) only\n\n**Use Cases:**\n* Add/update gift messages from cart page\n* Update personalization options\n* Modify custom form field values\n* Add special delivery instructions\n* Bulk update attributes for multiple items of same product","operationId":"update_basket_item_attributes","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateItemAttributesRequest"}}}},"responses":{"200":{"description":"Attributes successfully updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BasketResponse"}}}},"400":{"description":"Validation error (item not found, invalid attributes)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"tags":["basket"]}}}}
```