Migration Rest Portal

Build Apps

Go Headless

Client

API Preview

Develop Websites

REST

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

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.

createRedirectSession

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

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


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

CreateRedirectSessionOptions

Information required for generating a custom URL for Wix authentication.

auth

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

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

CreateRedirectSessionResponse

Details for redirecting the visitor to a Wix page.

redirectSession

RedirectSession

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

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

RedirectSessionAuthParams

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

authRequest

prompt

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

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

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.

slot

Total number of spots for this slot.
For example, if a session has a total of 10 spots and 3 spots are booked,
`spotsTotal` is 10 and `openSpots` is 7.

totalSpots

An object describing the slot's waitlist and its occupancy.

waitingList

WaitingList

Total number of spots and open spots for this waitlist.
For example, a Yoga class with 10 waitlist spots and 3 registered
on the waitlist has 10 `total_spots` and 7 `open_spots`.

Setup