> For the complete documentation index, see [llms.txt](https://apidocs.akinon.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidocs.akinon.com/commerce/basket.md). # Basket The basket module handles the management of products within the basket and other related transactions. Each user is allowed to have a single active `Basket`, and a `BasketItem` is created for every unique item that users add to their basket. ## Basket Model | Parameter | Data Type | Definition | | -------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------ | | id | integer | Database ID. | | created\_date | datetime (string) | Basket created on. | | modified\_date | datetime (string) | Basket last modified on. | | status | string | Basket status. *Basket status is defined on the BasketStatus enum.* | | version | integer | Version info. Version information is used to control whether the cached version matches the Basket data in the database. | | user | integer | User account linked to the basket. | | voucher\_code | string | Basket discount code. | ## BasketItem Model | Parameter | Data Type | Definition | | ----------------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------- | | id | integer | Database ID. | | created\_date | datetime (string) | Basket item created on. | | modified\_date | datetime (string) | Basket item last modified on. | | status | string | Version info. Version information is used to control whether the cached version matches the BasketItem data in the database. | | attributes | dict | Additional attributes, if any, of the basket item. | | attributes\_kwargs | dict | Additional keywords for additional attributes, if any, of the basket item. | | localized\_attributes | dict | Additional localized attributes, if any, of the basket item. | | localized\_attributes\_kwargs | dict | Additional keywords, if any, for additional localized attributes of the basket item. | | basket | integer | Basket linked to the basket item. | | reference | string | Unique key created for related basket item. | | product | integer | Item linked to the basket item | | quantity | integer | Quantity of basket item. | | tax\_rate | float | Tax rate of the basket item. | | currency\_type | string | Price currency of the basket item. | | unit\_price | float | Unit price of the basket item. | | image | string | Thumbnail image of the basket item. | | extra\_product\_price | integer | Additional product price variations, if any, for the basket item. | | extra\_product\_stock | integer | Additional stock information, if any, for the basket item. | | parent | integer | Parent product, if the basket item is a child product. | ## Basket Endpoints | Parameter | Data Type | Section to Submit | Definition | | ---------- | --------- | ----------------- | ----------------------------------------------- | | product | integer | body | ID of the item to be added to the basket. | | quantity | integer | body | Quantity of the item to be added to the basket. | | attributes | dict | body | Product properties. | | inquiry | dict | body | Product details, if the item is exchangeable. | | sub\_items | dict | body | Sub items. | ### `GET` Basket Items ​Returns the basket and product information. **Path:** `https://{commerce_url}/baskets/basket/` **Response** ```json { "basket": { "basketitem_set": [ { "quantity": 1, "product": { "pk": 1309, "name": "Gitar", "sku": "1020583031", "base_code": "1020583", "attributes": {}, "attribute_set": 152, "attributes_kwargs": {}, "extra_attributes": {}, "productimage_set": [ { "pk": 2576, "status": "active", "image": "HTTPs://akinon.akinoncdn.com/products/2021/09/10/3/e5b49285-7d8b-47a7-84f8-994c2217548a.jpg", "order": 1, "created_date": "2021-09-10T16:57:34.100718Z", "specialimage_set": [ ] } ], "price": "120", "in_stock": true, "currency_type": "try", "retail_price": "200", "unit_type": "qty", "absolute_url": "/1020583031-1020583-gitar/", "productvideo_set": [], "product_type": "0", "price_type": "default", "form_schema": null, "is_ready_to_basket": true, "stock": 51, "data_source": null }, "unit_price": "120.00", "currency_type": "try", "tax_rate": "18.00", "total_amount": "120.00", "shipping_discount": null, "attributes": {}, "id": 7387, "attributes_kwargs": {}, "image": null, "parent": null, "offer_badges": [ { "description": "Sitewide Campaign", "discount": "24.00" } ], "price": "120.00", "retail_price": "200.00", "stock": 51, "discount_amount": "24.00" } ], "total_amount": "96.00", "total_quantity": 1, "unavailable_basket_products": [], "upsell_details": [], "selectable_benefits": [], "discounts": [ { "description": "Sitewide Campaign", "discount": "24.00" } ], "total_discount_amount": "24.00", "total_product_amount": "120.00", "voucher_code": null, "pk": 6863, "created_date": "2021-09-20T12:27:31.459026Z", "modified_date": "2021-09-20T12:27:31.459045Z" } } ``` ### `POST` Add New Product to Basket ​This method is used to add a new product to the basket. **Path:** `https://{commerce_url}/baskets/basket/` **Request Body** ```json { "product": 49, "quantity": 2 } ``` ​**Response** Returns the same response as the GET method.\ ​ ### `PATCH` Update a Product Quantity Used to change the quantity of a product added to the basket. **Path:** `https://{commerce_url}/baskets/basket/` **Request Body** ```json { "product": 49, "quantity": 0 } ``` ​**Response** Returns the same response as the GET method.\ ​ ### `PUT` Update a Product Quantity **Path:** `https://{commerce_url}/baskets/basket/` **Request Body** ```json { "product": 49, "quantity": 0 } ``` **Response** Returns the same response as the GET method.\ ​ ### `DELETE` Remove All Products From Basket ​\ This method is used to delete all products added to the basket. **Path:** `https://{commerce_url}/baskets/basket/` **Response** ```json { "basket": { "basketitem_set": [], "total_amount": "0.00", "total_quantity": 0, "unavailable_basket_products": [], "upsell_details": [], "selectable_benefits": [], "discounts": [], "total_discount_amount": "0.00", "total_product_amount": "0.00", "voucher_code": null, "pk": 6863, "created_date": "2023-06-06T12:32:41.281764Z", "modified_date": "2023-07-05T10:22:34.911792Z", "segment": { "pk": null, "stock_list": null, "price_list": null } } } ``` ### `PATCH` Update Single Basket Item This method is used for making individual modification in basket items. If the basket item modification is successful, a new basket item is produced as a response. If the `BasketItem` to be modified cannot be found, it returns an error code of 400. **Path:** `basket_items/$` **Request Body** The following request body parameters can be used to update single basket item. | Parameter | Data Type | Definition | | ---------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | ID | integer | Database ID of the `BasketItem` to be modified. | | is\_all | boolean | If true is submitted, then the update applies to all quantities of the basket item. If false is submitted, then the update applies to one basket item. | | attributes | boolean | Additional attributes of the basket item to modify. | ```json { "id": 1720, "is_all": true } ``` ## Data Parameters for PUT Method | Parameter | Data Type | Section to Submit | Definition | | ---------- | --------- | ----------------- | ----------------------------------------------- | | product | integer | body | ID of the item to be added to the basket. | | quantity | integer | body | Quantity of the item to be added to the basket. | | attributes | dict | body | Product properties. | | inquiry | dict | body | Product details, if the item is exchangeable. | ### Payload Example ```json { "product": 1780, "quantity": 1, "attributes": { "example_attribute": 123 } } ``` ## Data Parameters for PATCH Method | Parameter | Data Type | Section to Submit | Definition | | --------------------- | --------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | external\_offer\_code | string | body | When this field is submitted, the code is applied to the basket without instant verification, regardless of other fields. | | remove\_voucher\_code | boolean | body | When True is submitted, the discount code is removed from the basket. When submitted simultaneously with `external_offer_code`, then the code submitted with `external_offer_code` is not removed. | | voucher\_code | string | body | Discount code to apply to the basket. Instant verification is also applied to the code submitted here. | ### Payload Examples ```json { "voucher_code": "aaa-bbb-ccc" } ``` ```json { "remove_voucher_code": true } ``` ```json { "external_offer_code": "ddd-eee-fff" } ``` ### Voucher Code Errors When the code submitted in `voucher_code` cannot be applied, the basket returns `406` and removes the code from the basket: ```json { "non_field_errors": "Voucher code is not valid", "error_code": "basket_voucher_100_1" } ``` | error\_code | Definition | | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | basket\_voucher\_100\_1 | The code does not exist or its campaign conditions are not met. When the campaign has an upsell message and its conditions are partly met, `non_field_errors` holds the upsell message. | | basket\_voucher\_100\_2 | The code was used before: it is already marked as used, or, when `max_usage_per_user` is `true` in the `BASKET_OFFER_ERROR_CONF` dynamic setting, the customer has reached the per-customer limit (`max_usage_per_user`) of its campaign. Otherwise the second case returns `basket_voucher_100_1`. | ## Data Parameters for DELETE Method There are no data parameters for the DELETE method. ### Response Parameters | Parameter | Data Type | Definition | | ----------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------- | | basketitem\_set | array | Details of basket items. | | quantity | integer | Quantity of basket item. | | product | dict | Details of basket item. | | unit\_price | string | Item unit price. | | currency\_type | string | Item price currency. | | tax\_rate | string | Tax rate. | | total\_amount | string | Net product price. | | shipping\_discount | string | Item shipping discount amount. | | attributes | dict | Item attributes. | | id | integer | Database ID of the item. | | attributes\_kwargs | dict | Item attribute keywords. | | image | string | Item image. | | parent | dict | If the item is a child product, details of the parent product. | | offer\_badges | array | Discounts. | | price | string | Item price. | | retail\_price | string | Item price before the discount. | | stock | integer | Item stock amount. | | discount\_amount | string | Item discount amount. | | total\_amount | string | Total price of basket items. | | total\_quantity | integer | Total quantity of basket items. | | unavailable\_basket\_products | array | Invalid or unavailable items in the basket. | | upsell\_details | array | Parameters and message details if there are items whose discount prices are no longer valid or if their prices increased later. | | selectable\_benefits | array | Earned campaigns whose benefit products the customer can choose. See [Selectable Benefits](#selectable-benefits). | | discounts | array | Discounts. | | total\_discount\_amount | string | Total discount amount. | | total\_product\_amount | string | Total price of items. | | voucher\_code | string | Discount code. | | pk | integer | Database ID of the user's basket. | | created\_date | string | Date when the basket was created in the database. | | modified\_date | string | Date when the basket was last modified in the database. | | segment: | dict | Information on which segment the customer is in | ### Selectable Benefits `selectable_benefits` lists the campaigns with **Show Gift Product** (`show_benefit_products`) enabled whose condition the basket satisfies, so the customer can choose the campaign's benefit products before adding any of them to the basket. A campaign stays in the list after its benefit products are added, and `is_claimable` shows whether more of them can be added. ```json "selectable_benefits": [ { "offer_id": 3302, "offer_type": "sitewide", "description": "Buy a perfume, get a palette for free", "product_collection": 1459, "allowed_quantity": 1, "claimed_quantity": 0, "is_claimable": true } ] ``` | Parameter | Data Type | Definition | | ------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | offer\_id | integer | ID of the campaign. Its benefit products are fetched from `/basket-offers/{offer_id}/`. | | offer\_type | string | Type of the campaign, e.g. `sitewide`, `coupon`, `voucher_code`. | | description | string | Campaign message, the same text as the campaign's entry in `discounts`. | | product\_collection | integer | ID of the benefit product collection, to list its products with pagination from `/list/?collection_ids={product_collection}`. | | allowed\_quantity | integer / null | Number of benefit products the basket has earned so far. `null` when the benefit has no product limit. | | claimed\_quantity | integer / null | Number of the earned benefit products that are already in the basket with the discount. `null` when the benefit has no product limit. | | is\_claimable | boolean | `true` when adding a benefit product to the basket gets the discount, `false` once every earned benefit product is in the basket. | `/basket-offers/{offer_id}/` returns each benefit product with its `benefit_price`, the price of one unit once the benefit is earned. When the benefit discounts a set of products, such as "2 products at 50% off", the discount of the set is split per unit. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://apidocs.akinon.com/commerce/basket.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.