Need to create rules based on bundles?
Learn more
LogoLogo
APIsChangelog
  • Getting started
  • Rules
  • Conditions
    • Scope
    • Aggregations
    • Nested
    • Dynamic values
  • Actions
    • Types
      • Percentage
      • Fixed amount
      • Fixed price
      • Buy X pay Y
      • Every X discount Y
    • Bundle
      • Balanced
      • Every
    • Aggregation
    • Limit
  • Matchers
  • Operators
  • Check and validation
  • Core API integration
    • Order rules
    • Price rules
    • Virtual relationships
  • Resources
    • Promotions
    • Price lists
  • Use cases
    • Promotions
      • Discount line items based on item's price
      • Get a discount when paying by credit card
      • Discount an order based on promo item and total number of items
      • Offer a specific shipping method for free in a specific country
      • Discount items with large stock availability
      • Discount all the SKU in an order based on the shipping country
      • Discount all the SKU in an order based on the customer email domain
    • Price lists
      • Discount all prices greater than or equal to a specific value
      • Discount specific SKUs for new clients
      • Change strike-through price based on customer email domain
On this page
  • Examples
  • Selector
  • Identifier
  • Apply on

Actions

How to set a rule's actions and what are the required and optional parameters to set

PreviousDynamic valuesNextTypes

Last updated 2 months ago

For each rule you need to provide one or more actions as an array of action objects.

Actions are triggered based on the provided rule's . Once the combination of conditions are evaluated according to the conditions logic specified at the level, if they are satisfied, all the related actions will be applied to the specified resource's fields. Among other effects, actions can modify order totals, apply fixed, percentage, and other types of discounts to specific items, or adjust quantities.

Multiple actions (even involving the same resource's field) are applied in the order they are listed within the rule payload.

For each action you must define at least its type and the discount value to be applied. Based on the some restrictions may apply, for example:

  • The list of required parameters may vary.

  • The required format/type for the value (if any) may vary.

  • Some optional key (e.g. bundle, limit, etc.) may be available or not.

Key
Type
Description
Example

type

String

"percentage"

selector

String

The resource on which to apply the action (expressed in dot notation). Can be an attribute if you set also the identifier key.

"order.line_items" "order.line_items.id"

identifier

String

An identifier value to address one or more specific instances of the resource based on the attribute defined in the selector key (if any). Cannot be used if the selector is a resource.

"WVyPSgRwxZ"

groups

Array

[ "discountable-items", "t-shirts" ]

bundle

Object

Additional directives on how to recursively pick a subset of elements from the specified groups.

aggregation

Object

Additional requirements on the aggregated items targeted by the action.

apply_on

String

The specific field of the selector resource on which to apply the action (available for specific action types only).

"compare_at_amount_cents"

discount_mode

String

"distributed"

limit

Object

Additional restrictions on the number of items on which an action will be applied (available for specific action types only, cannot be used if the bundle key is specified).

value

IntegerFloatObject

0.2 2500 { "x": 3, "y": 2 }

Referring to the , an action selector can be a resource or an attribute. If it's a resource (i.e. anything but the last leaf of the relationship tree using the dot notation — e.g. order or order.line_items) the action will be applied on a default field (usually the unit amount of the resource), unless specified differently in the apply_on key. If it's an attribute (e.g. or order.line_items.id), you need to set also the identifier key (e.g. WVyPSgRwxZ) so that the action will be applied to the specified instance only.

For those conditions that don't have a group explicitly specified, the UUID autogenerated by the will be automatically set as the group to which apply the action.

Examples

Selector

The following action applies a 10% discount to all the line items associated with an SKU:

"actions": [
  "type": "percentage",
  "selector": "order.line_items.sku",
  "value": 0.1
]

Identifier

The following action sets to 1500 cents the unit amount of the line items associated with the SKU identified by the code XMASMUG1234 only:

"actions": [
  "type": "fixed_price",
  "selector": "order.line_items.sku.code",
  "identifier": "XMASMUG1234",
  "value": 1500
]

Apply on

The following action applies a fixed amount discount of 1500 to the total amount (instead of the default unit amount) of all the line items associated with an SKU:

"actions": [
  "type": "fixed_amount",
  "selector": "order.line_items.sku",
  "apply_on": "total_amount_cents",
  "value": 1500
]

The following action applies a fixed amount discount of 1500 to the total amount (instead of the default unit amount) of the line items associated with the SKU identified by the code XMASMUG1234 only:

"actions": [
  "type": "fixed_amount",
  "selector": "order.line_items.sku.code",
  "identifier": "XMASMUG1234",
  "apply_on": "total_amount_cents",
  "value": 1500
]

The type of action you want to apply (check the ).

The groups that will be targeted by the action (must be one or more among the ones defined when grouping the matches of the related conditions — required when using ).

Learn more .

Learn more .

The type of distribution of the discount over the selected items. Can be one of default or distributed, default is default (available for actions only).

Learn more .

The amount or percentage (or any other format required) to be discounted (format and type may vary based on the ).

You can use apply_on on , , and actions only.

percentage
fixed amount
fixed price
list of available types
bundles
here
here
fixed amount
here
action type
conditions
rule
type of action
Core API integration
Core API integration