Introduction

HTTP functions allow you to expose the functionality of your site as a service. That means other people can write code to consume the functionality you expose by calling the functions of the API that you define.

Write and export HTTP functions to define custom site APIs. When you and others call the custom site APIs you defined, the corresponding HTTP function runs and the API responds with the HTTP function's return value.

Use the objects and functions in wix-http-functions to:

  • Define the HTTP method used to call the custom site API.
  • Access information passed in the custom site API request.
  • Construct a valid response for the custom site API.
Important:

This API is only intended for use in server-to-server communications. For example, don't use custom site APIs to set a cookie on a site visitor's browser as you may no longer be in compliance with applicable data privacy regulations.

Learn more about custom site APIs and HTTP functions

Did this help?

wixHttpFunctionRequest


wixHttpFunctionRequestWixHttpFunctionRequestRead-only

An object representing an incoming request received by a call to an HTTP function.

The WixHttpFunctionRequest object breaks the URL of the incoming call to an HTTP function into different parameters for easy access.

The URL of the incoming call to an HTTP function is broken into:

For premium sites, the URL of the incoming call has the following format: https://www.domain.com/_functions/myFunction/sub?q=value

  • baseUrl:     https://www.domain.com/_functions
  • path:          sub
  • query:        q=value

For free sites, the URL of the incoming call has the following format: https://user_name.wixsite.com/mysite/_functions/myFunction/sub?q=value

  • baseUrl:     https://user_name.wixsite.com/mysite/_functions
  • path:          sub
  • query:        q=value
0
Did this help?

badRequest( )


Returns a response with status code 400 (Bad Request) and the information from the options parameter.

The badRequest() function creates a response with the status code 400 (Bad Request).

Optionally, the badRequest() function can take a WixHttpFunctionResponseOptions object which is used to specify the response's body and headers.

Note: If the object contains a status it will be ignored.

Use the badRequest() function to create a response to return from an HTTP function. A 400 (Bad Request) response is usually used to indicate the request was unsuccessful because of a client error, such as a request using the incorrect syntax.

Method Declaration
Copy
function badRequest(
  options: WixHttpFunctionResponseOptions,
): WixHttpFunctionResponse;
Method Parameters
optionsWixHttpFunctionResponseOptions

The response options.

Returns
Return Type:WixHttpFunctionResponse
JavaScript
// In http-functions.js import { badRequest } from "wix-http-functions"; export function use_myFunction(request) { return badRequest(); }
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

created( )


Returns a response with status code 201 (Created) and the information from the options parameter.

The created() function creates a response with the status code 201 (Created).

Optionally, the created() function can take a WixHttpFunctionResponseOptions object which is used to specify the response's body and headers.

Note: If the object contains a status it will be ignored.

Use the created() function to create a response to return from an HTTP function. A 201 (Created) response is usually used to indicate that the request was successful and a new resource has been created.

Method Declaration
Copy
function created(
  options: WixHttpFunctionResponseOptions,
): WixHttpFunctionResponse;
Method Parameters
optionsWixHttpFunctionResponseOptions

The response options.

Returns
Return Type:WixHttpFunctionResponse
JavaScript
// In http-functions.js import { created } from "wix-http-functions"; export function use_myFunction(request) { return created(); }
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

delete( )


A function that responds to requests made with the HTTP DELETE method.

The HTTP DELETE method is usually called by consumers to delete an existing resource. If defined in this way and the resource is deleted, the function should respond with a 200 (OK) status code.

Respond to the request by returning a WixHttpFunctionResponse object you create using one of the response(), ok(), created(), notFound(), serverError(), badRequest(), or forbidden() functions.

The delete() function is not a function that you call from your code. You define the function in a file named http-functions.js in your site's Backend section. The function is called when your users make HTTP requests using the associated URLs as described below.

All DELETE requests with the following URL will be routed to this function:

Premium sites:

Copy
https://www.{user_domain}/_functions/

Free sites:

Copy
https://{user_name}.wixsite.com/{site_name}/_functions/

Notes:

  • The HTTP DELETE request can't contain a body and can't contain the header "Content-Type": "application/json". If the request breaks this syntax and includes either of these, the function returns a 400 (Bad Request) status code.
  • You must publish your site at least once before using both the testing and production endpoints. When you make changes to production endpoints you must publish your site for them to take effect. Testing endpoints will use the latest code in the editor.
Method Declaration
Copy
function delete(request: WixHttpFunctionRequest): WixHttpFunctionResponse
Method Parameters
requestWixHttpFunctionRequestRequired

The request object.

Returns
Return Type:WixHttpFunctionResponse

This example creates a DELETE HTTP function named myFunction.

JavaScript
// In http-functions.js import { ok } from "wix-http-functions"; // URL looks like: // https://www.mysite.com/_functions/myFunction/someId // or: // https://user.wixsite.com/mysite/_functions/myFunction/someId export function delete_myFunction(request) { const toRemove = request.path[0]; // remove the resource return ok(); }
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

forbidden( )


Returns a response with status code 403 (Forbidden) and the information from the options parameter.

The forbidden() function creates a response with the status code 403 (Forbidden).

Optionally, the forbidden() function can take a WixHttpFunctionResponseOptions object which is used to specify the response's body and headers.

Note: If the object contains a status it will be ignored.

Use the forbidden() function to create a response to return from an HTTP function. A 403 (Forbidden) response is used to indicate the request was valid but the server is refusing to process it, usually because the client does not have the necessary permissions for the requested resource.

Method Declaration
Copy
function forbidden(
  options: WixHttpFunctionResponseOptions,
): WixHttpFunctionResponse;
Method Parameters
optionsWixHttpFunctionResponseOptions

The response options.

Returns
Return Type:WixHttpFunctionResponse
JavaScript
// In http-functions.js import { forbidden } from "wix-http-functions"; export function use_myFunction(request) { return forbidden(); }
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

get( )


A function that responds to requests made with the HTTP GET method.

The HTTP GET method is usually called by consumers to retrieve a resource and should have no other effect. If used in this way and the resource is found, the function should respond with a 200 (OK) status code and the requested resource.

Respond to the request by returning a WixHttpFunctionResponse object you create using one of the response(), ok(), created(), notFound(), serverError(), badRequest(), or forbidden() functions.

The get() function is not a function that you call from your code. You define the function in a file named http-functions.js in your site's Backend section. The function is called when your users make HTTP requests using the associated URLs as described below.

All GET requests with the following URL will be routed to this function:

Premium sites:

Copy
https://www.{user_domain}/_functions/

Free sites:

Copy
https://{user_name}.wixsite.com/{site_name}/_functions/

Note: You must publish your site at least once before using both the testing and production endpoints. When you make changes to production endpoints you must publish your site for them to take effect. Testing endpoints will use the latest code in the editor.

Method Declaration
Copy
function get(request: WixHttpFunctionRequest): WixHttpFunctionResponse;
Method Parameters
requestWixHttpFunctionRequestRequired

The request object.

Returns
Return Type:WixHttpFunctionResponse

This example creates a GET HTTP function named myFunction.

JavaScript
// In http-functions.js import { ok, notFound } from "wix-http-functions"; // URL looks like: // https://www.mysite.com/_functions/myFunction/findMe // or: // https://user.wixsite.com/mysite/_functions/myFunction/findMe export function get_myFunction(request) { if (request.path[0] === "findMe") { const body = "Found it!"; return ok({ body: body }); } const body = "Can't find it!"; return notFound({ body: body }); }
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

notFound( )


Returns a response with status code 404 (Not Found) and the information from the options parameter.

The notFound() function creates a response with the status code 404 (Not Found).

Optionally, the notFound() function can take a WixHttpFunctionResponseOptions object which is used to specify the response's body and headers.

Note: If the object contains a status it will be ignored.

Use the notFound() function to create a response to return from an HTTP function. A 404 (Not Found) response is usually used to indicate that the requested resource was not found at the current time.

Method Declaration
Copy
function notFound(
  options: WixHttpFunctionResponseOptions,
): WixHttpFunctionResponse;
Method Parameters
optionsWixHttpFunctionResponseOptions

The response options.

Returns
Return Type:WixHttpFunctionResponse
JavaScript
// In http-functions.js import { notFound } from "wix-http-functions"; export function use_myFunction(request) { return notFound(); }
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

ok( )


Returns a response with status code 200 (OK) and the information from the options parameter.

The ok() function creates a response with the status code 200 (OK).

Optionally, the ok() function can take a WixHttpFunctionResponseOptions object which is used to specify the response's body and headers.

Note: If the object contains a status it will be ignored.

Use the response() function to create a response to return from an HTTP function. A 200 (OK) response is usually used to indicate that a request was successful.

Method Declaration
Copy
function ok(options: WixHttpFunctionResponseOptions): WixHttpFunctionResponse;
Method Parameters
optionsWixHttpFunctionResponseOptions

The response options.

Returns
Return Type:WixHttpFunctionResponse
JavaScript
// In http-functions.js import { ok } from "wix-http-functions"; export function use_myFunction(request) { return ok(); }
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

options( )


A function that responds to requests made with the HTTP OPTIONS method.

The HTTP OPTIONS method is usually called by consumers attempting to identify the allowed request methods or as part of a CORS preflight request. If defined in this way, the function should respond with a 204 (No Content) status code and header data that indicates which methods are allowed and from which origins.

The value for the "Access-Control-Allow-Origin" response header determines whether the response can be shared with a given requesting origin. Its value can be one of "*", a single specific origin URL, or null as described here. Due to security concerns, it is recommended that you use a single specific origin URL whenever possible. If you need to allow more than one origin URL, you should validate that the requesting origin is allowed access and then echo it back in the response header.

Respond to the request by returning a WixHttpFunctionResponse object you create using the response() function.

The options() function is not a function that you call from your code. You define the function in a file named http-functions.js in your site's Backend section. The function is called when your users make HTTP requests using the associated URLs as described below.

All OPTIONS requests with the following URL will be routed to this function:

Premium sites:

Copy
https://www.{user_domain}/_functions/

Free sites:

Copy
https://{user_name}.wixsite.com/{site_name}/_functions/

Note: You must publish your site at least once before using both the testing and production endpoints. When you make changes to production endpoints you must publish your site for them to take effect. Testing endpoints will use the latest code in the editor.

Method Declaration
Copy
function options(request: WixHttpFunctionRequest): WixHttpFunctionResponse;
Method Parameters
requestWixHttpFunctionRequestRequired

The request object.

Returns
Return Type:WixHttpFunctionResponse

This example creates an OPTIONS HTTP function named myFunction.

JavaScript
// In http-functions.js import { response } from "wix-http-functions"; // URL looks like: // https://www.mysite.com/_functions/myFunction/ // or: // https://user.wixsite.com/mysite/_functions/myFunction/ export function options_myFunction(request) { let headers = { "Access-Control-Allow-Origin": "https://www.example.com", "Access-Control-Allow-Methods": "POST, GET, OPTIONS", "Access-Control-Max-Age": "86400", }; return response({ status: 204, headers: headers }); }
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

post( )


A function that responds to requests made with the HTTP POST method.

The HTTP POST method is usually called by consumers to create a new resource. If defined in this way and the resource is created, the function should respond with a 201 (Created) status code and usually a reference to the new resource.

Respond to the request by returning a WixHttpFunctionResponse object you create using one of the response(), ok(), created(), notFound(), serverError(), badRequest(), or forbidden() functions.

The post() function is not a function that you call from your code. You define the function in a file named http-functions.js in your site's Backend section. The function is called when your users make HTTP requests using the associated URLs as described below.

All POST requests with the following URL will be routed to this function:

Premium sites:

Copy
https://www.{user_domain}/_functions/

Free sites:

Copy
https://{user_name}.wixsite.com/{site_name}/_functions/

Note: You must publish your site at least once before using both the testing and production endpoints. When you make changes to production endpoints you must publish your site for them to take effect. Testing endpoints will use the latest code in the editor.

Method Declaration
Copy
function post(request: WixHttpFunctionRequest): WixHttpFunctionResponse;
Method Parameters
requestWixHttpFunctionRequestRequired

The request object.

Returns
Return Type:WixHttpFunctionResponse

This example creates a POST HTTP function named myFunction.

JavaScript
// In http-functions.js import { created } from "wix-http-functions"; // URL looks like: // https://www.mysite.com/_functions/myFunction/ // or: // https://user.wixsite.com/mysite/_functions/myFunction/ export function post_myFunction(request) { return request.body.text().then((body) => { // insert the info from the body somewhere return created(); }); }
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

put( )


A function that responds to requests made with the HTTP PUT method.

The HTTP PUT method is usually called by consumers to update an existing resource.

If defined in this way and the resource is updated, the function should respond with a 200 (OK) status code. If defined in this way and the resource is created because it did not exist, you should respond with a 201 (Created) status code.

Respond to the request by returning a WixHttpFunctionResponse object you create using one of the response(), ok(), created(), notFound(), serverError(), badRequest(), or forbidden() functions.

The put() function is not a function that you call from your code. You define the function in a file named http-functions.js in your site's Backend section. The function is called when your users make HTTP requests using the associated URLs as described below.

All PUT requests with the following URL will be routed to this function:

Premium sites:

Copy
https://www.{user_domain}/_functions/

Free sites:

Copy
https://{user_name}.wixsite.com/{site_name}/_functions/

Note: You must publish your site at least once before using both the testing and production endpoints. When you make changes to production endpoints you must publish your site for them to take effect. Testing endpoints will use the latest code in the editor.

Method Declaration
Copy
function put(request: WixHttpFunctionRequest): WixHttpFunctionResponse;
Method Parameters
requestWixHttpFunctionRequestRequired

The request object.

Returns
Return Type:WixHttpFunctionResponse

This example creates a PUT HTTP function named myFunction.

JavaScript
// In http-functions.js import { ok } from "wix-http-functions"; // URL looks like: // https://www.mysite.com/_functions/myFunction/ // or: // https://user.wixsite.com/mysite/_functions/myFunction/ export function put_myFunction(request) { return request.body.text().then((body) => { // update the info from the body somewhere return ok(); }); }
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

response( )


Returns a response populated with the information from the options parameter. The response() function creates a custom response built with the information passed to the options parameter in a WixHttpFunctionCustomResponseOptions object.

Use the response() function to create a response to return from an HTTP function.

Method Declaration
Copy
function response(
  options: WixHttpFunctionCustomResponseOptions,
): WixHttpFunctionResponse;
Method Parameters
optionsWixHttpFunctionCustomResponseOptionsRequired

The response options.

Returns
Return Type:WixHttpFunctionResponse
JavaScript
// In http-functions.js import { response } from "wix-http-functions"; export function use_myFunction(request) { return response(); }
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

serverError( )


Returns a response with status code 500 (Internal Server Error) and the information from the options parameter.

The serverError() function creates a response with the status code 500 (Internal Server Error).

Optionally, the serverError() function can take a WixHttpFunctionResponseOptions object which is used to specify the response's body and headers.

Note: If the object contains a status it will be ignored.

Use the serverError() function to create a response to return from an HTTP function. A 500 (Internal Server Error) response is usually used to indicate the request was unsuccessful because of an unexpected error on the server.

Method Declaration
Copy
function serverError(
  options: WixHttpFunctionResponseOptions,
): WixHttpFunctionResponse;
Method Parameters
optionsWixHttpFunctionResponseOptions

The response options.

Returns
Return Type:WixHttpFunctionResponse
JavaScript
// In http-functions.js import { serverError } from "wix-http-functions"; export function use_myFunction(request) { return serverError(options); }
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

use( )


A function that responds to requests made with any HTTP method.

Requests made with any of the GET, POST, PUT, DELETE, or OPTIONS HTTP methods will be routed to this function unless another function is defined specifically for the request's HTTP method.

For example, if you create functions named get_myFunction and use_myFunction, GET calls to myFunction will be handled by get_myFunction, while POST, PUT, DELETE, and OPTIONS calls will be handled by use_myFunction.

The use() function is not a function that you call from your code. You define the function in a file named http-functions.js in your site's Backend section. The function is called when your users make HTTP requests using the associated URLs as described below.

All GET, POST, PUT, DELETE, and OPTIONS HTTP requests with the following URL will be routed to this function unless another function is defined specifically for the request's HTTP method:

Premium sites:

Copy
https://www.{user_domain}/_functions/

Free sites:

Copy
https://{user_name}.wixsite.com/{site_name}/_functions/

Respond to the request by returning a WixHttpFunctionResponse object you create using one of the response(), ok(), created(), notFound(), serverError(), badRequest(), or forbidden() functions.

Note: You must publish your site at least once before using both the testing and production endpoints. When you make changes to production endpoints you must publish your site for them to take effect. Testing endpoints will use the latest code in the editor.

Method Declaration
Copy
function use(request: WixHttpFunctionRequest): WixHttpFunctionResponse;
Method Parameters
requestWixHttpFunctionRequestRequired

The request object.

Returns
Return Type:WixHttpFunctionResponse
Create a catchall HTTP function

This example creates a catchall HTTP function named myFunction.

JavaScript
// In http-functions.js import { ok } from "wix-http-functions"; export function use_myFunction(request) { const method = request.method; // ... return ok(); }
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?