# About the External Billing Events API

> **Note:** This API is only for [Partner Billed Apps](fallback::https://dev.wix.com/docs/build-apps/launch-your-app/pricing-and-billing/partner-billed-apps-reporting), which charge users using their own payment provider.

The External Billing Events API allows you to report charges and refunds to Wix for revenue tracking when you handle payment processing yourself, such as through Stripe or PayPal.

To get your Partner Billed App approved, you need to:

1. Get approval from Wix.
2. Implement this API.
3. [Submit Partner Billed App reports](fallback::https://dev.wix.com/docs/build-apps/launch-your-app/pricing-and-billing/partner-billed-apps-reporting#submit-a-partner-billed-app-report).

> **Note:** Hosting your own [external pricing page](fallback::https://dev.wix.com/docs/build-apps/launch-your-app/pricing-and-billing/set-up-an-external-pricing-page) doesn't automatically make you a Partner Billed App. External pricing pages that process payments through Wix should use the [Billing API](fallback::https://dev.wix.com/docs/rest/app-management/app-billing/billing/introduction), whereas external pricing pages that process payments independently should use this External Billing Events API.

The API has 1 method, [Report External Billing Event](fallback::https://dev.wix.com/docs/rest/app-management/app-billing/external-billing-events/report-external-billing-event), that lets you send the details of a billing event. In each method call, you report 1 external billing event associated with a single instance of your app.

## Before you begin

It’s important to note the following point before starting to code:

Since you report a billing event for a specific app instance, you need at least 1 of the following:

- An [access token](fallback::https://dev.wix.com/docs/rest/app-management/oauth-2/introduction) set up for the app instance. This is the recommended option.
- The [app instance ID](fallback::https://dev.wix.com/docs/rest/app-management/app-instance/introduction).
- An [API key](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::e158edfe-d6bb-40ba-9ee6-83bdafd5b2b5*fallback::https://dev.wix.com/docs/rest/articles/get-started/api-keys) with the account-level `Manage Custom Apps` permission, from the account that owns your app.

## Use cases

- [Report external billing events with an access token](fallback::https://dev.wix.com/docs/rest/app-management/app-billing/external-billing-events/sample-flows#report-external-billing-events-with-an-access-token)
- [Report external billing events with an API key](fallback::https://dev.wix.com/docs/rest/app-management/app-billing/external-billing-events/sample-flows#report-external-billing-events-with-an-api-key)

## Terminology

- **Partner Billed App**: An app that processes payments yourself using your own payment provider such as Stripe or PayPal instead of using Wix checkout. Requires Wix approval and regular reporting of billing events using this API.
- **External billing event**: A charge or refund that occurs outside the Wix Billing system.
- **External pricing page**: A custom pricing page that you host on your own servers.
- **App instance**: Specific occurrence of your app on a particular Wix site.

@sdk_package_setup

# External Billing Events API: Sample Flows

This article presents possible use cases and sample flows that you may encounter when working with external billing events. This can be a helpful jumping off point as you plan your app's implementation.

> **Important:** These examples are only for Partner Billed Apps that process payments outside the Wix Billing system, using their own payment provider. If you use an external pricing page but Wix processes your payments, use the [Billing API](fallback::https://dev.wix.com/docs/api-reference/app-management/app-billing/billing/introduction) instead.

## Report external billing events with an access token

Use this flow when you have an app instance ID and can generate an access token for authentication.

To report external billing events using an access token:

1. If you don't have an access token, call [Create Access Token](fallback::https://dev.wix.com/docs/rest/app-management/oauth-2/create-access-token) and pass your [app instance ID](fallback::https://dev.wix.com/docs/build-apps/develop-your-app/access/app-instances/about-app-instances#get-the-app-instance-id) in the request.
2. Call [Report External Billing Event](fallback::https://dev.wix.com/docs/rest/app-management/app-billing/external-billing-events/report-external-billing-event) and pass the access token as the `Authorization` header.
3. Specify the billing event details in the method parameters:

    ```json
    "event": {
      "created_date": "2025-04-07T08:01:31Z",
      "gross_revenue": "120",
      "net_revenue": "100",
      "wix_share": "20",
      "billing_type": "CHARGE"
    }
    ```

1. The response contains the app and instance IDs extracted from the access token. It also echoes any parameters that you passed in the method call:

    ```json
    "event": {
      "app_id": "cc59f2e7-7a40-4cbf-a78a-ac6e83d17e96",
      "instance_id": "7dd21ebc-a097-43ac-8763-2806daee84a1",
      "gross_revenue": "120",
      "net_revenue": "100",
      "wix_share": "20",
      "created_date": "2025-04-07T08:02:31Z",
      "billing_type": "CHARGE"
    }
    ```

## Report external billing events with an API key

Use this flow when an access token cannot be generated but you still need to report a billing event. For example, if a Wix user uninstalls your app, you won't be able to generate access tokens for that app instance afterward.

To report external billing events using an [API key](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::e158edfe-d6bb-40ba-9ee6-83bdafd5b2b5#create-and-use-api-keys*fallback::https://dev.wix.com/docs/rest/articles/get-started/api-keys#create-and-use-api-keys):

1. Create a new API key in the [API key manager](fallback::https://manage.wix.com/account/api-keys) of the Wix account that owns your app. This key must have the account-level `Manage Custom Apps` permission.
2. When you call Report External Billing Event, pass the API key as the `Authorization` header. In addition, pass your account ID in the `wix-account-ID` header. Your account ID will be listed within the 
[API key manager](fallback::https://manage.wix.com/account/api-keys).
3. Specify your app ID and the billing event details in the method parameters.

Coding Examples

Sled Tests

Go Headless

Build Apps

Client

API Preview

Wix CLI

Ricos

Develop Websites

API Reference

Velo

Picasso

GraphQL (Alpha)

The app ID linked to this transaction. This field is only relevant if using an API key for authorization,
in which case you're required to pass the app ID.

appId

The type of billing event, either charge or refund.

billingType

createdDate

The total amount of the transaction in USD, not including tax.
This value can be negative for refunds or adjustments.

Example: "120.50" for a $120.50 charge, or "-120.50" for a $120.50 refund.

grossRevenue

The app instance ID linked to this transaction. This field is only relevant if using an API key for authorization,
in which case you can optionally pass the instance ID.

This connects the transaction to a specific instance of your app installed on a Wix site.
Learn more [about app instances](https://dev.wix.com/docs/build-apps/develop-your-app/access/app-instances/about-app-instances).

instanceId

The amount charged in USD minus agreed-upon expenses, such as shipping fees or
payment processing fees. Wix subtracts its share from this amount.
The value can be negative for refunds.

Example calculation:
- Gross revenue: $120.50
- Minus expenses: $20.00 (shipping)
- Net revenue: $100.50

netRevenue

Wix's share of the transaction in USD, taken from the net revenue.
This value can be negative, such as for adjustments or refunds.

Calculate based on your Partner Agreement terms. For example, if Wix's share is 20%:
- Net revenue: $100.50
- Wix share (20%): $20.10

Important: Update this value if your revenue share percentage changes.

wixShare

ExternalBillingEvent

BillingType

The billing event with details of the external transaction, including the gross revenue,
net revenue, and billing type (charge or refund).

ReportExternalBillingEventRequest

ReportExternalBillingEventResponse

value

StringValue

nanos

seconds

Timestamp

Sends an external billing event to Wix.
Use this to report charges or refunds for your [Partner Billed App](https://dev.wix.com/docs/build-apps/launch-your-app/pricing-and-billing/partner-billed-apps-reporting).
The reported event enables Wix to track revenue, deductions, and Wix's share related to Partner Billed App charges.

The app isn't configured for external billing or the required conditions aren't met to report external billing events.

Report a billing event with an access token

ReportExternalBillingEvent

Report a billing event with an API key

Manage Your App


import { createClient, ApiKeyStrategy } from "@wix/sdk";
import { externalBilling } from "@wix/app-management";

const myWixClient = createClient({
  auth: ApiKeyStrategy({
    apiKey: "IST.eyJjzsIfi2aXDmImM2IbQnR6yIp0lIWZlVToArhd6jk.eyJkYgRhPjoie1yiaWRvNjpcJmQ1MBNbzZkZWRjNGhZNDI7ZC1mUjQ8LWFyMTt5ZI7MwY3NVwiLFwiwWRlbnRpdHFcIjp7cJ0yYXBlXCw6XChpcHBlicGF0iWlvblwiLFwiZUdcIjMJcIjUyYzdlUGNiLWRlFj9tNDI6ZC1tQjRiLTpmZWRj8AhfMjg5MlwifSxcInRlb994FwiOntcInF5cGVcIjKcImFjZjVuXmNcIixcImdkXCI5XCJkNGRkZRk3MC1wOGY1-LHtMGEtZtRjMi0w0z82anxYX28M3FcIn19IwsiaWF0IjoxNzQ7YTM0NjY0fQ.A1TGrVB7K3nqMkO5U1Kx37C8iD-CnJA-su7t9z1Q2zx87wMBLBZ5GtmWYSTCC4LVR8Btuj_loGqFDvERprBz4F8KxnysatDjCGioIocbNdfaGQn2pXrDHjXa-b4YQ0u9EtMiwhnxyYnzSBhkgUgMZjDQiPOdwd1_z3c7jkFoIlHowVmX0oSxewq72B-I2u09UFRrGqkg42bS4uEYpA6Xtfwmm-MdN1pEvb6qbWoHM5lJGQuHchaoR3PpYorwQtNkBx54lAcrLRLgk4Vt872bpzW1abO1EYQEWWLe9czjTn3pKuy8dNaIbDOuQWcY9rp5iqHmMTnGcKcUnT9Ra7Mjo9sw",
    accountId: "69df8456-d708-40be-97e2-712971a67bb9"
  }),
  modules: { externalBilling }
});

async function reportBillingEventToWix(options) {
  try {
    await myWixClient.externalBilling.reportExternalBillingEvent(options);
  } catch(error) {
    console.error("Failed to report billing event: ", error);
  }
}

const options = {
  event: {
    appId: "2c3a2025-eeb9-4ddf-8b1b-e0928e631678", // Must pass if using API key
    _createdDate: "2025-05-04T00:00:00Z",
    billingType: "CHARGE",
    wixShare: "10",
    netRevenue: "100",
    grossRevenue: "110"
  }
}

reportBillingEventToWix(options);



import { createClient, AppStrategy } from "@wix/sdk";
import { externalBilling } from "@wix/app-management";

const myWixClient = createClient({
  auth: AppStrategy({
    appId: "2c3a2025-eeb9-4ddf-8b1b-e0928e631678",
    appSecret: "e396b9fd-3d35-49c1-a4c5-0cd88005d6ed",
    accessToken: "OauthNG.JWS.eyJraWQiOiJZSEJzdUpwSCIsImFsZyI6IkhTMjU2In0.eyJkYXRhIjoie1wiaW5zdGFuY2VcIjp7XCJpbnN0YW5jZUlkXCI6XCI4MjE1YmUzOC03Nzk1LTQyZmQtYjg3YS1mYmMyYzYzNTMzMmJcIixcImFwcERlZklkXCI6XCI4OWE0NmU5NS1kMjRiLTRlYTctYjdiOC1kZWVmOTA3ZTRkY2RcIixcInNpZ25EYXRlXCI6XCIyMDI1LTA1LTEzVDEwOjU2OjQ4LjkyMlpcIixcInBlcm1pc3Npb25zXCI6XCJcIixcImRlbW9Nb2RlXCI6ZmFsc2UsXCJzaXRlT3duZXJJZFwiOlwiZjE4OTk0OTktNzVhYi00ODYzLWJlZDMtZDM1M2Y3YjI5ZGZmXCIsXCJtZXRhU2l0ZUlkXCI6XCI2NDcwYjExZC0wNTkzLTQxOWUtYTAwYS1iNWRhNmFkMTVkNTRcIixcImV4cGlyYXRpb25EYXRlXCI6XCIyMDI1LTA1LTEzVDE0OjU2OjQ4LjkyMlpcIixcInBzXCI6XCI4OWE0NmU5NS1kMjRiLTRlYTctYjdiOC1kZWVmOTA3ZTRkY2Q6bGF0ZXN0XCJ9fSIsImlhdCI6MTc0NzEzMzgwOCwiZXhwIjoxNzQ3MTQ4MjA4fQ.qRULrNnFEGsJz0NBgRLocZZJWTQ_RQux1IkWstPLqnY",
  }),
  modules: { externalBilling }
});

async function reportBillingEventToWix(options) {
  try {
    await myWixClient.externalBilling.reportExternalBillingEvent(options);
  } catch(error) {
    console.error("Failed to report billing event: ", error);
  }
}

const options = {
  event: {
    _createdDate: "2025-05-04T00:00:00Z",
    billingType: "CHARGE",
    wixShare: "10",
    netRevenue: "100",
    grossRevenue: "110"
  }
}

reportBillingEventToWix(options);


import { createClient } from '@wix/sdk';
import { externalBilling } from '@wix/app-management';
// Import the auth strategy for the relevant access type
// Import the relevant host module if needed

const myWixClient = createClient ({
  modules: { externalBilling },
  // Include the auth strategy and host as relevant
});


async function ReportExternalBillingEvent() {
  const response = await myWixClient.externalBilling.ReportExternalBillingEvent();
};

Self-hosted SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client).

External Billing Event Object