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 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" } }.

POST /v2/loyalties/earning-rules

Create earning rule

cURL

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": "<string>",
  "trigger": {
    "custom_event": {
      "schema_id": "<string>"
    },
    "segment": {
      "id": "<string>"
    }
  },
  "earnings": [
    {
      "effects": [
        {}
      ],
      "rules": {
        "logic": "<string>"
      },
      "name": "<string>",
      "tier_rules": {
        "any_of": [
          {
            "tier_structure_id": "<string>",
            "tier_ids": [
              "<string>"
            ]
          }
        ]
      }
    }
  ],
  "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",
  "metadata": {},
  "trigger_limits": {
    "cooldown": {
      "fixed_cooldown": {
        "period": {
          "value": 2
        }
      }
    },
    "frequency": {
      "limits": [
        {
          "type": "TIME_BASED",
          "period": {
            "type": "CURRENT_PERIOD",
            "current_period": {}
          },
          "triggers": {
            "max": 2
          }
        }
      ]
    }
  }
}
'

200

{
  "id": "<string>",
  "name": "<string>",
  "status": "DRAFT",
  "earnings": [
    {
      "id": "<string>",
      "tier_rules": {
        "type": "NO_REQUIREMENTS",
        "any_of": [
          {
            "tier_structure_id": "<string>",
            "tier_ids": [
              "<string>"
            ]
          }
        ]
      },
      "effects": [
        {
          "type": "POINTS",
          "points": {
            "value": 4503599627370495,
            "card_definition_id": "<string>",
            "points_expiration": {
              "type": "NO_EXPIRATION",
              "rolling_expiration": {
                "period": {
                  "unit": "DAY",
                  "value": 2
                },
                "rounding": {
                  "type": "END_OF_MONTH",
                  "value": 6
                }
              },
              "calendar_expiration": {
                "expiration_dates": [
                  {
                    "day": 16,
                    "month": 6
                  }
                ]
              },
              "sliding_expiration": {
                "earning_activity": true,
                "period": {
                  "value": 2,
                  "unit": "DAY"
                }
              }
            }
          },
          "points_proportional": {
            "calculation_type": "PRE_DISCOUNT_ORDER_AMOUNT",
            "card_definition_id": "<string>",
            "points_expiration": {
              "type": "NO_EXPIRATION",
              "rolling_expiration": {
                "period": {
                  "unit": "DAY",
                  "value": 2
                },
                "rounding": {
                  "type": "END_OF_MONTH",
                  "value": 6
                }
              },
              "calendar_expiration": {
                "expiration_dates": [
                  {
                    "day": 16,
                    "month": 6
                  }
                ]
              },
              "sliding_expiration": {
                "earning_activity": true,
                "period": {
                  "value": 2,
                  "unit": "DAY"
                }
              }
            },
            "order": {
              "amount": {
                "every": 4503599627370496,
                "value": 4503599627370495.5
              },
              "total_amount": {
                "every": 4503599627370496,
                "value": 4503599627370495.5
              },
              "metadata": {
                "every": 4503599627370496,
                "value": 4503599627370495.5,
                "property": "<string>"
              }
            },
            "customer": {
              "metadata": {
                "every": 4503599627370496,
                "value": 4503599627370495.5,
                "property": "<string>"
              }
            },
            "custom_event": {
              "metadata": {
                "every": 4503599627370496,
                "value": 4503599627370495.5,
                "property": "<string>"
              }
            },
            "order_items": {
              "amount": {
                "every": 4503599627370496,
                "value": 4503599627370495.5,
                "applicable_to": [
                  {
                    "type": "product",
                    "product": {
                      "id": "<string>"
                    },
                    "sku": {
                      "id": "<string>"
                    },
                    "products_collection": {
                      "id": "<string>"
                    }
                  }
                ]
              },
              "subtotal_amount": {
                "every": 4503599627370496,
                "value": 4503599627370495.5,
                "applicable_to": [
                  {
                    "type": "product",
                    "product": {
                      "id": "<string>"
                    },
                    "sku": {
                      "id": "<string>"
                    },
                    "products_collection": {
                      "id": "<string>"
                    }
                  }
                ]
              },
              "quantity": {
                "every": 4503599627370496,
                "value": 4503599627370495.5,
                "applicable_to": [
                  {
                    "type": "product",
                    "product": {
                      "id": "<string>"
                    },
                    "sku": {
                      "id": "<string>"
                    },
                    "products_collection": {
                      "id": "<string>"
                    }
                  }
                ]
              }
            }
          },
          "benefit": {
            "id": "<string>"
          }
        }
      ],
      "name": "<string>",
      "rules": {
        "logic": "<string>"
      }
    }
  ],
  "trigger": {
    "event": "customer.order.paid",
    "custom_event": {
      "schema_id": "<string>"
    },
    "segment": {
      "id": "<string>"
    }
  },
  "validity_hours": {
    "type": "DAILY",
    "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": {
      "type": "NO_COOLDOWN",
      "fixed_cooldown": {
        "period": {
          "value": 2,
          "unit": "HOUR"
        }
      }
    },
    "frequency": {
      "type": "NO_LIMIT",
      "limits": [
        {
          "type": "TIME_BASED",
          "period": {
            "type": "CURRENT_PERIOD",
            "current_period": {
              "unit": "DAY"
            }
          },
          "triggers": {
            "max": 2
          }
        }
      ]
    }
  },
  "earning_limits": {
    "global": {
      "type": "NO_LIMIT",
      "limits": [
        {
          "type": "TIME_BASED",
          "period": {
            "type": "CURRENT_PERIOD",
            "current_period": {
              "unit": "DAY"
            }
          },
          "points": {
            "max": 2
          }
        }
      ]
    }
  },
  "metadata": {},
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "object": "earning_rule",
  "error": {
    "message": "<string>"
  }
}

Authorizations

X-App-Id & X-App-TokenbearerAuth

X-App-Id · string · header · required

X-App-Token · string · header · required

Body

application/json

Request body for creating an earning rule.

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

Earning definitions (rules and effects) evaluated when the trigger fires.

Minimum array length: 1

Show child attributes

status · enum<string>

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

Available options: DRAFT, ACTIVE

error · Custom error message configuration · object | null

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

Show child attributes

validity_hours · object | null

Hours during which the rule is active. Defaults to { "type": "ANY_TIME" } when omitted. Can be null.

Show child attributes

start_date · string<date-time> | null

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

end_date · string<date-time> | null

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

metadata · object | null

Arbitrary key-value metadata. Can be null.

trigger_limits · object | null

Cooldown and frequency limits for the trigger. Defaults to { "cooldown": { "type": "NO_COOLDOWN" }, "frequency": { "type": "NO_LIMIT" } } when omitted. Can be null.

Show child attributes

Response

200

application/json

Earning rule created

Earning rule as returned by the API.

id · 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