Earning Rule
All of:
- EarningRuleBase
| Attributes | Description |
|---|
validation_rule_id
string,
null | A unique validation rule identifier assigned by the Voucherify API. The validation rule is verified before points are added to the balance. |
updated_at
string,
null | Timestamp representing the date and time when the earning rule was last updated in ISO 8601 format. |
active
boolean | A flag to toggle the earning rule on or off. You can disable an earning rule even though it’s within the active period defined by the start_date and expiration_date of the campaign or the earning rule’s own start_date and expiration_date. true
indicates an active earning rulefalse
indicates an inactive earning rule
|
EarningRuleBase
| Attributes | Description |
|---|
id
string | Assigned by the Voucherify API, identifies the earning rule object. |
created_at
string | Timestamp representing the date and time when the earning rule was created. The value is shown in the ISO 8601 format. |
loyalty | One of:- Define fixed amount of points
- Calculate points proportionally
|
event | Defines the event which triggers the earning rule to add points to a loyalty card. Earning Rule Event |
custom_event
object | Contains details about the custom event. | Attributes | Description |
|---|
schema_id
string | Unique identifier of the custom event schema |
|
segment
object | Contains the ID of a customer segment. Required for the
customer.segment.entered
option in the event. | Attributes | Description |
|---|
id
string | Contains a unique identifier of a customer segment. Assigned by the Voucherify API. |
|
loyalty_tier
object | Defines the tier associated with the earning rule definition. | Attributes | Description |
|---|
id
string | Unique loyalty tier ID associated with the earning rule. ANY
: any loyalty tier within the campaign
Example:
ltr_pudTGWasuIqxdiDM0go31OV1 |
|
pending_points
object | Defines the configuration for pending points. Pending points can be used only with the
order.paid
event. | Attributes | Description |
|---|
period_type
string | Defines the type of the period during which the points are in the pending state. Currently, only
DAY
value is accepted. Available values:
DAY | period_value
integer | Defines for how long the points are in the pending state. The minimum value is 1, maximum is 90. |
|
source
object | Contains the custom earning rule name and parent campaign. | Attributes | Description |
|---|
banner
string | Name of the earning rule. This is displayed as a header for the earning rule in the Dashboard. | object_id
string | A unique campaign identifier assigned by the Voucherify API. | object_type
string | Defines the object associated with the earning rule. Defaults to
campaign. Available values:
campaign |
|
object
string | The type of the object represented by JSON. Default is earning_rule. Available values:
earning_rule |
automation_id
string | For internal use by Voucherify. |
start_date
string | Start date defines when the earning rule starts to be active. Activation timestamp is presented in the ISO 8601 format. The earning rule is inactive before this date. If you do not define the start date for an earning rule, it will inherit the campaign start date by default. |
expiration_date
string | Expiration date defines when the earning rule expires. Expiration timestamp is presented in the ISO 8601 format. The earning rule is inactive after this date. If you do not define the expiration date for an earning rule, it will inherit the campaign expiration date by default. |
validity_timeframe | See:
Validity Timeframe |
validity_day_of_week | See:
Validity Day Of Week |
validity_hours | See:
Validity Hours |
metadata
object | The metadata object stores all custom attributes assigned to the earning rule. A set of key/value pairs that you can attach to an earning rule object. It can be useful for storing additional information about the earning rule in a structured format. |
expiration_rules | See:
Earning Rule Expiration Rules |
Define fixed amount of points
| Attributes | Description |
|---|
type
string | The number of points to be added to the loyalty card. Available values:
FIXED |
points
integer | Defines how the points will be added to the loyalty card. FIXED adds a fixed number of points. |
points_formula
string | Formula used to dynamically calculate the rewarded points. |
Calculate points proportionally
One of:
- Define amount of points proportional to the order
- Define amount of points proportional to order items
- Define amount of points proportional to customer metadata
- Earning Rule Proportional Custom Event
Earning Rule Event
Validity Timeframe
| Attributes | Description |
|---|
duration
string | Defines the amount of time an earning rule will be active in ISO 8601 format. For example, an earning rule with a
duration
of
PT1H
will be valid for a duration of one hour. Example:
PT1H |
interval
string | Defines the intervening time between two time points in ISO 8601 format, expressed as a duration. For example, an earning rule with an
interval
of
P2D
will be valid every other day. Example:
P2D |
Validity Day Of Week
Integer array corresponding to the particular days of the week in which the voucher is valid.
0
Sunday1
Monday2
Tuesday3
Wednesday4
Thursday5
Friday6
Saturday
Validity Hours
| Attributes | Description |
|---|
daily
array | Defines the reccuring period(s) when the resource is active. The periods should not overlap.
Array of:| Attributes | Description |
|---|
start_time
string | Defines the starting hour of validity in the HH:mm format. The resource is
inactive before
this time. Example:
12:00 | days_of_week
array | Integer array corresponding to the particular days of the week in which the resource is valid. 0
Sunday1
Monday2
Tuesday3
Wednesday4
Thursday5
Friday6
Saturday
| expiration_time
string | Defines the ending hour of validity in the HH:mm format. The resource is
inactive after
this time. Example:
14:00 |
|
Earning Rule Expiration Rules
| Attributes | Description |
|---|
period_type
string | Type of period. Can be set for
MONTH
or
FIXED_DAY_OF_YEAR.
MONTH
requires the
period_value
field.
FIXED_DAY_OF_YEAR
requires the
fixed_month
and
fixed_day
fields. Available values:
FIXED_DAY_OF_YEAR,
MONTH |
period_value
integer | Value of the period. Required for the
period_type: MONTH. |
rounding_type
string | Type of rounding of the expiration period. Optional for the
period_type: MONTH. Available values:
END_OF_MONTH,
END_OF_QUARTER,
END_OF_HALF_YEAR,
END_OF_YEAR,
PARTICULAR_MONTH |
rounding_value
integer | Value of rounding of the expiration period. Required for the
rounding_type. |
fixed_month
integer | Determines the month when the points expire;
1
is January,
2
is February, and so on. Required for the
period_type: FIXED_DAY_OF_YEAR. |
fixed_day
integer | Determines the day of the month when the points expire. Required for the
period_type: FIXED_DAY_OF_YEAR. |
Define amount of points proportional to the order
One of:
- Order Amount
- Order Total Amount
- Order Metadata
Define amount of points proportional to order items
One of:
- Order Items Quantity
- Order Items Amount
- Order Items Subtotal Amount
| Attributes | Description |
|---|
type
string | Defines how the points will be added to the loyalty card.PROPORTIONAL adds points based on a pre-defined ratio. Available values:
PROPORTIONAL |
calculation_type
string | CUSTOMER_METADATA: Customer Metadata (X points for every Y in metadata attribute, defined in the property key under the customer.metadata object) Available values:
CUSTOMER_METADATA |
customer
object | | Attributes | Description |
|---|
metadata
object | Defines the ratio based on the property defined in the calculation_type parameter. For every given increment of value (1, 10, etc) defined in the every parameter for the property defined in calculation_type, give the customer the number of points defined in the points parameter. In other words, for every order metadata property value, give points. | Attributes | Description |
|---|
every
integer | For how many increments of the customer metadata property to grant points for. | points
integer | Number of points to be awarded, i.e. how many points to be added to the loyalty card. | points_formula
string | Formula used to dynamically calculate the rewarded points. | property
string | Customer metadata property. |
|
|
Earning Rule Proportional Custom Event
| Attributes | Description |
|---|
type
string | Defines how the points will be added to the loyalty card.PROPORTIONAL adds points based on a pre-defined ratio. Available values:
PROPORTIONAL |
calculation_type
string | CUSTOM_EVENT_METADATA: Custom event metadata (X points for every Y in metadata attribute). Available values:
CUSTOM_EVENT_METADATA |
custom_event
object | | Attributes | Description |
|---|
metadata
object | Defines the ratio based on the property defined in the calculation_type parameter. For every given increment of value (1, 10, etc) defined in the every parameter for the property defined in calculation_type, give the customer the number of points defined in the points parameter. In other words, for every order metadata property value, give points. | Attributes | Description |
|---|
every
integer | For how many increments of the customer metadata property to grant points for. | points
integer | Number of points to be awarded, i.e. how many points to be added to the loyalty card. | points_formula
string | Formula used to dynamically calculate the rewarded points. | property
string | Custom event metadata property. |
|
|
Order Amount
| Attributes | Description |
|---|
type
string | Defines how the points will be added to the loyalty card.PROPORTIONAL adds points based on a pre-defined ratio. Available values:
PROPORTIONAL |
calculation_type
string | ORDER_AMOUNT
: Pre-discount order amount (X points for every Y spent excluding discounts)
Available values:
ORDER_AMOUNT |
order
object | | Attributes | Description |
|---|
amount
object | Defines the ratio based on the property defined in the calculation_type parameter. For every set of value (1, 10, etc) defined in the every parameter for the property defined in calculation_type, give the customer the number of points defined in the points parameter. In other words, for every calculation_type, give points. | Attributes | Description |
|---|
every
integer | Value is multiplied by 100 to precisely represent 2 decimal places. For example, a $10 order amount is written as 1000. | points
integer | Number of points to be awarded, i.e. how many points to be added to the loyalty card. | points_formula
string | Formula used to dynamically calculate the rewarded points. |
|
|
Order Total Amount
| Attributes | Description |
|---|
type
string | Defines how the points will be added to the loyalty card.PROPORTIONAL adds points based on a pre-defined ratio. Available values:
PROPORTIONAL |
calculation_type
string | ORDER_TOTAL_AMOUNT
: Total order amount (X points for every Y spent including discount)
Available values:
ORDER_TOTAL_AMOUNT |
order
object | | Attributes | Description |
|---|
total_amount
object | Defines the ratio based on the property defined in the calculation_type parameter. For every set of value (1, 10, etc) defined in the every parameter for the property defined in calculation_type, give the customer the number of points defined in the points parameter. In other words, for every calculation_type, give points. | Attributes | Description |
|---|
every
integer | Value is multiplied by 100 to precisely represent 2 decimal places. For example, a $10 order amount is written as 1000. | points
integer | Number of points to be awarded, i.e. how many points to be added to the loyalty card. | points_formula
string | Formula used to dynamically calculate the rewarded points. |
|
|
| Attributes | Description |
|---|
type
string | Defines how the points will be added to the loyalty card.PROPORTIONAL adds points based on a pre-defined ratio. Available values:
PROPORTIONAL |
calculation_type
string | ORDER_METADATA
: Order Metadata (X points for every Y in metadata attribute, defined in the property key under the order.metadata object)
Available values:
ORDER_METADATA |
order
object | Defines the formula for calculating points proportionally. | Attributes | Description |
|---|
metadata
object | Defines the ratio based on the property defined in the calculation_type parameter. For every given increment of value (1, 10, etc) defined in the every parameter for the property defined in calculation_type, give the customer the number of points defined in the points parameter. In other words, for every order metadata property value, give points. | Attributes | Description |
|---|
every
integer | For how many increments of the order metadata property to grant points for. | points
integer | Number of points to be awarded, i.e. how many points to be added to the loyalty card. | points_formula
string | Formula used to dynamically calculate the rewarded points. | property
string | Order metadata property. |
|
|
Order Items Quantity
| Attributes | Description |
|---|
type
string | Defines how the points will be added to the loyalty card.PROPORTIONAL adds points based on a pre-defined ratio. Available values:
PROPORTIONAL |
calculation_type
string | ORDER_ITEMS_QUANTITY
: Quantity of items defined in the
order_items.quantity.applicable_to
array or
order_items.quantity.object
&
.id
(X points for every Y items excluding free items).
Available values:
ORDER_ITEMS_QUANTITY |
order_items
object | | Attributes | Description |
|---|
quantity
object | Defines the ratio based on the property defined in the calculation_type parameter. For every set of value (1, 10, etc) defined in the every parameter for the property defined in calculation_type, give the customer the number of points defined in the points parameter. In other words, for every calculation_type, give points. | Attributes | Description |
|---|
every
integer | Value is multiplied by 100 to precisely represent 2 decimal places. For example, a $10 order amount is written as 1000. | points
integer | Number of points to be awarded, i.e. how many points to be added to the loyalty card. | points_formula
string | Formula used to dynamically calculate the rewarded points. | object
string | Type of object which will be covered by the earning rule. This is required together with
id.
Can be replaced by the
applicable_to
array. In response, the value of the first object is returned even if
applicable_to
array was used. Available values:
products_collection,
product,
sku | id
string | Unique ID of the resource assigned by Voucherify. This is required together with
object.
Can be replaced by the
applicable_to
array. In response, the value of the first object is returned even if
applicable_to
array was used. Values are, for example,
pc_75U0dHlr7u75BJodrW1AE3t6
for product collection,
prod_0bae32322150fd0546
for a product, or
sku_0b7d7dfb090be5c619
for a SKU. | applicable_to
array | Defines products, SKUs, or product collections covered by the earning rule. Can be replaced by
object
and
id
to define only one object. Array of:| Attributes | Description |
|---|
object
string | Type of object which will be covered by the earning rule. Available values:
products_collection,
product,
sku | id
string | Unique ID of the resource assigned by Voucherify. Values are, for example,
pc_75U0dHlr7u75BJodrW1AE3t6
for product collection,
prod_0bae32322150fd0546
for a product, or
sku_0b7d7dfb090be5c619
for a SKU. |
|
|
|
Order Items Amount
| Attributes | Description |
|---|
type
string | Defines how the points will be added to the loyalty card.PROPORTIONAL adds points based on a pre-defined ratio. Available values:
PROPORTIONAL |
calculation_type
string | ORDER_ITEMS_AMOUNT; Pre-discount amount spent on items defined in the
order_items.quantity.applicable_to
array or
order_items.quantity.object
&
.id
(X points for every Y spent on items excluding discounts) Available values:
ORDER_ITEMS_AMOUNT |
order_items
object | | Attributes | Description |
|---|
amount
object | Defines the ratio based on the property defined in the calculation_type parameter. For every set of value (1, 10, etc) defined in the every parameter for the property defined in calculation_type, give the customer the number of points defined in the points parameter. In other words, for every calculation_type, give points. | Attributes | Description |
|---|
every
integer | Value is multiplied by 100 to precisely represent 2 decimal places. For example, a $10 order amount is written as 1000. | points
integer | Number of points to be awarded, i.e. how many points to be added to the loyalty card. | points_formula
string | Formula used to dynamically calculate the rewarded points. | object
string | Type of object which will be covered by the earning rule. This is required together with
id.
Can be replaced by the
applicable_to
array. In response, the value of the first object is returned even if
applicable_to
array was used. Available values:
products_collection,
product,
sku | id
string | Unique ID of the resource assigned by Voucherify. This is required together with
object.
Can be replaced by the
applicable_to
array. In response, the value of the first object is returned even if
applicable_to
array was used. Values are, for example,
pc_75U0dHlr7u75BJodrW1AE3t6
for product collection,
prod_0bae32322150fd0546
for a product, or
sku_0b7d7dfb090be5c619
for a SKU. | applicable_to
array | Defines products, SKUs, or product collections covered by the earning rule. Can be replaced by
object
and
id
to define only one object. Array of:| Attributes | Description |
|---|
object
string | Type of object which will be covered by the earning rule. Available values:
products_collection,
product,
sku | id
string | Unique ID of the resource assigned by Voucherify. Values are, for example,
pc_75U0dHlr7u75BJodrW1AE3t6
for product collection,
prod_0bae32322150fd0546
for a product, or
sku_0b7d7dfb090be5c619
for a SKU. |
|
|
|
Order Items Subtotal Amount
| Attributes | Description |
|---|
type
string | Defines how the points will be added to the loyalty card.PROPORTIONAL adds points based on a pre-defined ratio. Available values:
PROPORTIONAL |
calculation_type
string | ORDER_ITEMS_SUBTOTAL_AMOUNT; Amount spent on items defined in the order_items.subtotal_amount.object & .id (X points for every Y spent on items including discounts) Available values:
ORDER_ITEMS_SUBTOTAL_AMOUNT |
order_items
object | | Attributes | Description |
|---|
subtotal_amount
object | Defines the ratio based on the property defined in the calculation_type parameter. For every set of value (1, 10, etc) defined in the every parameter for the property defined in calculation_type, give the customer the number of points defined in the points parameter. In other words, for every calculation_type, give points. | Attributes | Description |
|---|
every
integer | Value is multiplied by 100 to precisely represent 2 decimal places. For example, a $10 order amount is written as 1000. | points
integer | Number of points to be awarded, i.e. how many points to be added to the loyalty card. | points_formula
string | Formula used to dynamically calculate the rewarded points. | object
string | Type of object which will be covered by the earning rule. This is required together with
id.
Can be replaced by the
applicable_to
array. In response, the value of the first object is returned even if
applicable_to
array was used. Available values:
products_collection,
product,
sku | id
string | Unique ID of the resource assigned by Voucherify. This is required together with
object.
Can be replaced by the
applicable_to
array. In response, the value of the first object is returned even if
applicable_to
array was used. Values are, for example,
pc_75U0dHlr7u75BJodrW1AE3t6
for product collection,
prod_0bae32322150fd0546
for a product, or
sku_0b7d7dfb090be5c619
for a SKU. | applicable_to
array | Defines products, SKUs, or product collections covered by the earning rule. Can be replaced by
object
and
id
to define only one object. Array of:| Attributes | Description |
|---|
object
string | Type of object which will be covered by the earning rule. Available values:
products_collection,
product,
sku | id
string | Unique ID of the resource assigned by Voucherify. Values are, for example,
pc_75U0dHlr7u75BJodrW1AE3t6
for product collection,
prod_0bae32322150fd0546
for a product, or
sku_0b7d7dfb090be5c619
for a SKU. |
|
|
|
