> 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

Call `FireworkSdk.shopping.trackPurchase` after your application confirms a completed purchase. This reports analytics; it does not charge the customer, modify the cart, or complete checkout. Initialize the SDK before tracking purchases.

## Function Signature

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

## Parameters

| Parameter        | Type                  | Required | Meaning / default                                                                                                                    |
| ---------------- | --------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `orderId`        | `String`              | Yes      | Your order/transaction identifier.                                                                                                   |
| `value`          | `Double?`             | No       | Final order value in currency units; `null` reports 0.0.                                                                             |
| `currencyCode`   | `String?`             | No       | Currency code, for example `USD`; defaults to `USD`.                                                                                 |
| `countryCode`    | `String?`             | No       | Country code, for example `US`; defaults to the device locale's country when available. Supply it explicitly for the order's market. |
| `additionalInfo` | `Map<String, String>` | No       | Additional metadata; defaults to an empty map.                                                                                       |
| `products`       | `List<ProductItem>?`  | No       | Purchased line items; defaults to `null`.                                                                                            |
| `shippingPrice`  | `Double?`             | No       | Shipping cost; `null` when unavailable/not applicable.                                                                               |
| `subtotal`       | `Double?`             | No       | Merchandise subtotal before taxes and discounts; `null` reports 0.0.                                                                 |
| `totalDiscounts` | `Double?`             | No       | Total discount amount; defaults to `null`. Available since 6.34.1.                                                                   |

Use currency amounts, not integer cents. The SDK reports the values you supply; it does not calculate the final order value from line items, shipping, or discounts. Prefer explicit order totals and currency for meaningful reporting.

## ProductItem Structure

```kotlin
// Public data fields; use the SDK's ProductItem rather than declaring your own.
data class ProductItem(
    val productId: String,
    val price: Double,
    val quantity: Int,
    val productName: String? = null,
    val sku: String? = null,
)
```

| Property      | Required                | Meaning                                                                                                                 |
| ------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `productId`   | Yes for the constructor | Commerce product identifier. Used as the tracking SKU when `sku` is omitted.                                            |
| `price`       | Yes                     | Unit price in currency units.                                                                                           |
| `quantity`    | Yes                     | Number of units purchased.                                                                                              |
| `productName` | No                      | Human-readable product name; available since 6.34.1.                                                                    |
| `sku`         | No                      | Purchased SKU, typically identifying a variant; takes precedence over `productId` for tracking. Available since 6.34.1. |

### SKU-only Products

Since **6.34.1**, `ProductItem.fromSku` supports integrations that only have a SKU:

```kotlin
val item = ProductItem.fromSku(
    sku = "SHIRT-BLUE-M",
    price = 29.99,
    quantity = 2,
    productName = "Blue shirt, medium",
)
```

The factory returns a `ProductItem` and uses the supplied SKU for its required product identifier. You do not need to look up a separate Firework internal ID.

## Usage Examples

### Basic Purchase Tracking

```kotlin
import com.firework.sdk.FireworkSdk

FireworkSdk.shopping.trackPurchase(
    orderId = "ORDER_123456",
    value = 99.99,
    currencyCode = "USD",
    countryCode = "US",
)
```

### Complete Purchase with Products

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

val purchasedProducts = listOf(
    ProductItem(
        productId = "PROD_001",
        price = 29.99,
        quantity = 2,
        productName = "Blue shirt, medium",
        sku = "SHIRT-BLUE-M",
    ),
    ProductItem.fromSku(
        sku = "CAP-BLACK",
        price = 39.99,
        quantity = 1,
        productName = "Black cap",
    ),
)

// Merchandise 99.97 - discount 10.00 + shipping 9.99 = 99.96 (no tax in this example).
FireworkSdk.shopping.trackPurchase(
    orderId = "ORDER_789012",
    value = 99.96,
    currencyCode = "USD",
    countryCode = "US",
    additionalInfo = mapOf("coupon_code" to "SAVE10", "payment_method" to "credit_card"),
    products = purchasedProducts,
    shippingPrice = 9.99,
    subtotal = 99.97,
    totalDiscounts = 10.00,
)
```

### Minimal Configuration

Only `orderId` is required by the API:

```kotlin
FireworkSdk.shopping.trackPurchase(orderId = "ORDER_MIN_001")
```

This omits line items and reports default monetary values. Use the complete example when your checkout provides order details. Call tracking from your confirmed-purchase flow; do not infer a completed purchase from a shopping CTA click.

## Related Documentation

* [Shoppable Videos](/firework-for-developers/android-sdk/integration-guide/shoppable-videos.md) - Shopping overview
* [Cart & Checkout](/firework-for-developers/android-sdk/integration-guide/shoppable-videos/cart-and-checkout.md) - CTA callbacks and checkout integration
* [Analytics](/firework-for-developers/android-sdk/integration-guide/analytics.md) - Event tracking and analytics