Digital Goods API

Usage of the API begins with a call to window.getDigitalGoodsService(), which might only be available in certain contexts (eg. HTTPS, app, browser, OS). If available, the method can be called with a service provider URL. The method returns a promise that is rejected if the given service provider is not available.

if (window.getDigitalGoodsService === undefined) {
  // Digital Goods API is not supported in this context.
  return;
}
try {
  const digitalGoodsService = await
      window.getDigitalGoodsService("https://example.com/billing");
  // Use the service here.
  ...
} catch (error) {
  // Our preferred service provider is not available.
  // Use a normal web-based payment flow.
  console.error("Failed to get service:", error.message);
  return;
}

const details = await digitalGoodsService
    .getDetails(['shiny_sword', 'gem', 'monthly_subscription']);
for (item of details) {
  const priceStr = new Intl.NumberFormat(
      locale,
      {style: 'currency', currency: item.price.currency}
    ).format(item.price.value);
  AddShopMenuItem(item.itemId, item.title, priceStr, item.description);
}

The getDetails() method returns server-side details about a given set of items, intended to be displayed to the user in a menu, so that they can see the available purchase options and prices without having to go through a purchase flow.

The returned ItemDetails sequence can be in any order and might not include an item if it doesn’t exist on the server (i.e. there is not a 1:1 correspondence between the input list and output).

The item ID is a string representing the primary key of the items, configured in the store server. There is no function to get a list of item IDs; those have to be hard-coded in the client code or fetched from the developer’s own server.

The item’s price is a PaymentCurrencyAmount containing the current price of the item in the user’s current region and currency. It is designed to be formatted for the user’s current locale using Intl.NumberFormat, as shown above.

For more information on the fields in the ItemDetails object, refer to the [ItemDetails dictionary] section below.

const details = await digitalGoodsService.getDetails(['monthly_subscription']);
const item = details[0];
new PaymentRequest(
  [{supportedMethods: 'https://example.com/billing',
    data: {itemId: item.itemId}}]);

The purchase flow itself uses the Payment Request API. We don’t show the full payment request code here, but note that the item ID for any items the user chooses to purchase can be sent in the data field of a methodData entry for the given payment method, in a manner specific to the store.

purchases = await digitalGoodsService.listPurchases();
for (p of purchases) {
  VerifyOnBackendAndGrantEntitlement(p.itemId, p.purchaseToken);
}

The listPurchases() method allows a client to get a list of items that are currently owned or purchased by the user. This might be necessary to check for entitlements (e.g. whether a subscription, promotional code, or permanent upgrade is active) or to recover from network interruptions during a purchase (e.g. item is purchased but not yet confirmed with a backend). The method returns item IDs and purchase tokens, which would typically be verified using a direct developer-to-provider API before granting entitlements.

const purchaseHistory = await digitalGoodsService.listPurchaseHistory();
for (p of purchaseHistory) {
  DisplayPreviousPurchase(p.itemId);
}

The listPurchaseHistory() method allows a client to list the latest purchases for each item type ever purchased by the user. Can include expired or consumed purchases. Some stores might not keep such history, in which case it would return the same data as the listPurchases() method.

digitalGoodsService.consume(purchaseToken);

Purchases that are designed to be purchased multiple times usually need to be marked as "consumed" before they can be purchased again by the user. An example of a consumable purchase is an in-game powerup that makes the player stronger for a short period of time. This can be done with the consume() method.

It is preferable to use a direct developer-to-provider API to consume purchases, if one is available, in order to more verifiably ensure that a purchase was used up.

<iframe
  src="https://sub.origin.example"
  allow="payment">
</iframe>

To indicate that a subdomain iframe is allowed to invoke the Digital Goods API, the allow attribute along with the "payment" keyword can be specified on the iframe element. Cross-origin iframes cannot invoke the Digital Goods API. The Permissions Policy specification provides further details and examples.

partial interface Window {
  [SecureContext] Promise<DigitalGoodsService> getDigitalGoodsService(
      DOMString serviceProvider);
};

[Exposed=Window, SecureContext] interface DigitalGoodsService {

  Promise<sequence<ItemDetails>> getDetails(sequence<DOMString> itemIds);

  Promise<sequence<PurchaseDetails>> listPurchases();

  Promise<sequence<PurchaseDetails>> listPurchaseHistory();

  Promise<undefined> consume(DOMString purchaseToken);
};

dictionary ItemDetails {
  required DOMString itemId;
  required DOMString title;
  required PaymentCurrencyAmount price;
  ItemType type;
  DOMString description;
  sequence<DOMString> iconURLs;
  DOMString subscriptionPeriod;
  DOMString freeTrialPeriod;
  PaymentCurrencyAmount introductoryPrice;
  DOMString introductoryPricePeriod;
  [EnforceRange] unsigned long long introductoryPriceCycles;
};

enum ItemType {
  "product",
  "subscription",
};

dictionary PurchaseDetails {
  required DOMString itemId;
  required DOMString purchaseToken;
};