Create earning rule

curl --request POST \
  --url https://{cluster}.voucherify.io/v2/loyalties/earning-rules \
  --header 'Content-Type: application/json' \
  --header 'X-App-Id: <api-key>' \
  --header 'X-App-Token: <api-key>' \
  --data '
{
  "name": "Order paid VIP and non-VIP segments",
  "trigger": {
    "event": "customer.order.paid"
  },
  "trigger_limits": {
    "cooldown": {
      "type": "NO_COOLDOWN"
    },
    "frequency": {
      "type": "NO_LIMIT"
    }
  },
  "earning_limits": {
    "global": {
      "type": "NO_LIMIT",
      "limits": []
    }
  },
  "earnings": [
    {
      "name": "Earning for VIPs",
      "effects": [
        {
          "type": "POINTS",
          "points": {
            "value": 300,
            "card_definition_id": "lcdef_1329efb2af8ba6486f"
          }
        }
      ],
      "rules": {
        "1": {
          "conditions": {
            "$is": [
              "seg_HFJezEkKnc0iHK50NWl6c6da"
            ]
          },
          "name": "customer.segment"
        },
        "logic": " 1"
      },
      "tier_rules": {
        "type": "NO_REQUIREMENTS"
      }
    },
    {
      "name": "Earning for non-VIPs",
      "effects": [
        {
          "type": "POINTS",
          "points": {
            "value": 150,
            "card_definition_id": "lcdef_1329efb2af8ba6486f"
          }
        }
      ],
      "tier_rules": {
        "type": "NO_REQUIREMENTS"
      }
    }
  ],
  "metadata": {},
  "validity_hours": {
    "type": "ANY_TIME"
  },
  "start_date": null,
  "end_date": null,
  "status": "DRAFT"
}
'

{
  "id": "lern_133a93007e0a5d2c4d",
  "name": "Earning rule 2026-10-22-04",
  "status": "DRAFT",
  "earnings": [
    {
      "id": "lernei_133a93007cca5d2c4c",
      "tier_rules": {
        "type": "NO_REQUIREMENTS"
      },
      "effects": [
        {
          "type": "POINTS",
          "points": {
            "value": 150,
            "card_definition_id": "lcdef_1329efb2af8ba6486f"
          }
        }
      ]
    }
  ],
  "trigger": {
    "event": "customer.order.paid"
  },
  "error": {
    "message": "You don't know what's right!"
  },
  "validity_hours": {
    "type": "DAILY",
    "daily": [
      {
        "days_of_week": [
          0,
          5,
          6
        ],
        "start_time": "15:00",
        "end_time": "17:30"
      }
    ]
  },
  "start_date": null,
  "end_date": null,
  "trigger_limits": {
    "cooldown": {
      "type": "FIXED_COOLDOWN",
      "fixed_cooldown": {
        "period": {
          "value": 1,
          "unit": "HOUR"
        }
      }
    },
    "frequency": {
      "type": "LIMITED",
      "limits": [
        {
          "type": "TIME_BASED",
          "period": {
            "type": "CURRENT_PERIOD",
            "current_period": {
              "unit": "WEEK"
            }
          },
          "triggers": {
            "max": 2
          }
        }
      ]
    }
  },
  "earning_limits": {
    "global": {
      "type": "NO_LIMIT",
      "limits": []
    }
  },
  "metadata": {},
  "created_at": "2026-10-22T11:26:04.277Z",
  "updated_at": null,
  "object": "earning_rule"
}

Create earning rule

Creates a new earning rule.

When status is omitted the rule is created as DRAFT. Omitted or null validity_hours default to { "type": "ANY_TIME" }, trigger_limits to { "cooldown": { "type": "NO_COOLDOWN" }, "frequency": { "type": "NO_LIMIT" } }, and earning_limits to { "global": { "type": "NO_LIMIT", "limits": [] } }. An ACTIVE rule whose trigger is customer.segment.entered activates a passive segment. Returns 423 when status is ACTIVE and an effect or tier rule points at a non-active benefit, card definition, or tier structure.

POST

loyalties

earning-rules

Create earning rule

curl --request POST \
  --url https://{cluster}.voucherify.io/v2/loyalties/earning-rules \
  --header 'Content-Type: application/json' \
  --header 'X-App-Id: <api-key>' \
  --header 'X-App-Token: <api-key>' \
  --data '
{
  "name": "Order paid VIP and non-VIP segments",
  "trigger": {
    "event": "customer.order.paid"
  },
  "trigger_limits": {
    "cooldown": {
      "type": "NO_COOLDOWN"
    },
    "frequency": {
      "type": "NO_LIMIT"
    }
  },
  "earning_limits": {
    "global": {
      "type": "NO_LIMIT",
      "limits": []
    }
  },
  "earnings": [
    {
      "name": "Earning for VIPs",
      "effects": [
        {
          "type": "POINTS",
          "points": {
            "value": 300,
            "card_definition_id": "lcdef_1329efb2af8ba6486f"
          }
        }
      ],
      "rules": {
        "1": {
          "conditions": {
            "$is": [
              "seg_HFJezEkKnc0iHK50NWl6c6da"
            ]
          },
          "name": "customer.segment"
        },
        "logic": " 1"
      },
      "tier_rules": {
        "type": "NO_REQUIREMENTS"
      }
    },
    {
      "name": "Earning for non-VIPs",
      "effects": [
        {
          "type": "POINTS",
          "points": {
            "value": 150,
            "card_definition_id": "lcdef_1329efb2af8ba6486f"
          }
        }
      ],
      "tier_rules": {
        "type": "NO_REQUIREMENTS"
      }
    }
  ],
  "metadata": {},
  "validity_hours": {
    "type": "ANY_TIME"
  },
  "start_date": null,
  "end_date": null,
  "status": "DRAFT"
}
'

{
  "id": "lern_133a93007e0a5d2c4d",
  "name": "Earning rule 2026-10-22-04",
  "status": "DRAFT",
  "earnings": [
    {
      "id": "lernei_133a93007cca5d2c4c",
      "tier_rules": {
        "type": "NO_REQUIREMENTS"
      },
      "effects": [
        {
          "type": "POINTS",
          "points": {
            "value": 150,
            "card_definition_id": "lcdef_1329efb2af8ba6486f"
          }
        }
      ]
    }
  ],
  "trigger": {
    "event": "customer.order.paid"
  },
  "error": {
    "message": "You don't know what's right!"
  },
  "validity_hours": {
    "type": "DAILY",
    "daily": [
      {
        "days_of_week": [
          0,
          5,
          6
        ],
        "start_time": "15:00",
        "end_time": "17:30"
      }
    ]
  },
  "start_date": null,
  "end_date": null,
  "trigger_limits": {
    "cooldown": {
      "type": "FIXED_COOLDOWN",
      "fixed_cooldown": {
        "period": {
          "value": 1,
          "unit": "HOUR"
        }
      }
    },
    "frequency": {
      "type": "LIMITED",
      "limits": [
        {
          "type": "TIME_BASED",
          "period": {
            "type": "CURRENT_PERIOD",
            "current_period": {
              "unit": "WEEK"
            }
          },
          "triggers": {
            "max": 2
          }
        }
      ]
    }
  },
  "earning_limits": {
    "global": {
      "type": "NO_LIMIT",
      "limits": []
    }
  },
  "metadata": {},
  "created_at": "2026-10-22T11:26:04.277Z",
  "updated_at": null,
  "object": "earning_rule"
}

Authorizations

X-App-Id

string

header

required

X-App-Token

string

header

required

Body

application/json

Request body schema for POST /v2/loyalties/earning-rules.

name

string

required

Earning rule name.

Required string length: 1 - 200

trigger

object

required

Event that triggers the earning rule. Depending on event, either custom_event or segment is required and the other trigger contexts must be null/absent.

Show child attributes

earnings

object[]

required

Defines the earnings evaluated when the trigger fires. Required. At least one item.

Minimum array length: 1

Show child attributes

error

Custom error message configuration · object | null

Default error returned when rule validation fails. Can be null.

Show child attributes

start_date

string<date-time> | null

Date-time from which the rule is active. Can be null. When both start_date and end_date are set, start_date must be earlier than end_date.

end_date

string<date-time> | null

Date-time until which the rule is active. Can be null.

metadata

object | null

Arbitrary key-value metadata. A request may omit this field or set it to null. null is stored as an empty object. The response always returns an object.

status

enum<string>

Initial status. Only DRAFT and ACTIVE are allowed at creation. Defaults to DRAFT.

Available options:

DRAFT,

ACTIVE

validity_hours

object | null

Hours during which the rule is active. Omit the field or set it to null to use { "type": "ANY_TIME" }. The response always returns validity_hours.

Show child attributes

trigger_limits

object | null

Cooldown and frequency limits for the trigger. Omit the field or set it to null to use { "cooldown": { "type": "NO_COOLDOWN" }, "frequency": { "type": "NO_LIMIT" } }. The response always returns trigger_limits.

Show child attributes

earning_limits

object | null

Limits how many points this rule can award. Omit the field or set it to null to use { "global": { "type": "NO_LIMIT", "limits": [] } }. The response always returns earning_limits.

Show child attributes

Response

Earning rule created

Response body schema for POST /v2/loyalties/earning-rules.

string

required

Earning rule ID (lern_...).

Pattern: ^lern_[a-f0-9]+$

name

string

required

Earning rule name.

Maximum string length: 200

status

enum<string>

required

Current status. DELETED also exists internally but deleted rules are excluded from API reads.

Available options:

DRAFT,

ACTIVE,

INACTIVE

earnings

object[]

required

Earning definitions of the rule. Contains at least one earning.

Minimum array length: 1

Show child attributes

trigger

object

required

Event that triggers the earning rule. Depending on event, either custom_event or segment is required and the other trigger contexts must be null/absent.

Show child attributes

validity_hours

object

required

Validity hours. Always present; defaults to { "type": "ANY_TIME" }.

Show child attributes

start_date

string<date-time> | null

required

Date-time from which the rule is active. Can be null.

end_date

string<date-time> | null

required

Date-time until which the rule is active. Can be null.

trigger_limits

object

required

Cooldown and frequency limits. Always present. cooldown and frequency are always objects. frequency.limits is always an array and is empty when frequency.type is NO_LIMIT.

Show child attributes

earning_limits

object

required

Limits how many points this rule can award. Always present. Defaults to no global limit (global.type NO_LIMIT and global.limits []).

Show child attributes

metadata

object

required

Arbitrary key-value metadata. Always present (empty object when unset).

created_at

string<date-time>

required

Creation timestamp (ISO 8601).

updated_at

string<date-time> | null

required

Last update timestamp (ISO 8601). null when never updated.

object

string

required

Object type marker. Always earning_rule.

Allowed value: "earning_rule"

error

Custom error message configuration · object

Default error configuration. Absent when not configured.

Show child attributes

Introduction

Endpoints

Events

Create earning rule

Authorizations

Body

Response