The earning rule object

This entity describes an earning rule object.

Attribute

Description

Example

id string

Assigned by the Voucherify API, identifies the earning rule object.

ern_P6MWOFGsv63sbTaTZBp0IHGK

created_at string, ISO 8601 date format

Timestamp representing the date and time when the earning rule was created in ISO 8601 format.

2016-11-16T14:14:31Z

updated_at string, ISO 8601 date format

Timestamp representing the date and time when the earning rule was created in ISO 8601 format.

2016-12-17T14:14:31Z

object string

A type of the object represented by JSON. The value is earning_rule.

validation_rule_id string

A unique validation rule identifier that is verified before points are added to balance

val_6o0qdvlbh1mt

loyalty

An object that defines the number of points that will be added to a loyalty card and how the points will be added.

  • FIXED adds a fixed number of points
  • PROPORTIONAL adds points proportionally based on a pre-defined ratio

There are pre-defined calculations for point accrual on a PROPORTIONAL type. Every loyalty object containing a PROPORTIONAL type contains a parameter calculation_type, which defines the method for calculating the amount of points to be awarded for the earning rule.

  • ORDER_ITEMS_SUBTOTAL_AMOUNT: Amount spent on items (X points for every Y $ spent on items including discounts)
  • ORDER_TOTAL_AMOUNT: Total order amount (X points for every Y spent including discount)
  • ORDER_AMOUNT: Pre-discount order amount (X points for every Y spent excluding discounts)
  • ORDER_ITEMS_AMOUNT: Pre-discount amount spent on items (X points for every Y $ spent on items excluding discounts)
  • ORDER_METADATA: Order Metadata (X points for every Y in metadata attribute)
  • CUSTOMER_METADATA: Customer Metadata (X points for every Y in metadata attribute)
  • ORDER_ITEMS_QUANTITY: Quantity of items in the cart (X points for every Y items excluding free items)
"loyalty": {
    "points": 3,
    "type": "FIXED"
}
"loyalty": {
    "type": "PROPORTIONAL",
    "calculation_type": "CUSTOMER_METADATA",
    "customer": {
      "metadata": {
        "every": 100,
        "points": 1,
        "property": "customer_life_time_value"
      }
    }
  }

See below table for examples to calculate points proportionally.

event string

It can be one of these options:

  • order.paid event
  • customer.segment.entered event
  • custom event name

order.paid

custom_event object

Required for the custom event option. Contains the ID of a custom event schema.

{
  "schema_id": "ms_fi47Dcu5T0m3v3nT5ch3ma"
}

segment object

Required for the customer.segment.entered option

{
   "id": "seg_f1r5Ts3gM3N7"
}

source object

Contains the configuration for a campaign this earning rule belongs to.

{
    "banner": "Yopu will get 3 points",
    "object_id": "camp_Zgj5HFIPcb70SWJ4IjBNta2F",
    "object_type": "campaign"
}

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

"active": true

start_date string

Activation timestamp in ISO 8601 format. Earning rule is inactive before this date. If you don't define the start date for an earning rule, it'll inherit the campaign start date by default.

"start_date": "2022-02-02T13:00:00.000Z"

expiration_date string

Expiration timestamp in ISO 8601 format. Earning rule is inactive after this date.If you don't define the expiration date for an earning rule, it'll inherit the campaign expiration date by default.

"expiration_date": "2022-03-03T14:30:00.000Z"

validity_timeframe object

Set recurrent time periods when the earning rule is valid. For example, valid for 1 hour every other day.

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

"validity_timeframe": {
"duration": "PT1H",
"interval": "P1D"
}

validity_day_of_week array of integers

Integer array corresponding to the particular days of the week in which the earning rule is valid.

  • 0 Sunday
  • 1 Monday
  • 2 Tuesday
  • 3 Wednesday
  • 4 Thursday
  • 5 Friday
  • 6 Saturday

"validity_day_of_week": [
4
],

automation_id string

{
    "id": "ern_P6MWOFGsv63sbTaTZBp0IHGK",
    "created_at": "2022-02-02T13:18:32.557Z",
    "updated_at": "2022-02-03T13:09:27.206Z",
    "validation_rule_id": "val_6o0qdvlbh1mt",
    "loyalty": {
        "points": 1000,
        "type": "FIXED"
    },
    "event": "order.paid",
    "source": {
        "banner": "Order paid 1000 points",
        "object_id": "camp_Pfja7X91b1GoyH5wnpzCwlP3",
        "object_type": "campaign"
    },
    "active": true,
    "start_date": "2022-02-02T13:00:00.000Z",
    "expiration_date": "2022-03-03T14:30:00.000Z",
    "validity_timeframe": {
        "duration": "PT1H",
        "interval": "P1D"
    },
    "object": "earning_rule",
    "automation_id": "auto_RVgObANuPToNla8LuD5aT3Zb"
}