Create Earning Rule

⚠️ BETA endpoint

This is a work-in-progress documentation of a BETA endpoint. The parameters, fields, request and response bodies, and other data may subject to change. If you want to share feedback or improvements, contact Voucherify support or your Technical Account Manager.

Creates a new earning rule. The rule defines a trigger event, validation rules, and effects (points or incentives) to award when triggered.

Requires name, trigger, and earnings (with at least one effect per earning). Status defaults to DRAFT if not specified.

POST /v2/loyalties/earning-rules

Create Earning Rule

cURL

curl --request POST \
  --url https://api.voucherify.io/v2/loyalties/earning-rules \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-App-Id: <api-key>' \
  --header 'X-App-Token: <api-key>' \
  --data '
{
  "name": "<string>",
  "trigger": {
    "custom_event": {
      "schema_id": "<string>"
    },
    "segment": {
      "id": "<string>"
    }
  },
  "earnings": [
    {
      "effects": [
        {
          "points": {
            "value": 4503599627370495,
            "card_definition_id": "<string>",
            "points_expiration": {
              "rolling_expiration": {
                "period": {
                  "value": 2
                },
                "rounding": {
                  "value": 6
                }
              },
              "calendar_expiration": {
                "expiration_dates": [
                  {
                    "day": 16,
                    "month": 6
                  }
                ]
              },
              "sliding_expiration": {
                "period": {
                  "value": 2
                },
                "earning_activity": true,
                "spending_activity": true,
                "custom_activity": true,
                "custom_activity_types": [
                  "<string>"
                ]
              }
            }
          },
          "points_proportional": {
            "card_definition_id": "<string>",
            "points_expiration": {
              "rolling_expiration": {
                "period": {
                  "value": 2
                },
                "rounding": {
                  "value": 6
                }
              },
              "calendar_expiration": {
                "expiration_dates": [
                  {
                    "day": 16,
                    "month": 6
                  }
                ]
              },
              "sliding_expiration": {
                "period": {
                  "value": 2
                },
                "earning_activity": true,
                "spending_activity": true,
                "custom_activity": true,
                "custom_activity_types": [
                  "<string>"
                ]
              }
            },
            "order": {},
            "order_items": {}
          },
          "incentive": {
            "id": "<string>"
          }
        }
      ],
      "name": "<string>",
      "rules": {
        "logic": "<string>"
      }
    }
  ],
  "status": "DRAFT",
  "error": {
    "message": "<string>"
  },
  "validity_hours": {
    "daily": [
      {
        "days_of_week": [
          3
        ],
        "start_time": "<string>",
        "end_time": "<string>"
      }
    ]
  },
  "start_date": "2023-11-07T05:31:56Z",
  "end_date": "2023-11-07T05:31:56Z",
  "trigger_limits": {
    "cooldown": {
      "fixed_cooldown": {
        "period": {
          "value": 2
        }
      }
    },
    "frequency": {
      "limits": [
        {
          "type": "TIME_BASED",
          "period": {
            "type": "CURRENT_PERIOD",
            "current_period": {}
          },
          "triggers": {
            "max": 2
          }
        }
      ]
    }
  },
  "metadata": {}
}
'

200

{
  "id": "<string>",
  "name": "<string>",
  "earnings": [
    {
      "name": "<string>",
      "rules": {
        "logic": "<string>"
      },
      "effects": [
        {
          "points": {
            "value": 123,
            "card_definition_id": "<string>",
            "points_expiration": {
              "rolling_expiration": {
                "period": {
                  "value": 2
                },
                "rounding": {
                  "value": 6
                }
              },
              "calendar_expiration": {
                "expiration_dates": [
                  {
                    "day": 16,
                    "month": 6
                  }
                ]
              },
              "sliding_expiration": {
                "earning_activity": true,
                "spending_activity": true,
                "custom_activity": true,
                "custom_activity_types": [
                  "<string>"
                ],
                "period": {
                  "value": 2
                }
              }
            }
          },
          "points_proportional": {
            "card_definition_id": "<string>",
            "order": {
              "amount": {
                "every": 123,
                "value": 123
              },
              "total_amount": {
                "every": 123,
                "value": 123
              },
              "metadata": {
                "every": 123,
                "value": 123,
                "property": "<string>"
              }
            },
            "customer": {
              "metadata": {
                "every": 123,
                "value": 123,
                "property": "<string>"
              }
            },
            "order_items": {
              "amount": {
                "every": 123,
                "value": 123,
                "applicable_to": [
                  {
                    "product": {
                      "id": "<string>"
                    },
                    "sku": {
                      "id": "<string>"
                    },
                    "products_collection": {
                      "id": "<string>"
                    }
                  }
                ]
              },
              "subtotal_amount": {
                "every": 123,
                "value": 123,
                "applicable_to": [
                  {
                    "product": {
                      "id": "<string>"
                    },
                    "sku": {
                      "id": "<string>"
                    },
                    "products_collection": {
                      "id": "<string>"
                    }
                  }
                ]
              },
              "quantity": {
                "every": 123,
                "value": 123,
                "applicable_to": [
                  {
                    "product": {
                      "id": "<string>"
                    },
                    "sku": {
                      "id": "<string>"
                    },
                    "products_collection": {
                      "id": "<string>"
                    }
                  }
                ]
              }
            },
            "points_expiration": {
              "rolling_expiration": {
                "period": {
                  "value": 2
                },
                "rounding": {
                  "value": 6
                }
              },
              "calendar_expiration": {
                "expiration_dates": [
                  {
                    "day": 16,
                    "month": 6
                  }
                ]
              },
              "sliding_expiration": {
                "earning_activity": true,
                "spending_activity": true,
                "custom_activity": true,
                "custom_activity_types": [
                  "<string>"
                ],
                "period": {
                  "value": 2
                }
              }
            }
          },
          "incentive": {
            "id": "<string>"
          }
        }
      ]
    }
  ],
  "trigger": {
    "custom_event": {
      "schema_id": "<string>"
    },
    "segment": {
      "id": "<string>"
    }
  },
  "metadata": {},
  "created_at": "2023-11-07T05:31:56Z",
  "object": "<string>",
  "error": {
    "message": "<string>"
  },
  "validity_hours": {
    "daily": [
      {
        "days_of_week": [
          123
        ],
        "start_time": "<string>",
        "end_time": "<string>"
      }
    ]
  },
  "start_date": "2023-11-07T05:31:56Z",
  "end_date": "2023-11-07T05:31:56Z",
  "trigger_limits": {
    "cooldown": {
      "fixed_cooldown": {
        "period": {
          "value": 123
        }
      }
    },
    "frequency": {
      "limits": [
        {
          "type": "TIME_BASED",
          "period": {
            "type": "CURRENT_PERIOD",
            "current_period": {}
          },
          "triggers": {
            "max": 123
          }
        }
      ]
    }
  },
  "updated_at": "2023-11-07T05:31:56Z"
}

{
  "code": 123,
  "key": "<string>",
  "message": "<string>",
  "details": "<string>",
  "request_id": "<string>",
  "resource_id": "<string>",
  "resource_type": "<string>"
}

{
  "code": 123,
  "key": "<string>",
  "message": "<string>",
  "details": "<string>",
  "request_id": "<string>",
  "resource_id": "<string>",
  "resource_type": "<string>"
}

{
  "code": 123,
  "key": "<string>",
  "message": "<string>",
  "details": "<string>",
  "request_id": "<string>",
  "resource_id": "<string>",
  "resource_type": "<string>"
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

X-App-Id · string · header · required

X-App-Token · string · header · required

Body

application/json

name · string · required

Human-readable name for the earning rule.

Required string length: 1 - 200

trigger · object · required

Show child attributes

earnings · object[] · required

Array of earning definitions, each with optional rules and required effects.

Minimum array length: 1

Show child attributes

status · enum<string> · default: DRAFT

Initial status. Defaults to DRAFT.

Available options: DRAFT, ACTIVE

error · object | null

Custom error message shown when earning rule conditions are not met.

Show child attributes

validity_hours · object | null

Time-of-day restrictions for when the rule is active.

Show child attributes

start_date · string<date-time> | null

Start date for rule validity (ISO 8601).

end_date · string<date-time> | null

End date for rule validity (ISO 8601).

trigger_limits · object | null

Cooldown and frequency limits for how often the rule can trigger per customer.

Show child attributes

metadata · object | null

Custom key-value metadata.

Response

200

application/json

Earning rule created successfully.

id · string · required

Unique earning rule identifier.

name · string · required

status · enum<string> · required

Available options: DRAFT, ACTIVE, INACTIVE, DELETED

earnings · object[] · required

Show child attributes

trigger · object · required

Show child attributes

metadata · object · required

created_at · string<date-time> · required

object · string · required

Allowed value: "earning_rule"

error · object | null

Show child attributes

validity_hours · object | null

Show child attributes

start_date · string<date-time> | null

end_date · string<date-time> | null

trigger_limits · object | null

Show child attributes

updated_at · string<date-time> | null