> 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

## Resource: Develop with the SDK

## Article: Develop with the SDK

## Article Link: https://dev.wix.com/docs/api-reference/articles/sdk-setup-and-usage/develop-with-the-sdk.md

## Article Content:

# Develop with the SDK

This article explains how to call methods from backend SDK modules across different Wix development frameworks and environments. Backend modules are SDK packages with REST API equivalents, and you can find them in this reference. They're universal and work in both Wix-hosted and self-hosted environments.

The approach you use depends on:
- Your development environment. Learn more about [website development](https://dev.wix.com/docs/develop-websites-sdk/get-started/overview/about-developing-websites.md), [app development frameworks](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/about-development-frameworks.md), and [headless development paths](https://dev.wix.com/docs/go-headless/develop-your-project/about-headless-development-paths.md).
- The context where your code runs. For example, in a site you can call SDK methods from a site page, a dashboard page, or backend code.
- Whether you need [elevated permissions](https://dev.wix.com/docs/api-reference/articles/authentication/about-elevated-permissions.md) to call restricted methods. Elevation lets you call methods that require higher-level permissions than the calling identity has, such as performing administrative operations from frontend code or handling sensitive data on behalf of site visitors or members.

SDK methods are asynchronous. Always call them inside an `async` function using `await`.

> **Note:** The examples in this article use methods from the [`@wix/ecom`](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/introduction?apiView=SDK.md) module:
> - [`currentCart.addToCurrentCart()`](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart/cart/add-to-current-cart?apiView=SDK.md): Adds items to the current visitor's cart. Can be called with a visitor or member identity.
> - [`orders.createOrder()`](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/orders/create-order?apiView=SDK.md): Creates an order. Requires higher-level permissions (app or Wix user identity).
> 
> Learn more about [identities](https://dev.wix.com/docs/api-reference/articles/authentication/about-identities.md).

This article covers the majority of typical use cases. If your specific scenario isn't included, consult the relevant documentation for further guidance.

## Wix Sites

When [developing websites](https://dev.wix.com/docs/develop-websites-sdk/get-started/overview/about-developing-websites.md) on Wix, you can add custom code to a site using the [code editor](https://dev.wix.com/docs/develop-websites-sdk/code-your-site/developer-environments/ides/code-editor/about-the-code-editor.md), the [Wix IDE](https://dev.wix.com/docs/develop-websites-sdk/code-your-site/developer-environments/ides/wix-ide/about-the-wix-ide.md), or a local IDE with [Git integration](https://dev.wix.com/docs/develop-websites-sdk/code-your-site/developer-environments/ides/git-integration/about-git-integration-with-wix-cli.md).

In Wix Sites, authentication is handled automatically. You don't need to create a Wix client.

Choose the tab that matches your use case:
- Site page: Call SDK methods from a [site page](https://dev.wix.com/docs/develop-websites-sdk/code-your-site/code-with-java-script/about-code-placement.md#frontend-code) with a visitor or member [identity](https://dev.wix.com/docs/develop-websites-sdk/code-your-site/authorization/about-identities.md).
- Site page with elevation: Call SDK methods from a site page using [elevation](https://dev.wix.com/docs/develop-websites-sdk/code-your-site/authorization/about-elevation.md) when they require higher-level permissions than the calling identity has.
- Dashboard page: Call SDK methods from a [dashboard page](https://dev.wix.com/docs/develop-websites/articles/coding-with-velo/frontend-code/dashboard-admin-pages/about-dashboard-pages.md) with a Wix user identity.
- Backend: Call SDK methods from [backend code](https://dev.wix.com/docs/develop-websites-sdk/code-your-site/build-a-custom-backend/about-the-site-backend.md) that isn't exposed to the frontend.
- Backend with elevation: Call SDK methods from backend code using elevation when they require higher-level permissions than the calling identity has.

::::tabs
:::Site-page

To call a backend SDK method from a site page:

1. In the page code, import the SDK module:

    ```js
    import { currentCart } from "@wix/ecom";
    ```

1. Call the SDK method:

    ```js
    async function myFunction() {
      const result = await currentCart.addToCurrentCart({
        lineItems: [{ catalogReference: { catalogItemId: "product-id-123", appId: "1380b703-ce81-ff05-f115-39571d94dfcd" }, quantity: 1 }]
      });
      const cart = result.cart;
      // Use cart
    }
    ```

:::
:::Site-page-with-elevation

To call a backend SDK method with elevated permissions from a site page:

1. Create a [web module](https://dev.wix.com/docs/develop-websites-sdk/code-your-site/build-a-custom-backend/web-modules/about-web-modules.md) file with a `.web.js` extension in your backend folder.

1. In the web module, import `Permissions` and `webMethod` from [`@wix/web-methods`](https://dev.wix.com/docs/sdk/core-modules/web-methods/introduction.md), [`auth`](https://dev.wix.com/docs/sdk/core-modules/essentials/auth.md) from `@wix/essentials`, and the SDK module:

    ```js
    import { Permissions, webMethod } from "@wix/web-methods";
    import { auth } from "@wix/essentials";
    import { orders } from "@wix/ecom";
    ```

1. Create a [web method](https://dev.wix.com/docs/develop-websites-sdk/code-your-site/build-a-custom-backend/web-modules/about-web-modules.md#web-methods) that elevates and calls the SDK method:

    ```js
    export const myWebMethod = webMethod(
      Permissions.Admin,
      async (orderData) => {
        const elevatedCreateOrder = auth.elevate(orders.createOrder);
        return await elevatedCreateOrder(orderData);
      }
    );
    ```

1. In the frontend code, import and call the web method:

    ```js
    import { myWebMethod } from "backend/myModule.web";

    async function myFunction() {
      const newOrder = await myWebMethod({
        channelInfo: { type: "WEB" },
        lineItems: [{
          productName: { original: "My Product" },
          price: { amount: "10.00" },
          quantity: 1,
          itemType: { preset: "PHYSICAL" },
        }],
        priceSummary: { total: { amount: "10.00" } },
      });
      // Use newOrder
    }
    ```

To learn more, see [Call Backend Code from the Frontend](https://dev.wix.com/docs/develop-websites-sdk/code-your-site/build-a-custom-backend/web-modules/call-backend-code-from-the-frontend.md). Note that the linked article doesn't cover elevation.

:::
:::Dashboard-page

To call a backend SDK method from a dashboard page:

1. In the dashboard page code, import the SDK module:

    ```js
    import { orders } from "@wix/ecom";
    ```

1. Call the SDK method: 

    ```js
    async function myFunction() {
      const newOrder = await orders.createOrder({
        channelInfo: { type: "WEB" },
        lineItems: [{
          productName: { original: "My Product" },
          price: { amount: "10.00" },
          quantity: 1,
          itemType: { preset: "PHYSICAL" },
        }],
        priceSummary: { total: { amount: "10.00" } },
      });
      // Use newOrder
    }
    ```

> **Note:** Some methods may still require elevation even in dashboard pages, depending on the specific permissions required. Check the method's documentation for authentication requirements.

:::
:::Backend

To call a backend SDK method from a backend file:

1. In the backend file, import the SDK module:

    ```js
    import { currentCart } from "@wix/ecom";
    ```

1. Call the SDK method:
    
    ```js
    export async function myBackendFunction(productId) {
      const result = await currentCart.addToCurrentCart({
        lineItems: [{ catalogReference: { catalogItemId: productId, appId: "1380b703-ce81-ff05-f115-39571d94dfcd" }, quantity: 1 }]
      });
      return result.cart;
    }
    ```

:::
:::Backend-with-elevation

To call a backend SDK method with elevated permissions from a backend file:

1. In your backend file, import [`auth`](https://dev.wix.com/docs/sdk/core-modules/essentials/auth.md) from `@wix/essentials` and the SDK module:

    ```js
    import { auth } from "@wix/essentials";
    import { orders } from "@wix/ecom";
    ```

1. Elevate and call the SDK method:

    ```js
    export async function myBackendFunction(orderData) {
      const elevatedCreateOrder = auth.elevate(orders.createOrder);
      return await elevatedCreateOrder(orderData);
    }
    ```

:::
::::

## Wix-hosted apps (Wix CLI)

The [Wix CLI](https://dev.wix.com/docs/wix-cli/guides/about-the-wix-cli.md) is the recommended CLI for new [apps](https://dev.wix.com/docs/build-apps.md). It supports Wix app development with a unified, [Astro](https://docs.astro.build/)-based development experience.

In Wix CLI app projects, authentication is handled automatically. You don't need to create a Wix client.

Choose the tab that matches your use case:
- Dashboard extension: Call SDK methods from a [dashboard extension](https://dev.wix.com/docs/wix-cli/guides/extensions/dashboard-extensions/about-dashboard-extensions.md) with a Wix user [identity](https://dev.wix.com/docs/api-reference/articles/authentication/about-identities?apiView=SDK.md).
- Backend extension: Call SDK methods from a [backend extension](https://dev.wix.com/docs/wix-cli/guides/extensions/backend-extensions/about-backend-extensions.md) with an app identity.
- Backend extension with elevation: Call SDK methods from a backend extension using [elevation](https://dev.wix.com/docs/wix-cli/guides/about-the-wix-cli.md) when they require higher-level permissions than the calling identity has.
- Site extension: Call SDK methods from a [site extension](https://dev.wix.com/docs/wix-cli/guides/extensions/site-extensions/about-site-extensions.md) with a visitor or member identity.
- Site extension with elevation: Call SDK methods from a site extension using elevation when they require higher-level permissions than the calling identity has.

::::tabs
:::Dashboard-extension

To call a backend SDK method from a dashboard extension:

1. In the dashboard extension code, import the SDK module:

    ```ts
    import { orders } from "@wix/ecom";
    ```

1. Call the SDK method:

    ```tsx
    function DashboardPage() {
      async function handleClick() {
        const newOrder = await orders.createOrder({
          channelInfo: { type: "WEB" },
          lineItems: [{
            productName: { original: "My Product" },
            price: { amount: "10.00" },
            quantity: 1,
            itemType: { preset: "PHYSICAL" },
          }],
          priceSummary: { total: { amount: "10.00" } },
        });
        console.log(newOrder);
      }

      return <button onClick={handleClick}>Create Order</button>;
    }
    ```

> **Note:** Some methods may still require elevation even in dashboard extensions, depending on the specific permissions required. Check the method's documentation for authentication requirements.

:::
:::Backend-extension

> **Note:** The following example calls the Wix SDK in an event extension, but the same principles apply to all backend extensions.

To call a backend SDK method in an event extension:

1. In the event extension file, import the SDK module:

    ```ts
    import { abandonedCheckouts, orders } from "@wix/ecom";
    ```

1. Call the SDK method:

    ```ts
    export default abandonedCheckouts.onAbandonedCheckoutCreated(async (event) => {
      // Create a follow-up order with a discount to recover the abandoned checkout
      const recoveryOrder = await orders.createOrder({
        channelInfo: { type: "WEB" },
        lineItems: [{
          productName: { original: "Checkout Recovery Offer" },
          price: { amount: "5.00" },
          quantity: 1,
          itemType: { preset: "PHYSICAL" },
        }],
        priceSummary: { total: { amount: "5.00" } },
      });
      console.log("Created recovery order for abandoned checkout:", recoveryOrder);
    });
    ```

:::
:::Backend-extension-with-elevation

> **Note:** The following example calls the Wix SDK in an event extension, but the same principles apply to all backend extensions.

To call a backend SDK method with elevated permissions in an event extension:

1. In the event extension file, import [`auth`](https://dev.wix.com/docs/sdk/core-modules/essentials/auth.md) from `@wix/essentials` and the SDK module:

    ```ts
    import { auth } from "@wix/essentials";
    import { abandonedCheckouts, orders } from "@wix/ecom";
    ```

1. Elevate and call the SDK method:

    ```ts
    export default abandonedCheckouts.onAbandonedCheckoutCreated(async (event) => {
      // Create a follow-up order with a discount to recover the abandoned checkout
      const elevatedCreateOrder = auth.elevate(orders.createOrder);
      const recoveryOrder = await elevatedCreateOrder({
        channelInfo: { type: "WEB" },
        lineItems: [{
          productName: { original: "Checkout Recovery Offer" },
          price: { amount: "5.00" },
          quantity: 1,
          itemType: { preset: "PHYSICAL" },
        }],
        priceSummary: { total: { amount: "5.00" } },
      });
      console.log("Created recovery order for abandoned checkout:", recoveryOrder);
    });
    ```

:::
:::Site-extension

To call a backend SDK method from a site extension:

1. In the site extension code, import the SDK module:

    ```ts
    import { currentCart } from "@wix/ecom";
    ```

1. Call the SDK method:

    ```ts
    async function myFunction() {
      const result = await currentCart.addToCurrentCart({
        lineItems: [{ catalogReference: { catalogItemId: "product-id-123", appId: "1380b703-ce81-ff05-f115-39571d94dfcd" }, quantity: 1 }]
      });
      const cart = result.cart;
      // Use cart
    }
    ```

:::
:::Site-extension-with-elevation
<!-- Based on current documentation, which isn't accurate. -->
To call a backend SDK method with elevated permissions from a site extension:

1. Create an [Astro server endpoint](https://docs.astro.build/en/guides/endpoints/#server-endpoints-api-routes) in your `src/pages/api/` directory.

1. In the endpoint, import `APIRoute` from `astro`, [`auth`](https://dev.wix.com/docs/sdk/core-modules/essentials/auth.md) from `@wix/essentials`, and the SDK module:

    ```ts
    // src/pages/api/create-order.ts
    import type { APIRoute } from "astro";
    import { auth } from "@wix/essentials";
    import { orders } from "@wix/ecom";
    ```

1. Elevate and call the SDK method in the Astro server endpoint:

    ```ts
    export const POST: APIRoute = async ({ request }) => {
      const orderData = await request.json();
      const elevatedCreateOrder = auth.elevate(orders.createOrder);
      const newOrder = await elevatedCreateOrder(orderData);
      return new Response(JSON.stringify(newOrder));
    };
    ```

1. In the site extension code, use [`httpClient.fetchWithAuth()`](https://dev.wix.com/docs/sdk/core-modules/essentials/http-client.md#fetchwithauth) to call the endpoint:

    ```ts
    import { httpClient } from "@wix/essentials";

    async function myFunction() {
      const response = await httpClient.fetchWithAuth("/api/create-order", {
        method: "POST",
        body: JSON.stringify({
          channelInfo: { type: "WEB" },
          lineItems: [{
            productName: { original: "My Product" },
            price: { amount: "10.00" },
            quantity: 1,
            itemType: { preset: "PHYSICAL" },
          }],
          priceSummary: { total: { amount: "10.00" } },
        }),
      });
      const newOrder = await response.json();
      // Use newOrder
    }
    ```

:::
::::

## Self-hosted apps

[Self-hosted apps](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/about-self-hosting-for-wix-apps.md) are Wix apps where you host the code on your own infrastructure. This gives you full control over your technology stack.

In self-hosted apps, you must create a [Wix client](https://dev.wix.com/docs/api-reference/articles/sdk-setup-and-usage/set-up-a-wix-client.md) to make authenticated SDK calls. The [authorization strategy](https://dev.wix.com/docs/api-reference/articles/sdk-setup-and-usage/set-up-a-wix-client.md#authorization-strategies-auth) depends on the context.

Choose the tab that matches your use case:
- Site widget or plugin: Call SDK methods from a [site widget](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/site-extensions/site-widgets/about-site-widget-extensions.md) or [site plugin](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/site-extensions/site-plugins/about-site-plugin-extensions.md) (custom element) with a visitor or member [identity](https://dev.wix.com/docs/build-apps/develop-your-app/access/about-identities.md).
- Embedded script: Call SDK methods from an [embedded script](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/site-extensions/embedded-scripts/about-embedded-scripts.md) with a visitor or member identity.
- Editor extension: Call SDK methods from an [editor extension](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/editor-extensions/about-editor-add-on-extensions.md) with a Wix user identity.
- Dashboard extension: Call SDK methods from a [dashboard extension](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/dashboard-extensions/about-dashboard-extensions.md) with a Wix user identity.
- Backend extension: Call SDK methods from a [backend extension](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/about-backend-extensions.md) with an app identity.

> **Note:** Site, editor, and dashboard extensions in self-hosted apps use host module authentication. Learn more about [host modules](https://dev.wix.com/docs/sdk/host-modules/about-host-modules.md).

::::tabs
:::Site-widget-or-plugin

To call a backend SDK method from a self-hosted site widget or plugin (custom element):

1. Import [`createClient`](https://dev.wix.com/docs/sdk/core-modules/sdk/wix-client.md) from `@wix/sdk` and [`site`](https://dev.wix.com/docs/sdk/host-modules/site/introduction.md) from `@wix/site`:

    ```js
    import { createClient } from "@wix/sdk";
    import { site } from "@wix/site";
    import { currentCart } from "@wix/ecom";
    ```

1. Create a client using the site `host` and `auth`:

    ```js
    const wixClient = createClient({
      host: site.host({ applicationId: "<YOUR_APP_ID>" }),
      auth: site.auth(),
      modules: { currentCart },
    });
    ```

1. In your custom element class, expose the access token injector so Wix can authenticate your client:

    ```js
    class MyWidget extends HTMLElement {
      constructor() {
        super();
        this.accessTokenListener = wixClient.auth.getAccessTokenInjector();
      }
    }
    ```

1. Call the SDK method using the client:

    ```js
    async function myFunction() {
      const result = await wixClient.currentCart.addToCurrentCart({
        lineItems: [{ catalogReference: { catalogItemId: "product-id-123", appId: "1380b703-ce81-ff05-f115-39571d94dfcd" }, quantity: 1 }]
      });
      // Use result
    }
    ```

To learn more, see [Authenticate using the Wix Client in Custom Elements](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/site-extensions/site-widgets-and-plugins/authenticate-using-the-wix-client-in-custom-elements-for-self-hosted-site-extensions.md).

:::
:::Embedded-script

> **Note:** Embedded scripts can be either standard JavaScript scripts (`type="text/javascript"` or no type) or JavaScript modules (`type="module"`). The script type affects how authentication is handled. Learn more about [script types](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/site-extensions/embedded-scripts/authenticate-using-the-wix-client-in-self-hosted-embedded-script-extensions.md#script-types).

To call a backend SDK method from a self-hosted embedded script:

1. Import [`createClient`](https://dev.wix.com/docs/sdk/core-modules/sdk/wix-client.md) from `@wix/sdk` and [`site`](https://dev.wix.com/docs/sdk/host-modules/site/introduction.md) from `@wix/site`:

    ```js
    import { createClient } from "@wix/sdk";
    import { site } from "@wix/site";
    import { currentCart } from "@wix/ecom";
    ```

1. Create a client using the site `host` and `auth`:

    ```js
    const wixClient = createClient({
      host: site.host({ applicationId: "<YOUR_APP_ID>" }),
      auth: site.auth(),
      modules: { currentCart },
    });
    ```

1. **JavaScript modules (ESM) only:** If your script uses `type="module"`, add `accesstoken="true"` to your script tag and export the access token injector function:

    ```js
    export const injectAccessTokenFunction = wixClient.auth.getAccessTokenInjector();
    ```

1. Call the SDK method using the client:

    ```js
    async function myFunction() {
      const result = await wixClient.currentCart.addToCurrentCart({
        lineItems: [{ catalogReference: { catalogItemId: "product-id-123", appId: "1380b703-ce81-ff05-f115-39571d94dfcd" }, quantity: 1 }]
      });
      // Use result
    }
    ```

To learn more, see [Authenticate using the Wix Client in Embedded Script Extensions](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/site-extensions/embedded-scripts/authenticate-using-the-wix-client-in-self-hosted-embedded-script-extensions.md).

:::
:::Editor-extension

To call a backend SDK method from a self-hosted editor extension:

1. Import [`createClient`](https://dev.wix.com/docs/sdk/core-modules/sdk/wix-client.md) from `@wix/sdk` and [`editor`](https://dev.wix.com/docs/sdk/host-modules/editor/introduction.md) from `@wix/editor`:

    ```js
    import { createClient } from "@wix/sdk";
    import { editor } from "@wix/editor";
    import { orders } from "@wix/ecom";
    ```

1. Create a client using the editor `host` and `auth`:

    ```js
    const wixClient = createClient({
      host: editor.host(),
      auth: editor.auth(),
      modules: { orders },
    });
    ```

1. Call the SDK method using the client:

    ```js
    async function myFunction() {
      const newOrder = await wixClient.orders.createOrder({
        channelInfo: { type: "WEB" },
        lineItems: [{
          productName: { original: "My Product" },
          price: { amount: "10.00" },
          quantity: 1,
          itemType: { preset: "PHYSICAL" },
        }],
        priceSummary: { total: { amount: "10.00" } },
      });
      // Use newOrder
    }
    ```

:::
:::Dashboard-extension

To call a backend SDK method from a self-hosted dashboard extension:

1. Import [`createClient`](https://dev.wix.com/docs/sdk/core-modules/sdk/wix-client.md) from `@wix/sdk` and [`dashboard`](https://dev.wix.com/docs/sdk/host-modules/dashboard/introduction.md) from `@wix/dashboard`:

    ```js
    import { createClient } from "@wix/sdk";
    import { dashboard } from "@wix/dashboard";
    import { orders } from "@wix/ecom";
    ```

1. Create a client using the dashboard `host` and `auth`:

    ```js
    const wixClient = createClient({
      host: dashboard.host(),
      auth: dashboard.auth(),
      modules: { orders },
    });
    ```

1. Call the SDK method using the client:

    ```js
    async function myFunction() {
      const newOrder = await wixClient.orders.createOrder({
        channelInfo: { type: "WEB" },
        lineItems: [{
          productName: { original: "My Product" },
          price: { amount: "10.00" },
          quantity: 1,
          itemType: { preset: "PHYSICAL" },
        }],
        priceSummary: { total: { amount: "10.00" } },
      });
      // Use newOrder
    }
    ```

> **Note:** Some methods may still require elevation even in dashboard extensions, depending on the specific permissions required. Check the method's documentation for authentication requirements.

:::
:::Backend-extension

To call a backend SDK method from a self-hosted backend extension:

1. Import [`createClient`](https://dev.wix.com/docs/sdk/core-modules/sdk/wix-client.md) and [`AppStrategy`](https://dev.wix.com/docs/sdk/core-modules/sdk/app-strategy.md) from `@wix/sdk`:

    ```js
    import { createClient, AppStrategy } from "@wix/sdk";
    import { orders } from "@wix/ecom";
    ```

1. Create a client with `AppStrategy` using your app credentials:

    ```js
    const wixClient = createClient({
      auth: AppStrategy({
        appId: "<YOUR_APP_ID>",
        appSecret: "<YOUR_APP_SECRET>",
        instanceId: "<APP_INSTANCE_ID>",
      }),
      modules: { orders },
    });
    ```

    To learn how to use `AppStrategy` to authenticate your client, see [AppStrategy](https://dev.wix.com/docs/sdk/core-modules/sdk/app-strategy.md).

1. Call the SDK method using the client:

    ```js
    async function myBackendFunction() {
      const newOrder = await wixClient.orders.createOrder({
        channelInfo: { type: "WEB" },
        lineItems: [{
          productName: { original: "My Product" },
          price: { amount: "10.00" },
          quantity: 1,
          itemType: { preset: "PHYSICAL" },
        }],
        priceSummary: { total: { amount: "10.00" } },
      });
      // Use newOrder
    }
    ```

:::
::::

## Wix-managed headless (Wix CLI)

The [Wix CLI](https://dev.wix.com/docs/wix-cli/guides/about-the-wix-cli.md) is the recommended CLI for new [headless projects](https://dev.wix.com/docs/go-headless.md). It supports headless development with a unified, [Astro](https://docs.astro.build/)-based development experience.

In Wix CLI headless projects, authentication is handled automatically. You don't need to create a Wix client.

Choose the tab that matches your use case:
- Dashboard extension: Call SDK methods from a [dashboard extension](https://dev.wix.com/docs/wix-cli/guides/extensions/dashboard-extensions/about-dashboard-extensions.md) with a Wix user [identity](https://dev.wix.com/docs/api-reference/articles/authentication/about-identities?apiView=SDK.md).
- Backend extension: Call SDK methods from a [backend extension](https://dev.wix.com/docs/wix-cli/guides/extensions/backend-extensions/about-backend-extensions.md) with an app identity.
- Backend extension with elevation: Call SDK methods from a backend extension using [elevation](https://dev.wix.com/docs/wix-cli/guides/about-the-wix-cli.md) when they require higher-level permissions than the calling identity has.
- Frontend: Call SDK methods from a [headless frontend](https://dev.wix.com/docs/wix-cli/guides/development/development-overview.md#astro-foundation) with a visitor or member identity.
- Frontend with elevation: Call SDK methods from a headless frontend using elevation when they require higher-level permissions than the calling identity has.

::::tabs
:::Dashboard-extension

To call a backend SDK method from a dashboard extension:

1. In the dashboard extension code, import the SDK module:

    ```ts
    import { orders } from "@wix/ecom";
    ```

1. Call the SDK method:

    ```tsx
    function DashboardPage() {
      async function handleClick() {
        const newOrder = await orders.createOrder({
          channelInfo: { type: "WEB" },
          lineItems: [{
            productName: { original: "My Product" },
            price: { amount: "10.00" },
            quantity: 1,
            itemType: { preset: "PHYSICAL" },
          }],
          priceSummary: { total: { amount: "10.00" } },
        });
        console.log(newOrder);
      }

      return <button onClick={handleClick}>Create Order</button>;
    }
    ```

> **Note:** Some methods may still require elevation even in dashboard extensions, depending on the specific permissions required. Check the method's documentation for authentication requirements.

:::
:::Backend-extension

> **Note:** The following example calls the Wix SDK in an event extension, but the same principles apply to all backend extensions.

To call a backend SDK method in an event extension:

1. In the event extension file, import the SDK module:

    ```ts
    import { abandonedCheckouts, orders } from "@wix/ecom";
    ```

1. Call the SDK method:

    ```ts
    export default abandonedCheckouts.onAbandonedCheckoutCreated(async (event) => {
      // Create a follow-up order with a discount to recover the abandoned checkout
      const recoveryOrder = await orders.createOrder({
        channelInfo: { type: "WEB" },
        lineItems: [{
          productName: { original: "Checkout Recovery Offer" },
          price: { amount: "5.00" },
          quantity: 1,
          itemType: { preset: "PHYSICAL" },
        }],
        priceSummary: { total: { amount: "5.00" } },
      });
      console.log("Created recovery order for abandoned checkout:", recoveryOrder);
    });
    ```

:::
:::Backend-extension-with-elevation

> **Note:** The following example calls the Wix SDK in an event extension, but the same principles apply to all backend extensions.

To call a backend SDK method with elevated permissions in an event extension:

1. In the event extension file, import [`auth`](https://dev.wix.com/docs/sdk/core-modules/essentials/auth.md) from `@wix/essentials` and the SDK module:

    ```ts
    import { auth } from "@wix/essentials";
    import { abandonedCheckouts, orders } from "@wix/ecom";
    ```

1. Elevate and call the SDK method:

    ```ts
    export default abandonedCheckouts.onAbandonedCheckoutCreated(async (event) => {
      // Create a follow-up order with a discount to recover the abandoned checkout
      const elevatedCreateOrder = auth.elevate(orders.createOrder);
      const recoveryOrder = await elevatedCreateOrder({
        channelInfo: { type: "WEB" },
        lineItems: [{
          productName: { original: "Checkout Recovery Offer" },
          price: { amount: "5.00" },
          quantity: 1,
          itemType: { preset: "PHYSICAL" },
        }],
        priceSummary: { total: { amount: "5.00" } },
      });
      console.log("Created recovery order for abandoned checkout:", recoveryOrder);
    });
    ```

:::
:::Frontend

To call a backend SDK method from a headless frontend:

1. In the page code, import the SDK module:

    ```html
    <script>
      import { currentCart } from "@wix/ecom";
      // ...
    </script>
    ```

1. Call the SDK method:

    ```html
    <script>
      // ...
      async function myFunction() {
        const result = await currentCart.addToCurrentCart({
          lineItems: [{ catalogReference: { catalogItemId: "product-id-123", appId: "1380b703-ce81-ff05-f115-39571d94dfcd" }, quantity: 1 }]
        });
        const cart = result.cart;
        // Use cart
      }
    </script>
    ```

:::
:::Frontend-with-elevation
<!-- Based on current documentation, which isn't accurate. -->
To call a backend SDK method with elevated permissions from a headless frontend:

1. Create an [Astro server endpoint](https://docs.astro.build/en/guides/endpoints/#server-endpoints-api-routes) in your `src/pages/api/` directory.

1. In the endpoint, import `APIRoute` from `astro`, [`auth`](https://dev.wix.com/docs/sdk/core-modules/essentials/auth.md) from `@wix/essentials`, and the SDK module:

    ```ts
    // src/pages/api/admin/create-order.ts
    import type { APIRoute } from "astro";
    import { auth } from "@wix/essentials";
    import { orders } from "@wix/ecom";
    ```

1. Elevate and call the SDK method in the Astro server endpoint:

    ```ts
    export const POST: APIRoute = async ({ request }) => {
      const orderData = await request.json();
      const elevatedCreateOrder = auth.elevate(orders.createOrder);
      const newOrder = await elevatedCreateOrder(orderData);
      return new Response(JSON.stringify(newOrder));
    };
    ```

1. In the frontend code, use [`httpClient.fetchWithAuth()`](https://dev.wix.com/docs/sdk/core-modules/essentials/http-client.md#fetchwithauth) to call the endpoint:

    ```astro
    <script>
      import { httpClient } from "@wix/essentials";

      async function myFunction() {
        const response = await httpClient.fetchWithAuth("/api/admin/create-order", {
          method: "POST",
          body: JSON.stringify({
          channelInfo: { type: "WEB" },
          lineItems: [{
            productName: { original: "My Product" },
            price: { amount: "10.00" },
            quantity: 1,
            itemType: { preset: "PHYSICAL" },
          }],
          priceSummary: { total: { amount: "10.00" } },
        }),
        });
        const newOrder = await response.json();
        console.log(newOrder);
      }
    </script>
    ```

:::
::::

## Self-managed headless

[Self-managed headless](https://dev.wix.com/docs/go-headless/develop-your-project/self-managed-headless/about-self-managed-headless.md) projects let you build a custom frontend with any framework while using Wix backend services. You're responsible for hosting and authentication.

In self-managed headless projects, you must create a [Wix client](https://dev.wix.com/docs/sdk/core-modules/sdk/wix-client.md) with an appropriate authentication strategy.

Choose the tab that matches your use case:
- Visitor or member: Call SDK methods with a visitor or member [identity](https://dev.wix.com/docs/go-headless/develop-your-project/self-managed-headless/authentication/about-authentication.md).
- Admin: Call SDK methods with admin-level permissions using an [API key](https://dev.wix.com/docs/api-reference/articles/authentication/api-keys/about-api-keys.md).

::::tabs
:::Visitor-or-member

To call a backend SDK method as a visitor or member:

1. Import [`createClient`](https://dev.wix.com/docs/sdk/core-modules/sdk/wix-client.md) and [`OAuthStrategy`](https://dev.wix.com/docs/sdk/core-modules/sdk/oauth-strategy.md) from `@wix/sdk`:

    ```js
    import { createClient, OAuthStrategy } from "@wix/sdk";
    import { currentCart } from "@wix/ecom";
    ```

1. Create a client with `OAuthStrategy`:

    ```js
    const wixClient = createClient({
      auth: OAuthStrategy({
        clientId: "<YOUR_CLIENT_ID>",
      }),
      modules: { currentCart },
    });
    ```

    > **Note:** Get your client ID from your project's [Headless Settings](https://www.wix.com/my-account/site-selector/?buttonText=Select%20Site&title=Select%20a%20Site&autoSelectOnSingleSite=true&actionUrl=https:%2F%2Fwww.wix.com%2Fdashboard%2F%7B%7BmetaSiteId%7D%7D%2Foauth-apps-settings) in the dashboard.

1. Call the SDK method using the client:

    ```js
    async function myFunction() {
      const result = await wixClient.currentCart.addToCurrentCart({
        lineItems: [{ catalogReference: { catalogItemId: "product-id-123", appId: "1380b703-ce81-ff05-f115-39571d94dfcd" }, quantity: 1 }]
      });
      // Use result
    }
    ```

For persistent sessions, you need to manage visitor and member tokens. Learn more about [handling visitors](https://dev.wix.com/docs/go-headless/develop-your-project/self-managed-headless/authentication/visitors/about-handling-visitors.md) and [handling members](https://dev.wix.com/docs/go-headless/develop-your-project/self-managed-headless/authentication/members/about-member-login.md).

:::
:::Admin

To call a backend SDK method with admin privileges:

1. [Generate an API key](https://dev.wix.com/docs/go-headless/develop-your-project/admin-operations/generate-an-api-key?apiView=SDK.md) in the [API Keys Manager](https://manage.wix.com/account/api-keys).

1. Import [`createClient`](https://dev.wix.com/docs/sdk/core-modules/sdk/wix-client.md) and [`ApiKeyStrategy`](https://dev.wix.com/docs/sdk/core-modules/sdk/api-key-strategy.md) from `@wix/sdk`, and the SDK module:

    ```js
    import { createClient, ApiKeyStrategy } from "@wix/sdk";
    import { orders } from "@wix/ecom";
    ```

1. Create a client with `ApiKeyStrategy`:

    ```js
    const wixClient = createClient({
      auth: ApiKeyStrategy({
        apiKey: "<YOUR_API_KEY>",
      }),
      modules: { orders },
    });
    ```

    To learn how to use `ApiKeyStrategy` to authenticate your client, see [ApiKeyStrategy](https://dev.wix.com/docs/sdk/core-modules/sdk/api-key-strategy.md).

1. Call the SDK method using the client:

    ```js
    async function myFunction() {
      const newOrder = await wixClient.orders.createOrder({
        channelInfo: { type: "WEB" },
        lineItems: [{
          productName: { original: "My Product" },
          price: { amount: "10.00" },
          quantity: 1,
          itemType: { preset: "PHYSICAL" },
        }],
        priceSummary: { total: { amount: "10.00" } },
      });
      // Use newOrder
    }
    ```

:::
::::

## Wix Blocks

[Wix Blocks](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-blocks/about-wix-blocks.md) is a visual editor for building Wix apps. You can create [widgets](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-blocks/site-widgets/about-site-widgets-in-blocks.md), [dashboard pages](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/dashboard-extensions/dashboard-pages/about-dashboard-page-extensions.md), and other app components using drag-and-drop design tools and custom code.

In Wix Blocks, authentication is handled automatically. You don't need to create a Wix client.

Choose the tab that matches your use case:
- Widget: Call SDK methods from a [widget](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-blocks/site-widgets/about-site-widgets-in-blocks.md) with a visitor or member [identity](https://dev.wix.com/docs/build-apps/develop-your-app/access/about-identities.md).
- Widget with elevation: Call SDK methods from a widget using [elevation](https://dev.wix.com/docs/build-apps/develop-your-app/access/authorization/about-elevation.md) when they require higher-level permissions than the calling identity has.
- Dashboard page: Call SDK methods from a [dashboard page](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-blocks/dashboard-pages/about-dashboard-pages-in-blocks.md) with a Wix user identity.

::::tabs
:::Widget

To call a backend SDK method from a widget:

1. In the widget code, import the SDK module:

    ```js
    import { currentCart } from "@wix/ecom";
    ```

1. Call the SDK method:

    ```js
    async function myFunction() {
      const result = await currentCart.addToCurrentCart({
        lineItems: [{ catalogReference: { catalogItemId: "product-id-123", appId: "1380b703-ce81-ff05-f115-39571d94dfcd" }, quantity: 1 }]
      });
      const cart = result.cart;
      // Use cart
    }
    ```

To learn more, see [Call Backend Code from the Frontend in Blocks](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-blocks/code-in-blocks/call-backend-code-from-the-frontend-in-blocks.md).

:::
:::Widget-with-elevation

To call a backend SDK method with elevated permissions from a widget:

1. In the Blocks editor, create a web module. This is a file in your `backend` directory with a `.web.js` extension.

1. In the web module, import `Permissions` and `webMethod` from [`@wix/web-methods`](https://dev.wix.com/docs/sdk/core-modules/web-methods/introduction.md), [`auth`](https://dev.wix.com/docs/sdk/core-modules/essentials/auth.md) from `@wix/essentials`, and the SDK module:

    ```js
    import { Permissions, webMethod } from "@wix/web-methods";
    import { auth } from "@wix/essentials";
    import { orders } from "@wix/ecom";
    ```

1. Create a web method that elevates and calls the SDK method:

    ```js
    export const myWebMethod = webMethod(
      Permissions.Admin,
      async (orderData) => {
        const elevatedCreateOrder = auth.elevate(orders.createOrder);
        return await elevatedCreateOrder(orderData);
      }
    );
    ```

1. In the widget code, import and call the web method:

    ```js
    import { myWebMethod } from "backend/myModule.web";

    async function myFunction() {
      const newOrder = await myWebMethod({
        channelInfo: { type: "WEB" },
        lineItems: [{
          productName: { original: "My Product" },
          price: { amount: "10.00" },
          quantity: 1,
          itemType: { preset: "PHYSICAL" },
        }],
        priceSummary: { total: { amount: "10.00" } },
      });
      // Use newOrder
    }
    ```

To learn more, see [Call Backend Code from the Frontend in Blocks](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-blocks/code-in-blocks/call-backend-code-from-the-frontend-in-blocks.md). Note that the linked article doesn't cover elevation.


:::
:::Dashboard-page

To call a backend SDK method from a Blocks dashboard page:

1. In the dashboard page code, import the SDK module:

    ```js
    import { orders } from "@wix/ecom";
    ```

1. Call the SDK method:

    ```js
    $w.onReady(async () => {
      const newOrder = await orders.createOrder({
        channelInfo: { type: "WEB" },
        lineItems: [{
          productName: { original: "My Product" },
          price: { amount: "10.00" },
          quantity: 1,
          itemType: { preset: "PHYSICAL" },
        }],
        priceSummary: { total: { amount: "10.00" } },
      });
      // Use newOrder
    });
    ```

> **Note:** Some methods may still require elevation even in dashboard pages, depending on the specific permissions required. Check the method's documentation for authentication requirements.

:::
::::

<!--
## CLI for Apps (Deprecated)

The [CLI for Apps](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-cli/about-the-wix-cli-for-apps.md) lets you build Wix apps using your local IDE. You can create site extensions, dashboard extensions, and backend extensions.

> **Note:** 
> 
> Wix is unifying app and headless project workflows in the [new Wix CLI](https://dev.wix.com/docs/wix-cli/guides/about-the-wix-cli.md). All new features will appear only in the new CLI.
> 
> The Wix CLI for Apps remains available for existing projects but will no longer receive updates or new features. For the best developer experience and the latest features, start new projects with the new Wix CLI.

In the CLI for Apps, authentication is handled automatically. You don't need to create a Wix client.

Choose the tab that matches your use case:
- Site extension: Call SDK methods from a [site extension](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/site-extensions/about-site-extensions.md) with a visitor or member [identity](https://dev.wix.com/docs/build-apps/develop-your-app/access/about-identities.md).
- Site extension with elevation: Call SDK methods from a site extension using [elevation](https://dev.wix.com/docs/build-apps/develop-your-app/access/authorization/about-elevation.md) when they require higher-level permissions than the calling identity has.
- Dashboard extension: Call SDK methods from a [dashboard extension](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/dashboard-extensions/about-dashboard-extensions.md) with a Wix user identity.
- Backend extension: Call SDK methods from a [backend extension](https://dev.wix.com/docs/wix-cli/legacy-clis/legacy-wix-cli-for-apps/supported-extensions/backend-extensions/about-cli-app-backend-extensions.md) with an app identity.
- Backend extension with elevation: Call SDK methods from a backend extension using elevation when they require higher-level permissions than the calling identity has.

::::tabs
:::Site-extension

To call a backend SDK method from a site extension:

1. In the site extension code, import the SDK module:

    ```ts
    import { currentCart } from "@wix/ecom";
    ```

1. Call the SDK method:

    ```ts
    async function myFunction() {
      const result = await currentCart.addToCurrentCart({
        lineItems: [{ catalogReference: { catalogItemId: "product-id-123", appId: "1380b703-ce81-ff05-f115-39571d94dfcd" }, quantity: 1 }]
      });
      const cart = result.cart;
      // Use cart
    }
    ```

:::
:::Site-extension-with-elevation

> **Note:** This example uses a web method extension to call the SDK method, but the same principles apply to all backend extensions. Learn more about [elevating API call permissions with the CLI for Apps](https://dev.wix.com/docs/wix-cli/legacy/wix-cli-for-apps/app-development/elevate-api-call-permissions-with-the-cli.md).

To call a backend SDK method with elevated permissions from a site extension:

1. Create a [web method extension](https://dev.wix.com/docs/wix-cli/legacy-clis/legacy-wix-cli-for-apps/supported-extensions/backend-extensions/api/web-methods/add-web-method-extensions-with-the-cli.md) in your project.

1. In the web method file, import `Permissions` and `webMethod` from [`@wix/web-methods`](https://dev.wix.com/docs/sdk/core-modules/web-methods/introduction.md), [`auth`](https://dev.wix.com/docs/sdk/core-modules/essentials/auth.md) from `@wix/essentials`, and the SDK module:

    ```ts
    import { Permissions, webMethod } from "@wix/web-methods";
    import { auth } from "@wix/essentials";
    import { orders } from "@wix/ecom";
    ```

1. Create a [web method](https://dev.wix.com/docs/wix-cli/legacy-clis/legacy-wix-cli-for-apps/supported-extensions/backend-extensions/api/web-methods/add-web-method-extensions-with-the-cli.md) that elevates and calls the SDK method:

    ```ts
    export const myWebMethod = webMethod(
      Permissions.Admin,
      async (orderData: { lineItems: Array<{ quantity: number }> }) => {
        const elevatedCreateOrder = auth.elevate(orders.createOrder);
        return await elevatedCreateOrder(orderData);
      }
    );
    ```

1. In the site extension code, import and call the web method:

    ```ts
    import { myWebMethod } from "../backend/orders.web";

    async function myFunction() {
      const newOrder = await myWebMethod({
        channelInfo: { type: "WEB" },
        lineItems: [{
          productName: { original: "My Product" },
          price: { amount: "10.00" },
          quantity: 1,
          itemType: { preset: "PHYSICAL" },
        }],
        priceSummary: { total: { amount: "10.00" } },
      });
      // Use newOrder
    }
    ```

:::
:::Dashboard-extension

To call a backend SDK method from a dashboard extension:

1. In the dashboard extension code, import the SDK module:

    ```ts
    import { orders } from "@wix/ecom";
    ```

1. Call the SDK method:

    ```tsx
    function DashboardPage() {
      async function handleClick() {
        const newOrder = await orders.createOrder({
          channelInfo: { type: "WEB" },
          lineItems: [{
            productName: { original: "My Product" },
            price: { amount: "10.00" },
            quantity: 1,
            itemType: { preset: "PHYSICAL" },
          }],
          priceSummary: { total: { amount: "10.00" } },
        });
        console.log(newOrder);
      }

      return <button onClick={handleClick}>Create Order</button>;
    }
    ```

> **Note:** Some methods may still require elevation even in dashboard extensions, depending on the specific permissions required. Check the method's documentation for authentication requirements.

:::
:::Backend-extension

> **Note:** The following example calls the Wix SDK in an event extension, but the same principles apply to all backend extensions.

To call a backend SDK method in an event extension:

1. In the event extension file, import the SDK module:

    ```ts
    import { abandonedCheckouts, orders } from "@wix/ecom";
    ```

1. Call the SDK method:

    ```ts
    export default abandonedCheckouts.onAbandonedCheckoutCreated(async (event) => {
      // Create a follow-up order with a discount to recover the abandoned checkout
      const recoveryOrder = await orders.createOrder({
        channelInfo: { type: "WEB" },
        lineItems: [{
          productName: { original: "Checkout Recovery Offer" },
          price: { amount: "5.00" },
          quantity: 1,
          itemType: { preset: "PHYSICAL" },
        }],
        priceSummary: { total: { amount: "5.00" } },
      });
      console.log("Created recovery order for abandoned checkout:", recoveryOrder);
    });
    ```

:::
:::Backend-extension-with-elevation

> **Note:** The following example calls the Wix SDK in an event extension, but the same principles apply to all backend extensions.

To call a backend SDK method with elevated permissions in an event extension:

1. In the event extension file, import [`auth`](https://dev.wix.com/docs/sdk/core-modules/essentials/auth.md) from `@wix/essentials` and the SDK module:

    ```ts
    import { auth } from "@wix/essentials";
    import { abandonedCheckouts, orders } from "@wix/ecom";
    ```

1. Elevate and call the SDK method:

    ```ts
    export default abandonedCheckouts.onAbandonedCheckoutCreated(async (event) => {
      // Create a follow-up order with a discount to recover the abandoned checkout
      const elevatedCreateOrder = auth.elevate(orders.createOrder);
      const recoveryOrder = await elevatedCreateOrder({
        channelInfo: { type: "WEB" },
        lineItems: [{
          productName: { original: "Checkout Recovery Offer" },
          price: { amount: "5.00" },
          quantity: 1,
          itemType: { preset: "PHYSICAL" },
        }],
        priceSummary: { total: { amount: "5.00" } },
      });
      console.log("Created recovery order for abandoned checkout:", recoveryOrder);
    });
    ```

:::
::::
-->