> 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/purchase-tracking.md).

# Purchase Tracking

Track completed purchases for analytics and conversion tracking.

## Function Signature

```kotlin
fun trackPurchase(
    orderId: String,
    value: Double?,
    currencyCode: String?,
    countryCode: String?,
    additionalInfo: Map<String, String>,
    products: List<ProductItem>?,
    shippingPrice: Double?,
    subtotal: Double?,
)
```

## Parameters

| Parameter        | Type                  | Required | Description                                       |
| ---------------- | --------------------- | -------- | ------------------------------------------------- |
| `orderId`        | `String`              | ✅        | Unique identifier for the order/transaction       |
| `value`          | `Double?`             | ❌        | Total transaction value (defaults to 0.0 if null) |
| `currencyCode`   | `String?`             | ❌        | Currency code (defaults to "USD" if null)         |
| `countryCode`    | `String?`             | ❌        | Country code (defaults to device locale if null)  |
| `additionalInfo` | `Map<String, String>` | ✅        | Additional custom tracking information            |
| `products`       | `List<ProductItem>?`  | ❌        | List of purchased products                        |
| `shippingPrice`  | `Double?`             | ❌        | Shipping cost for the order                       |
| `subtotal`       | `Double?`             | ❌        | Subtotal before shipping and taxes                |

## ProductItem Structure

```kotlin
data class ProductItem(
    val productId: String,    // External product identifier
    val price: Double,        // Price of the product
    val quantity: Int,        // Quantity purchased
)
```

## Usage Examples

### Basic Purchase Tracking

```kotlin
import com.firework.FireworkSdk
import com.firework.common.tracking.ProductItem

FireworkSdk.shopping.trackPurchase(
    orderId = "ORDER_123456",
    value = 99.99,
    currencyCode = "USD",
    countryCode = "US",
    additionalInfo = emptyMap(),
    products = null,
    shippingPrice = null,
    subtotal = null
)
```

### Complete Purchase with Products

```kotlin
import com.firework.FireworkSdk
import com.firework.common.tracking.ProductItem
import java.util.Locale

// Create product items
val purchasedProducts = listOf(
    ProductItem(
        productId = "PROD_001",
        price = 29.99,
        quantity = 2
    ),
    ProductItem(
        productId = "PROD_002", 
        price = 39.99,
        quantity = 1
    )
)

// Track complete purchase
FireworkSdk.shopping.trackPurchase(
    orderId = "ORDER_789012",
    value = 109.97,
    currencyCode = "USD",
    countryCode = Locale.getDefault().country,
    additionalInfo = mapOf(
        "customer_id" to "CUST_12345",
        "campaign_id" to "SUMMER_SALE_2024",
        "payment_method" to "credit_card"
    ),
    products = purchasedProducts,
    shippingPrice = 9.99,
    subtotal = 99.98
)
```

### Minimal Configuration

```kotlin
// Track with minimal required parameters
FireworkSdk.shopping.trackPurchase(
    orderId = "ORDER_MIN_001",
    value = null,         // Defaults to 0.0
    currencyCode = null,  // Defaults to "USD"
    countryCode = null,   // Defaults to device locale
    additionalInfo = emptyMap(),
    products = null,
    shippingPrice = null,
    subtotal = null
)
```

## Related Documentation

* [Shoppable Videos](/firework-for-developers/android-sdk/integration-guide/shoppable-videos.md) - Overview and enabling Player Version 2
* [Cart & Checkout](/firework-for-developers/android-sdk/integration-guide/shoppable-videos/cart-and-checkout.md) - Shopping cart, CTA button, and PDP configuration
* [Analytics](/firework-for-developers/android-sdk/integration-guide/analytics.md) - Event tracking and analytics