Go Headless

Build Apps

Client

API Preview

Develop Websites

REST

Velo

GraphQL (Alpha)

options

CreateRedirectSessionOptions

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


The `createRedirectSession()` function 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 a bookings, eCommerce, events, or paid plans transaction.

To initiate a redirect session:

1. Call `createRedirectSession()` 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 user 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 { createClient, OAuthStrategy } from '@wix/sdk';
import { redirects } from '@wix/redirects';

const wixClient = createClient({
  modules: { redirects } ,
  auth: OAuthStrategy({ clientId: 'MY-CLIENT-ID' })
});

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

createRedirectSession() with visitor/member access

import { createClient, ApiKeyStrategy } from '@wix/sdk';
import { redirects } from '@wix/redirects';

const wixClient = createClient({
  modules: { redirects },
  auth: ApiKeyStrategy({
    siteId: 'MY-SITE-ID',
    apiKey: 'MY-API-KEY'
  })
});

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

createRedirectSession() with API Key access

import { createClient } from '@wix/sdk';
import { dashboard } from '@wix/dashboard';
import { redirects } from '@wix/redirects';

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

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

createRedirectSession() with Dashboard app access

createRedirectSession

CreateRedirectSessionResponse

---
title: Introduction
---

# About the Redirects API

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.


To use the Redirects API, install the `@wix/redirects` package using npm or Yarn:
  ```console
npm install @wix/redirects
```

or

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

Then import `{ redirects }` from `@wix/redirects`:

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

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 pass 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 pass 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 pass 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 passes the following query parameters:
+ `planIds`:  IDs of the pricing plans on the custom page.
+ `checkoutData`: Pass this string back in `options.paidPlansCheckout.checkoutData` when redirecting back to Wix for checkout.

 Default: If you don't pass 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 pass a URL here. Instead, pass 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 pass 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

Pass 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 the visitor back to on the Wix Headless client site.

**Note**: For an authentication redirect, don't pass a post-flow URL here. Instead, pass 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

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

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

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 RedirectSession

urlDetails

URLDetails

RedirectSessionAuthParams

__Required.__ The authorization request to send to the authorization server.

authRequest

prompt

RedirectSessionBookingsBookParams

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

resourceId

RedirectSessionBookingsCheckoutParams

__Required.__ The calendar slot to check out.

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

__Required.__ ID of the checkout to process. Use [`createCheckout()`](https://dev.wix.com/api/sdk/ecom/checkout/createcheckout) or [`createCheckoutFromCurrentCart()`](https://dev.wix.com/api/sdk/ecom/currentcart/createcheckoutfromcurrentcart) to create a checkout and obtain an ID.

checkoutId

RedirectSessionEventsCheckoutParams

__Required.__ URL-friendly event slug, generated from the event title of the event. For example, `my-event-4`. Use [`listEvents()`](https://dev.wix.com/api/sdk/events/wixevents/listevents) to obtain an event slug.

eventSlug

__Required.__ ID of the temporary event reservation. Use [`createReservation()`](https://dev.wix.com/api/sdk/events/checkout/createreservation) to reserve a ticket temporarily and obtain a reservation ID.

reservationId

RedirectSessionLoginParams

RedirectSessionLogoutParams

__Required.__ ID of the OAuth app authorizing the client.

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

__Required.__ ID of the paid plan selected. Use [`queryPublicPlans()`](https://dev.wix.com/api/sdk/pricing-plans/plans/querypublicplans) to obtain a paid plan ID.

planId

A map of additional query parameters to pass to the created Wix URL.
Global query parameters to be passed to Wix, for example campaign parameters (UTM params).

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

*Required.** Slug of the product to navigate to.

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 `endDate` is ignored.

endDate

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.

sessionId

The start 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 `startDate` is ignored.

startDate

The timezone for which slot availability is to be calculated.

Learn more about [handling Daylight Savings Time (DST) for local time zones](https://dev.wix.com/api/sdk/bookings/availabilitycalendar/queryavailability#bookings_availabilitycalendar_queryavailability_handling-daylight-savings-time-dst-for-local-time-zones)
when calculating availability.

Whether the slot is bookable. Bookability is determined by checking a
session's open slots and booking policies. Locks are not taken into
account.

bookable

bookingPolicyViolations

isFromV2

Indicates whether the slot is locked because a waitlist exists.
When a slot frees up, the slot is offered to the next customer on the waitlist. Read-only.

locked

openSpots

number

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

createRedirectSession( )

Permission Scopes