About Checkout Settings

With the Checkout Settings API, you can retrieve and update the checkout settings for sites that have installed your app. These settings include adding or removing eCommerce policies, and setting checkbox behavior for a checkout.

Policies will appear as clickable links in the footer of your checkout, while checkboxes can be found when selecting the payment method. Clicking on the policy name opens a pop-up window with the policy text. The default checkout settings are provided when you first create a Wix eCommerce site.

Before you begin

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

Use Cases

Terminology

  • Checkout: The second stage of the eCommerce purchase flow: cart; checkout; order. A checkout holds information about items to be purchased, price and tax summaries, shipping and billing info, any applied discounts, and more.
  • Policy: Set of guidelines, rules, or principles established by an organization or authority to govern behavior, decision-making, and specific actions.
Did this help?

Checkout Settings: Sample Use Cases & Flows

This article presents possible use cases and corresponding sample flows that your app can support. It provides a useful starting point as you plan your app's implementation.

Update checkout settings across all sites

If you have several Wix eCommerce sites that use your app you might need to sync checkout settings across those sites. For example, if the return policies change on 1 site, and now the policies guarantee a 100-day item return, this change also needs to be reflected on other sites.

To update the checkout policy settings across all sites:

  1. Call Get Checkout Settings on the site where you updated the policy.
  2. Extract the checkoutPolicies.returnPolicy.content field value.
  3. Call Update Checkout Settings for your other sites and pass the new policy to each.
Did this help?

Checkout Settings Object


Properties
checkoutPoliciesCheckoutPolicies

Checkout policies.


checkoutFieldsCheckoutFields

Settings that apply to checkout fields and the checkout process.


createdDatestringRead-onlyformat date-time

Date and time the checkout settings were created.


updatedDatestringRead-onlyformat date-time

Date and time the checkout settings were updated.

CheckoutSettings
JSON
{ "checkoutSettings": { "checkoutPolicies": { "termsAndConditions": { "visible": true, "content": "All product listings, prices, and specifications are subject to change without notice. ACCS reserves the right to modify or discontinue products at any time." }, "privacyPolicy": { "visible": true, "content": "Your privacy is important to us. Please review our Privacy Policy to understand how we collect, use, and disclose information." }, "returnPolicy": { "visible": true, "content": "Please refer to our Return Policy page for information on returns and refunds. ACCS reserves the right to refuse returns that do not meet our policy criteria." }, "digitalItemPolicy": { "visible": false, "content": "" }, "contactUs": { "visible": true, "content": "email: accs@mail.com" }, "customPolicy": { "visible": true, "content": "Placing an order on our website constitutes an offer to purchase the products. We reserve the right to refuse or cancel any order for any reason. Payment must be received before order processing.", "title": "Orders and Payments" } }, "checkoutFields": { "subscriptionCheckbox": { "visible": true, "checkedByDefault": true }, "policyAgreementCheckbox": { "visible": true, "checkedByDefault": false }, "giftCardRedeemEnabled": true, "mitEnabled": false } } }
Did this help?

GET

Get Checkout Settings


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Retrieves the site's checkout settings.

Permissions
Manage eCommerce - all permissions
Read eCommerce - all read permissions
Manage Stores - all permissions
Read Stores - all read permissions
Manage Orders
Read Orders
Manage Restaurants - all permissions
Learn more about app permissions.
Endpoint
GET
https://www.wixapis.com/ecom/v1/checkout-settings

Request
This endpoint does not take any parameters.
Response Object
checkoutSettingsCheckoutSettings

Checkout settings.

Get checkout settings
Request
cURL
curl -X GET \ 'https://www.wixapis.com/ecom/v1/checkout-settings' \ -H 'Authorization: <AUTH>'
Response
JSON
{ "checkoutSettings": { "checkoutPolicies": { "termsAndConditions": { "visible": true, "content": "All product listings, prices, and specifications are subject to change without notice. ACCS reserves the right to modify or discontinue products at any time." }, "privacyPolicy": { "visible": true, "content": "Your privacy is important to us. Please review our Privacy Policy to understand how we collect, use, and disclose information." }, "returnPolicy": { "visible": true, "content": "Please refer to our Return Policy page for information on returns and refunds. ACCS reserves the right to refuse returns that do not meet our policy criteria." }, "digitalItemPolicy": { "visible": false, "content": "" }, "contactUs": { "visible": true, "content": "email: accs@mail.com" }, "customPolicy": { "visible": true, "content": "Placing an order on our website constitutes an offer to purchase the products. We reserve the right to refuse or cancel any order for any reason. Payment must be received before order processing.", "title": "Orders and Payments" } }, "checkoutFields": { "subscriptionCheckbox": { "visible": true, "checkedByDefault": true }, "policyAgreementCheckbox": { "visible": true, "checkedByDefault": false }, "giftCardRedeemEnabled": true, "mitEnabled": false } } }
Did this help?

PATCH

Update Checkout Settings


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Updates the site's checkout settings.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage eCommerce - all permissions
Manage Stores - all permissions
Manage Orders
Manage Restaurants - all permissions
Learn more about app permissions.
Endpoint
PATCH
https://www.wixapis.com/ecom/v1/checkout-settings

Body Params
checkoutSettingsCheckoutSettingsRequired

Checkout settings to update.

Response Object
checkoutSettingsCheckoutSettings

The updated checkout settings.

Update checkout settings
Request
cURL
curl -X PATCH \ 'https://www.wixapis.com/ecom/v1/checkout-settings' \ -H 'Content-Type: application/json' \ -H 'Authorization: <AUTH>' \ -d '{ "checkoutSettings": { "checkoutFields": { "giftCardRedeemEnabled": true, "mitEnabled": false } } }'
Response
JSON
{ "checkoutSettings": { "checkoutPolicies": { "termsAndConditions": { "visible": true, "content": "All product listings, prices, and specifications are subject to change without notice. ACCS reserves the right to modify or discontinue products at any time." }, "privacyPolicy": { "visible": true, "content": "Your privacy is important to us. Please review our Privacy Policy to understand how we collect, use, and disclose information." }, "returnPolicy": { "visible": true, "content": "Please refer to our Return Policy page for information on returns and refunds. ACCS reserves the right to refuse returns that do not meet our policy criteria." }, "digitalItemPolicy": { "visible": false, "content": "" }, "contactUs": { "visible": true, "content": "Email: accs@mail.com" }, "customPolicy": { "visible": true, "content": "Placing an order on our website constitutes an offer to purchase the products. We reserve the right to refuse or cancel any order for any reason. Payment must be received before order processing.", "title": "Orders and Payments" } }, "checkoutFields": { "subscriptionCheckbox": { "visible": true, "checkedByDefault": true }, "policyAgreementCheckbox": { "visible": true, "checkedByDefault": false }, "giftCardRedeemEnabled": true, "mitEnabled": false } } }
Event TriggersThis method triggers the following events:
Did this help?

Checkout Settings Updated


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Triggered when checkout settings are updated.

Permissions
Manage eCommerce - all permissions
Read eCommerce - all read permissions
Manage Stores - all permissions
Read Stores - all read permissions
Manage Orders
Read Orders
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.ecom.v1.checkout_settings.


slugstring

Event name. Expected updated.


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.


updatedEventUpdatedEvent

Event information.

Event Body

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

JSON
{ "data": { "eventType": "wix.ecom.v1.checkout_settings_updated", "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 } } }

CheckoutSettingsUpdated
JSON
{ "id": "7b05fbd6-c3e2-42c2-ace6-06272bd3fdfa", "entityFqdn": "wix.ecom.v1.checkout_settings", "slug": "updated", "entityId": "74a91ddc-8540-11ee-b9d1-0242ac120002", "updatedEvent": { "currentEntity": { "checkoutPolicies": { "termsAndConditions": { "visible": true, "content": "All product listings, prices, and specifications are subject to change without notice. ACCS reserves the right to modify or discontinue products at any time." }, "privacyPolicy": { "visible": true, "content": "Your privacy is important to us. Please review our Privacy Policy to understand how we collect, use, and disclose information." }, "returnPolicy": { "visible": true, "content": "Please refer to our Return Policy page for information on returns and refunds. ACCS reserves the right to refuse returns that do not meet our policy criteria." }, "digitalItemPolicy": { "visible": false, "content": "" }, "contactUs": { "visible": true, "content": "email: accs@mail.com" }, "customPolicy": { "visible": true, "content": "Placing an order on our website constitutes an offer to purchase the products. We reserve the right to refuse or cancel any order for any reason. Payment must be received before order processing.", "title": "Orders and Payments" } }, "checkoutFields": { "subscriptionCheckbox": { "visible": true, "checkedByDefault": true }, "policyAgreementCheckbox": { "visible": true, "checkedByDefault": false }, "giftCardRedeemEnabled": false, "mitEnabled": true } } }, "eventTime": "2023-11-16T13:28:59.036159Z", "triggeredByAnonymizeRequest": false, "entityEventSequence": "133" }
Did this help?