Buyer IDs
Each buyer appears to your organization under a buyer ID: random, stable across your apps, and different for every publisher. It never reveals their Praxical account, email or payment details. When an organization buys seats, the organization is the buyer and each seat holder has their own buyer ID.
Follow purchases
Create an automation credential with Read purchases in the app's security settings. It works only while you're an owner. The purchases feed lists paid purchases, oldest change first: keep next_cursor and poll with it to receive new and changed purchases. To answer what a buyer holds right now, from a purchase, gift, license code or organization seat, read the buyer.
curl --fail-with-body \
-H "Authorization: Bearer $PRAXICAL_PUBLISHER_TOKEN" \
"$PRAXICAL_API/api/v1/publisher/products/$PRAXICAL_PRODUCT_ID/purchases?cursor=$CURSOR"
curl --fail-with-body \
-H "Authorization: Bearer $PRAXICAL_PUBLISHER_TOKEN" \
"$PRAXICAL_API/api/v1/publisher/products/$PRAXICAL_PRODUCT_ID/buyers/$BUYER_ID"React to changes
Subscribe a webhook receiver to purchase.access_changed. It arrives when a paid purchase's access changes: a completed refund, a dispute, a renewal or a cancellation. payment.confirmed announces new purchases. Both carry the buyer ID and the purchase as it is now. The feed stays the source of truth, because webhooks can arrive late or out of order.
Sell on your own site
In the app's Integrations, list the sites that may show your checkout, then paste the embed code for an offer. The card shows your app and price. Buy opens Praxical checkout in a window of its own, where the buyer signs in and pays; the purchase joins their Praxical library and records your site. Only the sites you list can show the card or start a checkout from it. When the purchase completes, the element fires a praxical:purchase event.
<div id="buy" data-praxical-offer="OFFER_ID"></div>
<script src="https://store.praxical.io/embed/v1.js" async></script>
<script>
document.getElementById("buy").addEventListener("praxical:purchase", (event) => {
if (event.detail.state === "paid") showThankYou(event.detail.orderId);
});
</script>Link a buyer's account
To connect a user of your own site with their Praxical purchases, list your return address in the app's Integrations. Then send the signed-in user to /link/APP_ID with that redirect_uri and a random state. They approve on Praxical, and may also share their email address and name. They come back with a one-time code; check the state, then exchange the code from your server within ten minutes with a Read purchases credential. Store the buyer ID with their account. Their email address and name are included only while they consent; they can stop sharing in their Praxical account data.
Verify an entitlement token
The Praxical app can give your app a signed entitlement token for its signed-in user. Send it to your server and verify it against the Store's published keys: the signature, the issuer, your app's application ID as the audience, and the expiry. sub is the buyer ID; access lists what they hold now. Tokens last 24 hours and aren't revoked, so after a refund the user simply gets no new one. This deters casual sharing; it doesn't prevent copying.
In your app, get the token from the Praxical app that launched it: run "$PRAXICAL_CLI" entitlement-token, or POST {} to /v1/app/entitlement-token on the Unix socket $XDG_RUNTIME_DIR/praxical/daemon.sock. The answer is the token document (token, buyer_id, expires_at, access). Errors: not_an_app (not launched by Praxical), sign_in_required, no_entitlement and entitlement_tokens_unavailable.
import { createRemoteJWKSet, jwtVerify } from "jose";
const store = "https://store.praxical.io";
const keys = createRemoteJWKSet(new URL(`${store}/api/v1/entitlement-keys`));
export async function verify(token) {
const { payload } = await jwtVerify(token, keys, {
issuer: store,
audience: "io.example.yourapp",
typ: "praxical-entitlement+jwt",
algorithms: ["EdDSA"],
});
return { buyer: payload.sub, access: payload.access };
}