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)

Generic shipping rate calculation error.

Throw this error for cases the other errors don't cover.
You can optionally provide error data to help debug the issue.
Error data you provide appears in the monitoring log but is not exposed to the user.
This error may block the site visitor from proceeding to checkout, so throw it only if there is no other way to proceed.

GenericShippingRatesWixError

Invalid address error.

Throw this error when one or more fields in the address provided are invalid.
This error tells Wix that more address details are needed to calculate the shipping rate.
Wix may then prompt the user to provide more detailed address information.
The error data must include the invalid fields in the address. For example: `ShippingDestination.subdivision`.

InvalidAddressWixError

Invalid postal code error.

Throw this error when an invalid postal code is provided in the request.
This error tells Wix that a valid postal code is required to calculate the shipping rate.
You can optionally provide error data to help debug the issue.
Error data you provide appears in the monitoring log but is not exposed to the user.
This error may block the site visitor from proceeding to checkout, so throw it only if there is no other way to proceed.

InvalidPostalCodeWixError

if (request.postalCode.length < 2) {
    throw new InvalidPostalCodeWixError();
}

Example of InvalidPostalCodeWixError

Missing postal code error.

Throw this error when a postal code is not provided in the request.
This error tells Wix that a valid postal code is required to calculate the shipping rate.
You can optionally provide error data to help debug the issue.
Error data you provide appears in the monitoring log but is not exposed to the user.
This error may block the site visitor from proceeding to checkout, so throw it only if there is no other way to proceed.

MissingPostalCodeWixError

if (!request.postalCode) {
    throw new MissingPostalCodeWixError({
        supportedPostalCodes: ['124', '4532'],
    });
}

Example of MissingPostalCodeWixError

payload

GetShippingRatesEnvelope

This method retrieves applicable shipping rates for a delivery from your app.

Wix calls this method when certain actions are performed on the cart and/or checkout. For example, when an item is added to the cart, or the shipping destination is changed.

import { shippingRates } from '@wix/ecom/service-plugins';

shippingRates.provideHandlers({

  getShippingRates: 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:
        shippingRates: [
          {
            code: "usps-international",
            title: "USPS - International",
            logistics: {
              deliveryTime: "2-5 days",
            },
            cost: {
              price: "15",
              currency: "USD",
              additionalCharges: [
                {
                  price: "10",
                  type: "HANDLING_FEE",
                  details: "Handling fee of $5 applied for fragile items.",
                }
              ]
            }
          }
        ]
      }
    }
});


Example of a `shippingRates` return value 

getShippingRates

GetShippingRatesResponse

# About the Shipping Rates Service Plugin

As a shipping provider, you can integrate with Wix to allow a merchant's stores or businesses to request and use your shipping services on their Wix sites. Your shipping rates are then displayed on the site's cart and checkout pages.

The integration is done via an app in the Wix App Market and by implementing the Shipping Rates [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 whenever the site needs to retrieve shipping rates for a transaction.

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

+ Provide shipping estimates, including fees and times.
+ Provide shipping rates using your own custom logic.
+ Provide services for delivery and pickup.

## 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 [Shipping Rates Extension Configuration](https://dev.wix.com/docs/sdk/backend-modules/ecom/service-plugins/shipping-rates/extension-config).

### Define handler functions

Use [`shippingRates.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       |
|-----------------------------|----------------|
| [`getShippingRates()`](https://dev.wix.com/docs/sdk/backend-modules/ecom/service-plugins/shipping-rates/get-shipping-rates)    | Yes            |

## Code examples

Below is an example for implementing the Shipping Rates service plugin in your code.

### CLI: Basic code structure.

This is the basic code structure for implementing the Shipping Rates service plugin with the Wix CLI:

```js
import { shippingRates } from '@wix/ecom/service-plugins'

shippingRates.provideHandlers({
  getShippingRates: 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 Shipping Rates service plugin:

```js
import { createClient } from '@wix/sdk';
import { shippingRates } from '@wix/ecom/service-plugins'

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

wixClient.shippingRates.provideHandlers({
  getShippingRates: 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)
+ [Tutorial | Create a Self-hosted Custom Shipping Rates App](https://dev.wix.com/docs/build-apps/get-started/tutorials/tutorial-create-a-self-hosted-custom-shipping-rates-app)


ecom_shipping-rates

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

Providing shipping options for the US east coast.

East-Coast Shipping Provider

Shipping Rates Extension Config

Extension Config

ShippingRatesConfig

AdditionalCharge

Details of the additional charge. For example, `"Handling fee of $5 applied for gift wrapping"`.

details

string

Cost of additional charge. For example, `12.5`.

price

type

Address

Main address line, usually street and number as free text.

addressLine

streetAddress

addressLine1

Free text providing more detailed address info. Usually contains Apt, Suite, and Floor.

addressLine2

city

country

postalCode

Subdivision shorthand. Usually, a short code (2 or 3 letters) that represents a state, region, prefecture, or province. e.g. NY

subdivision

ApplicationError

code

data

description

CatalogReference

ID of the app providing the catalog.

You can get your app's ID from its page in the [Wix Dev Center](https://dev.wix.com/apps).

For items from Wix catalogs, the following values always apply:
+ Wix Stores: `"215238eb-22a5-4c36-9e7b-e7c08025e04e"`
+ Wix Bookings: `"13d21c63-b5ec-5912-8397-c3a5ddb27a97"`
+ Wix Restaurants: `"9a5d83fd-8570-482e-81ab-cfa88942ee60"`

appId

ID of the item within the catalog it belongs to.

catalogItemId

Additional item details in key:value pairs. Use this optional field to provide more specificity with item selection. The `options` field values differ depending on which catalog is providing the items.

For products and variants from a Wix Stores catalog, learn more about [eCommerce integration](https://dev.wix.com/docs/rest/business-solutions/stores/catalog/e-commerce-integration).

options

Context

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

currency

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

DeliveryLogistics

When the item is expected to be delivered in free text. For example, `"3-5 business days"`.

deliveryTime

Instructions for delivery. For example, for pickup: `"Ensure to come during business hours, and please don't park in the disabled spot"`.

instructions

Pickup details. Should be returned only if order is for pickup.

pickupDetails

PickupDetails

DeliveryPreferences

preferredCode

FieldViolation

field

ruleName

violatedRule

RuleType

FullAddressContactDetails

company

email

firstName

lastName

phone

Tax info. Currently usable only in Brazil.

vatId

VatId

GenericShippingRatesError

errors

metadata

request

GetShippingRatesRequest

buyerContactDetails

List of delivery preferences, for example preferred delivery code (`shippingOptionId`).

deliveryPreferences

lineItems

Persistent ID that correlates between the various eCommerce elements: cart, checkout, and order.

purchaseFlowId

shippingDestination

Address item is shipped from. This is the site owner's business address.

shippingOrigin

Whether tax is included in the items' prices.

taxIncludedInPrices

boolean

Weight measurement unit used for all items in the shipment.

Supported values:
+ `"KG"`: kilograms
+ `"LB"`: pounds

weightUnit

WeightUnit

Available shipping rates. These define the shipping rate options that are displayed to site visitors on the cart and checkout pages.

shippingRates

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

anonymousVisitorId

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

InvalidAddressError

fields

InvalidPostalCodeError

error

MissingPostalCodeError

PhysicalProperties

shippable

Stock-keeping unit. Learn more about [SKUs](https://www.wix.com/encyclopedia/definition/stock-keeping-unit-sku).

Line item weight. Measurement unit matches the weight unit specified in `weightUnit` in the request.

weight

number

address

Pickup method.

Supported values:
+ `"STORE_PICKUP"`: When pickup is from the merchant's brick and mortar store.
+ `"PICKUP_POINT"`: When item is shipped to a specified pickup point.

pickupMethod

PickupMethod

ProductItem

catalogReference

item delivery destination index in the shipping addresses list

deliveryDestinationIndex

where the item is delivered from index in the from addresses list

deliveryOriginIndex

name

physicalProperties

priceBeforeDiscount

quantity

whether tax is included in line item price

taxIncludedInPrice

Total line item price after discounts. This is equal to `price` multiplied by `quantity`.