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

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 (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

{
  "customerId": "123456",
  "orderId": "987654",
  "token": "unique-token-value",
  "merchantId": "your-merchant-id"
}

Usage Example

Using the SDK (recommended):

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:

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 — 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.