> Portal Navigation: > > - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version. > - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages). > - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`). > - Top-level index of all portals: https://dev.wix.com/docs/llms.txt > - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt # ReportExternalBillingEvent # Package: appBilling # Namespace: ExternalBillingBIService # Method link: https://dev.wix.com/docs/api-reference/app-management/app-billing/external-billing-events/report-external-billing-event.md ## Permission Scopes: Manage Your App: SCOPE.DC.MANAGE-YOUR-APP ## Introduction 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.md). The reported event enables Wix to track revenue, deductions, and Wix's share related to Partner Billed App charges. --- ## REST API ### Schema ``` Method: reportExternalBillingEvent Description: 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.md). The reported event enables Wix to track revenue, deductions, and Wix's share related to Partner Billed App charges. URL: https://www.wixapis.com/v1/billing-event Method: POST # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: event.grossRevenue, event.wixShare, event.billingType Method parameters: param name: event | type: ExternalBillingEvent - name: appId | type: string | description: The app GUID 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 GUID. - name: instanceId | type: string | description: The app instance GUID 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 GUID. 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.md). - name: grossRevenue | type: string | description: 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. | required: true - name: netRevenue | type: string | description: 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 - name: wixShare | type: string | description: 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. | required: true - name: createdDate | type: string | description: The date and time of the transaction. - name: billingType | type: BillingType | description: The type of billing event, either charge or refund. | required: true - enum: UNKNOWN, CHARGE, REFUND Return type: ReportExternalBillingEventResponse - name: event | type: ExternalBillingEvent | description: The billing event that was processed. - name: appId | type: string | description: The app GUID 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 GUID. - name: instanceId | type: string | description: The app instance GUID 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 GUID. 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.md). - name: grossRevenue | type: string | description: 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. - name: netRevenue | type: string | description: 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 - name: wixShare | type: string | description: 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. - name: createdDate | type: string | description: The date and time of the transaction. - name: billingType | type: BillingType | description: The type of billing event, either charge or refund. - enum: UNKNOWN, CHARGE, REFUND Possible Errors: HTTP Code: 428 | Status Code: FAILED_PRECONDITION | Application Code: FAILED_PRECONDITION | Description: The app isn't configured for external billing or the required conditions aren't met to report external billing events. ``` ### Examples ### Report a billing event with an access token ```curl curl -X POST \ 'https://www.wixapis.com/apps/v1/billing-event' \ -H 'Authorization: ' \ -H 'Content-Type: application/json' \ -d '{ "event": { "created_date": "2025-05-04T00:00:00Z", "billing_type": "CHARGE", "wix_share": "10", "net_revenue": "100", "gross_revenue": "110" } }' ``` ### Report a billing event with an API key ```curl curl -X POST \ 'https://www.wixapis.com/apps/v1/billing-event' \ -H 'Authorization: ' \ -H 'Content-Type: application/json' \ -H 'wix-account-id: ' \ -d '{ "event": { "app_id": "157f033e-c1ae-4418-adb0-79d2bcd9d4a8", "created_date": "2025-05-04T00:00:00Z", "billing_type": "CHARGE", "wix_share": "10", "net_revenue": "100", "gross_revenue": "110" } }' ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.appBilling.ExternalBillingBIService.reportExternalBillingEvent(options) Description: 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.md). The reported event enables Wix to track revenue, deductions, and Wix's share related to Partner Billed App charges. # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: options.event.grossRevenue, options.event.wixShare, options.event.billingType Method parameters: param name: options | type: ReportExternalBillingEventOptions none - name: event | type: ExternalBillingEvent | description: The billing event with details of the external transaction, including the gross revenue, net revenue, and billing type (charge or refund). - name: appId | type: string | description: The app GUID 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 GUID. - name: instanceId | type: string | description: The app instance GUID 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 GUID. 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.md). - name: grossRevenue | type: string | description: 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. | required: true - name: netRevenue | type: string | description: 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 - name: wixShare | type: string | description: 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. | required: true - name: _createdDate | type: Date | description: The date and time of the transaction. - name: billingType | type: BillingType | description: The type of billing event, either charge or refund. | required: true - enum: UNKNOWN, CHARGE, REFUND Return type: PROMISE - name: event | type: ExternalBillingEvent | description: The billing event that was processed. - name: appId | type: string | description: The app GUID 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 GUID. - name: instanceId | type: string | description: The app instance GUID 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 GUID. 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.md). - name: grossRevenue | type: string | description: 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. - name: netRevenue | type: string | description: 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 - name: wixShare | type: string | description: 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. - name: _createdDate | type: Date | description: The date and time of the transaction. - name: billingType | type: BillingType | description: The type of billing event, either charge or refund. - enum: UNKNOWN, CHARGE, REFUND Possible Errors: HTTP Code: 428 | Status Code: FAILED_PRECONDITION | Application Code: FAILED_PRECONDITION | Description: The app isn't configured for external billing or the required conditions aren't met to report external billing events. ``` ### Examples ### Report a billing event with an API key ```javascript import { createClient, ApiKeyStrategy } from "@wix/sdk"; import { externalBilling } from "@wix/app-management"; const myWixClient = createClient({ auth: ApiKeyStrategy({ apiKey: "", accountId: "", }), modules: { externalBilling }, }); const options = { event: { // Required when authenticating with an API key. appId: "", _createdDate: "2025-05-04T00:00:00Z", billingType: "CHARGE", grossRevenue: "110", netRevenue: "100", wixShare: "10", }, }; async function reportExternalBillingEvent() { await myWixClient.externalBilling.reportExternalBillingEvent(options); } ``` ### Report a billing event with an app access token ```javascript import { externalBilling } from "@wix/app-management"; const options = { event: { _createdDate: "2025-05-04T00:00:00Z", billingType: "CHARGE", grossRevenue: "110", netRevenue: "100", wixShare: "10", }, }; async function reportExternalBillingEvent() { await externalBilling.reportExternalBillingEvent(options); } ``` ### reportExternalBillingEvent (self-hosted) 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.md). ```javascript 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(options) { const response = await myWixClient.externalBilling.reportExternalBillingEvent(options); }; ``` ---