Skip to main content

Commerce.Client

Class

The primary interface for interacting with the commerce system within a Lens.

  • Snapchat: not supported
  • SPECS: fully supported
  • Camera Kit Web: not supported
  • Camera Kit Mobile: not supported
  • SnapchatNot supported — Available on SPECS only
  • SPECSFully supported
  • Camera Kit WebNot supported — Available on SPECS only
  • Camera Kit MobileNot supported — Available on SPECS only

Platform details

  • Snapchat — Not supported — Available on SPECS only.

  • SPECS — Fully supported.

  • Camera Kit Web — Not supported — Available on SPECS only.

  • Camera Kit Mobile — Not supported — Available on SPECS only.

The primary interface for interacting with the commerce system within a Lens. Once built and configured using the CommerceKitModule, its methods are used to perform all key commerce operations. This includes initiating connections to the payment service, querying details about products, launching purchase flows for users, checking a user's purchase history, and acknowledging completed purchases.

Index

Extends

Methods

acknowledgePurchase()

acknowledgePurchase(purchaseToken): Promise<PurchaseResult>

SPECS

After a user makes a purchase, especially for consumable or subscription items, it's crucial to acknowledge that purchase. This tells the payment system that you have successfully delivered the purchased item or service to the user, and prevents the purchase from being automatically refunded.

purchaseToken: The unique identifier associated with the purchase requiring acknowledgment. This token is received as part of the Purchase object.

Returns: A Promise that resolves with a PurchaseResult object that tells if the purchase has been successfully acknowledged, canceled by the user, or if an error occurred.

Throws: A Error if the purchase has already been acknowledged, there's no network connection, or the service is unavailable.

Parameters

ParameterType
purchaseTokenstring

Returns

Promise<PurchaseResult>


cancelSubscription()

cancelSubscription(purchaseToken): Promise<PurchaseResult>

SPECS

Cancels an active subscription. The user keeps access until the end of the current billing period (Purchase#expiryTime); the subscription then expires instead of renewing. The updated state is reflected in later Client#queryPurchase results and purchase updates.

purchaseToken: The unique identifier of the subscription purchase to cancel, from the Purchase object.

Returns: A Promise that resolves to a PurchaseResult describing whether the cancellation request was accepted; operation failures are reported through the result's responseCode rather than a rejection.

Parameters

ParameterType
purchaseTokenstring

Returns

Promise<PurchaseResult>

Since

Lens Scripting Version 377

Example

const result = await client.cancelSubscription(purchase.token);
if (result.responseCode === Commerce.ResponseCode.Success) {
print("Subscription canceled; access continues until the period ends");
}

endConnection()

endConnection(): void

SPECS

Closes the connection to the payment service. It's good practice to call this method when you're finished with commerce operations or when your Lens is being closed to free up resources. There is no return value, and it doesn't throw exceptions, as it handles its own finalization.

Returns

void


getTypeName()

static getTypeName(): TypeName<Client>

SPECS

Returns the fully-qualified JavaScript type name for this class (for example, "Component.Camera"). This is a static accessor (no instance required) and returns the same value as the instance getTypeName().

Returns

TypeName<Client>

Overrides

ScriptObject.getTypeName


getTypeName()

getTypeName(): string

Returns the name of this object's type.

Returns

string

Inherited from

ScriptObject.getTypeName


isOfType()

isOfType(type): boolean

Returns true if the object matches or derives from the passed in type.

Parameters

ParameterType
typestring

Returns

boolean

Inherited from

ScriptObject.isOfType


isSame()

isSame(other): boolean

Returns true if this object is the same as other. Useful for checking if two references point to the same thing.

Parameters

ParameterType
otherScriptObject

Returns

boolean

Inherited from

ScriptObject.isSame


launchPurchaseFlow()

launchPurchaseFlow(productId, offerId?): Promise<PurchaseResult>

SPECS

Starts the process for a user to buy a specific product. It will typically open a user interface where the user can confirm their purchase and enter payment details.

productId: The unique identifier of the product you want the user to purchase. offerId: For a subscription, the optional offer identifier from SubscriptionOfferDetails#offerId. Pass the identifier back unchanged. Omit it for non-subscription products.

Returns: A Promise that resolves to a PurchaseResult object. This object indicates whether the purchase flow was successfully launched, canceled by the user, or if an error occurred.

Throws: A Error if the product is not found, the user's payment method is invalid, there's no network connection, or the service is unavailable.

Parameters

ParameterType
productIdstring
offerId?string

Returns

Promise<PurchaseResult>

Example

async function purchaseFirstOffer(client: Commerce.Client, productId: string) {
const products = await client.queryProductDetails([productId]);
const offer = products[0]?.subscriptionOfferDetails?.[0];
if (offer) {
const result = await client.launchPurchaseFlow(productId, offer.offerId);
print(`Purchase flow launched: ${result.responseCode}`);
}
}

queryProductDetails()

queryProductDetails(productIds): Promise<Product[]>

SPECS

Allows you to retrieve detailed information about specific products from the commerce platform. You provide a list of product IDs, and it returns all available details for those products, such as display name, description, and price.

productIds: An array of strings, where each string is a unique identifier for a product you want to query.

Returns: A Promise that resolves to an array of Product objects. Each object in the array contains comprehensive details about a product. If a product ID is not found, it might not be included in the returned array, or an error might be thrown.

Throws: A Error if a product is not found, there's no network connection, or the service is unavailable.

Parameters

ParameterType
productIdsstring[]

Returns

Promise<Product[]>


queryPurchase()

queryPurchase(productType): Promise<Purchase[]>

SPECS

Allows you to check the user's ownership or purchase status for products of a specific category. For example, you can use it to see all "non-consumable" items the user has purchased. It's useful for verifying if a user has already bought certain items or to retrieve details of their existing purchases based on how the product is classified.

productType: The type of products you want to look up, like "non-consumable"

Returns: A list of Purchase objects that represent all transactions for products of the specified type. If no purchases of that type are found, the list will be empty. If there's a problem connecting to the service, it will show an error.

Parameters

ParameterType
productTypeProductType

Returns

Promise<Purchase[]>


queryPurchaseHistory()

queryPurchaseHistory(): Promise<Purchase[]>

SPECS

Fetches a record of all purchases the user has made previously. This is particularly useful for ensuring that users retain access to products they've already bought, especially for non-consumable items or subscriptions. It can also help verify past transactions.

Returns: A Promise that resolves to an array of Purchase objects. Each object in the array represents a past transaction.

Throws: An Error if there's no network connection or if the service is unavailable.

Returns

Promise<Purchase[]>


startConnection()

startConnection(): Promise<void>

SPECS

Initiates a connection to the payment service, which is a necessary first step before you can perform any commerce-related operations like querying products or launching purchase flows.

Returns: A Promise that resolves with no value when the connection is successfully established.

Throws: A Error if there's no network connection or if the payment service is temporarily unavailable. You should handle these errors to provide appropriate feedback to the user.

Returns

Promise<void>