Skip to main content
One-time items are consumables sold alongside your app: credit packs, boosts, top-ups. They are independent of your pricing plans: buying one doesn’t affect installation or subscriptions, and the same item can be bought any number of times. Items are sold through checkout links: your app decides when to offer them, typically a “Buy more credits” button pointing at the item’s checkout URL.

​
Create an item

In the Builder (Developer area), open your app and go to Store Listing → Pricing, then Add Item under One-time items. You can configure up to 10 one-time items per app. The same 20/80 revenue split applies as for pricing plans.

​
Selling an item

Each item has a copyable checkout URL of the form:
Copy it from the item’s row in the Pricing tab (also listed on the dashboard’s Checkout links page) and put it behind your purchase CTA.
Item checkout requires the buyer to be signed in to Fanvue. Items are independent of plans, so whether they work as a first purchase or an in-app top-up is down to how you’ve built your app.

​
Attribution

To tie a purchase back to a record in your own system, append a client_reference_id to the checkout URL:
It’s echoed as data.client_reference_id on the resulting app.payment.* and app.refund.created events. Passthrough-only; don’t put secrets in it. (metadata is not captured and remains {}.)

​
Fulfilment

Fulfil off app.payment.succeeded:
  1. Identify the purchase: billing_reason is one_time and purchase_reference carries the appotp_ prefix. item.uuid tells you which item was bought; buyer.uuid who bought it.
  2. Dedupe before crediting: the event id is stable across delivery retries, so record it and skip duplicates.
  3. Credit the buyer, then reconcile revenue against the payment’s invoice number (data.id).
Don’t fulfil on app.payment.pending; wait for .succeeded.

​
Refunds and disputes

app.refund.created fires on refund, chargeback, or cancellation (branch on reason); app.dispute.flagged and app.dispute.created warn you of chargebacks. Claw back credited balances keyed on payment_id, the invoice number of the original payment.

​
Reconciling

Re-read one-time payments any time with the read-only app payments endpoints, owner-scoped or buyer-scoped: See Reconciliation for how invoice numbers match across webhooks and endpoints.