> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voucherify.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Create earning rule
>
Documentation in progress
This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager.
Creates a new earning rule. When `status` is omitted the rule is created as `DRAFT`.
When `validity_hours` is omitted it defaults to `{ "type": "ANY_TIME" }`.
When `trigger_limits` is omitted it defaults to
`{ "cooldown": { "type": "NO_COOLDOWN" }, "frequency": { "type": "NO_LIMIT" } }`.
## OpenAPI
````yaml /openapi/loyalties-v2.json post /v2/loyalties/earning-rules
openapi: 3.1.0
info:
title: Voucherify API - Loyalty v2
version: v2018-08-01
description: >-
Voucherify promotion engine REST API. Please see
https://docs.voucherify.io/docs for more details.
contact:
name: Voucherify Team
url: https://www.voucherify.io/contact-support
email: support@voucherify.io
termsOfService: https://www.voucherify.io/legal/subscription-agreement
license:
name: MIT
url: https://github.com/voucherifyio/voucherify-js-sdk/blob/main/LICENSE
servers:
- url: https://{cluster}.voucherify.io
description: Base URL
variables:
cluster:
default: api
enum:
- api
- us1.api
- as1.api
- download
- us1.download
- as1.download
security: []
paths:
/v2/loyalties/earning-rules:
post:
tags:
- Earning Rules
summary: Create earning rule
description: >-
Documentation in progress
This documentation is in progress. The parameters, fields, request and
response bodies, and other data may be subject to change. If you need
more information or you want to share feedback, contact [Voucherify
support](https://www.voucherify.io/contact-support) or your Technical
Account Manager.
Creates a new earning rule. When `status` is omitted the rule is created
as `DRAFT`.
When `validity_hours` is omitted it defaults to `{ "type": "ANY_TIME"
}`.
When `trigger_limits` is omitted it defaults to
`{ "cooldown": { "type": "NO_COOLDOWN" }, "frequency": { "type":
"NO_LIMIT" } }`.
operationId: createEarningRule
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/V2LoyaltiesEarningRulesCreateRequestBody'
responses:
'200':
description: Earning rule created
content:
application/json:
schema:
$ref: '#/components/schemas/V2LoyaltiesEarningRulesCreateResponseBody'
'400':
description: >-
Validation error - request body or query parameters failed
validation, or the operation is not allowed in the current resource
state.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Resource not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'409':
description: Conflict - e.g. duplicate resource or invalid state transition.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
Internal server error:
value:
code: 500
key: api_error
message: >-
Something went wrong. Don't worry, your campaigns are
still safe and the Voucherify Team has been notified.
Check out our Help Center and forums for help, or head
back to home.
security:
- X-App-Id: []
X-App-Token: []
- bearerAuth: []
components:
schemas:
V2LoyaltiesEarningRulesCreateRequestBody:
title: V2 Loyalties Earning Rules Create Request Body
type: object
description: Request body schema for **POST** `/v2/loyalties/earning-rules`.
allOf:
- $ref: '#/components/schemas/EarningRuleCreateRequest'
V2LoyaltiesEarningRulesCreateResponseBody:
title: V2 Loyalties Earning Rules Create Response Body
type: object
description: Response body schema for **POST** `/v2/loyalties/earning-rules`.
allOf:
- $ref: '#/components/schemas/EarningRuleResponse'
ErrorResponse:
type: object
description: Standard error response returned by all Loyalty v2 endpoints.
properties:
code:
type: integer
description: HTTP status code of the error.
key:
type: string
description: Machine-readable error key.
message:
type: string
description: Human-readable error message.
details:
type: string
description: Additional details about the error.
request_id:
type: string
description: Unique identifier of the request that produced the error.
resource_id:
type: string
description: Unique identifier of the resource that produced the error.
resource_type:
type: string
description: Type of the resource that produced the error.
EarningRuleCreateRequest:
description: Request body for creating an earning rule.
allOf:
- $ref: '#/components/schemas/EarningRuleRequestBase'
- type: object
properties:
name:
type: string
minLength: 1
maxLength: 200
description: Earning rule name.
trigger:
$ref: '#/components/schemas/EarningRuleTrigger'
earnings:
type: array
minItems: 1
description: >-
Earning definitions (rules and effects) evaluated when the
trigger fires.
items:
$ref: '#/components/schemas/EarningRuleEarningCreate'
status:
type: string
enum:
- DRAFT
- ACTIVE
description: >-
Initial status. Only `DRAFT` and `ACTIVE` are allowed at
creation. Defaults to `DRAFT`.
validity_hours:
description: >-
Hours during which the rule is active. Defaults to `{ "type":
"ANY_TIME" }` when omitted. Can be `null`.
oneOf:
- $ref: '#/components/schemas/EarningRuleValidityHours'
- type: 'null'
trigger_limits:
description: >-
Cooldown and frequency limits for the trigger. Defaults to `{
"cooldown": { "type": "NO_COOLDOWN" }, "frequency": { "type":
"NO_LIMIT" } }` when omitted. Can be `null`.
oneOf:
- $ref: '#/components/schemas/EarningRuleTriggerLimits'
- type: 'null'
required:
- name
- trigger
- earnings
unevaluatedProperties: false
EarningRuleResponse:
type: object
description: Earning rule as returned by the API.
properties:
id:
type: string
pattern: ^lern_[a-f0-9]+$
description: Earning rule ID (`lern_...`).
name:
type: string
maxLength: 200
description: Earning rule name.
status:
type: string
enum:
- DRAFT
- ACTIVE
- INACTIVE
description: >-
Current status. `DELETED` also exists internally but deleted rules
are excluded from API reads.
earnings:
type: array
minItems: 1
description: Earning definitions of the rule. Contains at least one earning.
items:
$ref: '#/components/schemas/EarningRuleEarning'
trigger:
$ref: '#/components/schemas/EarningRuleTrigger'
error:
$ref: '#/components/schemas/LoyaltyV2ActivityEarningRuleError'
description: Default error configuration. Absent when not configured.
validity_hours:
$ref: '#/components/schemas/EarningRuleValidityHours'
description: >-
Validity hours. Always present; defaults to `{ "type": "ANY_TIME"
}`.
start_date:
type:
- string
- 'null'
format: date-time
description: Date-time from which the rule is active. Can be `null`.
end_date:
type:
- string
- 'null'
format: date-time
description: Date-time until which the rule is active. Can be `null`.
trigger_limits:
description: >-
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`.
allOf:
- $ref: '#/components/schemas/EarningRuleTriggerLimits'
- type: object
required:
- cooldown
- frequency
properties:
cooldown:
$ref: '#/components/schemas/EarningRuleTriggerLimitsCooldown'
frequency:
$ref: '#/components/schemas/EarningRuleTriggerLimitsFrequency'
earning_limits:
$ref: '#/components/schemas/LoyaltyV2ActivityEarningRuleEarningLimits'
description: >-
Limits how many points this rule can award. Always present. Defaults
to no global limit (`global.type` `NO_LIMIT` and `global.limits`
`[]`).
metadata:
$ref: '#/components/schemas/LoyaltyV2ActivityMetadata'
description: >-
Arbitrary key-value metadata. Always present (empty object when
unset).
created_at:
type: string
format: date-time
description: Creation timestamp (ISO 8601).
updated_at:
type:
- string
- 'null'
format: date-time
description: Last update timestamp (ISO 8601). `null` when never updated.
object:
type: string
const: earning_rule
description: Object type marker. Always `earning_rule`.
required:
- id
- name
- status
- earnings
- trigger
- validity_hours
- start_date
- end_date
- trigger_limits
- earning_limits
- metadata
- created_at
- updated_at
- object
EarningRuleRequestBase:
type: object
properties:
error:
description: Default error returned when rule validation fails. Can be `null`.
oneOf:
- $ref: '#/components/schemas/LoyaltyV2ActivityEarningRuleError'
- type: 'null'
start_date:
type:
- string
- 'null'
format: date-time
description: Date-time from which the rule is active. Can be `null`.
end_date:
type:
- string
- 'null'
format: date-time
description: Date-time until which the rule is active. Can be `null`.
metadata:
description: Arbitrary key-value metadata. Can be `null`.
oneOf:
- $ref: '#/components/schemas/LoyaltyV2ActivityMetadata'
- type: 'null'
EarningRuleTrigger:
type: object
description: >-
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.
properties:
event:
type: string
enum:
- customer.order.paid
- customer.custom_event
- customer.segment.entered
description: Triggering event type.
custom_event:
description: >-
Required when `event` is `customer.custom_event`. Absent for other
events.
oneOf:
- $ref: >-
#/components/schemas/LoyaltyV2ActivityEarningRuleTriggerCustomEvent
- type: 'null'
segment:
description: >-
Required when `event` is `customer.segment.entered`. Absent for
other events.
oneOf:
- $ref: '#/components/schemas/LoyaltyV2ActivityEarningRuleTriggerSegment'
- type: 'null'
additionalProperties: false
allOf:
- required:
- event
- if:
properties:
event:
const: customer.order.paid
then:
properties:
custom_event:
type: 'null'
segment:
type: 'null'
- if:
properties:
event:
const: customer.custom_event
then:
required:
- custom_event
properties:
custom_event:
$ref: >-
#/components/schemas/LoyaltyV2ActivityEarningRuleTriggerCustomEvent
segment:
type: 'null'
- if:
properties:
event:
const: customer.segment.entered
then:
required:
- segment
properties:
custom_event:
type: 'null'
segment:
$ref: >-
#/components/schemas/LoyaltyV2ActivityEarningRuleTriggerSegment
EarningRuleEarningCreate:
description: >-
A single earning definition combining optional validation rules with
effects.
allOf:
- $ref: '#/components/schemas/EarningRuleEarningBase'
unevaluatedProperties: false
EarningRuleValidityHours:
type: object
description: >-
Hours during which the earning rule is active. With `ANY_TIME`, `daily`
must be null/absent. With `DAILY`, `daily` is required (at least one
entry).
properties:
type:
type: string
enum:
- DAILY
- ANY_TIME
description: Validity hours type.
daily:
description: Daily validity windows. Can be `null`.
oneOf:
- type: array
minItems: 1
items:
$ref: >-
#/components/schemas/LoyaltyV2ActivityEarningRuleValidityDailyHours
- type: 'null'
additionalProperties: false
allOf:
- required:
- type
- if:
properties:
type:
const: ANY_TIME
then:
properties:
daily:
type: 'null'
- if:
properties:
type:
const: DAILY
then:
required:
- daily
properties:
daily:
type: array
minItems: 1
items:
$ref: >-
#/components/schemas/LoyaltyV2ActivityEarningRuleValidityDailyHours
EarningRuleTriggerLimits:
type: object
description: Cooldown and frequency limits applied to the earning rule trigger.
properties:
cooldown:
description: Cooldown configuration. `null`able (defaults to `NO_COOLDOWN`).
oneOf:
- $ref: '#/components/schemas/EarningRuleTriggerLimitsCooldown'
- type: 'null'
frequency:
description: Frequency limit configuration. `null`able (defaults to `NO_LIMIT`).
oneOf:
- $ref: '#/components/schemas/EarningRuleTriggerLimitsFrequency'
- type: 'null'
additionalProperties: false
EarningRuleEarning:
type: object
description: An earning definition as returned by the API.
properties:
id:
type: string
pattern: ^lernei_[a-f0-9]+$
description: Earning item ID (`lernei_...`).
name:
type:
- string
- 'null'
maxLength: 200
description: Earning item name. Can be `null`.
rules:
$ref: '#/components/schemas/EarningRuleRulesGroup'
description: Validation rules group. Absent when the earning has no rules.
tier_rules:
$ref: '#/components/schemas/EarningRuleTierRules'
description: >-
Tier requirements. Defaults to `{ "type": "NO_REQUIREMENTS" }` when
not explicitly configured.
effects:
type: array
minItems: 1
maxItems: 10
description: Effects applied when the rules match. Contains 1 to 10 effects.
items:
$ref: '#/components/schemas/EarningRuleEffect'
required:
- id
- tier_rules
- effects
LoyaltyV2ActivityEarningRuleError:
type: object
title: Custom error message configuration
description: Custom error message configuration.
properties:
message:
type: string
minLength: 1
maxLength: 200
description: Error message shown when validation fails.
required:
- message
additionalProperties: false
EarningRuleTriggerLimitsCooldown:
type: object
description: >-
Cooldown between consecutive triggers per member. With `NO_COOLDOWN`,
`fixed_cooldown` must be null/absent. With `FIXED_COOLDOWN`,
`fixed_cooldown` is required.
properties:
type:
type: string
enum:
- NO_COOLDOWN
- FIXED_COOLDOWN
description: Cooldown type.
fixed_cooldown:
description: Fixed cooldown configuration. Can be `null`.
oneOf:
- $ref: >-
#/components/schemas/EarningRuleTriggerLimitsCooldownFixedCooldown
- type: 'null'
additionalProperties: false
allOf:
- required:
- type
- if:
properties:
type:
const: NO_COOLDOWN
then:
properties:
fixed_cooldown:
type: 'null'
- if:
properties:
type:
const: FIXED_COOLDOWN
then:
required:
- fixed_cooldown
properties:
fixed_cooldown:
$ref: >-
#/components/schemas/EarningRuleTriggerLimitsCooldownFixedCooldown
EarningRuleTriggerLimitsFrequency:
type: object
description: >-
Frequency limit for triggers per member. With `NO_LIMIT`, `limits` must
be null or an empty array. With `LIMITED`, `limits` is required and must
contain exactly one limit.
properties:
type:
type: string
enum:
- NO_LIMIT
- LIMITED
description: Frequency limit type.
limits:
description: Frequency limits (at most one). Can be `null`.
oneOf:
- type: 'null'
- type: array
minItems: 0
maxItems: 1
items:
$ref: '#/components/schemas/EarningRuleTriggerLimitsFrequencyLimit'
additionalProperties: false
allOf:
- required:
- type
- if:
properties:
type:
const: NO_LIMIT
then:
properties:
limits:
oneOf:
- type: array
minItems: 0
maxItems: 0
items:
$ref: >-
#/components/schemas/EarningRuleTriggerLimitsFrequencyLimit
- type: 'null'
- if:
properties:
type:
const: LIMITED
then:
required:
- limits
properties:
limits:
type: array
minItems: 1
maxItems: 1
items:
$ref: '#/components/schemas/EarningRuleTriggerLimitsFrequencyLimit'
LoyaltyV2ActivityEarningRuleEarningLimits:
type: object
description: >-
Limits on points earned through this rule. Always present. Defaults to
`{ "global": { "type": "NO_LIMIT", "limits": [] } }`. Unlike card
definition earning limits, this object has no `transactions` key.
properties:
global:
$ref: '#/components/schemas/LoyaltyV2ActivityEarningRuleEarningLimitsGlobal'
required:
- global
additionalProperties: false
LoyaltyV2ActivityMetadata:
type: object
description: Arbitrary key-value metadata; any JSON object is accepted.
additionalProperties: true
LoyaltyV2ActivityEarningRuleTriggerCustomEvent:
type: object
description: Custom event trigger configuration.
properties:
schema_id:
type: string
pattern: ^ms_[a-zA-Z0-9]+
description: Custom event schema ID (`ms_...`).
required:
- schema_id
additionalProperties: false
LoyaltyV2ActivityEarningRuleTriggerSegment:
type: object
description: Segment trigger configuration.
properties:
id:
type: string
pattern: ^seg_[a-zA-Z0-9]+
description: Segment ID (`seg_...`).
required:
- id
additionalProperties: false
EarningRuleEarningBase:
type: object
properties:
rules:
description: >-
Validation rules group evaluated before applying effects. Can be
`null`.
oneOf:
- $ref: '#/components/schemas/EarningRuleRulesGroup'
- type: 'null'
effects:
type: array
minItems: 1
description: Effects applied when the rules match.
items:
$ref: '#/components/schemas/EarningRuleEffect'
name:
type:
- string
- 'null'
maxLength: 200
description: Optional earning item name. Can be `null`.
tier_rules:
description: Tier requirements restricting which members can earn. Can be `null`.
oneOf:
- $ref: '#/components/schemas/EarningRuleTierRules'
- type: 'null'
required:
- effects
LoyaltyV2ActivityEarningRuleValidityDailyHours:
type: object
description: Daily validity window on selected days of the week.
properties:
days_of_week:
type: array
minItems: 1
maxItems: 7
uniqueItems: true
description: Days of week (0 = Sunday ... 6 = Saturday). Items must be unique.
items:
type: integer
minimum: 0
maximum: 6
start_time:
type: string
description: Window start time in `HH:mm` format.
end_time:
type: string
description: Window end time in `HH:mm` format.
required:
- days_of_week
- start_time
- end_time
additionalProperties: false
EarningRuleRulesGroup:
type: object
description: >-
Group of rule definitions combined by a logical formula. Besides
`logic`, only positive-integer keys are allowed (property names must
match `^[1-9]\d*$`), each referencing a rule definition. The `logic`
value is a logical expression referencing the numbered rules, e.g. `"1
and 2"` or `"1 and (2 or 3)"`. At least one numbered rule is required
(`minProperties: 2` including `logic`).
properties:
logic:
type: string
description: >-
Logical expression combining the numbered rule definitions, e.g. `"1
and 2"`.
patternProperties:
^[1-9]\d*$:
$ref: '#/components/schemas/EarningRuleDefinition'
required:
- logic
minProperties: 2
additionalProperties: false
EarningRuleTierRules:
type: object
description: >-
Tier requirements for an earning. With `NO_REQUIREMENTS`, `any_of` must
be null/absent. With `ANY_OF`, `any_of` is required (at least one entry)
and the member must be in any of the listed tiers to earn.
properties:
type:
type: string
enum:
- NO_REQUIREMENTS
- ANY_OF
description: Tier requirement type.
any_of:
description: >-
Tier structure/tier combinations, any of which satisfies the
requirement. Can be `null`.
oneOf:
- type: array
minItems: 1
items:
$ref: >-
#/components/schemas/LoyaltyV2ActivityEarningRuleTierRulesAnyOfEntry
- type: 'null'
additionalProperties: false
allOf:
- required:
- type
- if:
properties:
type:
const: NO_REQUIREMENTS
then:
properties:
any_of:
type: 'null'
- if:
properties:
type:
const: ANY_OF
then:
required:
- any_of
properties:
any_of:
type: array
minItems: 1
items:
$ref: >-
#/components/schemas/LoyaltyV2ActivityEarningRuleTierRulesAnyOfEntry
EarningRuleEffect:
type: object
description: >-
Effect applied when an earning is triggered. Depending on `type`,
exactly one of `points`, `points_proportional` or `benefit` is required
and the others must be null/absent.
properties:
type:
type: string
enum:
- POINTS
- POINTS_PROPORTIONAL
- BENEFIT
description: Effect type.
points:
$ref: '#/components/schemas/EarningRuleEffectPoints'
points_proportional:
$ref: '#/components/schemas/EarningRuleEffectPointsProportional'
benefit:
$ref: '#/components/schemas/LoyaltyV2ActivityEarningRuleEffectBenefit'
additionalProperties: false
allOf:
- required:
- type
- if:
properties:
type:
const: POINTS
then:
required:
- points
properties:
points:
$ref: '#/components/schemas/EarningRuleEffectPoints'
points_proportional:
type: 'null'
benefit:
type: 'null'
- if:
properties:
type:
const: POINTS_PROPORTIONAL
then:
required:
- points_proportional
properties:
points:
type: 'null'
points_proportional:
$ref: '#/components/schemas/EarningRuleEffectPointsProportional'
benefit:
type: 'null'
- if:
properties:
type:
const: BENEFIT
then:
required:
- benefit
properties:
points:
type: 'null'
points_proportional:
type: 'null'
benefit:
$ref: '#/components/schemas/LoyaltyV2ActivityEarningRuleEffectBenefit'
EarningRuleTriggerLimitsCooldownFixedCooldown:
type: object
description: Fixed cooldown period configuration.
properties:
period:
$ref: >-
#/components/schemas/LoyaltyV2ActivityEarningRuleTriggerLimitsCooldownFixedCooldownPeriod
required:
- period
additionalProperties: false
EarningRuleTriggerLimitsFrequencyLimit:
type: object
description: >-
A single frequency limit. Currently only the `TIME_BASED` variant exists
(discriminated by `type`), which requires `period` and `triggers`.
required:
- type
properties:
type:
type: string
enum:
- TIME_BASED
description: Frequency limit variant.
oneOf:
- type: object
properties:
type:
const: TIME_BASED
period:
$ref: >-
#/components/schemas/EarningRuleTriggerLimitsFrequencyLimitTimeBasedPeriod
triggers:
$ref: >-
#/components/schemas/LoyaltyV2ActivityEarningRuleTriggerLimitsFrequencyLimitTimeBasedTriggers
required:
- period
- triggers
additionalProperties: false
LoyaltyV2ActivityEarningRuleEarningLimitsGlobal:
type: object
description: >-
Global (per member, across this rule) earning limits. With `NO_LIMIT`,
`limits` is an empty array. With `LIMITED`, `limits` contains exactly
one `TIME_BASED` limit.
properties:
type:
type: string
enum:
- NO_LIMIT
- LIMITED
description: Whether global earning limits apply.
limits:
type: array
description: Earning limits (at most one). Empty array when `type` is `NO_LIMIT`.
minItems: 0
maxItems: 1
items:
$ref: >-
#/components/schemas/LoyaltyV2ActivityEarningRuleEarningLimitsGlobalLimit
additionalProperties: false
allOf:
- required:
- type
- if:
properties:
type:
const: NO_LIMIT
then:
properties:
limits:
type: array
minItems: 0
maxItems: 0
items:
$ref: >-
#/components/schemas/LoyaltyV2ActivityEarningRuleEarningLimitsGlobalLimit
- if:
properties:
type:
const: LIMITED
then:
required:
- limits
properties:
limits:
type: array
minItems: 1
maxItems: 1
items:
$ref: >-
#/components/schemas/LoyaltyV2ActivityEarningRuleEarningLimitsGlobalLimit
LoyaltyV2ActivityEarningRuleTierRulesAnyOfEntry:
type: object
description: Tier structure with a list of qualifying tiers.
properties:
tier_structure_id:
type: string
pattern: ^lts_[a-f0-9]+$
description: Tier structure ID (`lts_...`).
tier_ids:
type: array
minItems: 1
description: Qualifying tier IDs (`lt_...`).
items:
type: string
pattern: ^lt_[a-f0-9]+$
required:
- tier_structure_id
- tier_ids
additionalProperties: false
EarningRuleEffectPoints:
type: object
description: >-
Fixed points effect - awards a fixed number of points to a card
definition.
properties:
value:
type: integer
minimum: 0
maximum: 9007199254740991
description: Fixed number of points to award.
card_definition_id:
type: string
pattern: ^lcdef_[a-f0-9]+$
description: Card definition ID (`lcdef_...`) the points are awarded to.
points_expiration:
description: Optional expiration override for the awarded points. Can be `null`.
oneOf:
- $ref: '#/components/schemas/EarningRuleEffectPointsExpiration'
- type: 'null'
required:
- value
- card_definition_id
additionalProperties: false
EarningRuleEffectPointsProportional:
type: object
description: >-
Proportional points effect - awards points using an "every X gives Y
points" formula.
Depending on `calculation_type`, one specific configuration object is
required and the others must be null/absent:
- `PRE_DISCOUNT_ORDER_AMOUNT`: requires `order.amount`
- `POST_DISCOUNT_ORDER_AMOUNT`: requires `order.total_amount`
- `ORDER_METADATA_VALUE`: requires `order.metadata`
- `CUSTOMER_METADATA_VALUE`: requires `customer.metadata`
- `CUSTOM_EVENT_METADATA_VALUE`: requires `custom_event.metadata`
- `PRE_DISCOUNT_ORDER_ITEMS_AMOUNT`: requires `order_items.amount`
- `POST_DISCOUNT_ORDER_ITEMS_AMOUNT`: requires
`order_items.subtotal_amount`
- `ORDER_ITEMS_QUANTITY`: requires `order_items.quantity`
The trigger further restricts allowed calculation types:
`customer.order.paid` allows all order/order-items types plus
`CUSTOMER_METADATA_VALUE`;
`customer.custom_event` allows `CUSTOMER_METADATA_VALUE` and
`CUSTOM_EVENT_METADATA_VALUE`;
`customer.segment.entered` allows only `CUSTOMER_METADATA_VALUE`.
properties:
calculation_type:
type: string
enum:
- PRE_DISCOUNT_ORDER_AMOUNT
- POST_DISCOUNT_ORDER_AMOUNT
- PRE_DISCOUNT_ORDER_ITEMS_AMOUNT
- POST_DISCOUNT_ORDER_ITEMS_AMOUNT
- ORDER_ITEMS_QUANTITY
- ORDER_METADATA_VALUE
- CUSTOMER_METADATA_VALUE
- CUSTOM_EVENT_METADATA_VALUE
description: How the proportional points are calculated.
card_definition_id:
type: string
pattern: ^lcdef_[a-f0-9]+$
description: Card definition ID (`lcdef_...`) the points are awarded to.
points_expiration:
description: Optional expiration override for the awarded points. Can be `null`.
oneOf:
- $ref: '#/components/schemas/EarningRuleEffectPointsExpiration'
- type: 'null'
order:
$ref: '#/components/schemas/EarningRulePointsProportionalOrder'
customer:
$ref: '#/components/schemas/EarningRulePointsProportionalCustomer'
custom_event:
$ref: '#/components/schemas/EarningRulePointsProportionalCustomEvent'
order_items:
$ref: '#/components/schemas/EarningRulePointsProportionalOrderItems'
required:
- calculation_type
- card_definition_id
additionalProperties: false
allOf:
- if:
properties:
calculation_type:
const: PRE_DISCOUNT_ORDER_AMOUNT
then:
required:
- order
properties:
order:
type: object
required:
- amount
customer:
type: 'null'
custom_event:
type: 'null'
order_items:
type: 'null'
- if:
properties:
calculation_type:
const: POST_DISCOUNT_ORDER_AMOUNT
then:
required:
- order
properties:
order:
type: object
required:
- total_amount
customer:
type: 'null'
custom_event:
type: 'null'
order_items:
type: 'null'
- if:
properties:
calculation_type:
const: ORDER_METADATA_VALUE
then:
required:
- order
properties:
order:
type: object
required:
- metadata
customer:
type: 'null'
custom_event:
type: 'null'
order_items:
type: 'null'
- if:
properties:
calculation_type:
const: CUSTOMER_METADATA_VALUE
then:
required:
- customer
properties:
customer:
$ref: '#/components/schemas/EarningRulePointsProportionalCustomer'
order:
type: 'null'
custom_event:
type: 'null'
order_items:
type: 'null'
- if:
properties:
calculation_type:
const: CUSTOM_EVENT_METADATA_VALUE
then:
required:
- custom_event
properties:
custom_event:
$ref: '#/components/schemas/EarningRulePointsProportionalCustomEvent'
order:
type: 'null'
customer:
type: 'null'
order_items:
type: 'null'
- if:
properties:
calculation_type:
const: PRE_DISCOUNT_ORDER_ITEMS_AMOUNT
then:
required:
- order_items
properties:
order_items:
type: object
required:
- amount
order:
type: 'null'
customer:
type: 'null'
custom_event:
type: 'null'
- if:
properties:
calculation_type:
const: POST_DISCOUNT_ORDER_ITEMS_AMOUNT
then:
required:
- order_items
properties:
order_items:
type: object
required:
- subtotal_amount
order:
type: 'null'
customer:
type: 'null'
custom_event:
type: 'null'
- if:
properties:
calculation_type:
const: ORDER_ITEMS_QUANTITY
then:
required:
- order_items
properties:
order_items:
type: object
required:
- quantity
order:
type: 'null'
customer:
type: 'null'
custom_event:
type: 'null'
LoyaltyV2ActivityEarningRuleEffectBenefit:
type: object
description: Benefit effect - grants a predefined benefit.
properties:
id:
type: string
pattern: ^lben_[a-f0-9]+$
description: Benefit ID (`lben_...`).
required:
- id
additionalProperties: false
LoyaltyV2ActivityEarningRuleTriggerLimitsCooldownFixedCooldownPeriod:
type: object
description: >-
Cooldown period. The maximum `value` depends on `unit`: `HOUR` - 24,
`DAY` - 90, `WEEK` - 52, `MONTH` - 12, `YEAR` - 1.
properties:
value:
type: integer
minimum: 1
description: >-
Period length. Maximum depends on `unit`: 24 for HOUR, 90 for DAY,
52 for WEEK, 12 for MONTH, 1 for YEAR.
unit:
type: string
enum:
- HOUR
- DAY
- WEEK
- MONTH
- YEAR
description: Period unit.
additionalProperties: false
allOf:
- required:
- value
- unit
- if:
properties:
unit:
const: HOUR
then:
properties:
value:
type: integer
minimum: 1
maximum: 24
- if:
properties:
unit:
const: DAY
then:
properties:
value:
type: integer
minimum: 1
maximum: 90
- if:
properties:
unit:
const: WEEK
then:
properties:
value:
type: integer
minimum: 1
maximum: 52
- if:
properties:
unit:
const: MONTH
then:
properties:
value:
type: integer
minimum: 1
maximum: 12
- if:
properties:
unit:
const: YEAR
then:
properties:
value:
type: integer
minimum: 1
maximum: 1
EarningRuleTriggerLimitsFrequencyLimitTimeBasedPeriod:
type: object
description: >-
Time-based frequency limit period. Currently only `CURRENT_PERIOD` is
supported; when selected, `current_period` is required.
properties:
type:
type: string
enum:
- CURRENT_PERIOD
description: Period type.
current_period:
description: Current calendar period configuration. Can be `null`.
oneOf:
- $ref: >-
#/components/schemas/LoyaltyV2ActivityEarningRuleTriggerLimitsFrequencyLimitTimeBasedCurrentPeriod
- type: 'null'
additionalProperties: false
allOf:
- required:
- type
- if:
properties:
type:
const: CURRENT_PERIOD
then:
required:
- current_period
properties:
current_period:
$ref: >-
#/components/schemas/LoyaltyV2ActivityEarningRuleTriggerLimitsFrequencyLimitTimeBasedCurrentPeriod
LoyaltyV2ActivityEarningRuleTriggerLimitsFrequencyLimitTimeBasedTriggers:
type: object
description: Maximum number of triggers allowed within the period.
properties:
max:
type: integer
minimum: 1
description: Maximum number of triggers per period.
required:
- max
additionalProperties: false
LoyaltyV2ActivityEarningRuleEarningLimitsGlobalLimit:
type: object
description: >-
A single global earning limit. Currently only the `TIME_BASED` variant
exists (discriminated by `type`), which requires `period` and `points`.
required:
- type
properties:
type:
type: string
enum:
- TIME_BASED
description: Earning limit variant.
oneOf:
- type: object
properties:
type:
const: TIME_BASED
period:
$ref: >-
#/components/schemas/LoyaltyV2ActivityEarningRuleEarningLimitsGlobalTimeBasedPeriod
points:
$ref: >-
#/components/schemas/LoyaltyV2ActivityEarningRuleEarningLimitsGlobalTimeBasedPoints
required:
- period
- points
additionalProperties: false
EarningRuleEffectPointsExpiration:
type: object
description: >-
Points expiration override. Depending on `type`, exactly one of
`rolling_expiration`, `calendar_expiration` or `sliding_expiration` is
required; for `NO_EXPIRATION` all three must be null/absent.
properties:
type:
type: string
enum:
- NO_EXPIRATION
- ROLLING_EXPIRATION
- CALENDAR_EXPIRATION
- SLIDING_EXPIRATION
description: Points expiration type.
rolling_expiration:
description: Rolling expiration configuration. Can be `null`.
oneOf:
- $ref: >-
#/components/schemas/EarningRuleEffectPointsExpirationRollingExpiration
- type: 'null'
calendar_expiration:
description: Calendar expiration configuration. Can be `null`.
oneOf:
- $ref: >-
#/components/schemas/EarningRuleEffectPointsExpirationCalendarExpiration
- type: 'null'
sliding_expiration:
description: Sliding expiration configuration. Can be `null`.
oneOf:
- $ref: >-
#/components/schemas/EarningRuleEffectPointsExpirationSlidingExpiration
- type: 'null'
additionalProperties: false
allOf:
- required:
- type
- if:
properties:
type:
const: NO_EXPIRATION
then:
properties:
rolling_expiration:
type: 'null'
calendar_expiration:
type: 'null'
sliding_expiration:
type: 'null'
- if:
properties:
type:
const: ROLLING_EXPIRATION
then:
required:
- rolling_expiration
properties:
rolling_expiration:
$ref: >-
#/components/schemas/EarningRuleEffectPointsExpirationRollingExpiration
calendar_expiration:
type: 'null'
sliding_expiration:
type: 'null'
- if:
properties:
type:
const: CALENDAR_EXPIRATION
then:
required:
- calendar_expiration
properties:
rolling_expiration:
type: 'null'
calendar_expiration:
$ref: >-
#/components/schemas/EarningRuleEffectPointsExpirationCalendarExpiration
sliding_expiration:
type: 'null'
- if:
properties:
type:
const: SLIDING_EXPIRATION
then:
required:
- sliding_expiration
properties:
rolling_expiration:
type: 'null'
calendar_expiration:
type: 'null'
sliding_expiration:
$ref: >-
#/components/schemas/EarningRuleEffectPointsExpirationSlidingExpiration
EarningRulePointsProportionalOrder:
type: object
description: >-
Order-based proportional calculation configuration. `amount` is used by
`PRE_DISCOUNT_ORDER_AMOUNT`, `total_amount` by
`POST_DISCOUNT_ORDER_AMOUNT` and `metadata` by `ORDER_METADATA_VALUE`.
properties:
amount:
$ref: >-
#/components/schemas/LoyaltyV2ActivityEarningRulePointsProportionalEvery
total_amount:
$ref: >-
#/components/schemas/LoyaltyV2ActivityEarningRulePointsProportionalEvery
metadata:
$ref: >-
#/components/schemas/LoyaltyV2ActivityEarningRulePointsProportionalMetadata
additionalProperties: false
EarningRulePointsProportionalCustomer:
description: >-
Customer-based proportional calculation configuration
(`CUSTOMER_METADATA_VALUE`).
allOf:
- $ref: '#/components/schemas/EarningRulePointsProportionalBase'
unevaluatedProperties: false
EarningRulePointsProportionalCustomEvent:
description: >-
Custom event based proportional calculation configuration
(`CUSTOM_EVENT_METADATA_VALUE`).
allOf:
- $ref: '#/components/schemas/EarningRulePointsProportionalBase'
unevaluatedProperties: false
EarningRulePointsProportionalOrderItems:
type: object
description: >-
Order items based proportional calculation configuration. `amount` is
used by `PRE_DISCOUNT_ORDER_ITEMS_AMOUNT`, `subtotal_amount` by
`POST_DISCOUNT_ORDER_ITEMS_AMOUNT` and `quantity` by
`ORDER_ITEMS_QUANTITY`.
properties:
amount:
$ref: >-
#/components/schemas/EarningRulePointsProportionalOrderItemsCalculation
subtotal_amount:
$ref: >-
#/components/schemas/EarningRulePointsProportionalOrderItemsCalculation
quantity:
$ref: >-
#/components/schemas/EarningRulePointsProportionalOrderItemsCalculation
additionalProperties: false
LoyaltyV2ActivityEarningRuleTriggerLimitsFrequencyLimitTimeBasedCurrentPeriod:
type: object
description: Current calendar period unit for the frequency limit.
properties:
unit:
type: string
enum:
- DAY
- WEEK
- MONTH
- QUARTER
- YEAR
description: Calendar period unit.
required:
- unit
additionalProperties: false
LoyaltyV2ActivityEarningRuleEarningLimitsGlobalTimeBasedPeriod:
type: object
description: >-
Time-based earning limit period. Currently only `CURRENT_PERIOD` is
supported; when selected, `current_period` is required.
properties:
type:
type: string
enum:
- CURRENT_PERIOD
description: Period type.
current_period:
description: Current calendar period configuration. Can be `null`.
oneOf:
- $ref: >-
#/components/schemas/LoyaltyV2ActivityEarningRuleEarningLimitsGlobalTimeBasedCurrentPeriod
- type: 'null'
additionalProperties: false
allOf:
- required:
- type
- if:
properties:
type:
const: CURRENT_PERIOD
then:
required:
- current_period
properties:
current_period:
$ref: >-
#/components/schemas/LoyaltyV2ActivityEarningRuleEarningLimitsGlobalTimeBasedCurrentPeriod
LoyaltyV2ActivityEarningRuleEarningLimitsGlobalTimeBasedPoints:
type: object
description: Maximum points that can be earned in the period.
properties:
max:
type: integer
minimum: 1
description: Maximum points in the period.
required:
- max
additionalProperties: false
EarningRuleEffectPointsExpirationRollingExpiration:
type: object
description: Rolling expiration - points expire a fixed period after earning.
properties:
period:
$ref: >-
#/components/schemas/LoyaltyV2ActivityEarningRuleEffectPointsExpirationRollingExpirationPeriod
rounding:
description: Optional rounding of the calculated expiration date. Can be `null`.
oneOf:
- $ref: >-
#/components/schemas/LoyaltyV2ActivityEarningRuleEffectPointsExpirationRollingExpirationRounding
- type: 'null'
required:
- period
additionalProperties: false
EarningRuleEffectPointsExpirationCalendarExpiration:
type: object
description: >-
Calendar expiration - points expire on fixed calendar dates (1 to 20
dates).
properties:
expiration_dates:
type: array
minItems: 1
maxItems: 20
description: Fixed expiration dates (day + month).
items:
$ref: >-
#/components/schemas/LoyaltyV2ActivityEarningRuleEffectPointsExpirationCalendarExpirationDate
required:
- expiration_dates
additionalProperties: false
EarningRuleEffectPointsExpirationSlidingExpiration:
type: object
description: Sliding expiration. Points expire after a period of member inactivity.
properties:
earning_activity:
type: boolean
description: Whether earning activity resets the expiration window.
period:
$ref: >-
#/components/schemas/LoyaltyV2ActivityEarningRuleEffectPointsExpirationSlidingExpirationPeriod
required:
- earning_activity
- period
additionalProperties: false
LoyaltyV2ActivityEarningRulePointsProportionalEvery:
type: object
description: '"Every X gives Y points" formula based on an amount.'
properties:
every:
type: integer
minimum: 1
maximum: 9007199254740991
description: >-
The divisor – every this amount (e.g. in cents) awards `value`
points.
value:
type: number
minimum: 0
maximum: 9007199254740991
description: Points awarded per `every` unit.
required:
- every
- value
additionalProperties: false
LoyaltyV2ActivityEarningRulePointsProportionalMetadata:
type: object
description: '"Every X gives Y points" formula based on a numeric metadata property.'
properties:
every:
type: integer
minimum: 1
maximum: 9007199254740991
description: The divisor – every this metadata value awards `value` points.
value:
type: number
minimum: 0
maximum: 9007199254740991
description: Points awarded per `every` unit.
property:
type: string
minLength: 1
description: Metadata property name holding the numeric value.
required:
- every
- value
- property
additionalProperties: false
EarningRulePointsProportionalBase:
type: object
properties:
metadata:
$ref: >-
#/components/schemas/LoyaltyV2ActivityEarningRulePointsProportionalMetadata
required:
- metadata
EarningRulePointsProportionalOrderItemsCalculation:
type: object
description: >-
Order items based calculation - "every X gives Y points" applied to
items matching the `applicable_to` criteria.
properties:
every:
type: integer
minimum: 1
maximum: 9007199254740991
description: The divisor - every this amount/quantity awards `value` points.
value:
type: number
minimum: 0
maximum: 9007199254740991
description: Points awarded per `every` unit.
applicable_to:
type: array
minItems: 1
description: Product/SKU/collection criteria selecting matching order items.
items:
$ref: '#/components/schemas/EarningRulePointsProportionalApplicableTo'
required:
- every
- value
- applicable_to
additionalProperties: false
LoyaltyV2ActivityEarningRuleEarningLimitsGlobalTimeBasedCurrentPeriod:
type: object
description: Current calendar period unit for the earning limit.
properties:
unit:
type: string
enum:
- DAY
- WEEK
- MONTH
- QUARTER
- YEAR
description: Calendar period unit.
required:
- unit
additionalProperties: false
LoyaltyV2ActivityEarningRuleEffectPointsExpirationRollingExpirationPeriod:
type: object
description: >-
Rolling expiration period. The maximum `value` depends on `unit`: `DAY`
- 90, `MONTH` - 12, `YEAR` - 5.
properties:
unit:
type: string
enum:
- DAY
- MONTH
- YEAR
description: Period unit.
value:
type: integer
minimum: 1
description: >-
Period length. Maximum depends on `unit`: 90 for DAY, 12 for MONTH,
5 for YEAR.
additionalProperties: false
allOf:
- required:
- unit
- value
- if:
properties:
unit:
const: DAY
then:
properties:
value:
type: integer
minimum: 1
maximum: 90
- if:
properties:
unit:
const: MONTH
then:
properties:
value:
type: integer
minimum: 1
maximum: 12
- if:
properties:
unit:
const: YEAR
then:
properties:
value:
type: integer
minimum: 1
maximum: 5
LoyaltyV2ActivityEarningRuleEffectPointsExpirationRollingExpirationRounding:
type: object
description: >-
`value` is the month (1-12). Required when `type` is
`END_OF_PARTICULAR_MONTH`. Absent for other rounding types.
properties:
type:
type: string
enum:
- END_OF_MONTH
- END_OF_QUARTER
- END_OF_HALF_YEAR
- END_OF_YEAR
- END_OF_PARTICULAR_MONTH
description: Rounding type.
value:
description: >-
Month number (1-12). Present only when `type` is
`END_OF_PARTICULAR_MONTH`.
oneOf:
- type: integer
minimum: 1
maximum: 12
- type: 'null'
additionalProperties: false
allOf:
- required:
- type
- if:
properties:
type:
const: END_OF_PARTICULAR_MONTH
then:
required:
- value
- type
properties:
value:
type: integer
minimum: 1
maximum: 12
- if:
properties:
type:
not:
const: END_OF_PARTICULAR_MONTH
then:
required:
- type
properties:
value:
type: 'null'
LoyaltyV2ActivityEarningRuleEffectPointsExpirationCalendarExpirationDate:
type: object
description: >-
A calendar expiration date. The maximum `day` depends on `month`: 29 for
February (month 2), 30 for April/June/September/November (4, 6, 9, 11),
31 for the remaining months.
properties:
day:
type: integer
minimum: 1
maximum: 31
description: Day of month (1-31; validated against the month length).
month:
type: integer
minimum: 1
maximum: 12
description: Month number (1-12).
additionalProperties: false
allOf:
- required:
- day
- month
- if:
properties:
month:
const: 2
then:
properties:
day:
type: integer
minimum: 1
maximum: 29
- if:
properties:
month:
enum:
- 4
- 6
- 9
- 11
then:
properties:
day:
type: integer
minimum: 1
maximum: 30
- if:
properties:
month:
enum:
- 1
- 3
- 5
- 7
- 8
- 10
- 12
then:
properties:
day:
type: integer
minimum: 1
maximum: 31
LoyaltyV2ActivityEarningRuleEffectPointsExpirationSlidingExpirationPeriod:
type: object
description: >-
Sliding expiration inactivity period. The maximum `value` depends on
`unit`: `DAY` - 90, `MONTH` - 12, `YEAR` - 1.
properties:
value:
type: integer
minimum: 1
description: >-
Period length. Maximum depends on `unit`: 90 for DAY, 12 for MONTH,
1 for YEAR.
unit:
type: string
enum:
- DAY
- MONTH
- YEAR
description: Period unit.
additionalProperties: false
allOf:
- required:
- value
- unit
- if:
properties:
unit:
const: DAY
then:
properties:
value:
type: integer
minimum: 1
maximum: 90
- if:
properties:
unit:
const: MONTH
then:
properties:
value:
type: integer
minimum: 1
maximum: 12
- if:
properties:
unit:
const: YEAR
then:
properties:
value:
type: integer
minimum: 1
maximum: 1
EarningRulePointsProportionalApplicableTo:
type: object
description: >-
Criterion selecting order items the calculation applies to. Depending on
`type`, exactly one of `product`, `sku` or `products_collection` is
required and the others must be null/absent.
properties:
type:
type: string
enum:
- product
- sku
- products_collection
description: Type of the referenced object.
product:
$ref: >-
#/components/schemas/LoyaltyV2ActivityEarningRulePointsProportionalApplicableToProduct
sku:
$ref: >-
#/components/schemas/LoyaltyV2ActivityEarningRulePointsProportionalApplicableToSku
products_collection:
$ref: >-
#/components/schemas/LoyaltyV2ActivityEarningRulePointsProportionalApplicableToProductsCollection
additionalProperties: false
allOf:
- required:
- type
- if:
properties:
type:
const: product
then:
required:
- product
properties:
product:
$ref: >-
#/components/schemas/LoyaltyV2ActivityEarningRulePointsProportionalApplicableToProduct
sku:
type: 'null'
products_collection:
type: 'null'
- if:
properties:
type:
const: sku
then:
required:
- sku
properties:
sku:
$ref: >-
#/components/schemas/LoyaltyV2ActivityEarningRulePointsProportionalApplicableToSku
product:
type: 'null'
products_collection:
type: 'null'
- if:
properties:
type:
const: products_collection
then:
required:
- products_collection
properties:
products_collection:
$ref: >-
#/components/schemas/LoyaltyV2ActivityEarningRulePointsProportionalApplicableToProductsCollection
product:
type: 'null'
sku:
type: 'null'
LoyaltyV2ActivityEarningRulePointsProportionalApplicableToProduct:
type: object
description: Product reference.
properties:
id:
type: string
pattern: ^prod_[a-f0-9]+
description: Product ID (`prod_...`).
required:
- id
additionalProperties: false
LoyaltyV2ActivityEarningRulePointsProportionalApplicableToSku:
type: object
description: SKU reference.
properties:
id:
type: string
pattern: ^sku_[a-f0-9]+
description: SKU ID (`sku_...`).
required:
- id
additionalProperties: false
LoyaltyV2ActivityEarningRulePointsProportionalApplicableToProductsCollection:
type: object
description: Products collection reference.
properties:
id:
type: string
pattern: ^pc_[a-zA-Z0-9]+
description: Products collection ID (`pc_...`).
required:
- id
additionalProperties: false
securitySchemes:
X-App-Id:
type: apiKey
name: X-App-Id
in: header
X-App-Token:
type: apiKey
name: X-App-Token
in: header
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.