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.

A successful call records vl.earning_rule.created.

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. On create, omit the field or set it to null to store no error. On update, omit the field or set it to null to keep the stored error. The response omits error when none is stored.

Show child attributes

start_date

string<date-time> | null

Sets the date-time from which the rule is active. A calendar date (YYYY-MM-DD) is accepted and stored as midnight UTC. Set to null to clear the start. start_date must be earlier than end_date. On update, an omitted date keeps the stored value and is included in that comparison.

end_date

string<date-time> | null

Sets the date-time until which the rule is active. A calendar date (YYYY-MM-DD) is accepted and stored as midnight UTC. Set to null to clear the end. On update, an omitted date keeps the stored value.

metadata

object | null

Arbitrary key-value metadata. The response always returns an object. On create, omit the field or set it to null to store {}. On update, omit the field to keep stored keys, set null to clear them, or send an object to merge those keys into the stored 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