Mintlify Sandbox

Coding Examples

Overview

Sled Tests

Go Headless

Studio Two

Dashboard Extensions

Backend Extensions

Site Extensions

Extend Websites with SDK

Wix APIs and References

Build Apps

Frontend Modules

Client (Deprecated)

API Preview

Wix CLI

Contexts

Ricos

Extend Websites with Velo

API Reference

Velo

Picasso

# Service Plugin Extension Files and Code

When you add a [service plugin](fallback::https://dev.wix.com/docs/overview/extensions-framework/backend-extensions/service-plugins) extension, the generated files land under `src/extensions/backend/service-plugins/<plugin-name>/`.

A Studio Two site, a Wix CLI app, and a Wix-managed headless project each generate a configuration file and a handler. Studio Two imports the builder from `@wix/custom-extensions`. A Wix CLI app and a headless project import it from `@wix/astro/builders`. In a Studio Two project, the extension is also registered in `extensions.ts`.

```text
src/
└── extensions/
    └── backend/
        └── service-plugins/
            └── <plugin-name>/
                ├── <plugin-name>.extension.ts
                └── <plugin-name>.ts
```

| File | What it's for |
|------|---------------|
| `<plugin-name>.extension.ts` | The [configuration file](fallback::#configuration-file) for the plugin ID, name, and handler path. |
| `<plugin-name>.ts` | The [handler](fallback::#handler) Wix calls during the host flow. |

`<plugin-name>` comes from the name you give the plugin. In Studio Two, that name is at most 19 characters.

## Configuration file

The `<plugin-name>.extension.ts` file declares the plugin. The builder function depends on the plugin type. An Ecom Additional Fees plugin uses `extensions.ecomAdditionalFees()`.

Import `extensions` from the package your project uses:

```ts
// Studio Two site
import { extensions } from '@wix/custom-extensions';
```

```ts
// Wix CLI app or headless project
import { extensions } from '@wix/astro/builders';
```

```ts
export default extensions.ecomAdditionalFees({
  id: '6eca2ad6-b311-4d92-92d3-88e4ff9fc021',
  name: 'ecom-additional-fee',
  source: './extensions/backend/service-plugins/ecom-additional-fee/ecom-additional-fee.ts',
});
```

A project may include extra fields for that plugin type. The API reference introduction for the plugin lists those fields.

### Configuration fields

These fields are on the generated Studio Two configuration. Other fields vary by plugin type.

| Field | Type | Description |
|--|--|--|
| `id` | string | Service plugin ID as a GUID. It must be unique across extensions in the project. **Generate** sets it. |
| `name` | string | The plugin name. In Studio Two, this is the folder and file name, and it is at most 19 characters. |
| `source` | string | Path to the handler file, relative to the project's `src/` directory. |

## Handler

The `<plugin-name>.ts` file is the code Wix calls. Import the plugin from its SDK module and pass your functions to `provideHandlers()`. The generated file includes one function per method, with an empty return value you replace.

In a Studio Two site or a Wix CLI app, call `provideHandlers()` directly:

```ts
import { additionalFees } from '@wix/ecom/service-plugins';

additionalFees.provideHandlers({
  calculateAdditionalFees: async ({ request, metadata }) => {
    return {
      additionalFees: [],
    };
  },
});
```

In a headless project, export the handlers:

```ts
import { additionalFees } from '@wix/ecom/service-plugins';

export default additionalFees.provideHandlers({
  calculateAdditionalFees: async ({ request, metadata }) => {
    return {
      additionalFees: [],
    };
  },
});
```

The import and the function names change with the plugin type. For what the function receives and what it must return, open that plugin in [Available Service Plugins](fallback::https://dev.wix.com/docs/backend-extensions/service-plugins/available-service-plugins) and follow the link to its API reference.

## Registration in Studio Two

A Studio Two project registers the plugin in `src/extensions.ts`. **Generate** adds the import and the `app().use()` call:

```ts
import { app } from '@wix/custom-extensions';
import ecomAdditionalFee from './extensions/backend/service-plugins/ecom-additional-fee/ecom-additional-fee.extension.ts';

export default app().use(ecomAdditionalFee);
```

When the project already has other extensions, **Generate** appends another `.use()` call to the existing chain.

## See also

- [About Service Plugins](fallback::https://dev.wix.com/docs/backend-extensions/service-plugins/about-service-plugins)
- [Available Service Plugins](fallback::https://dev.wix.com/docs/backend-extensions/service-plugins/available-service-plugins)
- [Service Plugins](fallback::https://dev.wix.com/docs/overview/extensions-framework/backend-extensions/service-plugins)

File	What it's for
`<plugin-name>.extension.ts`	The configuration file for the plugin ID, name, and handler path.
`<plugin-name>.ts`	The handler Wix calls during the host flow.