Commerce

Commerce is an optional service that validates in-app purchases and subscriptions server-side and gives your app a single, store-agnostic question to ask: does this user have this entitlement right now? It answers that question for a customer on every platform at once, so a subscription bought on an iPhone unlocks the same account on Android, on the desktop and on the web. On top of entitlements it adds offerings you configure remotely, paywalls and a customer center you design in the console, targeting and experiments, lifecycle webhooks, integrations and revenue reports.

Commerce wraps the Purchase API (see the monetization chapter) and doesn’t replace it. Purchases still go through the platform store, and code that talks to Purchase directly keeps working unchanged. When the service can’t answer — commerce is switched off in the build, the device is offline, or the account is over its plan — the app falls back to the store’s own receipts, so a paying user keeps access.

Codename One doesn’t process payments and never touches your money. The stores, or your own Stripe or Paddle account for web purchases, do. Commerce is infrastructure that sits beside the money flow.

Every cloud build is ready to use the service: there is nothing to add to the build. Three steps take you from nothing to a working paywall.

The paywall sells the packages of the offering and the service validates the purchase. From then on isEntitled("pro") returns true, on this device and on every other one the customer signs in to. Pass a PaywallListener instead of null to react the moment the purchase is confirmed, as the paywall section shows.

The core idea is the entitlement: an abstract access right such as pro or remove_ads. Your code checks the entitlement and never a store product:

The Products page of the console holds the mapping. Each row names a store, a product id in that store and the entitlement the product grants. One entitlement usually has several products: a monthly and an annual subscription in each store, and perhaps a lifetime purchase. Changing the entitlement of a product moves the product’s existing grants with it, so customers who already bought it follow the new mapping.

An entitlement is active when any of its granting products is active. A promotional grant and a paid subscription, or a sandbox and a production purchase, can both map to pro without one hiding the other. Access is decided by a single rule — the latest expiry over the active grants, evaluated against the service’s clock — so a device clock set back can’t extend it. Everything else (will-renew, billing stage, period type, family sharing) is advisory and never removes access by itself.

Installing a receipt store is part of the setup. Purchase submits pending purchases and reloads its receipt list only when one is installed, so without it the service is never handed a receipt from this device. On iOS isSubscriptionSupported() returns false until one is installed, so subscriptions don’t start at all. The monetization chapter builds a store you can use here.

You can still drive purchases by product id through the manager. These calls delegate to the Purchase API:

refresh() validates the device’s receipts with the service and then asks the service what the customer is entitled to. The customer is asked even when the device holds no receipt at all, which is what unlocks a purchase made on another platform or an entitlement granted from the console. It’s a blocking network call, so keep it off the EDT. Call it when the app starts and when it returns to the foreground:

You don’t need to call refresh() after a purchase. When Purchase finishes synchronizing receipts, the manager refreshes by itself in the background and the customer-info listeners hear the result. If you synchronize receipts yourself and want to act as soon as the answer is in, chain the refresh off the synchronization:

getCustomerInfo() returns everything the service last said about the customer. It never returns null and never touches the network:

Each EntitlementInfo carries these fields:

CustomerInfo also lists the active subscriptions by product id, the customer’s attributes, the virtual currency balances and a management address for the subscription.

To follow changes, add a listener. It’s called on the EDT whenever the customer information changes: after a refresh, a purchase, a restore, a sign-in or a sign-out.

The last answer the service gave is stored on the device, per customer. After a cold start isEntitled and getCustomerInfo answer from it at once, before any network call and with no network at all. A stored entitlement is reported exactly as it was stored, even when its expiry date has passed by the device’s clock. The device clock is the user’s to set, so only the service decides when an entitlement ends, and it does so on the next refresh().

isDegraded() is true after a call that couldn’t get an answer the app can trust: the service was unreachable, the response failed its signature check, or the account is over the validated volume of its plan. While it’s true, the stored answer stays in place, and isEntitled also accepts the store’s own receipt, treating the entitlement id as a subscription product id. A paying user is therefore not locked out while the network is down.

When commerce isn’t enabled in the build, or the manager is degraded, you can check the granting product yourself, as the receipt synchronization example does. Don’t do it when the service answered no: a refunded or revoked receipt still looks active on the device, and treating that as a grant unlocks the app after the service denied it.

The service keys everything on an app user id. Until you set one, the manager generates an anonymous id and persists it, so entitlements survive restarts on the device.

When the user signs in to your own account system, call logIn with your stable id for that user:

Signing in moves purchases from the device’s own anonymous id to the signed-in id, and only from there. It never moves purchases from one signed-in account to another, so logging in with someone else’s id doesn’t take their purchases. Pick app user ids that can’t be guessed, such as a random identifier your account system issues, rather than an email address or a counter. The original anonymous id stays available through CustomerInfo.getOriginalAppUserId(). logIn returns false and leaves the previous id in place when the service didn’t accept the change, and you can call it again.

setAppUserId sets the id without telling the service anything. Use it when the id is known before the first purchase, for example when your app requires an account before it shows anything. Use logIn whenever an anonymous customer might already own something.

A store purchase is tied to the store account on the device, not to your app user id. When a purchase is restored or validated under a different id than the one that owns it, for example after another user signs in on the same device and restores, the transfer policy of the app decides who keeps it. Set it on the App settings page of the console:

Every move is reported to your backend as a TRANSFER webhook event.

logOut() forgets the current customer. A new anonymous id is generated and the customer information becomes empty, so the next user of the device doesn’t inherit the previous user’s entitlements. Nothing is sent to the service. Refresh afterward to pick up what the store account on the device still owns:

restore() asks the store to restore the purchases of the store account on the device, on platforms that support it. The restored receipts reach the service through the receipt synchronization that follows, and the manager refreshes by itself. The customer-info listeners hear the result. The built-in paywall and the customer center both have a restore button that calls it.

An offering is the set of things you’re selling at one moment: "the standard plans," "the holiday sale." A package is one entry of an offering — a store product together with the role it plays, such as the monthly plan. Because offerings live in the console, you change what the app sells, and at what price points, without shipping an update.

On the Offerings page, create an offering and add packages to it. Each package has:

Mark one offering as the current one. That’s the offering getCurrent() returns unless a targeting rule or an experiment selects another.

getOfferings is a blocking network call. The last answer is stored on the device and is what the call returns when the service can’t be reached, so a paywall still opens offline. It never returns null. The result is empty, and getCurrent() is null, when commerce isn’t enabled in the build or there has never been an answer.

After a fresh answer the manager asks the store for the products of the packages, where the platform lists products, and attaches each to its package. getProduct() then carries the store’s localized price and name. On a platform whose store doesn’t list products it stays null.

Offering has shortcuts for the standard types — getMonthly(), getAnnual(), getWeekly() and getLifetime() — and getPackage(id) for any other. getMetadata() returns the free-form values you attached to the offering in the console, which is a convenient place for a headline or a feature flag that should change with the offering.

A placement is a named place in your app that sells something: "onboarding", "settings", "export_limit". Pass it to getOfferings(String). A targeting rule in the console can give a placement an offering of its own, so the upsell after onboarding and the one behind a locked feature can differ without a code change. A placement with no rule gets the current offering.

isEligibleForIntro() tells you whether this customer may still take the free trial or introductory price of a package. The service computes it from the customer’s purchase history across platforms, so a customer who used a trial on one device isn’t promised another one elsewhere. Use it to decide whether a paywall says "Start your free week" or "Subscribe." The built-in paywall variables described below follow the same rule.

purchase(CommercePackage) starts a subscription for every package that’s one and a one-time purchase otherwise. The outcome arrives through the customer-info listeners once the service has validated the purchase:

Targeting and experiments decide which offering getCurrent() returns for a given customer. Both are evaluated by the service on every getOfferings call, so they take effect without an app update.

A targeting rule on the Targeting page names an offering and the conditions under which a customer gets it. A rule can match on:

A condition you leave empty matches everyone. Rules are tried in priority order, lowest number first, and the first rule whose conditions all match wins. When no rule matches, the customer gets the current offering.

An experiment splits customers between two or more offerings so that you can compare them. On the Experiments page, give the experiment an id, optionally limit it to a placement, and add variants. Each variant names an offering and a weight. Start the experiment when it’s ready and stop it when you have an answer.

Assignment is deterministic. The service hashes the experiment id together with the app user id and maps the result onto the variant weights, so a customer always sees the same variant, on every device and after every restart, and nothing about the assignment needs to be stored. A customer who logs in moves from the anonymous id to the account id and is assigned by the account id from then on.

The app can read which variant it was given, for example to tag its own analytics:

The Experiments page reports, for each variant, the number of customers who saw a paywall of its offering, the number who went on to buy, and the conversion rate between the two. The counts come from the paywall events described in the next section, so an experiment needs the built-in paywall or your own logEvent calls to produce results.

A paywall is the screen that sells an offering. You design it in the console as a document attached to the offering, and the app draws it with native components. Changing the paywall doesn’t require an app update.

Paywall.show opens the paywall of an offering in a form of its own, over the current form. Closing the paywall or going back returns to the form that was showing. When a purchase or a restore completes, the paywall also returns to that form by itself and then tells the listener, so purchaseCompleted is the place to unlock the feature or show a form of your own. Call Paywall.show on the EDT:

Every listener method is called on the EDT:

An offering with no paywall document is shown with the built-in one: a close button, a title, the packages of the offering as a list, a purchase button, a restore button and a footer. It names no colors, so your theme decides them all. Paywall.createDefault(offering) returns that document as a map you can change before you hand it to a PaywallView.

PaywallView is the component behind Paywall.show. Use it directly to embed a paywall in a form of your own, and tell it what closing means there. An embedded view never navigates by itself: after a completed purchase or restore it stays where it’s and the listener decides what your form shows next.

The view reports IMPRESSION when it’s first shown, then PURCHASE_START, PURCHASE and CLOSE, through CommerceManager.logEvent. The console charts these as a funnel for each offering and paywall, and experiments count them. If you build a purchase screen of your own instead, call logEvent with the same event names to get the same reports. Events are queued and sent from a background thread, and reporting never delays or fails a purchase.

Every element of a paywall has a UIID, so your theme can restyle it. The colors a document names are applied on top of the theme.

A paywall document is a JSON object. The Paywalls page of the console edits it with a live preview that uses the same PaywallView class the device does.

A node is an object with a type. A node of a type the app doesn’t know is skipped, so a document that uses a newer node type still shows on an older build. Sizes are millimeters.

A text is first looked up in strings, by the device’s locale and then by the default locale. When it isn’t a key there, it’s used as written. Then the variables in it are replaced from the selected package, and replaced again whenever the customer selects another one:

A variable with no value becomes empty. A complete document:

The customer center is a ready-made form where a customer sees their active subscriptions and acts on them. One call shows it:

The Customer center page of the console decides which paths the form offers and in what order:

When the configuration can’t be fetched, the form offers MANAGE and RESTORE. The form’s texts can be translated per locale in the console. Its UIIDs are CustomerCenterForm, CustomerCenterHeader, CustomerCenterSubscription, CustomerCenterEmpty, CustomerCenterRow and CustomerCenterReason.

For the CANCEL path you define a list of reasons, such as "Too expensive" or "Not using it enough." The reason a customer picks is reported to the service, and the console charts the answers.

Each reason can carry a retention offer: a product, a line of text, and optionally the id of a promotional offer. A customer who picks that reason is shown the text and can accept or decline. Accepting buys the product, under the promotional offer when one is named and the store supports it. Declining continues to the store’s subscription management, where the customer cancels.

A promotional offer is an App Store discount for existing or lapsed subscribers that the store sells only when it comes with a signature made by the developer’s key. The service makes that signature for you. purchaseWithPromotionalOffer asks for it and then asks the store to sell the product under the offer:

It may be called on the EDT. It returns false, and buys nothing, when no signature is available: the platform’s store has no promotional offers, commerce isn’t enabled in the build, or the service couldn’t sign. Signing needs the commerce.apple.keyId and commerce.apple.privateKey secrets described under store credentials, and the key must be one App Store Connect accepts for subscription offers. Promotional offers are an App Store feature, on iOS and on the Mac. A retention offer on any other store sells its product at the regular price.

Commerce reports what happens around a purchase to the analytics providers the app registered (see the analytics chapter), and it joins a customer to the invite that brought them in (see Invite a friend). Neither needs code. An app with no provider sends nothing, and nothing is sent for a user whose consent doesn’t cover analytics.

Every event is in the category commerce. The built-in paywall and the customer center send theirs as the customer uses them:

An event about an offering also carries placement when the offering was read for a placement, and experiment and variant when an experiment chose it. A parameter with no value is left out.

purchase_initiated and purchase are the events Purchase has always sent, each still sent once. They gain the offering, package and experiment when the purchase was started with purchase(CommercePackage), which is what the built-in paywall does. A purchase started with a bare SKU carries the sku alone.

A paywall you draw yourself can send the same events, so that it shows up in the same reports:

Because the paywall and purchase events carry experiment and variant, any analytics report can be split by variant: how many customers of each variant opened the paywall, picked the annual package, or bought. experiment_exposure is sent once for each experiment and variant an installation is given, which gives every variant its denominator even for a customer who never opens a paywall.

The service knows which install belongs to which customer, so a purchase by a customer who arrived through an invitation is attributed to the inviter. The revenue it reports for that invite is verified: it’s the amount of the purchase the service validated with the store, and not a value the app claimed. You don’t call Invites.conversion for a purchase. Keep it for the conversions the service can’t see, such as finishing a tutorial.

When the user logs in with logIn, the attribution follows the customer to the account. The app user id of commerce and the user id of analytics stay separate, and logging in here doesn’t change the one you set with Analytics.setUserId.

A referral reward gives something to the inviter, the invited user, or both. Configure it on the Referral rewards page of the console. Each of the two rewards grants either an entitlement for a number of days or an amount of a virtual currency. Entitlement days stack: a second reward extends the first rather than replacing it.

The trigger decides when the rewards are granted:

Each reward is granted once. The inviter’s reward reaches the inviter’s device once that device has used analytics, which ties it to the inviter’s install. A refund of the invited user’s purchase doesn’t take a reward back.

The service grants the reward, so there’s nothing to deliver from the app. An entitlement reward answers isEntitled like a purchased one, and a currency reward is part of the balance. When an invitation is matched to the installation, commerce asks the service for the customer again in the background, and the customer information listener hears about the reward. getReferralRewards() lists what was granted and why, for example to thank the user:

A reward has an entitlement id or a currency code, an amount for a currency, an expiry date of 0 when it doesn’t expire, and the reason the service recorded. The list is empty for a customer with no rewards.

Attributes are name and value pairs you attach to a customer. Targeting rules read them, the console shows them on the Customers page, and integrations use some of them to identify the customer in another system.

setAttributes is a blocking network call that returns true when the service accepted the attributes. A null value deletes an attribute, and any other value is stored as its string form. The attributes come back with the customer information, in CustomerInfo.getAttributes(). Names that start with $ are reserved for the uses this chapter lists, such as $appsflyerId.

A virtual currency is a balance the service keeps for each customer: gems, credits, tokens. Define a currency on the Currencies page with a code and a name, and list the products that grant it with the amount each grants. When the service validates a purchase of such a product, it adds the amount to the customer’s balance. A consumable product that should be bought again and again is the usual choice.

The app reads balances from the customer information:

Spending is a server-side operation, so that a modified app can’t grant itself currency. Your backend adjusts a balance through the REST API described below, and the app sees the new balance after its next refresh().

iOS purchases work with no setup beyond the receipt store. A native Mac build sells through the Mac App Store with the same code, and the service validates its receipts with the same Apple credentials. If the Mac app’s bundle id differs from the package name of the project, enter it as the Mac bundle id on the App settings page of the console so that its receipts are accepted.

Point App Store Server Notifications V2 at https://cloud.codenameone.com/api/v2/commerce/notifications/apple in App Store Connect, so that renewals, cancellations, refunds and billing problems reach the service when they happen.

Android builds sell through Google Play by default. In the Play Console, set up Real-time developer notifications and route the Pub/Sub topic to https://cloud.codenameone.com/api/v2/commerce/notifications/google. Google purchases are validated with Google’s own server API, so the service account described under store credentials is required for them. Without it the service accepts the purchase in degraded mode and the app relies on the device’s receipt.

An Android app is built for one store. To build for the Amazon Appstore, set the build hint:

The build then uses the Amazon Appstore SDK instead of the Play Billing Library, declares the receiver Amazon’s client answers through, and leaves out the com.android.vending.BILLING permission, which the Amazon Appstore doesn’t accept. The Google Play settings android.licenseKey and android.billingclient.version aren’t used. Your code doesn’t change: Purchase and CommerceManager behave the same, and receipts carry the store code Receipt.STORE_CODE_AMAZON.

For validation, enter your Amazon shared secret (commerce.amazon.sharedSecret) on the Stores page of the console, and set the Amazon SNS topic ARN in the Amazon store settings there. The same page shows the notification address to register with Amazon. It ends in a token that identifies your app, so copy it as shown.

On platforms with no store — the browser and the desktop — the service sells through a hosted checkout page in your own Stripe or Paddle account. The same package can therefore be bought in the App Store on a phone and with a card on the web, and both grant the same entitlement.

To set it up:

In the app, purchase(CommercePackage) does the right thing on every platform. Where the platform has a store it sells the store product. Where it has none, and the package has a web price, it opens the hosted checkout in the browser. isWebPurchase tells you which of the two will happen, and purchaseOnWeb opens the checkout explicitly:

The customer pays outside the app, so nothing reports the outcome to the call. Once the app is back in the foreground, run refresh() off the EDT, and the customer-info listeners hear what was bought. The paywall does that by itself.

To send the customer back to pages of your own after the checkout, ask for the address and open it yourself. getWebPurchaseUrl is a blocking call that returns null when there is no web price for the package:

Check the terms of each app store before you offer a web checkout inside an app that’s distributed through that store.

Every package with a web price also has a purchase link you can put on a website or in an email, with no app involved:

The console shows the link, including your app’s token, next to the package. Opening it redirects to the checkout for the customer named in user. Use the same id the app passes to logIn, and the purchase unlocks in the app on its next refresh.

A customer who subscribed on the web manages the subscription in the billing portal of Stripe or Paddle. fetchManagementUrl() returns the right address for the customer’s newest active entitlement: a fresh portal address when it was bought on the web, and the store’s subscription page otherwise. A portal address is short-lived, so ask for it when you’re about to open it:

getManagementUrl() is the variant that never touches the network. It returns the portal address fetchManagementUrl() last answered with, or the store’s page from the last customer information.

By default the service validates the store-signed receipt the device presents. For Apple that’s enough to gate features and it works with no setup. For server-authoritative validation, where the service calls the stores' own server APIs to confirm the real subscription state, provide your credentials in the console. Apple and Google credentials are entered on the Setup page; Amazon, Stripe and Paddle credentials on the Stores page:

Secrets are stored AES-256-GCM encrypted. They’re decrypted only server-side at call time and are never shown in the console again.

Store notifications are idempotent. Each is deduplicated on the id the store gives it, so a redelivery never double-counts, and a store transaction is counted once however many devices present its receipt.

Commerce can forward every normalized state change to your own backend. Configure a URL and a signing secret on the Webhook page of the console. Each event is HMAC-SHA256 signed (header CN1-Commerce-Signature) and carries:

Delivery is at-least-once, in sequence order per customer, with retries that back off exponentially. The Webhook page lists recent deliveries and their outcome.

Integrations forward the same lifecycle events to other services, each in the format that service expects. Enable them on the Integrations page, where each takes its own credentials and a choice of event types to forward. A test button sends a sample event.

The attribution services identify a device by their own id, which only their SDK on the device knows. Read it from the SDK when the app starts and store it with setAttributes under the reserved name in the table. An event for a customer who lacks a required attribute isn’t sent to that destination. The other destinations still receive it.

Your backend can read and change customers through a REST API. Create a secret key on the API keys page. A key starts with sk_, belongs to one app, and is shown once when you create it, so store it then. Send it as a bearer token to https://cloud.codenameone.com/api/v2/commerce/v1:

A currency change with a negative delta spends. When the balance is too low the call answers 409 with the error insufficient_balance and changes nothing. reference makes the call safe to repeat: a second call with the same reference returns the first result, marked replayed, and doesn’t change the balance again. Use your own order id as the reference.

An unknown customer answers 404, and a request the service can’t read answers 400.

The Customers page of the console has the same controls to grant and revoke entitlements as the REST API. Pick an entitlement, optionally an expiry, and grant it. This is the way to give a customer access as a goodwill gesture, to unlock an account for a reviewer, or to give your team the paid features. A granted entitlement has the provenance PROMOTIONAL, is excluded from revenue, and reaches the app on its next refresh().

The Export page downloads two CSV files on demand, and can also deliver both every day to an Amazon S3 or Google Cloud Storage bucket you name.

For a scheduled export, choose the destination, the bucket and a prefix, and for S3 the region. S3 takes an access key id and a secret access key, and Google Cloud Storage takes a service account key. The files are named transactions-<day>.csv and subscribers-<day>.csv under the prefix.

Import brings existing customers into the service, for example when you add Commerce to an app that already has subscribers. Upload a CSV file in the console, or post it to /receipts/import. The first line must be this header:

Each row is validated exactly as a receipt from a device is, so an imported subscription is checked with the store and continues to renew, expire and report events like any other. The answer lists the rows that weren’t imported, with the reason for each.

The Commerce section in the console at https://cloud.codenameone.com/console/index.html is account-level by default, with an app filter to narrow to one app. Beside the configuration pages this chapter has described, it reports on the business:

Commerce normalizes every active subscription to a monthly figure (MRR) and reconstructs the trends from the subscription history. Every chart pairs a graph with its underlying data table for export-friendly inspection. All money is shown in your reporting currency, and transactions in other currencies are normalized to USD through daily exchange rates.

Commerce reuses the standard build_key that every Codename One cloud build already carries, so a cloud build needs no build hint to use the service. CommerceManager.isCloudEnabled() is true on any cloud build. These hints change the defaults:

The answers that decide what a customer owns — customer information, purchase validation, offerings, the customer center and promotional offer signatures — are signed by the service with an Ed25519 key. Each request carries a fresh random nonce, and the signature covers that nonce together with the response. An answer recorded earlier can’t be replayed to a later request, and an answer forged by something between the device and the service doesn’t verify.

An answer is trusted only when it’s signed and the signature verifies against the service’s public key. An answer that’s unsigned or wrongly signed is ignored, and so is every answer while the app knows no public key at all. The manager then becomes degraded. With a key, the app falls back to the stored answer and the store’s receipts, exactly as it does when the network is down. With no key, nothing was ever stored, so the app answers from the store’s own receipts alone.

A signed answer must also be the answer to this request: one that names another app user id, another application’s package name or another endpoint is ignored, and a stored answer is checked the same way when it’s loaded.

The stored answer is kept as the service signed it, and its signature is checked again every time the app starts. A stored answer that no longer verifies, for example after the key changed, is deleted rather than used.

The service address must use https. Plain http is accepted only on a loopback address — localhost, 127.0.0.1, [::1] or 10.0.2.2 — for testing on your own machine.

To run against a service of your own, set both hints. A self-hosted service needs commerce.cloud.publicKey; without it the app trusts none of its answers:

Use the public half of the key pair your service signs with. A key that’s set but can’t be read verifies nothing, so every answer is ignored and the app runs degraded. That’s deliberate: a broken key must not turn verification off.

The simulator reads the three commerce.cloud hints from the project’s codenameone_settings.properties, so you can point it at a staging service or at one running on your own machine:

The build key is stamped by the build server, and the simulator has none. Until one is set, isCloudEnabled() is false there and every call defers to the simulated Purchase API, which is enough to exercise your purchase flow and the built-in paywall. To talk to the service from the simulator, set the build key property before the first CommerceManager call:

With that in place the simulator fetches offerings, paywalls and the customer center from the service, and the purchases you make in the simulated store are sent for validation as Receipt.STORE_CODE_SIMULATOR receipts. You can also grant the test customer an entitlement on the Customers page of the console and watch refresh() pick it up. getAppUserId() returns the id to look for.

Commerce stores entitlement state and transaction metadata (store, product id, event type, amount, validation state) keyed by your app user id, together with the attributes you set. It never stores card numbers or payment credentials. Those stay with Apple, Google, Amazon, Stripe, Paddle or your processor. Family shared purchases grant access but are excluded from revenue. Deleting a customer through the REST API removes their grants, attributes and currency history.