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>",
  "stock": 1073741823,
  "points": {
    "value": 4611686018427388000,
    "card_definition_id": "<string>"
  },
  "points_proportional": {
    "card_definition_id": "<string>",
    "order": {},
    "order_items": {}
  },
  "material": {
    "product": {
      "id": "<string>"
    },
    "sku": {
      "product_id": "<string>",
      "id": "<string>"
    }
  },
  "digital": {
    "discount_coupons": {
      "campaign_id": "<string>"
    },
    "gift_vouchers": {
      "campaign_id": "<string>",
      "balance": 4611686018427388000
    }
  }
}
'

{
  "id": "linc_abc123def456",
  "name": "<string>",
  "stock": 1073741823,
  "created_at": "2023-11-07T05:31:56Z",
  "object": "<string>",
  "points": {
    "value": 4611686018427388000,
    "card_definition_id": "<string>"
  },
  "points_proportional": {
    "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": [
          {
            "product": {
              "id": "<string>"
            },
            "sku": {
              "id": "<string>"
            },
            "products_collection": {
              "id": "<string>"
            }
          }
        ]
      },
      "subtotal_amount": {
        "every": 4611686018427388000,
        "value": 4611686018427388000,
        "applicable_to": [
          {
            "product": {
              "id": "<string>"
            },
            "sku": {
              "id": "<string>"
            },
            "products_collection": {
              "id": "<string>"
            }
          }
        ]
      },
      "quantity": {
        "every": 4611686018427388000,
        "value": 4611686018427388000,
        "applicable_to": [
          {
            "product": {
              "id": "<string>"
            },
            "sku": {
              "id": "<string>"
            },
            "products_collection": {
              "id": "<string>"
            }
          }
        ]
      }
    }
  },
  "material": {
    "product": {
      "id": "<string>"
    },
    "sku": {
      "product_id": "<string>",
      "id": "<string>"
    }
  },
  "digital": {
    "discount_coupons": {
      "campaign_id": "<string>"
    },
    "gift_vouchers": {
      "campaign_id": "<string>",
      "balance": 4611686018427388000
    }
  },
  "updated_at": "2023-11-07T05:31:56Z"
}

Create an incentive

⚠️ 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 incentive. The type field determines which detail object (points, points_proportional, material, or digital) is required. Exactly one detail object must be provided matching the type.

POST

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>",
  "stock": 1073741823,
  "points": {
    "value": 4611686018427388000,
    "card_definition_id": "<string>"
  },
  "points_proportional": {
    "card_definition_id": "<string>",
    "order": {},
    "order_items": {}
  },
  "material": {
    "product": {
      "id": "<string>"
    },
    "sku": {
      "product_id": "<string>",
      "id": "<string>"
    }
  },
  "digital": {
    "discount_coupons": {
      "campaign_id": "<string>"
    },
    "gift_vouchers": {
      "campaign_id": "<string>",
      "balance": 4611686018427388000
    }
  }
}
'

{
  "id": "linc_abc123def456",
  "name": "<string>",
  "stock": 1073741823,
  "created_at": "2023-11-07T05:31:56Z",
  "object": "<string>",
  "points": {
    "value": 4611686018427388000,
    "card_definition_id": "<string>"
  },
  "points_proportional": {
    "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": [
          {
            "product": {
              "id": "<string>"
            },
            "sku": {
              "id": "<string>"
            },
            "products_collection": {
              "id": "<string>"
            }
          }
        ]
      },
      "subtotal_amount": {
        "every": 4611686018427388000,
        "value": 4611686018427388000,
        "applicable_to": [
          {
            "product": {
              "id": "<string>"
            },
            "sku": {
              "id": "<string>"
            },
            "products_collection": {
              "id": "<string>"
            }
          }
        ]
      },
      "quantity": {
        "every": 4611686018427388000,
        "value": 4611686018427388000,
        "applicable_to": [
          {
            "product": {
              "id": "<string>"
            },
            "sku": {
              "id": "<string>"
            },
            "products_collection": {
              "id": "<string>"
            }
          }
        ]
      }
    }
  },
  "material": {
    "product": {
      "id": "<string>"
    },
    "sku": {
      "product_id": "<string>",
      "id": "<string>"
    }
  },
  "digital": {
    "discount_coupons": {
      "campaign_id": "<string>"
    },
    "gift_vouchers": {
      "campaign_id": "<string>",
      "balance": 4611686018427388000
    }
  },
  "updated_at": "2023-11-07T05:31:56Z"
}

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.

Show child attributes

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

Show child attributes

material

object

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

Show child attributes

digital

object

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

Show child attributes

Response

The created incentive.

Incentive response object.

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.

Show child attributes

points_proportional

object

Show child attributes

material

object

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

Show child attributes

digital

object

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

Show child attributes

updated_at

string<date-time> | null

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

Last modified on June 2, 2026

List incentives Get an incentive

⌘I