About Orders Settings

With the Orders Settings API, you can retrieve and update settings that apply to a site’s eCommerce orders. These settings include adding or removing customer email notifications about order status, defining when to update the store inventory, and creating invoices.

The default orders 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

  • Order: The final stage of the eCommerce purchase flow: cart, checkout, and order. An order represents a customer's request to purchase one or more products or services from a seller. It typically includes details such as the type and quantity of items, shipping address, payment information, and any other relevant transaction details.
  • Invoice: Commercial document issued by a seller to a buyer, providing a detailed account of products or services rendered, along with the corresponding costs.
  • Inventory: List of goods, products, or materials that a business holds for the purpose of resale or use in its operations.
Did this help?

Orders Settings: Sample Use Cases and 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 orders settings across all sites

If you have several Wix eCommerce sites that use your app you might need to apply the same orders settings to those sites. For example, if now the store inventory is updated only after an order is paid, this change also needs to be reflected on other sites.

To update the orders settings across all sites:

  1. Call Get Orders Settings on the site where you updated the settings.
  2. Extract the inventoryUpdateTrigger field value.
  3. Call Update Orders Settings for your other sites and pass the new settings to each.
Did this help?

Orders Settings Object


Properties
inventoryUpdateTriggerstring

Defines when to update the store inventory:

  • ON_ORDER_PAID: Stock quantities will update only after the payment is approved.
  • ON_ORDER_PLACED: Stock quantities will update while the payment is being processed. If the payment did not go through, items will restock.

Default: ON_ORDER_PLACED


createInvoiceboolean

Whether to automatically create invoices for every new order paid online.
Default: false
Note: The issued invoice for an order is not a tax invoice and doesn't reflect refunds. You are responsible for ensuring that invoices you issue conform to any relevant legal requirements.


createdDatestringRead-onlyformat date-time

Date and time the orders settings were created.


updatedDatestringRead-onlyformat date-time

Date and time the orders settings were updated.

OrdersSettings
JSON
{ "ordersSettings": { "inventoryUpdateTrigger": "ON_ORDER_PLACED", "createInvoice": false } }
Did this help?

GET

Get Orders 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 order 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/orders-settings

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

Orders settings.

Get orders settings
Request
cURL
curl -X GET \ 'https://www.wixapis.com/ecom/v1/orders-settings' \ -H 'Content-Type: application/json' \ -H 'Authorization: <AUTH>'
Response
JSON
{ "ordersSettings": { "inventoryUpdateTrigger": "ON_ORDER_PLACED", "createInvoice": false, "createdDate": "2024-07-04T15:10:46.070Z", "updatedDate": "2024-07-04T15:10:46.070Z" } }
Did this help?

PATCH

Update Orders 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 orders 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/orders-settings

Body Params
ordersSettingsOrdersSettingsRequired

Orders settings to update.

Response Object
ordersSettingsOrdersSettings

The updated orders settings.

Update orders settings
Request
cURL
curl -X PATCH \ 'https://www.wixapis.com/ecom/v1/orders-settings' \ -H 'Content-Type: application/json' \ -H 'Authorization: <AUTH>' \ -d '{ "ordersSettings": { "createInvoice": true } }'
Response
JSON
{ "ordersSettings": { "inventoryUpdateTrigger": "ON_ORDER_PLACED", "createInvoice": true, "createdDate": "2024-07-04T15:10:46.070Z", "updatedDate": "2024-07-04T15:10:46.070Z" } }
Event TriggersThis method triggers the following events:
Did this help?

Orders 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 orders 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.orders_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.orders_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 } } }

OrdersSettingsUpdated
JSON
{ "id": "9be4e9be-8dfe-11ee-b9d1-0242ac120002", "entityFqdn": "wix.ecom.v1.orders_settings", "slug": "updated", "entityId": "df9b0d5a-8dfe-11ee-b9d1-0242ac120002", "updatedEvent": { "currentEntity": { "ordersSettings": { "inventoryUpdateTrigger": "ON_ORDER_PLACED", "createInvoice": true } } }, "eventTime": "2023-11-28T17:01:59.036159Z", "triggeredByAnonymizeRequest": false }
Did this help?