Commerce.Client
ClassThe 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
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
Methods
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
| Parameter | Type |
|---|---|
purchaseToken | string |
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
| Parameter | Type |
|---|---|
purchaseToken | string |
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()
staticgetTypeName():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
getTypeName()
getTypeName():
string
Returns the name of this object's type.
Returns
string
Inherited from
isOfType()
isOfType(
type):boolean
Returns true if the object matches or derives from the passed in type.
Parameters
| Parameter | Type |
|---|---|
type | string |
Returns
boolean
Inherited from
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
| Parameter | Type |
|---|---|
other | ScriptObject |
Returns
boolean
Inherited from
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
| Parameter | Type |
|---|---|
productId | string |
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
| Parameter | Type |
|---|---|
productIds | string[] |
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
| Parameter | Type |
|---|---|
productType | ProductType |
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>