> For the complete documentation index, see [llms.txt](https://docs.firework.com/firework-for-developers/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.firework.com/firework-for-developers/android-sdk/integration-guide/shoppable-videos/cart-and-checkout.md).

# Cart & Checkout

The SDK does not manage the shopping cart internally. You are responsible for:

* Maintaining cart state
* Managing cart items
* Handling checkout flow

The SDK provides callbacks and configuration options for cart integration. This page covers:

* [Shopping CTA Button](#shopping-cta-button) - Handle add-to-cart / shop-now actions on the PDP
* [Customize Shopping CTA Button](#customize-shopping-cta-button) - Style the CTA button
* [Shopping Cart](#shopping-cart) - Cart behaviors and callbacks
* [Product Detail Page (PDP)](#product-detail-page-pdp) - PDP link button configuration
* ["Shop Now" Mode](#shop-now-mode) - Direct navigation without a cart
* [Error Handling](#error-handling) - Shopping error events
* [Programmatic Control](#programmatic-control) - Dismiss shopping UI, open cart

## Shopping CTA Button

The shopping CTA button appears on the product detail page and triggers the add-to-cart or shop-now action.

<figure><img src="/files/QhzVHycUOYhWEzzjJrlM" alt="" width="303"><figcaption><p>Product details page - CTA button (3)</p></figcaption></figure>

### CTA Button Click Listener

Handle clicks on the shopping CTA button:

```kotlin
class MainActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        
        FireworkSdk.shopping.setOnCtaButtonClicked { productId, unitId, productWebUrl, videoInfo ->
            // Handle CTA click
            // Add product to cart, navigate to checkout, etc.
        }
     }

    override fun onDestroy() {
        FireworkSdk.shopping.setOnCtaButtonClicked(null)
        super.onDestroy()
    }
}
```

### CTA Button Status

For long-running operations (e.g., adding to cart via API), notify the SDK of the operation status:

```kotlin
FireworkSdk.shopping.setOnCtaButtonClicked { productId, unitId, productWebUrl, videoInfo ->
    // Set loading state
    FireworkSdk.shopping.setCtaButtonStatus(CtaButtonStatus.Loading)
    
    try {
        val result = api.addToCart(productId, unitId)
        
        if (result.isSuccess) {
            FireworkSdk.shopping.setCtaButtonStatus(CtaButtonStatus.Success)
        } else {
            FireworkSdk.shopping.setCtaButtonStatus(CtaButtonStatus.Error)
        }
    } catch (e: Exception) {
        FireworkSdk.shopping.setCtaButtonStatus(CtaButtonStatus.Error)
    }
}
```

**Status Types:**

* `CtaButtonStatus.Loading` - Operation in progress
* `CtaButtonStatus.Success` - Operation completed successfully
* `CtaButtonStatus.Error` - Operation failed

> **Note**: If status is not provided within 10 seconds, the SDK assumes the operation failed.

### CTA Button Text

Choose between "Add to cart" and "Shop now" labels:

```kotlin
FireworkSdk.shopping.setShoppingViewOptions(
    ShoppingViewOptions(
        productDetailsOptions = ProductDetailsOptions(
                shoppingCtaButtonOptions = ShoppingCtaButtonOptions(
                        text = ShoppingCtaButtonOptions.Text.SHOP_NOW
                // or ShoppingCtaButtonOptions.Text.ADD_TO_CART
                ),
        ),
     )
 )
```

**Usage Guidelines:**

* **Add to cart**: Use when shopping cart is enabled
* **Shop now**: Use for direct navigation to product pages without cart

## Customize Shopping CTA Button

You can customize the "Add to Cart" button appearance by overriding the `FwShoppingCtaButtonStyle` in your app's theme:

### Basic Styling

```xml
<resources>
   <style name="FwShoppingCtaButtonStyle" parent="FwShoppingCtaButtonParentStyle">
        <item name="android:backgroundTint">@color/backgroundColor</item>
        <item name="android:textColor">@color/myTextColor</item>
        <item name="android:textSize">16sp</item>
    </style>
</resources>
```

### Shape Customization

To customize button shape (rounded corners, etc.):

```xml
<resources>
    <style name="FwShoppingCtaButtonStyle" parent="FwShoppingCtaButtonParentStyle">
        <item name="shapeAppearanceOverlay">@style/MyAddToCartButtonShapeStyle</item>
    </style>
    
    <style name="MyAddToCartButtonShapeStyle">
        <item name="cornerFamily">rounded</item> <!-- "rounded" or "cut" -->
        <item name="cornerSizeTopLeft">6dp</item>
        <item name="cornerSizeBottomLeft">6dp</item>
        <item name="cornerSizeBottomRight">6dp</item>
        <item name="cornerSizeTopRight">6dp</item>
    </style>
</resources>
```

## Shopping Cart

### Cart Behavior

Configure how the shopping cart behaves using `CartBehaviour`:

```kotlin
FireworkSdk.shopping.setShoppingCartBehaviour(behaviour: CartBehaviour)
```

**Available Behaviors:**

1. **CartBehaviour.NoCart** (Default)
   * Shopping cart icon is hidden
   * Suitable for "Shop now" mode without cart
2. **CartBehaviour.Callback**
   * Cart icon is shown
   * `OnCartActionListener.onCartClicked` is triggered when clicked
   * Use when opening cart as a separate activity
3. **CartBehaviour.Embedded**
   * Cart icon is shown
   * Fragment from `EmbeddedCartFactory` is displayed when clicked
   * Requires calling `setEmbeddedCartFactory` first

### Embedded Cart Example

```kotlin
class MainActivity : AppCompatActivity() {

    private val embeddedCartFactory = object : EmbeddedCartFactory {
        override fun getInstance(): Fragment {
            return CustomShoppingCartFragment()
        }
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        
        // Set the factory
        FireworkSdk.shopping.setEmbeddedCartFactory(embeddedCartFactory)
        
        // Enable embedded cart behavior
        FireworkSdk.shopping.setShoppingCartBehaviour(
            Shopping.CartBehaviour.Embedded(title = "Shopping Cart")
        )
    }
}
```

### Cart Click Listener

> **Important**: This listener only works with `CartBehaviour.Callback`.

<figure><img src="/files/QhzVHycUOYhWEzzjJrlM" alt="" width="303"><figcaption><p>Product details page - Cart icon (1)</p></figcaption></figure>

```kotlin
class MainActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        
        // Set callback behavior
        FireworkSdk.shopping.setShoppingCartBehaviour(Shopping.CartBehaviour.Callback)
        
        // Handle cart clicks
        FireworkSdk.shopping.setOnCartClickListener { videoInfo ->
            // Open cart activity or fragment
            startActivity(Intent(this, CartActivity::class.java))
        }
    }

    override fun onDestroy() {
        FireworkSdk.shopping.setOnCartClickListener(null)
        super.onDestroy()
    }
}
```

## Product Detail Page (PDP)

### PDP Link Button Click Listener

<figure><img src="/files/QhzVHycUOYhWEzzjJrlM" alt="" width="303"><figcaption><p>Product details page - PDP link (2)</p></figcaption></figure>

Handle clicks on the PDP link button:

```kotlin
class MainActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        
        FireworkSdk.shopping.setOnProductLinkClickListener { productId, unitId, productWebUrl, videoInfo ->

            // Let fullscreen player jump into picture in picture mode
            FireworkSdk.enterPip()
            // Handle custom navigation
            // Return true to handle it yourself, false to let SDK handle it
            
            openProductPage(productWebUrl)
            return true
        }
    }

    override fun onDestroy() {
        FireworkSdk.shopping.setOnProductLinkClickListener(null)
        super.onDestroy()
    }
}
```

**Return Value:**

* `true` - Your app handles the navigation
* `false` - SDK opens the product page

### PDP Link Button Visibility

Control whether the PDP link button is shown:

```kotlin
FireworkSdk.shopping.setShoppingViewOptions(
        ShoppingViewOptions(
        productDetailsOptions = ProductDetailsOptions(
                    linkButtonOptions = LinkButtonOptions(isVisible = false),
                )
        )
 )
```

## "Shop Now" Mode

Configure the SDK for direct product page navigation without a shopping cart:

```kotlin
private fun setupShopNowMode() {
    with(FireworkSdk.shopping) {
        // Hide cart button
        setShoppingCartBehaviour(Shopping.CartBehaviour.NoCart)
        
        // Configure PDP options
        setShoppingViewOptions(
            ShoppingViewOptions(
                productDetailsOptions = ProductDetailsOptions(
                    linkButtonOptions = LinkButtonOptions(isVisible = false),
                    shoppingCtaButtonOptions = ShoppingCtaButtonOptions(
                        text = ShoppingCtaButtonOptions.Text.SHOP_NOW
                    ),
                ),
            ),
        )
        
        // Handle CTA clicks
        setOnCtaButtonClicked { productId, unitId, productWebUrl, videoInfo ->
            openWebUrlInBrowser(productWebUrl)
            FireworkSdk.enterPip()  // Move player to PIP
        }
    }
}
```

## Error Handling

Implement `OnShoppingErrorListener` to receive shopping error events:

```kotlin
class MainActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        
        FireworkSdk.shopping.setOnShoppingErrorListener { error ->
            when (error) {
                is ShoppingError.AddToCartError -> handleCartError(error)
                is ShoppingError.ShowProductInfoError -> handleProductError(error)
            }
        }
    }
    
    private fun handleCartError(error: ShoppingError.AddToCartError) {
        when (error) {
            ShoppingError.AddToCartError.NullProductId -> 
                Log.e(TAG, "Product ID is null")
            ShoppingError.AddToCartError.NullProductUnitId -> 
                Log.e(TAG, "Product unit ID is null")
            ShoppingError.AddToCartError.NullCartActionListener -> 
                Log.e(TAG, "Cart listener not set")
            ShoppingError.AddToCartError.Timeout -> 
                Log.e(TAG, "Add to cart timeout")
        }
    }
    
    private fun handleProductError(error: ShoppingError.ShowProductInfoError) {
        when (error) {
            ShoppingError.ShowProductInfoError.FailedToLaunchUrl -> 
                Log.e(TAG, "Failed to launch product URL")
            ShoppingError.ShowProductInfoError.NullProductId -> 
                Log.e(TAG, "Product ID is null")
            ShoppingError.ShowProductInfoError.NullUnitId -> 
                Log.e(TAG, "Unit ID is null")
            ShoppingError.ShowProductInfoError.NullProductWebUrl -> 
                Log.e(TAG, "Product URL is null")
        }
    }

    override fun onDestroy() {
        FireworkSdk.shopping.setOnShoppingErrorListener(null)
        super.onDestroy()
    }
}
```

### Error Types

```kotlin
sealed interface ShoppingError {
    sealed interface AddToCartError : ShoppingError {
        object NullProductId : AddToCartError
        object NullProductUnitId : AddToCartError
        object NullCartActionListener : AddToCartError
        object Timeout : AddToCartError
    }

    sealed interface ShowProductInfoError : ShoppingError {
        object FailedToLaunchUrl : ShowProductInfoError
        object NullProductId : ShowProductInfoError
        object NullUnitId : ShowProductInfoError
        object NullProductWebUrl : ShowProductInfoError
    }
}
```

## Programmatic Control

### Dismiss Shopping UI

Close the shopping interface programmatically:

```kotlin
FireworkSdk.shopping.dismiss()
```

### Open Shopping Cart

Open the shopping cart programmatically:

```kotlin
FireworkSdk.shopping.openShoppingCart()
```

## Related Documentation

* [Shoppable Videos](/firework-for-developers/android-sdk/integration-guide/shoppable-videos.md) - Overview and enabling Player Version 2
* [Product Cards](/firework-for-developers/android-sdk/integration-guide/shoppable-videos/product-cards.md) - Product card appearance and click behavior
* [Purchase Tracking](/firework-for-developers/android-sdk/integration-guide/shoppable-videos/purchase-tracking.md) - Conversion tracking
* [Product Hydration](/firework-for-developers/android-sdk/integration-guide/shoppable-videos/product-hydration.md) - Real-time product data integration