Get 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.

Returns a single incentive by its ID.

GET /v2/loyalties/incentives/{id}

Get an incentive

cURL

curl --request GET \
  --url https://api.voucherify.io/v2/loyalties/incentives/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'X-App-Id: <api-key>' \
  --header 'X-App-Token: <api-key>'

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

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

Path Parameters

id · string · required

Unique incentive identifier (prefix: linc_).

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

Example:

"linc_abc123def456"

Response

200

application/json

The 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.