Skip to main content
POST
/
v2
/
loyalties
/
incentives
Create an incentive
curl --request POST \
  --url https://api.voucherify.io/v2/loyalties/incentives \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-App-Id: <api-key>' \
  --header 'X-App-Token: <api-key>' \
  --data '
{
  "name": "<string>",
  "type": "POINTS",
  "stock": 1073741823,
  "status": "DRAFT",
  "points": {
    "value": 4611686018427388000,
    "card_definition_id": "<string>"
  },
  "points_proportional": {
    "calculation_type": "PRE_DISCOUNT_ORDER_AMOUNT",
    "card_definition_id": "<string>",
    "order": {},
    "order_items": {}
  },
  "material": {
    "type": "PRODUCT",
    "product": {
      "id": "<string>"
    },
    "sku": {
      "product_id": "<string>",
      "id": "<string>"
    }
  },
  "digital": {
    "type": "GIFT_VOUCHERS",
    "discount_coupons": {
      "campaign_id": "<string>"
    },
    "gift_vouchers": {
      "campaign_id": "<string>",
      "balance": 4611686018427388000
    }
  }
}
'
{
  "id": "linc_abc123def456",
  "name": "<string>",
  "type": "POINTS",
  "status": "DRAFT",
  "stock": 1073741823,
  "created_at": "2023-11-07T05:31:56Z",
  "object": "<string>",
  "points": {
    "value": 4611686018427388000,
    "card_definition_id": "<string>"
  },
  "points_proportional": {
    "calculation_type": "PRE_DISCOUNT_ORDER_AMOUNT",
    "card_definition_id": "<string>",
    "order": {
      "amount": {
        "every": 4611686018427388000,
        "value": 4611686018427388000
      },
      "total_amount": {
        "every": 4611686018427388000,
        "value": 4611686018427388000
      },
      "metadata": {
        "every": 4611686018427388000,
        "value": 4611686018427388000,
        "property": "<string>"
      }
    },
    "customer": {
      "metadata": {
        "every": 4611686018427388000,
        "value": 4611686018427388000,
        "property": "<string>"
      }
    },
    "order_items": {
      "amount": {
        "every": 4611686018427388000,
        "value": 4611686018427388000,
        "applicable_to": [
          {
            "type": "product",
            "product": {
              "id": "<string>"
            },
            "sku": {
              "id": "<string>"
            },
            "products_collection": {
              "id": "<string>"
            }
          }
        ]
      },
      "subtotal_amount": {
        "every": 4611686018427388000,
        "value": 4611686018427388000,
        "applicable_to": [
          {
            "type": "product",
            "product": {
              "id": "<string>"
            },
            "sku": {
              "id": "<string>"
            },
            "products_collection": {
              "id": "<string>"
            }
          }
        ]
      },
      "quantity": {
        "every": 4611686018427388000,
        "value": 4611686018427388000,
        "applicable_to": [
          {
            "type": "product",
            "product": {
              "id": "<string>"
            },
            "sku": {
              "id": "<string>"
            },
            "products_collection": {
              "id": "<string>"
            }
          }
        ]
      }
    }
  },
  "material": {
    "type": "PRODUCT",
    "product": {
      "id": "<string>"
    },
    "sku": {
      "product_id": "<string>",
      "id": "<string>"
    }
  },
  "digital": {
    "type": "GIFT_VOUCHERS",
    "discount_coupons": {
      "campaign_id": "<string>"
    },
    "gift_vouchers": {
      "campaign_id": "<string>",
      "balance": 4611686018427388000
    }
  },
  "updated_at": "2023-11-07T05:31:56Z"
}

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.

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

Request body for creating an incentive. The type field determines which detail object is required. Exactly one of points, points_proportional, material, or digital must be non-null, matching the given type.

​
name
string
required

Human-readable name (must be unique per project).

Required string length: 1 - 200
​
type
enum<string>
required

Type of incentive. Determines which detail object is present in the response and required in create/update requests.

Available options:
POINTS,
POINTS_PROPORTIONAL,
MATERIAL,
DIGITAL
​
stock
integer
required

Initial stock count.

Required range: 0 <= x <= 2147483647
​
status
enum<string>

Status allowed when creating an incentive.

Available options:
DRAFT,
ACTIVE
​
points
object

Fixed-points incentive configuration.

​
points_proportional
object

Proportional-points incentive configuration. The calculation_type determines which sub-object is required: - PRE_DISCOUNT_ORDER_AMOUNT -> order.amount - POST_DISCOUNT_ORDER_AMOUNT -> order.total_amount - ORDER_METADATA_VALUE -> order.metadata - CUSTOMER_METADATA_VALUE -> customer.metadata - PRE_DISCOUNT_ORDER_ITEMS_AMOUNT -> order_items.amount - POST_DISCOUNT_ORDER_ITEMS_AMOUNT -> order_items.subtotal_amount - ORDER_ITEMS_QUANTITY -> order_items.quantity

​
material
object

Material incentive configuration. Exactly one of product or sku must be provided based on type.

​
digital
object

Digital incentive configuration. Exactly one of discount_coupons or gift_vouchers must be provided based on type.

Response

The created incentive.

Incentive response object.

​
id
string
required

Unique incentive identifier.

Pattern: ^linc_[a-f0-9]+$
Example:

"linc_abc123def456"

​
name
string
required

Human-readable name.

Maximum string length: 200
​
type
enum<string>
required

Type of incentive. Determines which detail object is present in the response and required in create/update requests.

Available options:
POINTS,
POINTS_PROPORTIONAL,
MATERIAL,
DIGITAL
​
status
enum<string>
required

Current lifecycle status of the incentive.

Available options:
DRAFT,
ACTIVE,
DELETED
​
stock
integer
required

Remaining stock count.

Required range: 0 <= x <= 2147483647
​
created_at
string<date-time>
required

ISO 8601 creation timestamp.

​
object
string
required

Object type discriminator.

Allowed value: "incentive"
​
points
object

Fixed-points incentive configuration.

​
points_proportional
object

Proportional-points incentive configuration. The calculation_type determines which sub-object is required: - PRE_DISCOUNT_ORDER_AMOUNT -> order.amount - POST_DISCOUNT_ORDER_AMOUNT -> order.total_amount - ORDER_METADATA_VALUE -> order.metadata - CUSTOMER_METADATA_VALUE -> customer.metadata - PRE_DISCOUNT_ORDER_ITEMS_AMOUNT -> order_items.amount - POST_DISCOUNT_ORDER_ITEMS_AMOUNT -> order_items.subtotal_amount - ORDER_ITEMS_QUANTITY -> order_items.quantity

​
material
object

Material incentive configuration. Exactly one of product or sku must be provided based on type.

​
digital
object

Digital incentive configuration. Exactly one of discount_coupons or gift_vouchers must be provided based on type.

​
updated_at
string<date-time> | null

ISO 8601 last-update timestamp, or null if never updated.

Last modified on May 11, 2026