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 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 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.
Did this help?

Redirect Session Object


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

Properties
idstringformat GUID

ID of the redirect session created.


fullUrlstringRead-onlymaxLength 2048

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.


urlDetailsUrlDetails

Details about the URL of the redirect session.


sessionTokenstringRead-onlymaxLength 2048

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


shortUrlstringRead-onlymaxLength 2048

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.

Did this help?

POST

Create Redirect Session


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.
  2. 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.
  3. Make sure the pages at the callback URLs you provided take care of the next stages in your visitor flow.
Permissions
Manage Bookings Services and Settings
Manage Portfolio
Manage Restaurants - all permissions
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/_api/redirects-api/v1/redirect-session

Body Params
callbacksCallbacks

Details of pages to redirect the visitor back to on the Wix Headless client site. When redirecting to any callback URL, Wix specifies the boolean wixMemberLoggedIn parameter. If true, a member logged in during the preceding Wix-managed process.

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


preferencesPreferences

Optional preferences for customizing redirection to Wix pages.


ONE OF:

bookingsCheckoutBookingsCheckout

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


ecomCheckoutEcomCheckout

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


eventsCheckoutEventsCheckout

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


paidPlansCheckoutPaidPlansCheckout

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


loginLogin

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


logoutLogout

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.


authAuth

Information required for generating a custom URL for Wix authentication.


storesProductStoresProduct

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


bookingsBookBookingsBook

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

Response Object
redirectSessionRedirectSession

Details for redirecting the visitor to a Wix page.

Create a redirect session for an eCommerce checkout
Request
cURL
curl -X POST 'https://www.wixapis.com/redirect-session/v1/redirect-session' \ -H 'authorization: <AUTH>' \ -d '{ "ecomCheckout": { "checkoutId": "7d2b240c-5c60-4580-8bc3-948bca6b4e4e" }, "callbacks": { "postFlowUrl": "https://www.my-store.com" } }'
Response
JSON
{ "redirectSession": { "id": "<REDIRECT_SESSION_ID>", "fullUrl": "https://www.checkout.my-site.com/checkout?appSectionParams=%7B%22checkoutId%22%3A%227d2b240c-5c60-4580-8bc3-948bca6b4e4e%22%7D&headlessExternalUrls=~%28home~%27https*3a*2f*2fwww.my-store.com*%29" } }
Event TriggersThis method triggers the following events:
Did this help?

Redirect Session Created


Triggerd when a redirect session is created

Permissions
Manage Bookings Services and Settings
Manage Portfolio
Manage Restaurants - all permissions
Learn more about app permissions.
Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring

Unique event ID. Allows clients to ignore duplicate webhooks.


entityFqdnstring

Fully qualified domain name of the entity associated with the event. Expected wix.headless.v1.redirect_session.


slugstring

Event name. Expected created.


entityIdstring

ID of the entity associated with the event.


eventTimestringformat date-time

Event timestamp.


triggeredByAnonymizeRequestboolean

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


originatedFromstring

If present, indicates the action that triggered the event.


createdEventCreatedEvent

Event information.

Event Body

The data payload will include the following as an encoded JWT:

JSON
{ "data": { "eventType": "wix.headless.v1.redirect_session_created", "instanceId": "<app-instance-id>", "data": "<stringified-JSON>", // The identity field is sent as a stringified JSON "identity": { "identityType": "<identityType>", // ANONYMOUS_VISITOR, MEMBER, WIX_USER, APP "anonymousVisitorId": "<anonymousVisitorId>", // in case of ANONYMOUS_VISITOR "memberId": "<memberId>", // in case of MEMBER "wixUserId": "<wixUserId>", // in case of WIX_USER "appId": "<appId>" // in case of APP } } }
Did this help?