# Track Purchase Endpoint

# Track Purchase Endpoint

## Summary
The track purchase endpoint registers a purchase event so the Frak backend can send `PurchaseCompleted` interactions automatically once the purchase is confirmed via webhook.

## Requirements
- At least one identity source: a Frak Wallet session (`x-wallet-sdk-auth`) **or** a client id (`x-frak-client-id`). Anonymous users are supported.
- A `merchantId` — resolved explicitly, from session storage, or via the merchant lookup API.
- Purchase details: `customerId`, `orderId`, and `token`.

## Endpoint

```http
POST /user/track/purchase
```

### Headers
- `Accept`: `application/json`
- `Content-Type`: `application/json`
- `x-wallet-sdk-auth` (optional): JWT token from the user SDK session. Obtain via [`watchWalletStatus`](/developers/references/core-sdk/actions/functions/watchwalletstatus/) (`status.interactionToken`).
- `x-frak-client-id` (optional): Unique client identifier for anonymous user tracking. At least one of `x-wallet-sdk-auth` or `x-frak-client-id` must be present.

### Request Body
The request body should be a JSON object with the following properties:

- `customerId` (`string | number`): The ID of the customer making the purchase. Should match the value sent during purchase validation.
- `orderId` (`string | number`): The ID of the order being placed. Should match the value sent during purchase validation.
- `token` (`string`): A unique token related to the purchase.
- `merchantId` (`string`): The merchant identifier. Resolved from the explicit parameter, `frak-merchant-id` in session storage, or the merchant lookup API.

#### Example Request Body
```json
{
  "customerId": "123456",
  "orderId": "987654",
  "token": "unique-token-value",
  "merchantId": "your-merchant-id"
}
```

## Usage Example

Using the SDK (recommended):

```js
import { trackPurchaseStatus } from "@frak-labs/core-sdk/actions";

await trackPurchaseStatus({
  customerId: checkout.order.customer.id,
  orderId: checkout.order.id,
  token: checkout.token,
  merchantId: "your-merchant-id",
});
```

Direct `fetch` call:

```js
const interactionToken = window.sessionStorage.getItem("frak-wallet-interaction-token");
const clientId = localStorage.getItem("frak-client-id");

const headers = {
  'Accept': 'application/json',
  'Content-Type': 'application/json',
};
if (interactionToken) headers['x-wallet-sdk-auth'] = interactionToken;
if (clientId) headers['x-frak-client-id'] = clientId;

const payload = {
  customerId: checkout.order.customer.id,
  orderId: checkout.order.id,
  token: checkout.token,
  merchantId: "your-merchant-id",
};

fetch('https://backend.frak.id/user/track/purchase', {
  method: 'POST',
  headers,
  body: JSON.stringify(payload),
});
```

## Response
The endpoint responds with an acknowledgment of whether the purchase registration was successful.

## Related SDK Method
- [`trackPurchaseStatus`](/developers/references/core-sdk/actions/functions/trackpurchasestatus/) — wrapper around this endpoint with automatic merchant id resolution and identity header management.

## Notes
- `merchantId` is required. The SDK resolves it automatically from: explicit param → `frak-merchant-id` in session storage → backend lookup.
- At least one identity header (`x-wallet-sdk-auth` or `x-frak-client-id`) must be present. The SDK skips the request if neither is available.
- Ensure `customerId`, `orderId`, and `token` values match between the client and the purchase validation webhooks.