About the Earnings APIs

The Earnings APIs let a Wix Partner read what they earned through the Wix Partner Program and what Wix actually paid them. They're read-only: Wix creates every record automatically as the partner earns and is paid, so partners retrieve and reconcile their earnings but never create or change them. All amounts are in US dollars (USD), and reads are scoped to the caller's own partner account.

A partner earns revenue share from independent streams, each with its own per-earning payout API, and a separate API surfaces the invoices Wix pays those earnings out on:

• Revenue Share Premium Payouts: Revenue share from premium subscriptions the partner sold, such as Wix.com, Studio, or POS plans. 1 payout per subscription transaction, each with an approval status.
• Revenue Share GPV Payouts: Revenue share derived from gross payment volume (GPV), the payment volume processed across the sites the partner manages. 1 payout per day, with a per-site breakdown.
• Marketplace Payouts: Revenue share from marketplace transactions, such as template sales. 1 payout per transaction, with reversals carried as negative payouts.
• Materialized Invoices: The invoices Wix's payment handler, Tipalti, raised for the partner and their payment state, grouped by earnings month and status. An invoice's status is PAID for a settled invoice, UNPAID for a scheduled but unpaid invoice, or BELOW_THRESHOLD for an invoice Wix hasn't scheduled yet, so a returned amount isn't necessarily money already received. Each invoice total breaks down into premium, GPV, marketplace, and app market sub-totals, and LastPayment reports the status of the partner's most recent payment.

How the APIs fit together

The payout APIs record what a partner earned. Premium and marketplace payouts are per-transaction, 1 payout per subscription charge or marketplace sale. GPV payouts are a daily aggregate, 1 payout per transactionDate covering all the volume processed that day. The Materialized Invoices API records the invoice side. Each materialized invoice's revenueStreamsAggregation splits a month's total into premium, GPV, and marketplace sub-totals that reconcile back to the matching payouts, plus an appMarket sub-total for Wix App Market earnings, which has no payout API of its own.

The payout and invoice surfaces join on the invoice reference code. A payout carries the code of the invoice Wix included it in as its invoiceId, and the same code appears in the materialized invoice's invoicesRefCodes. Read a payout API to see what a partner earned, then follow that code into Materialized Invoices to see whether and when Wix invoiced and paid it.

Payout dates and reversals

These behaviors are shared across the payout APIs, and they shape any figure you report. Each API's own introduction covers how the behavior works for that stream:

• Each payout carries a transactionDate for when the earning occurred. That's the field to filter and sort a reporting period on, not the record's created or updated date. For the per-stream detail, see GPV payout periods, premium payout dates and invoices, and marketplace payout dates and invoices.
• Premium and marketplace payouts carry reversals and cancellations as negative payouts. Queries return them and totals count them, so sum across payouts rather than filtering them out to get a partner's net earnings. For the per-stream detail, see premium approval status and reversals and marketplace approval status and reversals. GPV payouts have no reversal model. Wix restates the day's aggregate payout instead.

Differences from the Wix Studio dashboard

Partners also see these earnings in the Wix Studio dashboard. The dashboard draws on the same records but relabels statuses, computes narrower totals, and resolves some IDs to names that the APIs don't return. Each API's own introduction has a "Differences from the Wix Studio dashboard" section that maps its fields and totals to what the dashboard shows.

Before you begin

It's important to note the following points before starting to code:

• Every Earnings API is read-only. Wix creates the records, and a partner can't create, update, or delete them.
• Reads are scoped to the caller's partner account. A record belonging to another account reads as not found.
• All monetary amounts are in USD, even where a field name carries no currency suffix.