Apps Billing

Apps Billing lets Partners with approved applications charge sellers directly through YouCan. YouCan collects payments from the seller's balance or attached payment method, then automatically passes revenue to Partners via Payouts. YouCan handles all chargeback processes — you own your pricing model.

Payouts

Your share of collected revenue accumulates in your Partner balance. Once your balance reaches $100, you can request a payout from the Partners dashboard at /dashboard/apps/:id/insights.

Charge types

Type	Description
One-time	A single payment that requires seller approval each time.
Recurring (time-based)	A subscription billed monthly (30_days) or yearly (365_days). Supports a trial period. After the first approval, YouCan handles renewals automatically.

How billing works

1. A seller takes an action in your app that involves a charge (e.g. purchasing a feature or upgrading a plan).
2. Your app creates a charge via the StoreAdmin API.
3. YouCan verifies the charge and returns a confirmation_url — redirect the seller there.
4. The seller approves (or declines) the charge on the YouCan-hosted page.
5. YouCan redirects back to the return_url you specified on the charge.
6. Your app reads the charge status to confirm and unlock the feature.

Charge statuses

Status	Description
pending	Charge created but not yet reviewed by the seller.
active	Charge approved by the seller and currently active.
deferred	Charge deferred to the next billing cycle (e.g. a plan downgrade).
frozen	Charge frozen due to non-payment.
declined	Seller declined the charge. Terminal state.
expired	Charge was not approved before it expired. Terminal state.
canceled	Charge was canceled. See Cancellation. Terminal state.

Plan upgrades and downgrades

Recurring charge plan changes go through the same approval flow. The proration strategy applies when both the old and new plan share the same billing interval (30_days). Otherwise the new plan is deferred until the end of the current billing period.

Cancellation

There is currently no API for your app (or the seller) to directly cancel a charge on demand. A recurring charge is canceled automatically in these cases:

• The app is uninstalled. Any active recurring charge for that store is scheduled for cancellation.
• A plan change replaces it. Upgrading or downgrading creates a new charge and cancels the one it replaces.
• It's frozen for too long without payment. Stale frozen charges are canceled after an extended grace period.

WARNING

Cancellation can happen immediately or at the end of the current billing period, and this isn't always visible right away:

• Immediate — status becomes canceled right away.
• At period end (this is what app uninstallation triggers) — status stays active and period_ends_at is unchanged until the current period elapses, at which point status becomes canceled. So immediately after a seller uninstalls your app, a GET /billing/apps/charges call will still show status: "active" — this is expected. The seller will not be billed for a renewal; the status simply doesn't flip to canceled until the period actually ends.

If you need to know sooner whether a seller has uninstalled your app, treat the app.uninstalled webhook itself as your signal, rather than polling the charge's status.

Requirements

• Your application must be approved to create real charges.
• Charges created for non-approved apps or development stores must set "test": true.

Webhooks

YouCan emits the following webhook topic for billing events:

Topic	Triggered when
app.charge_updated	The status of a one-time or recurring charge changes.

Subscribe via the REST Hooks API.

TIP

The payload always includes both status and period_ends_at, whatever triggered the event. For an at-period-end cancellation (e.g. from app uninstallation), the first webhook fires immediately with status: "active" and a future period_ends_at — a second webhook fires later, once the period ends, with status: "canceled".

API reference

Page	Description
List charges	Retrieve all charges for the current store.
Create a one-time charge	Issue a single payment request to a seller.
Create a recurring charge	Issue a subscription charge with optional trial.