Get to know our frameworks

Select an app template built on your preferred framework.

Build apps on our native app editor. Use drag and drop elements, Velo code and Wix APIs to develop custom features.

Streamline your app development process with the Wix CLI. Get a familiar developer experience with minimal setup and configuration.

Take full control over your app's tech stack, deployment, and hosting.

App templates

Wix Blocks templates

Wix CLI templates

Self-hosted templates

Kickstart your app development with templates built on your preferred Wix developer tool. Browse templates for practical foundation and get to know the Wix ecosystem.

Wix App Templates for Developers

This example apps can be used as a starting point for building your own app, for concrete examples of how to use Wix framework, or for inspiration.

Choose a template.<0 />Build an app.

Browse by:

How to build it step by step:

This template is built with:

Read how this template was built, step by step.

How we built this template

Deployment instructions:

Choose a package manager and run the command in your terminal.

Copy command

Before you get started, make sure you have the following:

Prerequisite steps

Get started with Wix CLI

Begin by setting up your Next.js project with your preferred hosting platform.

Select your hosting service

Start the deployment flow and set up your template repo on Netlify. After you finish set up, come back here and add your Netlify custom domain.

Copy the code from our Git repo to deploy your app on any platform that supports Next.js.

Start the deployment flow and set up your template repo on Vercel. After you finish set up, come back here and add your Vercel generated URL.

Add the base URL and give your app a name.

App details

Go to the app dashboard and test your app to ensure a smooth integration within the Wix ecosystem. <0>Learn more about app checks and testing</0>

Define your environment

Terminal

Related templates

Note

Warning

Your app name will be used as the namespace suffix.

Name your app to generate a namespace. This lets you refer to your app in code later on.

Go Headless

Build Apps

Client

API Preview

Ricos

Develop Websites

REST

Velo

GraphQL (Alpha)

payload

ChargeLimitUpdatedEventEnvelope

Triggered in case the charge limit for an instance of your app is updated.


You can't update the charge limit after you've set an initial
value. Site owners can increase the limit in their site's dashboard,
currently they aren't allowed to decrease it.

import { customCharges } from '@wix/app-management/service-plugins';

customCharges.provideHandlers({

  chargeLimitUpdatedEvent: async ( payload ) => {
    const {request, metadata} = payload;
        // Use the `request` and `metadata` received from Wix and
        // apply custom logic.
      return {}
    }
});


Example of a charge limit updated event 

chargeLimitUpdatedEvent

ChargeLimitUpdatedResponse

ChargesRejectedEventEnvelope

Triggered in case Wix doesn't accept the charges you've returned in the
List Charges method.


You aren't allowed to charge a site owner more than the charge limit. Wix
call List Charges in regular intervals until the sum of all charges is lower than the
charge limit. Wix doesn't create an invoice in case the charges aren't accepted.

import { customCharges } from '@wix/app-management/service-plugins';

customCharges.provideHandlers({

  chargesRejectedEvent: async ( payload ) => {
    const {request, metadata} = payload;
        // Use the `request` and `metadata` received from Wix and
        // apply custom logic.
      return {}
    }
});


Example of a charges rejected event 

chargesRejectedEvent

ChargesRejectedResponse

GetChargeLimitEnvelope

Wix calls this method to retrieve the initial charge limit for a paid instance
of your app. This happens every time a customer is upgrading to a paid version of
your app.

You can't update the charge limit after you've set an initial
value. Customers can increase the limit in their site's dashboard, currently they
aren't allowed to decrease it.

import { customCharges } from '@wix/app-management/service-plugins';

customCharges.provideHandlers({

  getChargeLimit: 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:
        chargeLimit: "1000.00"
      }
    }
});


Example of a `chargeLimit` return value 

getChargeLimit

GetChargeLimitResponse

InvoiceCreatedEventEnvelope

Triggered in case Wix creates an invoice that includes charges for an instance
of your app.

import { customCharges } from '@wix/app-management/service-plugins';

customCharges.provideHandlers({

  invoiceCreatedEvent: async ( payload ) => {
    const {request, metadata} = payload;
        // Use the `request` and `metadata` received from Wix and
        // apply custom logic.
      return {}
    }
});


Example of an invoice created event 

invoiceCreatedEvent

InvoiceCreatedResponse

ListChargesEnvelope

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.

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"
          }
        ]
      }
    }
});


Example of a `charges` return value 

listCharges

ListChargesResponse

# About the Custom Charges Service Plugin

As a custom charges provider, you can integrate with Wix to allow a merchant to manage what customers must pay to use an app. This includes regularly recurring base prices, installation and usage fees, and any other custom charges.

The integration is done via an app in the Wix App Market and by implementing the Custom Charges [service plugin](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/service-plugins/about-service-plugin-extensions). After the app is installed on a site, Wix triggers a call to your service when specific actions are taken on the site. Refer to each function's description for details about those actions.

Using the service plugin, you can design your app to:

+ Add an app's charges to the invoice that Wix sends to site owners.
+ Receive notifications about charges that Wix doesn't accept, created invoices, or when customers increase their charge limit.
+ Keep your customers informed about how much an app would charge them if Wix were to send an invoice at this moment.

## Before you begin

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

Before you can implement the Custom Charges service plugin, it's essential to set up [Usage-Based Pricing](https://dev.wix.com/docs/build-apps/launch-your-app/pricing-and-billing/set-up-a-usage-based-business-model) for the app in the [Wix Developers Center](https://dev.wix.com/). Note that you have to [submit a request](https://www.wix.com/support-chatbot?nodeId=25a57397-ccf7-4376-8b74-48d51edf7159&referral=devRels) to enable Usage-Based Pricing. Keep in mind that Usage-Based Pricing is currently in Alpha, this means it's still in development and may change in the future.
+ You can't bill your customers before they [upgrade](https://support.wix.com/en/article/upgrading-an-app-from-the-wix-app-market) to a paid version of the app.
+ You're able to include up to 5 custom charges per invoice.
+ You must set an initial charge limit and can't bill customers more than this limit per billing cycle. You can't change the limit later, but customers are able to increase it themselves.
+ You receive notifications in case Wix doesn't accept the charges you return via the service plugin. Currently, there is no notification if the customer agrees to your proposed charge limit or pays an invoice.
+ Currently, Wix supports the following currencies: `AUD`, `BRL`, `CAD`, `EUR`, `GBP`, `ILS`, `INR`, `JPY`, `MXN`, `PLN`, `RUB`, `TRY`, `USD`. Wix may add more currencies in the future.
+ We recommend to use the `instanceId` instead of the `subscriptionId` to track usage and billing for apps.
+ If we discover 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.

## Get started

Follow these steps to begin implementing your service plugin.

### Choose a framework

You can implement this service plugin with the following [frameworks](https://dev.wix.com/docs/build-apps/get-started/overview/wix-s-development-frameworks):

+ **Wix CLI:** Learn how to [implement a service plugin with the CLI and the SDK](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-cli/supported-extensions/backend-extensions/service-plugins/add-service-plugin-extensions-with-the-cli).
+ **Self-hosted:** Learn how to [implement a self-hosted service plugin with the SDK and the Wix Dev Center](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions-with-the-sdk).

### Configure your service plugin

To configure and customize your plugin, you need to provide important information in the service plugin configuration file. You can [configure your plugin in the Wix Dev Center](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions-with-the-sdk#step-1--add-a-service-plugin-extension-to-your-app). For details, see [Custom Charges Extension Configuration](https://dev.wix.com/docs/sdk/backend-modules/app-management/service-plugins/custom-charges/extension-config).

### Define handler functions

Use [`customCharges.provideHandlers()`](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions-with-the-sdk#step-4--define-handler-functions) to define the following handler functions that implement your custom business logic. Make sure you define all required functions.

| Function                    | Required       |
|-----------------------------|----------------|
| [`chargeLimitUpdatedEvent()`](https://dev.wix.com/docs/sdk/backend-modules/app-management/service-plugins/custom-charges/charge-limit-updated-event)    | Yes            |
| [`chargesRejectedEvent()`](https://dev.wix.com/docs/sdk/backend-modules/app-management/service-plugins/custom-charges/charges-rejected-event)    | Yes            |
| [`getChargeLimit()`](https://dev.wix.com/docs/sdk/backend-modules/app-management/service-plugins/custom-charges/get-charge-limit)    | Yes            |
| [`invoiceCreatedEvent()`](https://dev.wix.com/docs/sdk/backend-modules/app-management/service-plugins/custom-charges/invoice-created-event)    | Yes            |
| [`listCharges()`](https://dev.wix.com/docs/sdk/backend-modules/app-management/service-plugins/custom-charges/list-charges)    | Yes            |

## Code examples

Below is an example for implementing the Custom Charges service plugin in your code.

### CLI: Basic code structure

This is the basic code structure for implementing the Custom Charges service plugin with the Wix CLI:

```js
import { customCharges } from '@wix/app-management/service-plugins'

customCharges.provideHandlers({
  chargeLimitUpdatedEvent: async (payload) => {

    const { request, metadata } = payload;

    // Add your logic here

  },
  chargesRejectedEvent: async (payload) => {

    const { request, metadata } = payload;

    // Add your logic here

  },
  getChargeLimit: async (payload) => {

    const { request, metadata } = payload;

    // Add your logic here

  },
  invoiceCreatedEvent: async (payload) => {

    const { request, metadata } = payload;

    // Add your logic here

  },
  listCharges: async (payload) => {

    const { request, metadata } = payload;

    // Add your logic here

  }  
});
  
```

### Self-hosted: Basic code structure

This is the basic code structure for implementing a self-hosted Custom Charges service plugin:

```js
import { createClient } from '@wix/sdk';
import { customCharges } from '@wix/app-management/service-plugins'

const wixClient = createClient({
  auth: {
    appId: <YOUR_APP_ID>,
    publicKey: <YOUR_APP_PUBLIC_KEY>
  },
  modules: { customCharges }
});

wixClient.customCharges.provideHandlers({
  chargeLimitUpdatedEvent: async (payload) => {

    const { request, metadata } = payload;

    // Add your logic here

  },
  chargesRejectedEvent: async (payload) => {

    const { request, metadata } = payload;

    // Add your logic here

  },
  getChargeLimit: async (payload) => {

    const { request, metadata } = payload;

    // Add your logic here

  },
  invoiceCreatedEvent: async (payload) => {

    const { request, metadata } = payload;

    // Add your logic here

  },
  listCharges: async (payload) => {

    const { request, metadata } = payload;

    // Add your logic here

  }  
});

// Implement a router to process all requests
express.post('/plugins-and-webhooks/*', (req, res) => {
  wixClient.process(req);
});
  
```

## See also

+ [About Service Plugin Extensions](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/service-plugins/about-service-plugin-extensions)
+ [Add a Service Plugin Extension With the CLI](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-cli/supported-extensions/backend-extensions/service-plugins/add-service-plugin-extensions-with-the-cli)
+ [Add a Self-hosted Service Plugin With the SDK](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions-with-the-sdk)


app-management_custom-charges

To configure and customize your service plugin, you need to provide important details in the `plugin.json` configuration file.

Custom Charges Extension Config

Extension Config

CustomChargesConfig

AlternativeUri

Custom URI that Wix uses to call your server for this method. The path-suffix documented in the method will not be appended to this URI.
Must be a secured endpoint beginning with `https://`. For example, `https://www.my-shipping-provider.com/my-shipping-rates`.

absoluteUri

string

Name of the method to create a custom URI for.

For `methodName`, use the name of the method in PascalCase.
For example, for Get Shipping Rates use `GetShippingRates`.

methodName

metadata

Context

request

ChargeLimitUpdatedRequest

chargeLimit

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 the charges. Wix may add supported currencies in the future.

currency

ID of the subscription for which the charge limit has been updated.
To track usage and billing for apps, we recommend to use `instanceId` instead
of the `subscriptionId`.

subscriptionId

ChargeLineItem

ID of the charge. Make sure to save the charge ID on your servers for future
reference. Identical to `lineItem.chargeId` in the Invoice Created Event.

Max: 64 characters

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`

amount

description

ChargesRejectedRequest

ChargesRejectedReason

IDs of the rejected charges.

Max: 5 charges

chargeIds

Maximum amount that your app may charge the customer per billing cycle.

Min: `0.50`

Information about why Wix has rejected your app's charges.

+ `"UNKNOWN_REASON"`: There is no information about why Wix has rejected the charges.
+ `"CHARGE_LIMIT_EXCEEDED"`: The sum of the charges is higher than the limit that you may charge the customer per billing cycle.
+ `"TOO_MANY_CHARGES"`: You can't provide more than 5 charges per invoice.
+ `"INVALID_FORMAT"`: You must submit charges as whole numbers or use a dot to separate major and minor units. For example, `10` or `1.50`. Currently, Wix doesn't validate whether the submitted number of decimals for the minor unit is supported for the given currency.

Max: 20 reasons

reasons

ID of the subscription for which Wix hasn't accepted your custom charges.
To track usage and billing for apps, we recommend to use `instanceId` instead
of the `subscriptionId`.

[ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) 3-letter currency code.

An object that describes the identity that triggered this request.

identity

IdentificationData

instanceId

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"`.

languages

A unique identifier of the request. You may print this ID to your logs to help with future debugging and easier correlation with Wix's logs.

requestId

Base part of your integration's deployment URI for the Custom Charges SPI.
For example `"https://provider.example.com"`, if Wix should call your
integration at `https://provider.example.com/v1/charge-limit` for the
Get Charge Limit method.

baseUri

SpiBaseUri

GetChargeLimitRequest

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 the charge limit. Wix may add supported currencies in the future.

ID of the subscription for which Wix retrieves the charge limit. Equals
`null` in case Wix hasn't created the subscription when retrieving an
initial charge limit. To track usage and billing for apps, we recommend to
use `instanceId` instead of the `subscriptionId`.

Retrieved charge limit for the app instance. You can't update the
charge limit after you've set an initial value. Site owners can increase the
limit in their site's dashboard, currently they aren't allowed to decrease it.

ID of a site visitor that has not logged in to the site.

anonymousVisitorId

appId

ID of a site visitor that has logged in to the site.

memberId

ID of a Wix user (site owner, contributor, etc.).

wixUserId

identityType

IdentityType

Intent

InvoiceCreatedRequest

invoiceId

lineItems

ID of the subscription for which Wix has created an invoice that includes
your custom charges. To track usage and billing for apps, we recommend to use
`instanceId` instead of the `subscriptionId`.

InvoiceLineItem

ID of the line item in the invoice that Wix sends to the customer.

ID of the charge as returned in List Charges.

Max: 64 characters

chargeId

ListChargesRequest

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.

Information about what Wix intends to do with the retrieved charges.

+ `"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.

intent

End of the period Wix retrieves the app instance's charges for in
`YYYY-MM-DDThh:mm:ss.sssZ` format.

periodEnd

Begin of the period Wix retrieves the app instance's charges for in
`YYYY-MM-DDThh:mm:ss.sssZ` format.

periodStart

ID 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`.

charges

Alternate, custom URIs to replace the default URIs for specific service plugin methods.

alternativeUris

Base URI where the methods are called. Wix appends the path to the `baseUri`.
For example, to call the Get Shipping Rates method at `https://my-shipping-provider.com/v1/getRates`, the base URI you provide here is `https://my-shipping-provider.com/`.

Extension Config

chargeLimitUpdatedEvent( )