app-store-server-api

When testing with StoreKit in Xcode, transactions are signed by a local CA instead of Apple. To verify these, you must pass the SHA256 fingerprint of the Xcode root certificate to the decoding functions.

Use APPLE_ROOT_CA_G3_FINGERPRINT for production and your local fingerprint for development.

import { decodeTransactions, APPLE_ROOT_CA_G3_FINGERPRINT } from "app-store-server-api"

const LOCAL_ROOT_FINGERPRINT = "AA:BB:CC:DD:..."
const fingerprint = process.env.NODE_ENV === "production" 
  ? APPLE_ROOT_CA_G3_FINGERPRINT 
  : LOCAL_ROOT_FINGERPRINT

const transactions = await decodeTransactions(response.signedTransactions, fingerprint)

Install the package via npm to use the App Store Server API client in your Node.js project.

Requirements:

• Node.js 22 or newer
• This package is ESM-only. Use import or dynamic import() if using CommonJS.

npm install app-store-server-api

When calling decoding functions, you can optionally pass a rootCertFingerprint string. This allows you to override the default Apple G3 CA fingerprint validation. This is useful for testing environments or when you need to validate against a specific root certificate fingerprint.

If the certificate chain validation fails (e.g., expired certificates, invalid issuer chain, or mismatched root fingerprint), the functions will throw a CertificateValidationError.

You can request a test notification from Apple and then check its status using the token provided in the request response.

// Request a test notification
const response = await api.requestTestNotification()
const token = response.testNotificationToken

// Check the status of that notification
const status = await api.getTestNotificationStatus(token)

Retrieve the subscription statuses for an originalTransactionId. To access the actual transaction and renewal details, you must decode the signed information using decodeTransaction and decodeRenewalInfo.

import { decodeTransaction, decodeRenewalInfo } from "app-store-server-api"

const response = await api.getSubscriptionStatuses(originalTransactionId)

// Find the specific transaction
const item = response.data[0].lastTransactions.find(item => item.originalTransactionId === originalTransactionId)

// Decode the signed info
const transactionInfo = await decodeTransaction(item.signedTransactionInfo)
const renewalInfo = await decodeRenewalInfo(item.signedRenewalInfo)

To use the API, create an instance of AppStoreServerAPI. You will need your private key, Key ID, Issuer ID, and App Bundle ID. You must also specify the Environment (e.g., Environment.Production).

Note on Issuer ID: To obtain your Issuer ID, you must first create an API key for App Store Connect (not the App Store Server API). The ID will appear after the first key is created.

import { AppStoreServerAPI, Environment } from "app-store-server-api"

const KEY = `-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----`
const KEY_ID = "ABCD123456"
const ISSUER_ID = "91fa5999-7b54-4363-a2a8-265363fa6cbe"
const APP_BUNDLE_ID = "com.yourcompany.app"

const api = new AppStoreServerAPI(KEY, KEY_ID, ISSUER_ID, APP_BUNDLE_ID, Environment.Production)

Check the status of an order using an orderId. Use the OrderLookupStatus enum to verify if the order is valid before processing the transactions.

import { OrderLookupStatus, decodeTransactions } from "app-store-server-api"

const response = await api.lookupOrder(orderId)

if (response.status === OrderLookupStatus.Valid) {
  const transactions = await decodeTransactions(response.signedTransactions)
  // ... handle transactions
}

Fetch a history of notifications. You must provide a startDate and endDate (in milliseconds). The earliest supported start date is June 6th, 2022. If hasMore is true, use history.paginationToken to fetch subsequent pages.

const response = await api.getNotificationHistory({
  startDate: 1654466400000, // June 6th 2022
  endDate: new Date().getTime()
})

if (response.hasMore) {
  // Use response.paginationToken for the next request
}

Retrieve the transaction history for a specific originalTransactionId. The response can be paginated using the revision field if hasMore is true.

Use decodeTransactions to verify that the transactions were signed by Apple and to access their contents.

import { decodeTransactions, ProductTypeParameter, SortParameter } from "app-store-server-api"

// Basic lookup
const response = await api.getTransactionHistory(originalTransactionId)
const transactions = await decodeTransactions(response.signedTransactions)

// Pagination
if (response.hasMore) {
  const nextResponse = await api.getTransactionHistory(originalTransactionId, { revision: response.revision })
}

// Using filters and sort options
const filteredResponse = await api.getTransactionHistory(originalTransactionId, {
  productType: ProductTypeParameter.AutoRenewable,
  sort: SortParameter.Descending
})

When interacting with the API, you may encounter specific error types exported by the library:

• AppStoreError: Represents errors returned by the App Store Server API.
• CertificateValidationError: Represents errors occurring during the validation of Apple's certificates.

import { AppStoreError, CertificateValidationError } from 'app-store-server-api';

try {
  // API call
} catch (error) {
  if (error instanceof AppStoreError) {
    // Handle API error
  } else if (error instanceof CertificateValidationError) {
    // Handle certificate error
  }
}

Use these methods to retrieve details about specific transactions or a user's transaction history.

• getTransactionHistory(transactionId, query): Retrieves the transaction history for a specific ID. Accepts an optional TransactionHistoryQuery object.
• getTransactionInfo(transactionId): Retrieves detailed information for a single transaction.
• getAppTransactionInfo(transactionId): Retrieves app-level transaction info using an originalTransactionId, transactionId, or appTransactionId.

// Get history
const history = await api.getTransactionHistory('12345', { /* query params */ });

// Get specific transaction info
const info = await api.getTransactionInfo('12345');

// Get app transaction info
const appInfo = await api.getAppTransactionInfo('12345');