Go Headless

Build Apps

Client

API Preview

Develop Websites

REST

Velo

GraphQL (Alpha)

# About Custom Discount Triggers Service Plugin

The eCommerce Custom Discount Triggers service plugin (formerly SPI) allows you to provide custom triggers that specify when a discount can apply to a cart and checkout.

Custom triggers play a part in the definition of [discount rules](fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/discount-rules/introduction) - sets of triggers and scopes that together define the necessary conditions for a discount to apply to items in the cart and checkout. For example, a trigger that only fires between 4pm-6pm on Mondays through Thursdays.

The integration is done via an app in the Wix App Market (created in the [Wix Developers Center](fallback::https://dev.wix.com/)) and the Wix Custom Discount Triggers service plugin.

Learn more about [service plugin extensions](fallback::https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/service-plugins/about-service-plugin-extensions).

## Before you begin

To use a custom trigger to apply a discount, you must first create a discount rule. [Create an automatic discount using the dashboard](fallback::https://support.wix.com/en/article/wix-stores-creating-automatic-discounts), or by using the [Discount Rules API](fallback::https://dev.wix.com/api/rest/wix-ecommerce/discount-rules/create-discount-rule).

## Use cases
+ [Offer a happy hour discount](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::91415019-b55c-4d83-bbf5-f4b8cd2e469eslug::sample-flows#offer-a-happy-hour-discount*fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/custom-discount-triggers-integration-spi/sample-flows#offer-a-happy-hour-discount)
+ [Offer a sale on digital products](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::91415019-b55c-4d83-bbf5-f4b8cd2e469eslug::sample-flows#offer-a-sale-on-digital-products*fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/custom-discount-triggers-integration-spi/sample-flows#offer-a-sale-on-digital-products)

## Configuration

Complete the following steps to adapt Wix system's integration to make your custom triggers available to merchants and their customers.

1. Go to the [Extensions](fallback::https://dev.wix.com/docs/build-apps/develop-your-app/extensions/about-extensions) tab in the Wix Developers Center.
1. Click **Create Extension** in the top right.
1. Filter by **eCommerce** in the left menu, then find **Ecom Discounts Trigger** and click **Create**.

1. Provide the following configuration:

    | Name                 | Type                     | Description       |
    | ---------------------|--------------------------|-------------------|
    | `deploymentUri`|string|Required. Base URI where the endpoints are called. Wix appends the endpoint path to the base URI. For example, to call the Get Eligible Triggers endpoint at `https://my-discount-app.com/v1/getEligibleTriggers`, the base URI you provide here is `https://my-discount-app.com/`. |
    | `componentName`|string|A unique name for this component. This is an internal name that will only appear in the Dev Center. |


# Sample Flows

This article presents sample flows your app can support. You aren't limited to these exact flows, but they can be a helpful jumping off point as you plan your Custom Discount Triggers integration.

## Offer a happy hour discount

Your app can allow sites to offer customers a happy hour discount. With a custom trigger based on the time an order is placed, an [automatic discount](fallback::https://support.wix.com/en/article/wix-stores-creating-automatic-discounts) can be applied.

To create a custom trigger for a happy hour discount:

1. Configure your app with custom triggers that are retrieved by Wix when [List Triggers](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::91415019-b55c-4d83-bbf5-f4b8cd2e469eslug::list-triggers*fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/custom-discount-triggers-integration-spi/list-triggers) is called. For example, give a custom trigger these properties:
- `"id"`: `"happy-hour-trigger"`
- `"name"`: `"Happy Hour, weekdays, 16:00-18:00"`

2. [Create a discount rule](fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/discount-rules/create-discount-rule) that includes the amount of the discount to apply, which items to apply the discount to, and which custom trigger to use to trigger the rule.

3. Wix calls [Get Eligible Triggers](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::91415019-b55c-4d83-bbf5-f4b8cd2e469eslug::get-eligible-triggers*fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/custom-discount-triggers-integration-spi/get-eligible-triggers) when actions are taken on the cart or checkout entities/pages. Your app should determine if the time of the customer's action should trigger the Happy Hour discount rule to apply. If so, the customer will see the discounted price.

## Offer a sale on digital products

Your app can allow sites to offer discounts on certain types of products, such as, digital products.

To create a custom trigger for a digital discount:

1. Configure your app with custom triggers that are retrieved by Wix when [List Triggers](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::91415019-b55c-4d83-bbf5-f4b8cd2e469eslug::list-triggers*fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/custom-discount-triggers-integration-spi/list-triggers) is called. For example, give a custom trigger these properties:
- `"id"`: `"digital-sale-trigger"`
- `"name"`: `"Digital products discount"`

2. [Create a discount rule](fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/discount-rules/create-discount-rule) that includes the amount of the discount to apply, which category of items to apply the discount to, and which custom trigger to use to trigger the rule.

3. Wix calls [Get Eligible Triggers](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::91415019-b55c-4d83-bbf5-f4b8cd2e469eslug::get-eligible-triggers*fallback::https://dev.wix.com/docs/rest/business-solutions/e-commerce/custom-discount-triggers-integration-spi/get-eligible-triggers) when actions are taken on the cart or checkout entities/pages. Use [Get Product](fallback::https://dev.wix.com/docs/rest/business-solutions/stores/catalog/get-product) to check the `productType` and determine if the product a customer views triggers the digital discount rule to apply. If so, the customer will see the discounted price.


Catalog and item reference. Holds IDs for the item and the catalog it came from, as well as further optional info.
This field is empty in the case of a custom line item.

price

quantity

LineItem

CustomTrigger

Required. Base URI where the endpoints are called.
Wix appends the endpoint path to the base URI. For example, to call the Get Eligible Triggers endpoint at `https://my-discount-app.com/v1/getEligibleTriggers`, the base URI you provide here is `https://my-discount-app.com/`.

deploymentUri

CustomTriggerConfig

Custom trigger ID. Must be passed with relevant `identifier`.

customTriggerId

Unique trigger identifier. The value must be the same as its equivalent in `triggers[i].identifier` in the request payload.

identifier

EligibleTrigger

lineItems

Persistent ID that correlates between the various eCommerce elements: cart, checkout, and order.

purchaseFlowId

List of triggers to be checked for discount eligibility.

triggers

GetEligibleTriggersRequest

List of eligible triggers. These are used by the Discount Rules API and Wix eCommerce to apply the relevant discount.

eligibleTriggers

GetEligibleTriggersResponse

ListTriggersRequest

customTriggers

ListTriggersResponse

Custom trigger name to display in the dashboard.

name

Unique trigger identifier. The same value must be returned in `eligibleTriggers[i].identifier`.

TriggerToFilterBy

Used for grouping line items. Sent when an item is added to a cart, checkout, or order.

ID of the app providing the catalog.

You can get your app's ID from its page in the [Wix Dev Center](https://dev.wix.com/apps).

For items from Wix catalogs, the following values always apply:
+ Wix Stores: `"215238eb-22a5-4c36-9e7b-e7c08025e04e"`
+ Wix Bookings: `"13d21c63-b5ec-5912-8397-c3a5ddb27a97"`
+ Wix Restaurants: `"9a5d83fd-8570-482e-81ab-cfa88942ee60"`

appId

ID of the item within the catalog it belongs to.

catalogItemId

Additional item details in key:value pairs. Use this optional field to provide more specificity with item selection. The `options` field values differ depending on which catalog is providing the items.

For products and variants from a Wix Stores catalog, learn more about [eCommerce integration](https://dev.wix.com/docs/rest/business-solutions/stores/catalog/e-commerce-integration).

options

CatalogReference

value

Int32Value

values

ListValue

NullValue

StringValue

fields

Struct

Value

boolValue

listValue

nullValue

numberValue

stringValue

structValue

kind

this message is not directly used by any service,
it exists to describe the expected parameters that SHOULD be provided to invoked Velo methods as part of open-platform.
e.g. SPIs, event-handlers, etc..
NOTE: this context object MUST be provided as the last argument in each Velo method signature.

Example:
```typescript
export function wixStores_onOrderCanceled({ event, metadata }: OrderCanceledEvent) {
...
}
```

[ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) 3-letter currency code.

currency

An object that describes the identity that triggered this request.

instanceId

A string representing a language and region in the format of `"xx-XX"`. First 2 letters represent the language code according to ISO 639-1. This is followed by a dash "-", and then a by 2 capital letters representing the region according to ISO 3166-2. For example, `"en-US"`.

languages

A unique identifier of the request. You may print this ID to your logs to help with future debugging and easier correlation with Wix's logs.

requestId

Context

identityType

IdentificationData

IdentityType

ID of a site visitor that has not logged in to the site.

anonymousVisitorId

ID of a site visitor that has logged in to the site.

memberId

ID of a Wix user (site owner, contributor, etc.).

wixUserId

Integration service plugin that allows custom triggers to be used with the Discount Rules service.

Lists all custom triggers provided by your service plugin integration.

This method is automatically called by Wix eCommerce to populate the custom [minimum requirements section of an automatic discount](https://support.wix.com/en/article/wix-stores-creating-automatic-discounts#:~:text=Create%20minimum%20requirements).

The data payload will include the following object as an encoded JWT. For the purposes of this example, we show the request and response objects decoded.

List custom triggers - decoded JWT

ListTriggers

Retrieves eligible custom discount triggers based on the provided items.

This method is automatically called by Wix eCommerce to retrieve the custom discount triggers provided by your extension.
This happens when actions are performed on the cart and checkout entities/pages. For example, when an item is added to the cart.