> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voucherify.io/llms.txt
> Use this file to discover all available pages before exploring further.
# List Validation Rules
> Retrieve validation rules.
## OpenAPI
````yaml /openapi/validation-rules.json get /v1/validation-rules
openapi: 3.0.1
info:
title: Voucherify API - Validation Rules
version: v2018-08-01
description: >-
Voucherify promotion engine REST API. Please see
https://docs.voucherify.io/docs for more details.
contact:
name: Voucherify Team
url: https://www.voucherify.io/contact-support
email: support@voucherify.io
termsOfService: https://www.voucherify.io/legal/subscription-agreement
license:
name: MIT
url: https://github.com/voucherifyio/voucherify-js-sdk/blob/main/LICENSE
servers:
- url: https://{cluster}.voucherify.io
description: Base URL
variables:
cluster:
default: api
enum:
- api
- us1.api
- as1.api
- download
- us1.download
- as1.download
security: []
paths:
/v1/validation-rules:
get:
tags:
- Validation Rules
summary: List Validation Rules
description: Retrieve validation rules.
operationId: list-validation-rules
parameters:
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/page'
- schema:
$ref: '#/components/schemas/ParameterOrderListValidationRules'
in: query
name: order
description: >-
This is a property that controls the sorting direction of the
results. Sort the results using one of the filtering options, where
the dash `-` preceding a sorting option means sorting in a
descending order.
- name: start_date
in: query
schema:
$ref: '#/components/schemas/ParameterDate'
description: >-
Timestamp representing the date and time which results must start
on. Represented in ISO 8601 format.
- name: end_date
in: query
schema:
$ref: '#/components/schemas/ParameterDate'
description: >-
Timestamp representing the date and time which results must end on.
Represented in ISO 8601 format.
responses:
'200':
description: Returns a dictionary of validation rules.
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationRulesListResponseBody'
examples:
Example:
value:
object: list
data_ref: data
data:
- id: val_auLlxlfTR9Ps
name: Customer in Segment
rules:
'1':
name: customer.segment
rules: {}
property: null
conditions:
$is:
- seg_18tD3HR0h8ymPC07rBMLryk3
logic: '1'
applicable_to:
excluded: []
included: []
included_all: false
created_at: '2021-12-10T11:08:16.499Z'
updated_at: '2021-12-10T12:01:41.665Z'
type: advanced
context_type: earning_rule.order.paid
assignments_count: 1
object: validation_rules
- id: val_AvIe1WWuBXre
name: Order Volume - Price of Any Item - = 1500 USD
rules:
'1':
name: order.items.price_any
rules: {}
property: null
conditions:
$is:
- 150000
logic: '1'
applicable_to:
excluded: []
included: []
included_all: false
created_at: '2021-12-13T06:54:06.864Z'
type: advanced
context_type: reward_assignment.pay_with_points
object: validation_rules
- id: val_aZhPe4tQYMgr
name: Business Validation Rule - excluded
rules:
logic: ''
applicable_to:
excluded:
- object: products_collection
id: pc_7fVU2RxybhR66YxC7r7BKKRh
source_id: null
- object: sku
id: sku_0bae3b28f610fd0da1
source_id: first_product_sku_1
included: []
included_all: true
created_at: '2022-09-13T14:38:33.710Z'
type: basic
context_type: >-
campaign.discount_coupons.discount.apply_to_items_by_quantity
assignments_count: 1
object: validation_rules
- id: val_bbJCAXAWtYX0
name: >-
Business Validation Rule - Test - Discount Effect -
Amount - Items - each unit of matched product
rules:
logic: ''
applicable_to:
excluded: []
included:
- object: products_collection
id: pc_a11pr0dUc75
source_id: null
effect: APPLY_TO_EVERY
quantity_limit: 1
included_all: false
created_at: '2022-09-02T17:04:23.814Z'
type: basic
context_type: >-
campaign.discount_coupons.discount.apply_to_items_by_quantity
assignments_count: 1
object: validation_rules
- id: val_BkV21MUJGaiT
name: Order Volume - Total Amount More than 100
rules:
'1':
name: order.amount
rules: {}
property: null
conditions:
$more_than:
- 10000
logic: '1'
applicable_to:
excluded: []
included: []
included_all: false
created_at: '2021-12-10T14:01:10.750Z'
type: advanced
context_type: reward_assignment.pay_with_points
object: validation_rules
- id: val_BTQg027UGl0v
name: Business Validation Rule - Get some $ off
rules:
logic: ''
applicable_to:
excluded: []
included:
- object: product
id: prod_0a41dd45dc85fcab40
source_id: '10474'
included_all: false
created_at: '2021-12-07T06:58:23.759Z'
updated_at: '2021-12-22T08:11:18.773Z'
type: advanced
context_type: campaign.discount_coupons.discount.apply_to_items
assignments_count: 1
object: validation_rules
total: 6
security:
- X-App-Id: []
X-App-Token: []
- X-Voucherify-OAuth:
- api
- validation-rules
components:
parameters:
limit:
name: limit
in: query
required: false
schema:
$ref: '#/components/schemas/ParameterLimit'
description: >-
Limits the number of objects to be returned. The limit can range between
1 and 100 items. If no limit is set, it returns 10 items.
page:
name: page
in: query
required: false
schema:
$ref: '#/components/schemas/ParameterPage'
description: Which page of results to return. The lowest value is `1`.
schemas:
ParameterOrderListValidationRules:
type: string
enum:
- created_at
- '-created_at'
- updated_at
- '-updated_at'
- name
- '-name'
ParameterDate:
type: string
example: '2023-12-22T10:13:06.487Z'
format: date-time
ValidationRulesListResponseBody:
description: Response body schema for **GET** `v1/validation-rules`.
type: object
title: Validation Rules List Response Body
properties:
object:
type: string
description: >-
The type of the object represented by JSON. This object stores
information about validation rules.
default: list
data_ref:
type: string
description: >-
Identifies the name of the attribute that contains the array of
validation rules.
default: data
data:
type: array
description: An array of validation rules.
items:
$ref: '#/components/schemas/ValidationRule'
total:
type: integer
description: Total number of validation rules in the project.
required:
- object
- data_ref
- data
- total
ParameterLimit:
type: integer
minimum: 1
maximum: 100
ParameterPage:
type: integer
minimum: 1
maximum: 100
ValidationRule:
title: Validation Rule
allOf:
- $ref: '#/components/schemas/ValidationRuleBase'
- title: Validation Rule
type: object
description: This is an object representing a response validation rule.
properties:
id:
type: string
example: val_eR1c41hu0vUU
description: Unique validation rule ID.
created_at:
type: string
example: '2022-03-23T07:44:00.444Z'
description: >-
Timestamp representing the date and time when the validation
rule was created. The value is shown in the ISO 8601 format.
format: date-time
updated_at:
type: string
example: '2022-04-26T08:35:54.960Z'
description: >-
Timestamp representing the date and time when the validation
rule was updated. The value is shown in the ISO 8601 format.
format: date-time
assignments_count:
description: >-
The number of instances the validation rule has been assigned to
different types of redeemables.
type: integer
object:
type: string
default: validation_rules
description: >-
The type of the object represented by JSON. This object stores
information about the validation rule.
required:
- id
- name
- rules
- applicable_to
- created_at
- type
- context_type
- object
ValidationRuleBase:
title: Validation Rule Base
type: object
description: This is an object representing a request validation rule.
properties:
name:
type: string
description: Custom, unique name for set of validation rules.
example: Business Validation Rule
rules:
$ref: '#/components/schemas/ValidationRuleRules'
bundle_rules:
$ref: '#/components/schemas/ValidationRuleBundleRules'
error:
type: object
description: >-
Contains the error message returned from API when validation /
redemption fails to meet requirements of defined rules.
properties:
message:
type: string
description: >-
The error message returned from API when validation / redemption
fails to meet requirements of defined rules.
applicable_to:
type: object
properties:
excluded:
type: array
description: Defines which items are excluded from a discount.
items:
$ref: '#/components/schemas/ApplicableTo'
included:
type: array
description: Defines which items are included in a discount.
items:
$ref: '#/components/schemas/ApplicableTo'
included_all:
type: boolean
description: Indicates whether all items are included in the discount.
type:
type: string
enum:
- expression
- basic
- advanced
- complex
default: expression
description: Type of validation rule.
context_type:
type: string
default: global
enum:
- earning_rule.order.paid
- earning_rule.custom_event
- earning_rule.customer.segment.entered
- earning_rule.customer.tier.joined
- earning_rule.customer.tier.left
- earning_rule.customer.tier.upgraded
- earning_rule.customer.tier.downgraded
- earning_rule.customer.tier.prolonged
- campaign.discount_coupons
- campaign.discount_coupons.discount.apply_to_order
- campaign.discount_coupons.discount.apply_to_items
- campaign.discount_coupons.discount.apply_to_items_proportionally
- >-
campaign.discount_coupons.discount.apply_to_items_proportionally_by_quantity
- campaign.discount_coupons.discount.apply_to_items_by_quantity
- campaign.discount_coupons.discount.fixed.apply_to_items
- campaign.discount_coupons.discount.percent.apply_to_items
- campaign.gift_vouchers
- campaign.gift_vouchers.gift.apply_to_order
- campaign.gift_vouchers.gift.apply_to_items
- campaign.referral_program
- campaign.referral_program.discount.apply_to_order
- campaign.referral_program.discount.apply_to_items
- campaign.referral_program.discount.apply_to_items_proportionally
- >-
campaign.referral_program.discount.apply_to_items_proportionally_by_quantity
- campaign.referral_program.discount.apply_to_items_by_quantity
- campaign.referral_program.discount.fixed.apply_to_items
- campaign.referral_program.discount.percent.apply_to_items
- campaign.promotion
- campaign.promotion.discount.apply_to_order
- campaign.promotion.discount.apply_to_items
- campaign.promotion.discount.apply_to_items_proportionally
- >-
campaign.promotion.discount.apply_to_items_proportionally_by_quantity
- campaign.promotion.discount.apply_to_items_by_quantity
- campaign.promotion.discount.fixed.apply_to_items
- campaign.promotion.discount.percent.apply_to_items
- campaign.loyalty_program
- voucher.discount_voucher
- voucher.discount_voucher.discount.apply_to_order
- voucher.discount_voucher.discount.apply_to_items
- voucher.discount_voucher.discount.apply_to_items_proportionally
- >-
voucher.discount_voucher.discount.apply_to_items_proportionally_by_quantity
- voucher.discount_voucher.discount.apply_to_items_by_quantity
- voucher.discount_voucher.discount.fixed.apply_to_items
- voucher.discount_voucher.discount.percent.apply_to_items
- voucher.gift_voucher
- voucher.gift_voucher.gift.apply_to_order
- voucher.gift_voucher.gift.apply_to_items
- voucher.loyalty_card
- distribution.custom_event
- distribution.order.paid
- distribution.order.created
- distribution.order.canceled
- distribution.order.updated
- reward_assignment.pay_with_points
- global
description: >-
Validation rule context type.
| **Context Type** | **Definition** |
|:---|:---|
| earning_rule.order.paid | |
| earning_rule.custom_event | |
| earning_rule.customer.segment.entered | |
| campaign.discount_coupons | |
| campaign.discount_coupons.discount.apply_to_order | |
| campaign.discount_coupons.discount.apply_to_items | |
| campaign.discount_coupons.discount.apply_to_items_proportionally
| |
|
campaign.discount_coupons.discount.apply_to_items_proportionally_by_quantity
| |
| campaign.discount_coupons.discount.fixed.apply_to_items | |
| campaign.gift_vouchers | |
| campaign.gift_vouchers.gift.apply_to_order | |
| campaign.gift_vouchers.gift.apply_to_items | |
| campaign.referral_program | |
| campaign.referral_program.discount.apply_to_order | |
| campaign.referral_program.discount.apply_to_items | |
| campaign.referral_program.discount.apply_to_items_proportionally
| |
|
campaign.referral_program.discount.apply_to_items_proportionally_by_quantity
| |
| campaign.referral_program.discount.fixed.apply_to_items | |
| campaign.promotion | |
| campaign.promotion.discount.apply_to_order | |
| campaign.promotion.discount.apply_to_items | |
| campaign.promotion.discount.apply_to_items_proportionally | |
|
campaign.promotion.discount.apply_to_items_proportionally_by_quantity
| |
| campaign.promotion.discount.fixed.apply_to_items | |
| campaign.loyalty_program | |
| voucher.discount_voucher | |
| voucher.discount_voucher.discount.apply_to_order | |
| voucher.discount_voucher.discount.apply_to_items | |
| voucher.discount_voucher.discount.apply_to_items_proportionally |
|
|
voucher.discount_voucher.discount.apply_to_items_proportionally_by_quantity
| |
| voucher.discount_voucher.discount.fixed.apply_to_items | |
| voucher.gift_voucher | |
| voucher.gift_voucher.gift.apply_to_order | |
| voucher.gift_voucher.gift.apply_to_items | |
| voucher.loyalty_card | |
| distribution.custom_event | |
| reward_assignment.pay_with_points | |
| global | |
ValidationRuleRules:
title: Validation Rule Rules
type: object
description: >-
Contains all the rule definitions for the validation rule. It is a set
of key value pairs representing the rules and logic between the rules.
The keys are numbered consecutively beginning from `1`. The values are
objects containing the rule conditions.
properties:
logic:
type: string
example: (1 and 2) and (3)
description: Defines the logic between the rules.
additionalProperties:
type: object
description: Contains the name of the validation rule.
properties:
name:
type: string
description: >-
Voucherify's specific rule name. Read [Validation rule
reference](/optimize/validation-rules-reference) to learn how
specific rules work. The list of available names is provided
below.
|**Type**|**Name** |
---- | -----------|
|**Customer** | customer.segment
customer.metadata* |
|**Order** |order.amount
order.total_amount
order.initial_amount
order.items.count
order.items.price_any
order.items.price_each
order.items.metadata_any
order.items.metadata_each
order.metadata* |
| **Campaign** | campaign.orders.amount_discounted
campaign.orders.amount
campaign.redemptions.count
campaign.redemptions.count.daily
campaign.redemptions.count.weekly
campaign.redemptions.count.monthly
campaign.redemptions.customers_count
campaign.redemptions.customers_count.daily
campaign.redemptions.customers_count.weekly
campaign.redemptions.customers_count.monthly |
| **Redemption** |redemption.gift.amount
redemption.count.daily
redemption.count.weekly
redemption.count.monthly
redemption.count.per_customer
redemption.count.per_customer.daily
redemption.count.per_customer.weekly
redemption.count.per_customer.monthly
redemption.api_key
redemption.count.per_api_key
redemption.user.login
redemption.count.per_user
redemption.metadata
redemption.reward.pay_with_points.points_used |
| **Product** | product.id
product.price
product.quantity
product.discount_applicable
product.metadata*
product.metadata.aggregated_quantity
product.metadata.aggregated_amount
product.metadata.discount_applicable
product.metadata.match_all |
| **SKU** | sku.id
sku.price
sku.quantity
sku.discount_applicable |
| **Publication** | publication.redeemable_by_linked_customer |
| **Custom Event** | custom_event.metadata* |
| **Order items** | order.items.every
order.items.any
order.items.none
order.items.cheapest
order.items.most_expensive | order.items.quantity
order.items.aggregated_quantity
order.items.price
order.items.aggregated_amount
order.items.metadata* |
*Requires the `property` field to be defined.
property:
type: string
nullable: true
description: >-
Custom name for a metadata property associated with the condition
to be satisfied. **Required** if the property `name` is any of the
following:
customer_metadata
custom_event_metadata
order_items_metadata
order_metadata
product_metadata
redemption_metadata
conditions:
$ref: '#/components/schemas/ValidationRuleConditions'
rules:
$ref: '#/components/schemas/ValidationRuleRules01'
error:
type: object
description: >-
Contains the error message returned from API when validation /
redemption fails to meet requirements of defined rule.
properties:
message:
type: string
description: >-
The error message returned from API when validation /
redemption fails to meet requirements of defined rule.
ValidationRuleBundleRules:
title: Validation Rule Bundle Rules
type: object
description: >-
Contains all the definitions for the bundle rules. It is a set of key
value pairs representing the rules and logic between them. The keys are
numbered consecutively beginning from `1`. The values are objects
containing the rule conditions.
While updating with the PUT method, you can pass `"bundle_rules": null`
to delete the configuration; in the response, an empty object is then
returned.
properties:
limit:
type: integer
description: >-
Defines how many bundles can be identified in the order and the
maximum multiplier of the discount per identified bundle. For
example, if the order meets 3 bundles, but `limit: 2`, the discount
will be multiplied by 2.
nullable: true
minimum: 1
maximum: 100
default: 1
additionalProperties:
type: object
description: Contains the name of the bundle rule.
properties:
name:
type: string
description: >-
Voucherify's specific bundle rule name. Currently, it is only
`order.items.any`.
enum:
- order.items.any
conditions:
type: object
description: >-
Defines the conditions of the bundle rule. The order items in the
customer's cart must meet the conditions. Because the rule
concerns order items, the only permissible condition is `$is`.
properties:
$is:
type: array
maxItems: 1
items:
type: object
description: ''
properties:
id:
type: string
description: >-
Unique identifier of the product, SKU, or collection
assigned by Voucherify.
type:
type: string
description: >-
Type of the order item. It can be a `product_or_sku` or
`products_collection`
enum:
- product_or_sku
- products_collection
object:
type: string
description: >-
Object used in the bundle rule. It can be a
`products_collection`, `product`, or `sku`.
enum:
- products_collection
- product
- sku
required:
- id
- type
- object
rules:
properties:
logic:
type: string
example: '1'
description: Defines the logic between the sub-rules.
additionalProperties:
type: object
description: Contains the name of the validation sub-rule.
maxProperties: 1
properties:
name:
type: string
description: >-
Voucherify's specific sub-rule name. Currently, it is only
`order.items.aggregated_quantity`.
enum:
- order.items.aggregated_quantity
conditions:
type: object
description: >-
Defines the conditions of the bundle rule. The quantity of
order items in the customer's cart must meet the conditions.
properties:
$is:
type: array
maxItems: 1
items:
type: number
minimum: 1
description: >-
The quantity of units in the customer's order must be
equal or higher than the defined number.
rules:
type: object
description: An empty object.
error:
type: object
description: >-
**CURRENTLY UNSUPPORTED**. Contains the error message returned
from API when validation / redemption fails to meet requirements
of defined rule.
properties:
message:
type: string
description: >-
The error message returned from API when validation /
redemption fails to meet requirements of defined rule.
ApplicableTo:
title: Applicable To
type: object
properties:
object:
type: string
enum:
- product
- sku
- products_collection
description: >-
This object stores information about the resource to which the
discount is applicable.
id:
type: string
description: >-
Unique product collection, product, or SKU identifier assigned by
Voucherify.
source_id:
type: string
description: The source identifier from your inventory system.
product_id:
type: string
description: Parent product's unique ID assigned by Voucherify.
product_source_id:
type: string
description: Parent product's source ID from your inventory system.
price:
type: number
description: >-
New fixed price of an item. Value is multiplied by 100 to precisely
represent 2 decimal places. For example, a $10 price is written as
1000. In case of the fixed price being calculated by the formula,
i.e. the price_formula parameter is present in the fixed price
definition, this value becomes the fallback value. Such that in a
case where the formula cannot be calculated due to missing metadata,
for example, this value will be used as the fixed price.
price_formula:
type: number
description: >-
Formula used to dynamically calculate the discounted price of an
item.
effect:
description: Defines how the discount is applied to the customer's order.
allOf:
- $ref: '#/components/schemas/ApplicableToEffect'
quantity_limit:
type: integer
description: >-
The maximum number of units allowed to be discounted per order line
item.
aggregated_quantity_limit:
type: integer
description: >-
The maximum number of units allowed to be discounted combined across
all matched order line items.
amount_limit:
type: integer
description: >-
Upper limit allowed to be applied as a discount per order line item.
Value is multiplied by 100 to precisely represent 2 decimal places.
For example, a $6 maximum discount is written as 600.
aggregated_amount_limit:
type: integer
description: >-
Maximum discount amount per order. Value is multiplied by 100 to
precisely represent 2 decimal places. For example, a $6 maximum
discount on the entire order is written as 600. This value is
definable for the following discount effects:
- `APPLY_TO_ITEMS` (each item subtotal is discounted equally)
- `APPLY_TO_ITEMS_BY_QUANTITY` (each unit of matched products has
the same discount value)
product_campaign_quantity_limit:
type: integer
description: >-
Limits the number of discounted item units (product, SKU,
collection) that all customers can receive in a given campaign. If a
product is selected, the limit covers all discounts across all SKUs
belonging to that product. If a product collection is selected, the
limit covers all products/SKUs within the collection.
This limit is available on demand as part of campaign budget limits.
Contact [Voucherify
support](https://www.voucherify.io/contact-support) or your account
manager to learn more.
product_campaign_quantity_limit_formula:
type: string
description: >-
Formula used to dynamically calculate the maximum units per
campaign.
This limit is available on demand as part of campaign budget limits.
Contact [Voucherify
support](https://www.voucherify.io/contact-support) or your account
manager to learn more.
product_customer_campaign_quantity_limit:
type: integer
description: >-
Limits the number of discounted item units (product, SKU,
collection) that one customer can receive in a given campaign.
This limit is available on demand as part of campaign budget limits.
Contact [Voucherify
support](https://www.voucherify.io/contact-support) or your account
manager to learn more.
product_customer_campaign_quantity_limit_formula:
type: string
description: >-
Formula used to dynamically calculate the maximum units per customer
in a campaign.
This limit is available on demand as part of campaign budget limits.
Contact [Voucherify
support](https://www.voucherify.io/contact-support) or your account
manager to learn more.
product_in_collection_campaign_quantity_limit:
type: integer
description: >-
Limits the number of discounted item units of a given product in a
collection that all customers can receive in a given campaign.
This limit is available on demand as part of campaign budget limits.
Contact [Voucherify
support](https://www.voucherify.io/contact-support) or your account
manager to learn more.
product_in_collection_campaign_quantity_limit_formula:
type: string
description: >-
Formula used to dynamically calculate the maximum units per campaign
for a product in a collection.
This limit is available on demand as part of campaign budget limits.
Contact [Voucherify
support](https://www.voucherify.io/contact-support) or your account
manager to learn more.
product_in_collection_customer_campaign_quantity_limit:
type: integer
description: >-
Limits the number of discounted item units of a given product in a
collection that one customer can receive in a campaign.
This limit is available on demand as part of campaign budget limits.
Contact [Voucherify
support](https://www.voucherify.io/contact-support) or your account
manager to learn more.
product_in_collection_customer_campaign_quantity_limit_formula:
type: string
description: >-
Formula used to dynamically calculate the maximum units per customer
for a product in a collection.
This limit is available on demand as part of campaign budget limits.
Contact [Voucherify
support](https://www.voucherify.io/contact-support) or your account
manager to learn more.
product_promotion_tier_quantity_limit:
type: integer
description: >-
Limits the number of discounted item units that all customers can
receive in a promotion tier.
This limit is available on demand as part of campaign budget limits.
Contact [Voucherify
support](https://www.voucherify.io/contact-support) or your account
manager to learn more.
product_promotion_tier_quantity_limit_formula:
type: string
description: >-
Formula used to dynamically calculate the maximum units per
promotion tier.
This limit is available on demand as part of campaign budget limits.
Contact [Voucherify
support](https://www.voucherify.io/contact-support) or your account
manager to learn more.
product_customer_promotion_tier_quantity_limit:
type: integer
description: >-
Limits the number of discounted item units that one customer can
receive in a given promotion tier.
This limit is available on demand as part of campaign budget limits.
Contact [Voucherify
support](https://www.voucherify.io/contact-support) or your account
manager to learn more.
product_customer_promotion_tier_quantity_limit_formula:
type: string
description: >-
Formula used to dynamically calculate the maximum units per customer
in a promotion tier.
This limit is available on demand as part of campaign budget limits.
Contact [Voucherify
support](https://www.voucherify.io/contact-support) or your account
manager to learn more.
product_in_collection_promotion_tier_quantity_limit:
type: integer
description: >-
Limits the number of discounted item units of a given product in a
collection that all customers can receive in a given promotion tier.
This limit is available on demand as part of campaign budget limits.
Contact [Voucherify
support](https://www.voucherify.io/contact-support) or your account
manager to learn more.
product_in_collection_promotion_tier_quantity_limit_formula:
type: string
description: >-
Formula used to dynamically calculate the maximum units per
promotion tier for a product in a collection.
This limit is available on demand as part of campaign budget limits.
Contact [Voucherify
support](https://www.voucherify.io/contact-support) or your account
manager to learn more.
product_in_collection_customer_promotion_tier_quantity_limit:
type: integer
description: >-
Limits the number of discounted item units of a given product in a
collection that one customer can receive in a promotion tier.
This limit is available on demand as part of campaign budget limits.
Contact [Voucherify
support](https://www.voucherify.io/contact-support) or your account
manager to learn more.
product_in_collection_customer_promotion_tier_quantity_limit_formula:
type: string
description: >-
Formula used to dynamically calculate the maximum units per customer
in a promotion tier for a product in a collection.
This limit is available on demand as part of campaign budget limits.
Contact [Voucherify
support](https://www.voucherify.io/contact-support) or your account
manager to learn more.
order_item_indices:
type: array
description: >-
Lists which order lines are (not) covered by the discount. The order
in the array is determined by the sequence of applied discounts,
while the numbers correspond to the order lines sent in the `order`
object in the request. The first order line is assigned `0`, the
second order line is assigned `1`, and so on.
items:
type: integer
order_item_units:
type: array
description: >-
Lists which units within order lines are covered by the discount.
The order line items are listed according to sequence of applied
discounts while the `index` corresponds to the order line sent in
the `order` object in the request.
items:
type: object
properties:
index:
type: integer
description: >-
Number assigned to the order line item in accordance with the
order sent in the request.
minimum: 0
units:
type: array
description: >-
Numbers of units in the order line covered by the discount;
e.g. `2, 5, 8` for 10 units with the setting
`"skip_initially": 1`, `"repeat": 3`. The counting of units
starts from `1`. The maximum quantity of all handled units is
1000. If the quantity of all order items exceeds 1000, this
array is not returned, but `units_limit_exceeded: true`.
However, the discount is calculated properly for all relevant
units.
items:
type: integer
units_limit_exceeded:
type: boolean
description: >-
Returned as `true` only when the sum total of `quantity` of
all order items exceeds 1000.
repeat:
type: integer
description: >-
Determines the recurrence of the discount, e.g. `"repeat": 3` means
that the discount is applied to every third item.
skip_initially:
type: integer
description: >-
Determines how many items are skipped before the discount is
applied.
target:
type: string
description: >-
Determines to which kinds of objects the discount is applicable.
`ITEM` includes products and SKUs. `UNIT` means particular units
within an order line.
enum:
- ITEM
- UNIT
required:
- object
- id
- effect
ValidationRuleConditions:
title: Validation Rule Conditions
type: object
description: >
A set of key value pairs representing the condition name and value. The
list of available conditions is provided below:
| **Condition (key)** |
**Definition** |
|---------------------|---------------------------------------------------------------|
| `$is` | A property is a predefined
value. |
| `$is_not` | A property is not a predefined
value. |
| `$in` | A property is one value of the values in a
predefined list of values. |
|`$not_in` | A property is not one of the values in a
predefined list of values. |
| `$less_than` | A property is less than a predefined value.
Can be also used with datetime. |
| `$less_than_or_equal` | A property is less than or equal to a
predefined value. Can be also used with datetime. |
| `$more_than` | A property is more than a predefined value.
Can be also used with datetime. |
| `$more_than_or_equal` | A property is more than or equal to a
predefined value. Can be also used with datetime. |
| `$starts_with` | A property starts with the predefined sequence
of characters. |
| `$ends_with ` | A property ends with the predefined sequence
of characters. |
| `$contains` | A property contains the predefined sequence of
characters. |
| `$timeframe` | A property occurs within the time frame, i.e.
every 1 day for 1 hour, e.g. `$timeframe:
["2024-11-12T14:59:23.019Z;P1D;PT1H"]`
|
| `$timeframe_absolute` | A property occurs between two dates and times,
e.g.
`2024-11-14T16:02:00.000Z;2024-11-28T16:02:00.000Z`
|
| `$timeframe_daily_hours` | A property occurs between selected hours on
selected days of the week, e.g. `18:00;20:01;2,3`, where `0` equals
Sunday, `1` equals Monday, `2` equals Tuesday, `3` equals Wednesday, `4`
equals Thursday, `5` equals Friday, and `6` equals
Saturday. |
| `$dow` | A property occurs within given days of the
week, where `0` equals Sunday, `1` equals Monday, `2` equals Tuesday,
`3` equals Wednesday, `4` equals Thursday, `5` equals Friday, and `6`
equals Saturday.
|
| `$count` | For array metadata; the property must have
exactly the defined number of
elements. |
| `$count_more` | For array metadata; the property must have
more elements than the defined
number. |
| `$count_less` | For array metadata; the property must have
less elements than the defined
number. |
| `$from` | The property must belong to the predefined
value. Related to product collections and best used together with the
`$is` condition.
|
| `$after` | The value is after the date. |
| `$before` | The value is before the
date. |
| `$more_than_ago` | The date is more than the defined
value ago expressed in number of days, relative to today, e.g. more than
3 days ago. |
| `$less_than_ago` | The date is less than the defined
value ago expressed in number of days, relative to today, less than 3
days ago. |
| `is_days_ago` | The date is exactly the defined value
ago expressed in number of days, relative to today, e.g. exactly 3 days
ago. |
| `$more_than_future` | The date is more than the defined
value in the future expressed in number of days, relative to today, e.g.
more than 3 days in the
future. |
| `$less_than_ago` | The date is less than the defined
value in the future expressed in number of days, relative to today, e.g.
less than 3 days in the
future. |
| `$is_days_in_future` | The date is exactly the defined
value in the future expressed in number of days, relative to today, e.g.
exactly 3 days in the
future. |
properties:
$is:
$ref: '#/components/schemas/AnyOne'
$is_not:
$ref: '#/components/schemas/AnyOne'
$in:
$ref: '#/components/schemas/Any'
$not_in:
$ref: '#/components/schemas/Any'
$less_than:
$ref: '#/components/schemas/AnyOne'
$less_than_or_equal:
$ref: '#/components/schemas/AnyOne'
$more_than:
$ref: '#/components/schemas/AnyOne'
$more_than_or_equal:
$ref: '#/components/schemas/AnyOne'
$starts_with:
$ref: '#/components/schemas/AnyString'
$ends_with:
$ref: '#/components/schemas/AnyString'
$contains:
$ref: '#/components/schemas/AnyString'
$timeframe:
$ref: '#/components/schemas/AnyString'
$timeframe_absolute:
$ref: '#/components/schemas/AnyString'
$timeframe_daily_hours:
$ref: '#/components/schemas/AnyString'
$dow:
type: array
items:
type: integer
minimum: 0
maximum: 6
$count:
$ref: '#/components/schemas/AnyNumber'
$count_more:
$ref: '#/components/schemas/AnyNumber'
$count_less:
$ref: '#/components/schemas/AnyNumber'
$not_differ:
$ref: '#/components/schemas/Any'
$not_intersect:
$ref: '#/components/schemas/Any'
$from:
$ref: '#/components/schemas/Any'
$after:
$ref: '#/components/schemas/AnyDateDateTime'
$before:
$ref: '#/components/schemas/AnyDateDateTime'
$more_than_ago:
$ref: '#/components/schemas/AnyNumber'
$less_than_ago:
$ref: '#/components/schemas/AnyNumber'
$is_days_ago:
$ref: '#/components/schemas/AnyNumber'
$more_than_future:
$ref: '#/components/schemas/AnyNumber'
$less_than_future:
$ref: '#/components/schemas/AnyNumber'
$is_days_in_future:
$ref: '#/components/schemas/AnyNumber'
ValidationRuleRules01:
title: Validation Rule Rules
type: object
description: >-
Contains all the rule definitions for the validation rule. It is a set
of key value pairs representing the rules and logic between the rules.
The keys are numbered consecutively beginning from `1`. The values are
objects containing the rule conditions.
properties:
logic:
type: string
example: (1 and 2) and (3)
description: Defines the logic between the rules.
additionalProperties:
type: object
description: Contains the name of the validation rule.
properties:
name:
type: string
description: >-
Voucherify's specific rule name. Read [Validation rule
reference](/optimize/validation-rules-reference) to learn how
specific rules work. The list of available names is provided
below.
|**Type**|**Name** |
---- | -----------|
|**Customer** | customer.segment
customer.metadata* |
|**Order** |order.amount
order.total_amount
order.initial_amount
order.items.count
order.items.price_any
order.items.price_each
order.items.metadata_any
order.items.metadata_each
order.metadata* |
| **Campaign** | campaign.orders.amount_discounted
campaign.orders.amount
campaign.redemptions.count
campaign.redemptions.count.daily
campaign.redemptions.count.weekly
campaign.redemptions.count.monthly
campaign.redemptions.customers_count
campaign.redemptions.customers_count.daily
campaign.redemptions.customers_count.weekly
campaign.redemptions.customers_count.monthly |
| **Redemption** |redemption.gift.amount
redemption.count.daily
redemption.count.weekly
redemption.count.monthly
redemption.count.per_customer
redemption.count.per_customer.daily
redemption.count.per_customer.weekly
redemption.count.per_customer.monthly
redemption.api_key
redemption.count.per_api_key
redemption.user.login
redemption.count.per_user
redemption.metadata
redemption.reward.pay_with_points.points_used |
| **Product** | product.id
product.price
product.quantity
product.discount_applicable
product.metadata*
product.metadata.aggregated_quantity
product.metadata.aggregated_amount
product.metadata.discount_applicable
product.metadata.match_all |
| **SKU** | sku.id
sku.price
sku.quantity
sku.discount_applicable |
| **Publication** | publication.redeemable_by_linked_customer |
| **Custom Event** | custom_event.metadata* |
| **Order items** | order.items.every
order.items.any
order.items.none
order.items.cheapest
order.items.most_expensive | order.items.quantity
order.items.aggregated_quantity
order.items.price
order.items.aggregated_amount
order.items.metadata* |
*Requires the `property` field to be defined.
property:
type: string
nullable: true
description: >-
Custom name for a metadata property associated with the condition
to be satisfied. **Required** if the property `name` is any of the
following:
customer_metadata
custom_event_metadata
order_items_metadata
order_metadata
product_metadata
redemption_metadata
conditions:
$ref: '#/components/schemas/ValidationRuleConditions'
rules:
$ref: '#/components/schemas/ValidationRuleRules02'
error:
type: object
description: >-
Contains the error message returned from API when validation /
redemption fails to meet requirements of defined rule.
properties:
message:
type: string
description: >-
The error message returned from API when validation /
redemption fails to meet requirements of defined rule.
ApplicableToEffect:
title: Applicable To Effect
type: string
enum:
- APPLY_TO_EVERY
- APPLY_TO_CHEAPEST
- APPLY_FROM_CHEAPEST
- APPLY_TO_MOST_EXPENSIVE
- APPLY_FROM_MOST_EXPENSIVE
AnyOne:
title: Any
type: array
items:
oneOf:
- title: string
type: string
- title: string - date
type: string
format: date
- title: string - date-time
type: string
format: date-time
- title: number
type: number
- title: object
type: object
maxItems: 1
Any:
title: Any
type: array
items:
oneOf:
- title: string
type: string
- title: string - date
type: string
format: date
- title: string - date-time
type: string
format: date-time
- title: number
type: number
- title: object
type: object
AnyString:
title: Any String
type: array
items:
type: string
AnyNumber:
title: Any Number
type: array
items:
type: number
minimum: 0
maxItems: 1
AnyDateDateTime:
title: Any Date and Date-Time
type: array
items:
oneOf:
- type: string
title: Date
format: date
- type: string
title: Date-time
format: date-time
maxItems: 1
ValidationRuleRules02:
title: Validation Rule Rules
type: object
description: >-
Contains all the rule definitions for the validation rule. It is a set
of key value pairs representing the rules and logic between the rules.
The keys are numbered consecutively beginning from `1`. The values are
objects containing the rule conditions.
properties:
logic:
type: string
example: (1 and 2) and (3)
description: Defines the logic between the rules.
additionalProperties:
type: object
description: Contains the name of the validation rule.
properties:
name:
type: string
description: >-
Voucherify's specific rule name. Read [Validation rule
reference](/optimize/validation-rules-reference) to learn how
specific rules work. The list of available names is provided
below.
|**Type**|**Name** |
---- | -----------|
|**Customer** | customer.segment
customer.metadata* |
|**Order** |order.amount
order.total_amount
order.initial_amount
order.items.count
order.items.price_any
order.items.price_each
order.items.metadata_any
order.items.metadata_each
order.metadata* |
| **Campaign** | campaign.orders.amount_discounted
campaign.orders.amount
campaign.redemptions.count
campaign.redemptions.count.daily
campaign.redemptions.count.weekly
campaign.redemptions.count.monthly
campaign.redemptions.customers_count
campaign.redemptions.customers_count.daily
campaign.redemptions.customers_count.weekly
campaign.redemptions.customers_count.monthly |
| **Redemption** |redemption.gift.amount
redemption.count.daily
redemption.count.weekly
redemption.count.monthly
redemption.count.per_customer
redemption.count.per_customer.daily
redemption.count.per_customer.weekly
redemption.count.per_customer.monthly
redemption.api_key
redemption.count.per_api_key
redemption.user.login
redemption.count.per_user
redemption.metadata
redemption.reward.pay_with_points.points_used |
| **Product** | product.id
product.price
product.quantity
product.discount_applicable
product.metadata*
product.metadata.aggregated_quantity
product.metadata.aggregated_amount
product.metadata.discount_applicable
product.metadata.match_all |
| **SKU** | sku.id
sku.price
sku.quantity
sku.discount_applicable |
| **Publication** | publication.redeemable_by_linked_customer |
| **Custom Event** | custom_event.metadata* |
| **Order items** | order.items.every
order.items.any
order.items.none
order.items.cheapest
order.items.most_expensive | order.items.quantity
order.items.aggregated_quantity
order.items.price
order.items.aggregated_amount
order.items.metadata* |
*Requires the `property` field to be defined.
property:
type: string
nullable: true
description: >-
Custom name for a metadata property associated with the condition
to be satisfied. **Required** if the property `name` is any of the
following:
customer_metadata
custom_event_metadata
order_items_metadata
order_metadata
product_metadata
redemption_metadata
conditions:
$ref: '#/components/schemas/ValidationRuleConditions'
rules:
$ref: '#/components/schemas/ValidationRuleRules03'
error:
type: object
description: >-
Contains the error message returned from API when validation /
redemption fails to meet requirements of defined rule.
properties:
message:
type: string
description: >-
The error message returned from API when validation /
redemption fails to meet requirements of defined rule.
ValidationRuleRules03:
title: Validation Rule Rules
type: object
description: >-
Contains all the rule definitions for the validation rule. It is a set
of key value pairs representing the rules and logic between the rules.
The keys are numbered consecutively beginning from `1`. The values are
objects containing the rule conditions.
properties:
logic:
type: string
example: (1 and 2) and (3)
description: Defines the logic between the rules.
additionalProperties:
type: object
description: Contains the name of the validation rule.
properties:
name:
type: string
description: >-
Voucherify's specific rule name. Read [Validation rule
reference](/optimize/validation-rules-reference) to learn how
specific rules work. The list of available names is provided
below.
|**Type**|**Name** |
---- | -----------|
|**Customer** | customer.segment
customer.metadata* |
|**Order** |order.amount
order.total_amount
order.initial_amount
order.items.count
order.items.price_any
order.items.price_each
order.items.metadata_any
order.items.metadata_each
order.metadata* |
| **Campaign** | campaign.orders.amount_discounted
campaign.orders.amount
campaign.redemptions.count
campaign.redemptions.count.daily
campaign.redemptions.count.weekly
campaign.redemptions.count.monthly
campaign.redemptions.customers_count
campaign.redemptions.customers_count.daily
campaign.redemptions.customers_count.weekly
campaign.redemptions.customers_count.monthly |
| **Redemption** |redemption.gift.amount
redemption.count.daily
redemption.count.weekly
redemption.count.monthly
redemption.count.per_customer
redemption.count.per_customer.daily
redemption.count.per_customer.weekly
redemption.count.per_customer.monthly
redemption.api_key
redemption.count.per_api_key
redemption.user.login
redemption.count.per_user
redemption.metadata
redemption.reward.pay_with_points.points_used |
| **Product** | product.id
product.price
product.quantity
product.discount_applicable
product.metadata*
product.metadata.aggregated_quantity
product.metadata.aggregated_amount
product.metadata.discount_applicable
product.metadata.match_all |
| **SKU** | sku.id
sku.price
sku.quantity
sku.discount_applicable |
| **Publication** | publication.redeemable_by_linked_customer |
| **Custom Event** | custom_event.metadata* |
| **Order items** | order.items.every
order.items.any
order.items.none
order.items.cheapest
order.items.most_expensive | order.items.quantity
order.items.aggregated_quantity
order.items.price
order.items.aggregated_amount
order.items.metadata* |
*Requires the `property` field to be defined.
property:
type: string
nullable: true
description: >-
Custom name for a metadata property associated with the condition
to be satisfied. **Required** if the property `name` is any of the
following:
customer_metadata
custom_event_metadata
order_items_metadata
order_metadata
product_metadata
redemption_metadata
conditions:
$ref: '#/components/schemas/ValidationRuleConditions'
rules:
type: object
description: >-
Another set of validation rules. If you need to create complex
rules with more nested rules, use the validation rule builder in
the dashboard.
error:
type: object
description: >-
Contains the error message returned from API when validation /
redemption fails to meet requirements of defined rule.
properties:
message:
type: string
description: >-
The error message returned from API when validation /
redemption fails to meet requirements of defined rule.
securitySchemes:
X-App-Id:
type: apiKey
name: X-App-Id
in: header
X-App-Token:
type: apiKey
name: X-App-Token
in: header
X-Voucherify-OAuth:
type: oauth2
flows:
implicit:
authorizationUrl: https://api.voucherify.io/v1/oauth/token
scopes:
api: Gives access to whole server-side API.
vouchers: >-
Gives access to all endpoints and methods starting with
`v1/vouchers`.
client_api: Gives access to whole client-side API.
client_vouchers: >-
Gives access to all endpoints and methods starting with
`/client/v1/vouchers`.
promotions: >-
Gives access to all endpoints and methods starting with
`/v1/promotions`.
client_promotions: >-
Gives access to all endpoints and methods starting with
`/client/v1/promotions`
campaigns: >-
Gives access to all endpoints and methods starting with
`v1/campaigns`.
client_publish: >-
Gives access to all endpoints and methods starting with
`/client/v1/publish`.
exports: >-
Gives access to all endpoints and methods starting with
`/v1/exports`.
publications: >-
Gives access to all endpoints and methods starting with
`/v1/publications`.
client_validate: >-
Gives access to all endpoints and methods starting with
`/client/v1/validate`.
validations: >-
Gives access to all endpoints and methods starting with
`/v1/validations`.
client_validations: >-
Gives access to all endpoints and methods starting with
`/client/v1/validations`.
qualifications: >-
Gives access to all endpoints and methods starting with
`/v1/qualifications`.
client_qualifications: >-
Gives access to all endpoints and methods starting with
`/client/v1/qualifications`.
client_redeem: >-
Gives access to all endpoints and methods starting with
`/client/v1/redeem
redemptions: >-
Gives access to all endpoints and methods starting with
`/v1/redemptions`.
client_redemptions: >-
Gives access to all endpoints and methods starting with
`/client/v1/redemptions`
customers: >-
Gives access to all endpoints and methods starting with
`/v1/customers`.
client_customers: >-
Gives access to all endpoints and methods starting with
`/client/v1/customers`.
orders: >-
Gives access to all endpoints and methods starting with
`/v1/orders`.
products: >-
Gives access to all endpoints and methods starting with
`/v1/products`.
skus: >-
Gives access to all endpoints and methods starting with
`/v1/SKUs`.
validation-rules: >-
Gives access to all endpoints and methods starting with
`/v1/validation-rules`.
validation-rules-assignments: >-
Gives access to all endpoints and methods starting with
`/v1/validation-rules-assignments
segments: >-
Gives access to all endpoints and methods starting with
`/v1/segments`.
events: >-
Gives access to all endpoints and methods starting with
`/v1/events`.
client_events: >-
Gives access to all endpoints and methods starting with
`client/v1/events`.
rewards: >-
Gives access to all endpoints and methods starting with
`/v1/rewards`.
assets: >-
Gives access to all endpoints and methods starting with
`/v1/assets`.
task-results: >-
Gives access to all endpoints and methods starting with
`/v1/task-results`.
loyalties: >-
Gives access to all endpoints and methods starting with
`/v1/loyalties`.
client_consents: >-
Gives access to all endpoints and methods starting with
`client/v1/consents`.
consents: >-
Gives access to all endpoints and methods starting with
`/v1/consents`.
async-actions: >-
Gives access to all endpoints and methods starting with
`/v1/async-actions`.
product-collections: >-
Gives access to all endpoints and methods starting with
`/v1/product-collections`.
categories: >-
Gives access to all endpoints and methods starting with
`/v1/categories`.
metadata-schemas: >-
Gives access to all endpoints and methods starting with
`/v1/metadata-schemas`.
locations: >-
Gives access to all endpoints and methods starting with
`/v1/locations`.
referrals: >-
Gives access to all endpoints and methods starting with
`/v1/referrals`.
trash-bin: >-
Gives access to all endpoints and methods starting with
`/v1/trash-bin`.
templates: >-
Gives access to all endpoints and methods starting with
`/v1/templates`.
````