GuidesHelp CenterRelease notesRoadmap
API Reference

Earning Rule Object

Earning Rule

All of:

  1. EarningRuleBase
  2. AttributesDescription
    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 rule
    • false indicates an inactive earning rule

EarningRuleBase

AttributesDescription
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.

loyaltyOne 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.

AttributesDescription
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.

AttributesDescription
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.

AttributesDescription
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.

AttributesDescription
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.

AttributesDescription
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_timeframeSee: Validity Timeframe
validity_day_of_weekSee: Validity Day Of Week
validity_hoursSee: 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_rulesSee: Earning Rule Expiration Rules

Define fixed amount of points

AttributesDescription
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.

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

AttributesDescription
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 Sunday
  • 1 Monday
  • 2 Tuesday
  • 3 Wednesday
  • 4 Thursday
  • 5 Friday
  • 6 Saturday

Validity Hours

AttributesDescription
daily
array

Defines the reccuring period(s) when the resource is active. The periods should not overlap.

Array of:
AttributesDescription
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 Sunday
  • 1 Monday
  • 2 Tuesday
  • 3 Wednesday
  • 4 Thursday
  • 5 Friday
  • 6 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

AttributesDescription
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

Define amount of points proportional to customer metadata

AttributesDescription
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
AttributesDescription
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.

AttributesDescription
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.

property
string

Customer metadata property.

Earning Rule Proportional Custom Event

AttributesDescription
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
AttributesDescription
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.

AttributesDescription
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.

property
string

Custom event metadata property.

Order Amount

AttributesDescription
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
AttributesDescription
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.

AttributesDescription
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.

Order Total Amount

AttributesDescription
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
AttributesDescription
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.

AttributesDescription
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.

Order Metadata

AttributesDescription
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.

AttributesDescription
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.

AttributesDescription
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.

property
string

Order metadata property.

Order Items Quantity

AttributesDescription
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 order_items.quantity.object & .id (X points for every Y items excluding free items)

Available values: ORDER_ITEMS_QUANTITY
order_items
object
AttributesDescription
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.

AttributesDescription
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.

object
string

Type of object taken under consideration.

Available values: products_collection, product, sku
id
string

Unique ID of the resource, i.e. pc_75U0dHlr7u75BJodrW1AE3t6, prod_0bae32322150fd0546, or sku_0b7d7dfb090be5c619.

Order Items Amount

AttributesDescription
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.amount.object & .id (X points for every Y spent on items excluding discounts)

Available values: ORDER_ITEMS_AMOUNT
order_items
object
AttributesDescription
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.

AttributesDescription
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.

object
string

Type of object taken under consideration.

Available values: products_collection, product, sku
id
string

Unique ID of the resource, i.e. pc_75U0dHlr7u75BJodrW1AE3t6, prod_0bae32322150fd0546, or sku_0b7d7dfb090be5c619.

Order Items Subtotal Amount

AttributesDescription
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
AttributesDescription
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.

AttributesDescription
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.

object
string

Type of object taken under consideration.

Available values: products_collection, product, sku
id
string

Unique ID of the resource, i.e. pc_75U0dHlr7u75BJodrW1AE3t6, prod_0bae32322150fd0546, or sku_0b7d7dfb090be5c619.