Go Headless

Build Apps

Client

API Preview

Ricos

Develop Websites

REST

Velo

GraphQL (Alpha)

Redirects

Redirects 1 0 0

options

CreateRedirectSessionOptions

Creates a URL for redirecting a visitor from an external client site to a Wix page for Wix-managed functionality.

The Create Redirect Session method enables your external Wix Headless client site, built on any platform, to integrate Wix-managed frontend functionality for specific processes.
For example, your site can temporarily redirect a visitor to Wix for authentication, or for a checkout process for bookings, eCommerce, events, or paid plans transactions.

To initiate a redirect session:

1. Call Create Redirect Session with the details required for Wix to take care of one specific process (for example, authentication or a bookings checkout). Provide one or more callback URLs, so Wix can redirect the visitor back to your site as appropriate when the process is over.
1. Redirect your visitor to the URL provided in the response. This URL includes query parameters informing Wix where to redirect the visitor back to on your external site.
1. Make sure the pages at the callback URLs you provided take care of the next stages in your visitor flow.

import { redirects } from '@wix/redirects';

async function createRedirectSession(options) {
  const response = await redirects.createRedirectSession(options);
};

createRedirectSession: Wix-hosted

import { auth } from '@wix/essentials';
import { redirects } from '@wix/redirects';


async function myCreateRedirectSessionMethod(options) {
  const response = await myWixClient.redirects.myCreateRedirectSessionMethod(options);
};

createRedirectSession: (with elevated permissions)

import { createClient } from '@wix/sdk';
import { redirects } from '@wix/redirects';
// Import the auth strategy for the relevant access type
// Import the relevant host module if needed

const myWixClient = createClient ({
  modules: { redirects },
  // Include the auth strategy and host as relevant
});


async function createRedirectSession(options) {
  const response = await myWixClient.redirects.createRedirectSession(options);
};

Self-hosted SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client).

createRedirectSession: Self-hosted

createRedirectSession

Manage Bookings Services and Settings

Manage Events

Manage Portfolio

Access Verticals by Automations

Set Up Automations

Manage Restaurants - all permissions

CreateRedirectSessionResponse

---
title: Introduction
---

# About the Redirects API

> **Note:** This API is only intended for use with [Wix Headless](https://dev.wix.com/docs/go-headless/getting-started/about-headless/about-wix-headless).

Wix Headless provides you with the flexibility to create an app or site on any platform and take advantage of Wix's backend business solutions via APIs. However, for some processes, such as authentication and checkout, you can save time and effort by using standard frontend pages produced by Wix. The Redirects API enables you to temporarily redirect visitors from your external site to a Wix-managed page for these processes, and then return them to your site. These Wix-managed pages are seamlessly incorporated into the user experience of your external site.

With the Redirects API, you can:

+ Redirect a site visitor to a Wix authentication page, then have them redirected back to your external site with authorization credentials.
+ Take advantage of Wix frontend functionality by redirecting users to Wix-managed pages for bookings, eCommerce, events, and paid plans transaction checkouts.
+ Customize your flow, integrating Wix-managed pages alongside custom external pages. For example, use a Wix checkout with an external thank you page.

## Before you begin

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

+ After a redirect session for authentication, Wix returns visitors to the redirect URI you provide only if the full **URI** has been authorized in advance. Make sure to add approved authentication URIs in the [Headless Settings menu](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 Wix project dashboard.
+ After all other redirect sessions, Wix returns visitors to the post-flow URL you provide only if the **domain** has been authorized in advance. Make sure to add approved domains in the [Headless Settings menu](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 Wix project dashboard.

## Terminology

+ **Redirect session:** A temporary redirection of a visitor from an external site to a Wix-managed page for a process such as authentication or checkout.


@package_metadata:@wix/redirects

To use the Redirects API, install the `@wix/redirects` package.

### Install the package
To install the package, follow the instructions below based on your development environment.

#### Wix sites and Blocks apps
When developing with:
 - Editor or Wix IDE: Use the [package manager](https://dev.wix.com/docs/develop-websites/articles/coding-with-velo/packages/work-with-npm-packages-in-the-editor).
 - Local IDE: Use the [Wix CLI](https://dev.wix.com/docs/develop-websites/articles/coding-with-velo/packages/work-with-npm-packages-with-the-wix-cli). Run the following command:
  ```console
npm install @wix/redirects
```

or

```console
yarn add @wix/redirects
```


#### Wix apps and Headless
When developing CLI or self-hosted Wix apps, as well as headless apps or sites, run the following command:
  ```console
npm install @wix/redirects
```

or

```console
yarn add @wix/redirects
```

#### Import the package

To import the package in your code:

```js
import { redirects } from '@wix/redirects'
```
  

redirects_redirects

AuthorizeRequest

ID of the Wix OAuth app requesting authorization.

clientId

string

Code challenge to use for PKCE verification.
This field is only used if `responseType` is set to `code`.

codeChallenge

Code challenge method to use for PKCE verification.
This field is only used if `responseType` is set to `code`.

Supported values:
+ `S256`: The code challenge is transformed using SHA-256 encyption.
+ `S512`: The code challenge is transformed using SHA-512 encyption.

codeChallengeMethod

URI to redirect the browser to after authentication and authorization. The browser is redirected to this URI whether the authentication and authorization process is successful or not.

redirectUri

esired response format.

Supported values:
+ `query`: The response parameters are encoded as query string parameters and added to the `redirectUri` when redirecting.
+ `fragment`: The response parameters are encoded as URI fragment parameters and added to the `redirectUri` when redirecting.
+ `web_message`: The response parameters are encoded as a JSON object and added to the body of a [web message response](https://datatracker.ietf.org/doc/html/draft-sakimura-oauth-wmrm-00).

Default value: `query`

responseMode

Desired authorization [grant type](https://auth0.com/docs/authenticate/protocols/oauth#grant-types).

Supported values:
+ `code`: The endpoint returns an authorization code that can be used to obtain an access token.

responseType

Desired scope of access. If this field is left empty, only an access token is granted.
To received a refresh token, pass `offline_access` as the value of this field.

scope

Session token of the site visitor to authorize.

sessionToken

signInUrl

A value used to confirm the state of an application before and after it makes an authorization
request. If a value for this field is set in the request, it's added to the `redirectUri` when the browser
is redirected there.
Learn more about [using the state parameter](https://auth0.com/docs/secure/attack-protection/state-parameters).

state

BookingPolicyViolations

Bookings policy violation. Online booking is disabled for this slot.

bookOnlineDisabled

boolean

Bookings policy violation. Too early to book this slot.

tooEarlyToBook

Bookings policy violation. Too late to book this slot.

tooLateToBook

CallbackParams

The URL for a custom bookings services page implemented outside of Wix.

Default: If you don't specify a URL, a Wix bookings services page is used.

bookingsServiceListUrl

The URL for a custom eCommerce cart page implemented outside of Wix.

Default: If you don't specify a URL, a Wix cart page is used.

cartPageUrl

The URL for a custom login page implemented outside of Wix.

Default: If you don't specify a URL, a Wix login page is used.

loginUrl

The URL for a custom pricing plans page implemented outside of Wix. When redirecting to this URL, Wix specifies the following query parameters:
+ `planIds`:  IDs of the pricing plans on the custom page.
+ `checkoutData`: Specify this string back in `options.paidPlansCheckout.checkoutData` when redirecting back to Wix for checkout.

 Default: If you don't specify a URL, a Wix pricing plans page is used.

planListUrl

The URL Wix should redirect the visitor to when the Wix-managed process is completed, abandoned, or interrupted.

**Note**: For an authentication redirect, don't specify a URL here. Instead, specify one in `options.auth.authRequest.redirectUri`.

postFlowUrl

The URL for a custom thank you page implemented on a site outside of Wix. The visitor is directed to this page after the Wix-managed process is completed.
When redirecting to this URL, Wix passes different query parameters depending on the preceding transaction:

After a pricing plans checkout:
+ `planOrderId`: ID of a pricing plan order.

After an eCommerce checkout:
+ `orderId`: ID of an eCommerce order.

After an Events checkout:
+ `orderNumber`: Unique order number for the transaction.
+ `eventId`: ID of the event.

If the process is abandoned or interrupted, the visitor is redirected to the URL specified in `postFlowUrl` instead.

Default: If you don't specify a URL, the visitor is redirected to a Wix thank you page, and from there to the URL specified in `postFlowUrl`.

thankYouPageUrl

Information required for generating a custom URL for Wix authentication.

auth

Information required for generating a custom URL for Wix bookings book page.

bookingsBook

Information required for generating a custom URL for a Wix Bookings checkout.

bookingsCheckout

Information required for generating a custom URL for a Wix eCommerce checkout.

ecomCheckout

Information required for generating a custom URL for a Wix Events checkout.

eventsCheckout

Specify an empty object in this parameter to generate a URL for Wix login without first checking whether the visitor is authenticated.

login

Information required for generating a custom URL to log out from a Wix account. This process invalidates the visitor or member token and clears cookies associated with the Wix domain from their browser.

logout

Information required for generating a custom URL for a Wix Paid Plans checkout.

paidPlansCheckout

Information required for generating a custom URL for a Wix stores product page.

storesProduct

Details of pages to redirect back to on the Wix Headless client site.

**Note**: For an authentication redirect, don't specify a post-flow URL here. Instead, specify one in `options.auth.authRequest.redirectUri`.

callbacks

Optional preferences for customizing redirection to Wix pages.

preferences

RedirectSessionPreferences

Details for redirecting the visitor to a Wix page.

redirectSession

RedirectSession

EventMetadata

Unique event ID.
Allows clients to ignore duplicate webhooks.

A sequence number defining the order of updates to the underlying entity.
For example, given that some entity was updated at 16:00 and than again at 16:01,
it is guaranteed that the sequence number of the second update is strictly higher than the first.
As the consumer, you can use this value to ensure that you handle messages in the correct order.
To do so, you will need to persist this number on your end, and compare the sequence number from the
message against the one you have stored. Given that the stored number is higher, you should ignore the message.

entityEventSequence

Assumes actions are also always typed to an entity_type
Example: wix.stores.catalog.product, wix.bookings.session, wix.payments.transaction

entityFqdn

ID of the entity associated with the event.

entityId

Event timestamp in [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) format and UTC time. For example: 2020-04-26T13:57:50.699Z

eventTime

eventType

The identification type and identity data.

identity

IdentificationData

instanceId

If present, indicates the action that triggered the event.

originatedFrom

This is top level to ease client code dispatching of messages (switch on entity_fqdn+slug)
This is although the created/updated/deleted notion is duplication of the oneof types
Example: created/updated/deleted/started/completed/email_opened

slug

Whether the event was triggered as a result of a privacy regulation application
(for example, GDPR).

triggeredByAnonymizeRequest

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

WebhookIdentityType

Location

Business location ID. Available only for locations that are business locations,
meaning the `location_type` is `"OWNER_BUSINESS"`.

formattedAddress

The full translated address of this location.

formattedAddressTranslated

Location type.

- `"OWNER_BUSINESS"`: The business address, as set in the site’s general settings.
- `"OWNER_CUSTOM"`: The address as set when creating the service.
- `"CUSTOM"`: The address as set for the individual session.

locationType

LocationType

name

OnRedirectSessionCreatedHandler

event

RedirectSessionCreatedEnvelope

void

Display the login page to the member, prompting them to enter their credentials.

Bypass the Wix login page and redirect the member directly to your site.
This option checks if the member has an active session from a previous login
and, if so, immediately redirects to the specified URL while retrieving tokens.

Prompt

The full URL of the Wix page to redirect the visitor to. This URL includes query parameters informing Wix where to redirect the visitor back to on the Wix Headless client site.

fullUrl

The session token to pass to the Wix page to maintain the visitor's identity.

The short URL of the Wix page to redirect the visitor to. This URL includes query parameters informing Wix where to redirect the visitor back to on the Wix Headless client site.

shortUrl

Details about the URL of the redirect session.

urlDetails

URLDetails

RedirectSessionAuthParams

authRequest

The type of prompt to use during the authorization process.

prompt

RedirectSessionBookingsBookParams

For use when filtering the bookings page by a specific resource.

resourceId

RedirectSessionBookingsCheckoutParams

slotAvailability

SlotAvailability

The timezone to use when presenting the selected slot to users, in [tz database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) format. For example, `America/Santiago`.

Default: If you don't specify a timezone, the timezone in `slotAvailability.slot.timezone` is used.

timezone

entity

metadata

RedirectSessionEcomCheckoutParams

- SDK: Use [Create Checkout](https://dev.wix.com/docs/sdk/backend-modules/ecom/checkout/create-checkout) or [Create Checkout From Current Cart](https://dev.wix.com/docs/sdk/backend-modules/ecom/current-cart/create-checkout-from-current-cart).
- REST: Use [Create Checkout From Cart](https://dev.wix.com/docs/rest/business-solutions/e-commerce/cart/create-checkout-from-cart).

checkoutId

RedirectSessionEventsCheckoutParams

eventSlug

reservationId

RedirectSessionLoginParams

RedirectSessionLogoutParams

RedirectSessionPaidPlansCheckoutParams

For use when pricing plan selection is part of a checkout flow, only if the paid plan selection page is implemented on an external Wix Headless client site.
In this case, a string is received by the external pricing plans page as a `checkoutData` query parameter. Pass this string back here when redirecting back to Wix for checkout.

checkoutData

planId

Map of additional global query parameters to add to the created Wix URL.
For example, [UTM parameters](https://en.wikipedia.org/wiki/UTM_parameters).

additionalQueryParameters

Whether to maintain the identity used in the redirect to Wix (not relevant for `logout` and `auth` intents), or to use a new visitor identity.

Default: `true`

maintainIdentity

Whether to use a standard Wix template for Wix-managed pages the visitor is redirected to. Set to `false` only if your client site connects with a Wix site that has custom pages.

Default: `true`

useGenericWixPages

RedirectSessionStoresProductParams

productSlug

Slot

The end time of this slot in
[RFC 3339](https://www.rfc-editor.org/rfc/rfc3339) format.

If `timezone` is specified,
dates are based on the local date/time. This means that the timezone offset
in the `end_date` is ignored.

endDate

ID for the slot's corresponding event, when the event is either a single event
or a specific event generated from a recurring event.

eventId

location

The resource required for this slot. Currently, the only supported resource
is the relevant staff member for the slot.

resource

SlotResource

scheduleId

serviceId

ID for the slot's corresponding session, when the session is either a single session
or a specific session generated from a recurring session.

Deprecated. Please use `eventId` instead.

onRedirectSessionCreated( )