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 /v2/loyalties/incentives

Create an incentive

cURL

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
    }
  }
}
'

200

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

{
  "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": 409,
  "key": "non_draft_program",
  "message": "Invalid vl_program status",
  "details": "Cannot modify card definition assignment when program status is not DRAFT"
}

{
  "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

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 | null

Fixed-points incentive configuration.

Show child attributes

points_proportional · object | null

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 | null

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

Show child attributes

digital · object | null

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

Show child attributes

Response

200

application/json

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.

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

updated_at · string<date-time> | null

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