FUN-2085: Pass attribution metadata through purchase results

api-report/purchases-js.api.json

@@ -4007,7 +4007,7 @@
             {
               "kind": "PropertySignature",
               "canonicalReference": "@revenuecat/purchases-js!PresentPaywallParams#customVariables:member",
-              "docComment": "/**\n * Custom variables to pass to the paywall at runtime, overriding defaults set in the RevenueCat dashboard.\n *\n * Variables must be defined in the dashboard first. Reference them in paywall text using the `custom.` prefix (e.g. `{{ custom.player_name }}`).\n *\n * @example\n * ```ts\n * presentPaywall({\n *   customVariables: {\n *     player_name: CustomVariableValue.string('Ada'),\n *     level: CustomVariableValue.string('42'),\n *   },\n * });\n * ```\n *\n */\n",
+              "docComment": "/**\n * Custom variables to pass to the paywall at runtime, overriding defaults set in the RevenueCat dashboard.\n *\n * Variables must be defined in the dashboard first. Reference them in paywall text using the `custom.` prefix (e.g. `{{ custom.player_name }}`).\n *\n * @example\n * ```ts\n * presentPaywall({\n *   customVariables: {\n *     player_name: CustomVariableValue.string('Ada'),\n *     level: CustomVariableValue.number(42),\n *     is_premium: CustomVariableValue.boolean(true),\n *   },\n * });\n * ```\n *\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",

api-report/purchases-js.api.md

@@ -397,6 +397,7 @@ export interface PurchaseResult {
     readonly operationSessionId: string;
     readonly redemptionInfo: RedemptionInfo | null;
     readonly storeTransaction: StoreTransaction;
+    /* Excluded from this release type: attributionMetadata */
 }
 
 // @public

src/entities/purchase-result.ts

@@ -26,6 +26,12 @@ export interface PurchaseResult {
    * The store transaction associated with the purchase.
    */
   readonly storeTransaction: StoreTransaction;
+
+  /**
+   * Opaque attribution metadata returned by the checkout status response.
+   * @internal
+   */
+  readonly attributionMetadata?: Record<string, unknown>;
 }
 
 /**

src/helpers/purchase-operation-helper.ts

@@ -113,6 +113,7 @@ export interface OperationSessionSuccessfulResult {
   storeTransactionIdentifier: string;
   productIdentifier: string;
   purchaseDate: Date;
+  attributionMetadata?: Record<string, unknown>;
 }
 
 export class PurchaseOperationHelper {
@@ -333,6 +334,8 @@ export class PurchaseOperationHelper {
                   storeTransactionIdentifier: storeTransactionIdentifier,
                   productIdentifier: productIdentifier,
                   purchaseDate: purchaseDate,
+                  attributionMetadata:
+                    operationResponse.attribution_metadata ?? undefined,
                 });
                 return;
               case CheckoutSessionStatus.Failed:

src/main.ts

@@ -950,6 +950,7 @@ export class Purchases {
           customerInfo: await this._getCustomerInfoForUserId(appUserId),
           redemptionInfo: operationResult.redemptionInfo,
           operationSessionId: operationResult.operationSessionId,
+          attributionMetadata: operationResult.attributionMetadata,
           storeTransaction: {
             storeTransactionId: operationResult.storeTransactionIdentifier,
             productIdentifier: rcPackage.webBillingProduct.identifier,
@@ -1492,6 +1493,7 @@ export class Purchases {
         customerInfo: await this._getCustomerInfoForUserId(appUserId),
         redemptionInfo: operationResult.redemptionInfo,
         operationSessionId: operationResult.operationSessionId,
+        attributionMetadata: operationResult.attributionMetadata,
         storeTransaction: {
           storeTransactionId: operationResult.storeTransactionIdentifier,
           productIdentifier: rcPackage.webBillingProduct.identifier,

src/networking/responses/checkout-status-response.ts

@@ -34,4 +34,5 @@ export interface CheckoutStatusInnerResponse {
 
 export interface CheckoutStatusResponse {
   readonly operation: CheckoutStatusInnerResponse;
+  readonly attribution_metadata?: Record<string, unknown>;
 }

src/paddle/paddle-service.ts

@@ -310,6 +310,8 @@ export class PaddleService {
                   storeTransactionIdentifier: storeTransactionIdentifier ?? "",
                   productIdentifier: productIdentifier,
                   purchaseDate: purchaseDate ?? new Date(),
+                  attributionMetadata:
+                    operationResponse.attribution_metadata ?? undefined,
                 });
                 return;
               case CheckoutSessionStatus.Failed:

src/tests/helpers/purchase-operation-helper.test.ts

@@ -716,6 +716,14 @@ describe("PurchaseOperationHelper", () => {
       }),
     );
     const getCheckoutStatusResponse: CheckoutStatusResponse = {
+      attribution_metadata: {
+        meta: {
+          canonical_event_id: "fb-order-id",
+          canonical_event_name: "Subscribe",
+          workflow_event_id: "workflow-event-id",
+          workflow_event_name: "workflows_purchase",
+        },
+      },
       operation: {
         status: CheckoutSessionStatus.Succeeded,
         is_expired: false,
@@ -753,6 +761,14 @@ describe("PurchaseOperationHelper", () => {
     );
     expect(pollResult.productIdentifier).toEqual("test-product_identifier");
     expect(pollResult.purchaseDate).toEqual(new Date("2025-07-15T04:21:11Z"));
+    expect(pollResult.attributionMetadata).toEqual({
+      meta: {
+        canonical_event_id: "fb-order-id",
+        canonical_event_name: "Subscribe",
+        workflow_event_id: "workflow-event-id",
+        workflow_event_name: "workflows_purchase",
+      },
+    });
   });
 
   test("pollCurrentPurchaseForCompletion success with missing info in poll returns error", async () => {

src/tests/main.test.ts

@@ -835,6 +835,59 @@ describe("Purchases.purchase()", () => {
     expect(performStripePurchaseSpy).not.toHaveBeenCalled();
   });
 
+  test("passes attributionMetadata through the purchase result", async () => {
+    const purchases = configurePurchases();
+    const customerInfo = { originalAppUserId: "test-user-id" } as CustomerInfo;
+    type PurchasesWithCustomerInfoGetter = Purchases & {
+      _getCustomerInfoForUserId: (appUserId: string) => Promise<CustomerInfo>;
+    };
+    const purchasesWithCustomerInfoGetter =
+      purchases as PurchasesWithCustomerInfoGetter;
+    vi.spyOn(
+      purchasesWithCustomerInfoGetter,
+      "_getCustomerInfoForUserId",
+    ).mockResolvedValue(customerInfo);
+
+    const resolve = vi.fn();
+    const onFinished = purchases["createCheckoutOnFinishedHandler"](
+      resolve,
+      "test-app-user-id",
+      createMonthlyPackageMock(),
+    );
+
+    const attributionMetadata = {
+      meta: {
+        canonical_event_id: "fb-order-id",
+        canonical_event_name: "Subscribe",
+        workflow_event_id: "workflow-event-id",
+        workflow_event_name: "workflows_purchase",
+      },
+    };
+
+    await onFinished({
+      redemptionInfo: null,
+      operationSessionId: "test-operation-session-id",
+      storeTransactionIdentifier: "test-store-transaction-id",
+      productIdentifier: "test-product-id",
+      purchaseDate: new Date("2024-01-01T00:00:00.000Z"),
+      attributionMetadata,
+    });
+
+    expect(resolve).toHaveBeenCalledWith(
+      expect.objectContaining({
+        customerInfo,
+        redemptionInfo: null,
+        operationSessionId: "test-operation-session-id",
+        attributionMetadata,
+        storeTransaction: {
+          storeTransactionId: "test-store-transaction-id",
+          productIdentifier: "monthly",
+          purchaseDate: new Date("2024-01-01T00:00:00.000Z"),
+        },
+      }),
+    );
+  });
+
   test("throws error if api key is not provided", () => {
     // @ts-expect-error - we want to test the error case
     expect(() => Purchases.configure()).toThrowError(PurchasesError);