> 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 # ListCharges # Package: appBilling # Namespace: CustomChargesProvider # Method link: https://dev.wix.com/docs/api-reference/app-management/app-billing/custom-charges-service-plugin/list-charges.md ## Introduction Wix calls this method to retrieve a list of charges for a paid instance of your app. This happens when Wix creates an invoice or in case the customer wants to preview how much your app would charge them at the moment. You must return the charges in the currency that's specified in the request, you aren't allowed to return more than 5 charges, and their sum must be lower than the charge limit. You may not bill customers for any usage that didn’t occur during the period Wix specifies when retrieving the charges. If Wix discovers that your app has charged customers for usage outside of an invoice's specified period, we may take action such as blocking your app from charging the customer, removing your app from the Wix App Market, revoking your access to the Wix developer program, or pursuing legal action to recover damages caused by overcharging. We understand that mistakes can happen and encourage you to contact [the Wix App Market team](https://devforum.wix.com/kb/en/contact) immediately if you become aware of any overcharging issues so that we can work together to resolve the situation. > **Note:** > This feature isn't yet available to all users. Your app can have only 1 usage-based plan and no other plans. To add a usage-based plan to your app, [submit a request to add a usage-based plan](https://www.wix.com/support-chatbot?nodeId=25a57397-ccf7-4376-8b74-48d51edf7159&referral=devRels). --- ## REST API ### Schema ``` Method: listCharges Description: Wix calls this method to retrieve a list of charges for a paid instance of your app. This happens when Wix creates an invoice or in case the customer wants to preview how much your app would charge them at the moment. You must return the charges in the currency that's specified in the request, you aren't allowed to return more than 5 charges, and their sum must be lower than the charge limit. You may not bill customers for any usage that didn’t occur during the period Wix specifies when retrieving the charges. If Wix discovers that your app has charged customers for usage outside of an invoice's specified period, we may take action such as blocking your app from charging the customer, removing your app from the Wix App Market, revoking your access to the Wix developer program, or pursuing legal action to recover damages caused by overcharging. We understand that mistakes can happen and encourage you to contact [the Wix App Market team](https://devforum.wix.com/kb/en/contact) immediately if you become aware of any overcharging issues so that we can work together to resolve the situation. > **Note:** > This feature isn't yet available to all users. Your app can have only 1 usage-based plan and no other plans. To add a usage-based plan to your app, [submit a request to add a usage-based plan](https://www.wix.com/support-chatbot?nodeId=25a57397-ccf7-4376-8b74-48d51edf7159&referral=devRels). URL: null Method: POST Method parameters: param name: currency | type: currency | description: Supported values: `AUD`, `BRL`, `CAD`, `EUR`, `GBP`, `ILS`, `INR`, `JPY`, `MXN`, `PLN`, `RUB`, `TRY`, `USD`. 3-letter currency code in [ISO-4217 alphabetic](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) format of your charges to return. Wix may add supported currencies in the future. param name: intent | type: Intent - enum: DISPLAY_ONLY - Inform the customer about how much your app would charge them at the moment. Wix doesn't create an invoice. CREATE_INVOICE - Create an invoice for the customer. param name: periodEnd | type: periodEnd | description: End of the period Wix retrieves the app instance's charges for in `YYYY-MM-DDThh:mm:ss.sssZ` format. param name: periodStart | type: periodStart | description: Begin of the period Wix retrieves the app instance's charges for in `YYYY-MM-DDThh:mm:ss.sssZ` format. param name: subscriptionId | type: subscriptionId | description: GUID of the subscription for which Wix retrieves your custom charges. To track usage and billing for apps, we recommend to use `instanceId` instead of the `subscriptionId`. Return type: ListChargesResponse - name: charges | type: array | description: Retrieved charges. Max: 10 charges - name: id | type: string | description: GUID of the charge. Make sure to save the charge GUID on your servers for future reference. Identical to `lineItem.chargeId` in the Invoice Created Event. Max: 64 characters - name: description | type: string | description: Charge description. - name: amount | type: string | description: Charge amount in the currency that's specified in the request. Use a whole number or separate major and minor units with a dot. For example, `10` or `1.99`. If you return an amount with more minor units than supported according to [ISO-4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes), Wix truncates the additional minor units. Min: `0.50` ``` ### Examples ### Return your app's custom charges. The data payload includes the following object as an encoded JWT. Here, we show the request and response objects decoded. ```curl curl -X POST \ 'https://provider.example.com/v1/charges' \ -H 'Authorization: ' \ -d '{ "data": { "request": { "subscriptionId": "efa6b37d-74c6-44bb-b639-28c4af3957dd", "currency": "USD", "periodStart": 1677674012000, "periodEnd": 1680179612000, "intent": "CREATE_INVOICE" }, "metadata": { "requestId": "1680014776.67327419774788218037", "identity": { "identityType": "APP", "appId": "365288ae-38f4-4932-92d5-d45c596c7260" }, "instanceId": "3aa496c3-aa49-4369-84e6-3fa1876f191d" } }, "aud": "6675724b-bf3e-482a-9a00-65616953b570", "iss": "wix.com", "iat": 1680014777, "exp": 1683614777 }' ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.appBilling.CustomChargesProvider.listCharges(request, metadata) Description: Wix calls this method to retrieve a list of charges for a paid instance of your app. This happens when Wix creates an invoice or in case the customer wants to preview how much your app would charge them at the moment. You must return the charges in the currency that's specified in the request, you aren't allowed to return more than 5 charges, and their sum must be lower than the charge limit. You may not bill customers for any usage that didn’t occur during the period Wix specifies when retrieving the charges. If Wix discovers that your app has charged customers for usage outside of an invoice's specified period, we may take action such as blocking your app from charging the customer, removing your app from the Wix App Market, revoking your access to the Wix developer program, or pursuing legal action to recover damages caused by overcharging. We understand that mistakes can happen and encourage you to contact [the Wix App Market team](https://devforum.wix.com/kb/en/contact) immediately if you become aware of any overcharging issues so that we can work together to resolve the situation. > **Note:** > This feature isn't yet available to all users. Your app can have only 1 usage-based plan and no other plans. To add a usage-based plan to your app, [submit a request to add a usage-based plan](https://www.wix.com/support-chatbot?nodeId=25a57397-ccf7-4376-8b74-48d51edf7159&referral=devRels). Method parameters: param name: metadata | type: Context | description: this message is not directly used by any service, it exists to describe the expected parameters that SHOULD be provided to invoked Velo methods as part of open-platform. e.g. SPIs, event-handlers, etc.. NOTE: this context object MUST be provided as the last argument in each Velo method signature. Example: ```typescript export function wixStores_onOrderCanceled({ event, metadata }: OrderCanceledEvent) { ... } ``` - name: requestId | type: string | description: A unique identifier of the request. You may print this GUID to your logs to help with future debugging and easier correlation with Wix's logs. - name: currency | type: string | description: [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) 3-letter currency code. - name: identity | type: IdentificationData | description: An object that describes the identity that triggered this request. - ONE-OF: - name: anonymousVisitorId | type: string | description: GUID of a site visitor that has not logged in to the site. - name: memberId | type: string | description: GUID of a site visitor that has logged in to the site. - name: wixUserId | type: string | description: GUID of a Wix user (site owner, contributor, etc.). - name: appId | type: string | description: GUID of an app. - name: languages | type: array | description: A string representing a language and region in the format of `"xx-XX"`. First 2 letters represent the language code according to ISO 639-1. This is followed by a dash "-", and then a by 2 capital letters representing the region according to ISO 3166-2. For example, `"en-US"`. - name: instanceId | type: string | description: The service provider app's instance GUID. param name: request | type: ListChargesRequest - name: subscriptionId | type: string | description: GUID of the subscription for which Wix retrieves your custom charges. To track usage and billing for apps, we recommend to use `instanceId` instead of the `subscriptionId`. - name: currency | type: string | description: Supported values: `AUD`, `BRL`, `CAD`, `EUR`, `GBP`, `ILS`, `INR`, `JPY`, `MXN`, `PLN`, `RUB`, `TRY`, `USD`. 3-letter currency code in [ISO-4217 alphabetic](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) format of your charges to return. Wix may add supported currencies in the future. - name: periodStart | type: Date | description: Begin of the period Wix retrieves the app instance's charges for in `YYYY-MM-DDThh:mm:ss.sssZ` format. - name: periodEnd | type: Date | description: End of the period Wix retrieves the app instance's charges for in `YYYY-MM-DDThh:mm:ss.sssZ` format. - name: intent | type: Intent | description: Information about what Wix intends to do with the retrieved charges. - enum: - DISPLAY_ONLY: Inform the customer about how much your app would charge them at the moment. Wix doesn't create an invoice. - CREATE_INVOICE: Create an invoice for the customer. Return type: PROMISE - name: charges | type: array | description: Retrieved charges. Max: 10 charges - name: _id | type: string | description: GUID of the charge. Make sure to save the charge GUID on your servers for future reference. Identical to `lineItem.chargeId` in the Invoice Created Event. Max: 64 characters - name: description | type: string | description: Charge description. - name: amount | type: string | description: Charge amount in the currency that's specified in the request. Use a whole number or separate major and minor units with a dot. For example, `10` or `1.99`. If you return an amount with more minor units than supported according to [ISO-4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes), Wix truncates the additional minor units. Min: `0.50` ``` ### Examples ### Example of a `charges` return value ```javascript import { customCharges } from '@wix/app-management/service-plugins'; customCharges.provideHandlers({ listCharges: async ( payload ) => { const {request, metadata} = payload; // Use the `request` and `metadata` received from Wix and // apply custom logic. return { // Return your response exactly as documented to integrate with Wix. // Return value example: charges: [ { _id: "Some Charge Id 1", description: "Setup fee", amount: "200.00" }, { _id: "Some Charge Id 2", description: "Usage charges", amount: "300.00" } ] } } }); ``` ### listCharges (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 { customCharges } from '@wix/app-management/service-plugins'; // Import the auth strategy for the relevant access type // Import the relevant host module if needed const myWixClient = createClient ({ modules: { customCharges }, // Include the auth strategy and host as relevant }); async function listCharges(request,metadata) { const response = await myWixClient.customCharges.listCharges(request,metadata); }; ``` ---