Add support for Set App Account Token endpoint

Author: Riyaz Panjwani

index.ts

@@ -3,6 +3,7 @@
 import fetch from 'node-fetch';
 import { CheckTestNotificationResponse, CheckTestNotificationResponseValidator } from './models/CheckTestNotificationResponse';
 import { ConsumptionRequest } from './models/ConsumptionRequest';
+import { UpdateAppAccountTokenRequest } from './models/UpdateAppAccountTokenRequest'
 import { Environment } from './models/Environment';
 import { ExtendRenewalDateRequest } from './models/ExtendRenewalDateRequest';
 import { ExtendRenewalDateResponse, ExtendRenewalDateResponseValidator } from './models/ExtendRenewalDateResponse';
@@ -24,6 +25,7 @@ export { AccountTenure } from "./models/AccountTenure"
 export { AutoRenewStatus } from './models/AutoRenewStatus'
 export { CheckTestNotificationResponse } from './models/CheckTestNotificationResponse'
 export { ConsumptionRequest } from './models/ConsumptionRequest'
+export { UpdateAppAccountTokenRequest } from './models/UpdateAppAccountTokenRequest'
 export { ConsumptionStatus } from './models/ConsumptionStatus'
 export { Data } from './models/Data'
 export { DeliveryStatus } from './models/DeliveryStatus'
@@ -375,6 +377,18 @@ export class AppStoreServerAPIClient {
         await this.makeRequest("/inApps/v1/transactions/consumption/" + transactionId, "PUT", {}, consumptionRequest, null);
     }
 
+    /**
+     * Sets the app account token value for a purchase the customer makes outside your app, or updates its value in an existing transaction.
+     *
+     * @param originalTransactionId The original transaction identifier of the transaction to receive the app account token update.
+     * @param updateAppAccountTokenRequest The request body that contains a valid app account token value.
+     * @throws APIException If a response was returned indicating the request could not be processed.
+     * {@link https://developer.apple.com/documentation/appstoreserverapi/set-app-account-token Set App Account Token}
+     */
+    public async setAppAccountToken(originalTransactionId: string, updateAppAccountTokenRequest: UpdateAppAccountTokenRequest): Promise<void> {
+        await this.makeRequest("/inApps/v1/transactions/" + originalTransactionId + "/appAccountToken", "PUT", {}, updateAppAccountTokenRequest, null);
+    }
+
     private createBearerToken(): string {
         const payload = {
             bid: this.bundleId
@@ -694,6 +708,27 @@ export enum APIError {
      */
     APP_TRANSACTION_ID_NOT_SUPPORTED_ERROR = 4000048,
 
+    /**
+     * An error that indicates the app account token value is not a valid UUID.
+     *
+     * {@link https://developer.apple.com/documentation/appstoreserverapi/invalidappaccounttokenuuiderror InvalidAppAccountTokenUUIDError}
+     */
+    INVALID_APP_ACCOUNT_TOKEN_UUID_ERROR = 4000183,
+
+    /**
+     * An error that indicates the transaction is for a product the customer obtains through Family Sharing, which the endpoint doesn’t support.
+     *
+     * {@link https://developer.apple.com/documentation/appstoreserverapi/familytransactionnotsupportederror FamilyTransactionNotSupportedError}
+     */
+    FAMILY_TRANSACTION_NOT_SUPPORTED_ERROR = 4000185,
+
+    /**
+     * An error that indicates the endpoint expects an original transaction identifier.
+     *
+     * {@link https://developer.apple.com/documentation/appstoreserverapi/transactionidisnotoriginaltransactioniderror TransactionIdIsNotOriginalTransactionIdError}
+     */
+    TRANSACTION_ID_IS_NOT_ORIGINAL_TRANSACTION_ID_ERROR = 4000187,
+
     /**
      * An error that indicates the subscription doesn't qualify for a renewal-date extension due to its subscription state.
      * 

models/UpdateAppAccountTokenRequest.ts

@@ -0,0 +1,16 @@
+// Copyright (c) 2025 Apple Inc. Licensed under MIT License.
+
+/**
+ * The request body that contains an app account token value.
+ *
+ * {@link https://developer.apple.com/documentation/appstoreserverapi/updateappaccounttokenrequest UpdateAppAccountTokenRequest}
+ */
+export interface UpdateAppAccountTokenRequest {
+
+    /**
+     * The UUID that an app optionally generates to map a customer's in-app purchase with its resulting App Store transaction.
+     *
+     * {@link https://developer.apple.com/documentation/appstoreserverapi/appaccounttoken appAccountToken}
+     **/
+    appAccountToken: string
+}

tests/resources/models/familyTransactionNotSupportedError.json

@@ -0,0 +1,4 @@
+{
+  "errorCode": 4000185,
+  "errorMessage": "Invalid request. Family Sharing transactions aren't supported by this endpoint."
+}

tests/resources/models/invalidAppAccountTokenUUIDError.json

@@ -0,0 +1,4 @@
+{
+  "errorCode": 4000183,
+  "errorMessage": "Invalid request. The app account token field must be a valid UUID."
+}

tests/resources/models/transactionIdNotOriginalTransactionId.json

@@ -0,0 +1,4 @@
+{
+  "errorCode": 4000187,
+  "errorMessage": "Invalid request. The transaction ID provided is not an original transaction ID."
+}

tests/unit-tests/api_client.test.ts

@@ -2,6 +2,7 @@
 
 import { AccountTenure } from "../../models/AccountTenure";
 import { ConsumptionRequest } from "../../models/ConsumptionRequest";
+import { UpdateAppAccountTokenRequest } from "../../models/UpdateAppAccountTokenRequest";
 import { ConsumptionStatus } from "../../models/ConsumptionStatus";
 import { DeliveryStatus } from "../../models/DeliveryStatus";
 import { Environment } from "../../models/Environment";
@@ -556,4 +557,88 @@ describe('The api client ', () => {
             expect(error.message).toBe("Xcode is not a supported environment for an AppStoreServerAPIClient")
          }
      })
+
+    it('calls setAppAccountToken', async () => {
+        const client = getAppStoreServerAPIClient("", 200, (path: string, parsedQueryParameters: URLSearchParams, method: string, stringBody: string | undefined, headers: { [key: string]: string; }) => {
+            expect("PUT").toBe(method)
+            expect("/inApps/v1/transactions/49571273/appAccountToken").toBe(path)
+            expect(parsedQueryParameters.entries.length).toBe(0)
+
+            expect(stringBody).toBeTruthy()
+            const body = JSON.parse(stringBody!)
+            expect("7389a31a-fb6d-4569-a2a6-db7d85d84813").toBe(body.appAccountToken)
+        });
+
+        const updateAppAccountTokenRequest: UpdateAppAccountTokenRequest = {
+            appAccountToken: "7389a31a-fb6d-4569-a2a6-db7d85d84813"
+        }
+
+        client.setAppAccountToken("49571273", updateAppAccountTokenRequest);
+    })
+
+    it('calls setAppAccountToken but receives an invalid UUID error', async () => {
+        const client = getClientWithBody("tests/resources/models/invalidAppAccountTokenUUIDError.json", (path: string, parsedQueryParameters: URLSearchParams, method: string, stringBody: string | undefined, headers: { [key: string]: string; }) => {
+            expect("PUT").toBe(method)
+            expect("/inApps/v1/transactions/49571273/appAccountToken").toBe(path)
+            expect(parsedQueryParameters.entries.length).toBe(0)
+            expect(stringBody).toBeTruthy()
+        }, 400);
+
+        try {
+            const updateAppAccountTokenRequest: UpdateAppAccountTokenRequest = {
+                appAccountToken: "abc"
+            }
+            await client.setAppAccountToken("49571273", updateAppAccountTokenRequest);
+            fail('this test call is expected to throw')
+        } catch (e) {
+            let error = e as APIException
+            expect(error.httpStatusCode).toBe(400)
+            expect(error.apiError).toBe(4000183)
+            expect(error.errorMessage).toBe("Invalid request. The app account token field must be a valid UUID.")
+        }
+    })
+
+    it('calls setAppAccountToken but receives family transaction not supported error', async () => {
+        const client = getClientWithBody("tests/resources/models/familyTransactionNotSupportedError.json", (path: string, parsedQueryParameters: URLSearchParams, method: string, stringBody: string | undefined, headers: { [key: string]: string; }) => {
+            expect("PUT").toBe(method)
+            expect("/inApps/v1/transactions/1234/appAccountToken").toBe(path)
+            expect(parsedQueryParameters.entries.length).toBe(0)
+            expect(stringBody).toBeTruthy()
+        }, 400);
+
+        try {
+            const updateAppAccountTokenRequest: UpdateAppAccountTokenRequest = {
+                appAccountToken: "7389a31a-fb6d-4569-a2a6-db7d85d84813"
+            }
+            await client.setAppAccountToken("1234", updateAppAccountTokenRequest);
+            fail('this test call is expected to throw')
+        } catch (e) {
+            let error = e as APIException
+            expect(error.httpStatusCode).toBe(400)
+            expect(error.apiError).toBe(4000185)
+            expect(error.errorMessage).toBe("Invalid request. Family Sharing transactions aren't supported by this endpoint.")
+        }
+    })
+
+    it('calls setAppAccountToken but transactionId not originalTransactionId error', async () => {
+        const client = getClientWithBody("tests/resources/models/transactionIdNotOriginalTransactionId.json", (path: string, parsedQueryParameters: URLSearchParams, method: string, stringBody: string | undefined, headers: { [key: string]: string; }) => {
+            expect("PUT").toBe(method)
+            expect("/inApps/v1/transactions/1234/appAccountToken").toBe(path)
+            expect(parsedQueryParameters.entries.length).toBe(0)
+            expect(stringBody).toBeTruthy()
+        }, 400);
+
+        try {
+            const updateAppAccountTokenRequest: UpdateAppAccountTokenRequest = {
+                appAccountToken: "7389a31a-fb6d-4569-a2a6-db7d85d84813"
+            }
+            await client.setAppAccountToken("1234", updateAppAccountTokenRequest);
+            fail('this test call is expected to throw')
+        } catch (e) {
+            let error = e as APIException
+            expect(error.httpStatusCode).toBe(400)
+            expect(error.apiError).toBe(4000187)
+            expect(error.errorMessage).toBe("Invalid request. The transaction ID provided is not an original transaction ID.")
+        }
+    })
 })