> For the complete documentation index, see [llms.txt](https://docs.verifone.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verifone.com/psdk-latest/psdk-user-guide-and-training/psdk-user-guide/general_basket_flow.md). # Basket Management / Line Item Display Displaying and managing line items involves creating and sending [BasketItem](https://docs.verifone.com/psdk-api-latest/android-java/index/basketitem) subclass instances to the POI. {% @plantuml/diagram content=" @startuml hide footbox ``` actor Cashier order 10 participant POS order 20 participant PSDK order 30 ||| ... POS <- PSDK: CommerceEvent.SESSION_STARTED POS <-> PSDK: transactionManager.getBasketManager() loop until basket is built Cashier -> POS: Select item for basket POS -> POS: Create Merchandise object and update calculate basket amount total. POS ->> PSDK: basketManager.addMerchandise(merchandise, amountTotal) POS <- PSDK: BasketEvent.TYPE with BasketAction.ADDED and the updated items. ...add/modify/remove additional items... end POS ->> PSDK: basketManager.finalizeBasket() ...basket adjudication, refer to advanced flows... POS <- PSDK: BasketEvent.TYPE with BasketAction.FINALIZED. POS -> POS: Setup amount totals and payment POS ->> PSDK: mTransactionManager.startPayment() ... ||| @enduml" %} ``` ## Basket Manager Lifecycle It’s important to only retrieve the basket manager after a session is started, it is only valid within the context of a session. When a new session is started, a new basket manager should be retrieved, they must not be reused across sessions. ### Finishing a Basket When all of the items are added, it is important to call [BasketManager.finalizeBasket()](https://docs.verifone.com/psdk-api-latest/android-java/index/basketmanager#finalizebasket) to indicate that the basket is complete. It is still possible to add, modify, or remove items after the basket is finalized, to support those scenarios where the cashier or customer forgot to include something, but if the basket is modified again, the basket should be finalized again. ### Restoring a Basket from a Previous Order A Basket can be restored in one action using [BasketManager.registerBasket(basket, amountTotals)](https://docs.verifone.com/psdk-api-latest/android-java/index/basketmanager#registerbasket-basket-amounttotals). This takes all of the items in that basket object and places them on the POI display screen, simplifying the task of re-adding each item from a saved cart. The current Basket can be retrieved using [BasketManager.getBasket()](https://docs.verifone.com/psdk-api-latest/android-java/index/basketmanager#getbasket), kept locally, and then registered later if this is simpler, or a new Basket object can be populated and then registered. *** ## Best Practices ### Adding/Display Items Quickly Adding items to the display can take a bit of time. Generally cashiers can add items faster than the display can update, so it’s best to add as soon as the cashier enters it, then queue up additional items while waiting for the BasketEvent to arrive. Once the event arrives, add all of the items in the queue at once, since the methods allow for arrays of items to be sent. ### Modifying/Removing Items It’s important to either set the ID using [BasketItem.setBasketItemId(…)](https://docs.verifone.com/psdk-api-latest/android-java/index/basketitem#setbasketitemid-string) explicitly or to match the ID returned by the [BasketEvent](https://docs.verifone.com/psdk-api-latest/android-java/index/basketevent) once the item is added. Setting the Basket Item ID explicitly makes it much simpler to later modify or remove the item, since that’s the only reference the payment service has to know which item ought to be modified or removed, since other system identifying information is lost when the object is sent between processes. See Separate Processes means Separate Objects for more information. ### Providing the Amount Total The current running total must be provided with every basket action, allowing the POI display to stay accurate with the items. Neither the payment service nor the POI want to do any math to track the current running total, this must be provided by the POS for the most accurate results. *** ## Basket Item Objects Basket items are tracked using the [BasketItem.getBasketItemId()](https://docs.verifone.com/psdk-api-latest/android-java/index/basketitem#getbasketitemid) ID. This ID is automatically created by the service if not already set, and is provided back in the [BasketEvent](https://docs.verifone.com/psdk-api-latest/android-java/index/basketevent) when the item is placed in the basket. This is an important ID, since modifying or removing the item later depends on this field. Setting the Display Line determines what is shown on the line item display, with an optional Description field being displayed in different text directly below the item. If the Display Line is not provided, it will automatically look to the Name and then the Description to determine what to show to the user. {% hint style="info" %} The payment service runs in a separate process, which means that setting fields on an object in the SDK does not automatically set those fields in the service. In order to carry those changes across, the object must be sent to the service using one of the methods listed. {% endhint %} {% hint style="info" %} **See also** * [BasketItem](https://docs.verifone.com/psdk-api-latest/android-java/index/basketitem) {% endhint %} ### AmountTotals Provides an object to contain all of the relevant fields for an item. This is the best way to set the value of an item before sending it, allowing the granular amounts to be communicated when payment is being processed. In some regions, the tax data per item is required, so including this information can ease the work transitioning between regions. When setting an [AmountTotals](https://docs.verifone.com/psdk-api-latest/android-java/index/amounttotals) object on a [BasketItem](https://docs.verifone.com/psdk-api-latest/android-java/index/basketitem), the other amounts on the BasketItem do not need to be set. The AmountTotals for a BasketItem should only be the amounts for that display line, e.g., if there is a quantity of 4, the AmountTotals should be the total amount for that display line, but should not be the cart total. Gratuity is not expected for basket items. The amounts can be positive or negative, depending on the purpose. It’s generally useful to set a negative amount for returned merchandise and offers, while positive amounts will be used in most other cases. {% hint style="info" %} **See also** * [AmountTotals](https://docs.verifone.com/psdk-api-latest/android-java/index/amounttotals) {% endhint %} ### Merchandise Represents normal cart items, such as a chocolate bar, iced coffee, or hat. Allows quantity, unit price, unit of measurement, and extended price in addition to the fields provided by BasketItem. Many of the different use cases can be satisfied by only using this object, the others are optional, but can provide a better display to the customer when used. {% hint style="info" %} **See also** * [Merchandise](https://docs.verifone.com/psdk-api-latest/android-java/index/merchandise) * [BasketManager.addMerchandise(Merchandise\[\], AmountTotals)](https://docs.verifone.com/psdk-api-latest/android-java/index/basketmanager#addmerchandise-arraylistmerchandise-amounttotals) * [BasketManager.modifyMerchandise(Merchandise\[\], AmountTotals)](https://docs.verifone.com/psdk-api-latest/android-java/index/basketmanager#modifymerchandise-arraylistmerchandise-amounttotals) * [BasketManager.removeMerchandise(Merchandise\[\], AmountTotals)](https://docs.verifone.com/psdk-api-latest/android-java/index/basketmanager#removemerchandise-arraylistmerchandise-amounttotals) {% endhint %} ### Modifier Modifies the merchandise to which it is attached. This cannot be sent on its own, it can only be linked to merchandise already in the cart. This is good to show the build of a merchandise, such as adding chocolate sauce to an iced coffee for an additional fee, or specifying that the hat was of a medium size without any additional fee. {% hint style="info" %} **See also** * [Modifier](https://docs.verifone.com/psdk-api-latest/android-java/index/modifier) * [BasketManager.addModifierToMerchandise(Modifier, Merchandise, AmountTotals)](https://docs.verifone.com/psdk-api-latest/android-java/index/basketmanager#addmodifiertomerchandise-modifier-merchandise-amounttotals) * [BasketManager.removeModifierFromMerchandise(Modifier, Merchandise, AmountTotals)](https://docs.verifone.com/psdk-api-latest/android-java/index/basketmanager#removemodifierfrommerchandise-modifier-merchandise-amounttotals) * [BasketManager.modifyMerchandise(Merchandise\[\], AmountTotals) ](https://docs.verifone.com/psdk-api-latest/android-java/index/basketmanager#modifymerchandise-arraylistmerchandise-amounttotals)(to update modifiers already attached) {% endhint %} ### Offer An offer is used to provide some discount or award. There are many types of offers, enumerated by [Offer.OfferType.](https://docs.verifone.com/psdk-api-latest/android-java/index/offer#getoffertype) Most of the fields are optional. The amount should be specified as negative if it is reducing the total cost, the payment service and payment app will not modify it. If this offer is linked to a specific item in the basket, use [Offer.setReferenceBasketLineItemId(…) ](https://docs.verifone.com/psdk-api-latest/android-java/index/offer#setreferencebasketlineitemid-string)to match it to the item. {% hint style="info" %} **See also** * [Offer](https://docs.verifone.com/psdk-api-latest/android-java/index/offer) * [BasketManager.addOffers(Offer\[\], AmountTotals)](https://docs.verifone.com/psdk-api-latest/android-java/index/basketmanager#addoffers-arraylistoffer-amounttotals) * [BasketManager.modifyOffers(Offer\[\], AmountTotals)](https://docs.verifone.com/psdk-api-latest/android-java/index/basketmanager#modifyoffers-arraylistoffer-amounttotals) * [BasketManager.removeOffers(Offer\[\], AmountTotals)](https://docs.verifone.com/psdk-api-latest/android-java/index/basketmanager#removeoffers-arraylistoffer-amounttotals) {% endhint %} ### Donation Identifies an amount that is to be donated. {% hint style="warning" %} **Todo:** Add a see-also section referencing how to add items to a basket, and create a new section for storing a basket for later. {% endhint %} {% hint style="info" %} **See also** * [Donation](https://docs.verifone.com/psdk-api-latest/android-java/index/donation) * [BasketManager.addDonations(Donation\[\], AmountTotals)](https://docs.verifone.com/psdk-api-latest/android-java/index/basketmanager#adddonations-arraylistdonation-amounttotals) * [BasketManager.modifyDonations(Donation\[\], AmountTotals)](https://docs.verifone.com/psdk-api-latest/android-java/index/basketmanager#modifydonations-arraylistdonation-amounttotals) * [BasketManager.removeDonations(Donation\[\], AmountTotals)](https://docs.verifone.com/psdk-api-latest/android-java/index/basketmanager#removedonations-arraylistdonation-amounttotals) {% endhint %} *** {% columns %} {% column width="25%" %}
{% endcolumn %} {% column width="25%" %} {% endcolumn %} {% column width="16.66666666666666%" %} **Version:**\ **Date:** {% endcolumn %} {% column width="33.333333333333336%" %} space.vars.psdk\_version\ space.vars.psdk\_date {% endcolumn %} {% endcolumns %} --- # 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.verifone.com/psdk-latest/psdk-user-guide-and-training/psdk-user-guide/general_basket_flow.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.