Examine Campaign Qualification

curl --request POST \
  --url https://{cluster}.voucherify.io/v1/campaigns/qualification \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-App-Id: <api-key>' \
  --header 'X-App-Token: <api-key>' \
  --data '
{
  "customer": {
    "source_id": "source-id",
    "metadata": {
      "key": "value"
    }
  },
  "order": {
    "amount": 10000,
    "items": [
      {
        "product_id": "product-id",
        "quantity": "1",
        "price": 10000,
        "related_object": "product",
        "product": {
          "metadata": {
            "key": "value"
          }
        }
      }
    ]
  },
  "metadata": {
    "key": "value"
  }
}
'

{
  "object": "list",
  "data_ref": "data",
  "data": [
    {
      "id": "camp_f7fBbQxUuTN7dI7tGOo5XMDA",
      "name": "<string>",
      "description": "<string>",
      "campaign_type": "GIFT_VOUCHERS",
      "type": "AUTO_UPDATE",
      "voucher": {
        "type": "DISCOUNT_VOUCHER",
        "discount": {
          "type": "AMOUNT",
          "amount_off": 100,
          "amount_off_formula": "<string>",
          "aggregated_amount_limit": 123,
          "effect": "APPLY_TO_ORDER"
        },
        "redemption": {
          "quantity": 123
        },
        "code_config": {
          "length": "<string>",
          "charset": "<string>",
          "prefix": "<string>",
          "postfix": "<string>",
          "pattern": "<string>"
        },
        "is_referral_code": true
      },
      "auto_join": true,
      "join_once": true,
      "use_voucher_metadata_schema": true,
      "validity_timeframe": {
        "duration": "PT1H",
        "interval": "P2D"
      },
      "validity_day_of_week": [
        0
      ],
      "validity_hours": {
        "daily": [
          {
            "start_time": "12:00",
            "days_of_week": [
              0
            ],
            "expiration_time": "14:00"
          }
        ]
      },
      "activity_duration_after_publishing": "<string>",
      "vouchers_count": 123,
      "start_date": "2022-09-20T00:00:00.000Z",
      "expiration_date": "2022-09-30T00:00:00.000Z",
      "active": true,
      "metadata": {},
      "created_at": "2021-12-01T08:00:50.038Z",
      "updated_at": "2022-09-20T09:18:19.623Z",
      "category": "<string>",
      "creation_status": "DONE",
      "vouchers_generation_status": "DONE",
      "protected": true,
      "validation_rules_assignments": {
        "object": "list",
        "data_ref": "data",
        "data": [
          {
            "id": "asgm_N7t39epaQR2SkQcW",
            "rule_id": "val_ssbxf1L9aKri",
            "related_object_id": "camp_AaP9MC1Y0GpBII84UTIuasvb",
            "related_object_type": "campaign",
            "created_at": "2022-02-14T15:12:06.817Z",
            "object": "validation_rules_assignment",
            "rule": {}
          }
        ],
        "total": 123
      },
      "category_id": "cat_0b688929a2476386a7",
      "categories": {
        "id": "<string>",
        "name": "<string>",
        "hierarchy": 1,
        "object": "category",
        "created_at": "2022-07-14T10:45:13.156Z",
        "updated_at": "2022-08-16T10:52:08.094Z"
      },
      "object": "campaign",
      "referral_program": {
        "conversion_event_type": "redemption",
        "custom_event": {
          "id": "ms_fi47Dcu5T0m3v3nT5ch3ma",
          "name": "<string>"
        },
        "referee_reward": {
          "related_object_parent": {
            "id": "<string>",
            "name": "<string>",
            "object": "<string>"
          },
          "type": "LOYALTY_CARD",
          "amount": "<string>"
        }
      }
    }
  ],
  "total": 123,
  "id": "qfl_dNZ3gWfKVNa8Zw15hn30uqdU",
  "created_at": "2023-04-04T13:13:03.119Z",
  "tracking_id": "<string>"
}

Examine Campaign Qualification

❗️ Deprecated

This endpoint represents the deprecated version of the API responsible for qualification, and we do not recommend using it. The new Qualifications API introduces additional features and improvements while maintaining backward compatibility. Developers are encouraged to migrate to the latest version to take advantage of the latest enhancements and bug fixes. No updates will be provided to the deprecated endpoint.

The method can be used for sending a request to display all campaigns qualified to the given customer and context (e.g., order).

The maximum number of returned campaigns is 50.

What campaign types are included in the response?

DISCOUNT_COUPONS
GIFT_VOUCHERS
REFERRAL_PROGRAM

What’s excluded?

A checking logic will be run only among campaigns and will ignore generic (standalone) vouchers. For generic (standalone) vouchers, you should run a dedicated endpoint for searching and identifing vouchers.

Subsequent Steps

As a recommended subsequent step after selecting a qualified campaign is to publish a voucher code from that campaign. The API method for publishing will return a unique code which will belong to a given customer.

Sample use case

As a sample use case, you can imagine a requirement of displaying coupons (grouped in campaigns) that a customer is eligible to use. The customer should get assigned to the particular voucher from the campaign and then may redeem that particular code when he/she places an order.

Read about Qualification API limits before you start.

POST

campaigns

qualification

Examine Campaign Qualification

curl --request POST \
  --url https://{cluster}.voucherify.io/v1/campaigns/qualification \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-App-Id: <api-key>' \
  --header 'X-App-Token: <api-key>' \
  --data '
{
  "customer": {
    "source_id": "source-id",
    "metadata": {
      "key": "value"
    }
  },
  "order": {
    "amount": 10000,
    "items": [
      {
        "product_id": "product-id",
        "quantity": "1",
        "price": 10000,
        "related_object": "product",
        "product": {
          "metadata": {
            "key": "value"
          }
        }
      }
    ]
  },
  "metadata": {
    "key": "value"
  }
}
'

{
  "object": "list",
  "data_ref": "data",
  "data": [
    {
      "id": "camp_f7fBbQxUuTN7dI7tGOo5XMDA",
      "name": "<string>",
      "description": "<string>",
      "campaign_type": "GIFT_VOUCHERS",
      "type": "AUTO_UPDATE",
      "voucher": {
        "type": "DISCOUNT_VOUCHER",
        "discount": {
          "type": "AMOUNT",
          "amount_off": 100,
          "amount_off_formula": "<string>",
          "aggregated_amount_limit": 123,
          "effect": "APPLY_TO_ORDER"
        },
        "redemption": {
          "quantity": 123
        },
        "code_config": {
          "length": "<string>",
          "charset": "<string>",
          "prefix": "<string>",
          "postfix": "<string>",
          "pattern": "<string>"
        },
        "is_referral_code": true
      },
      "auto_join": true,
      "join_once": true,
      "use_voucher_metadata_schema": true,
      "validity_timeframe": {
        "duration": "PT1H",
        "interval": "P2D"
      },
      "validity_day_of_week": [
        0
      ],
      "validity_hours": {
        "daily": [
          {
            "start_time": "12:00",
            "days_of_week": [
              0
            ],
            "expiration_time": "14:00"
          }
        ]
      },
      "activity_duration_after_publishing": "<string>",
      "vouchers_count": 123,
      "start_date": "2022-09-20T00:00:00.000Z",
      "expiration_date": "2022-09-30T00:00:00.000Z",
      "active": true,
      "metadata": {},
      "created_at": "2021-12-01T08:00:50.038Z",
      "updated_at": "2022-09-20T09:18:19.623Z",
      "category": "<string>",
      "creation_status": "DONE",
      "vouchers_generation_status": "DONE",
      "protected": true,
      "validation_rules_assignments": {
        "object": "list",
        "data_ref": "data",
        "data": [
          {
            "id": "asgm_N7t39epaQR2SkQcW",
            "rule_id": "val_ssbxf1L9aKri",
            "related_object_id": "camp_AaP9MC1Y0GpBII84UTIuasvb",
            "related_object_type": "campaign",
            "created_at": "2022-02-14T15:12:06.817Z",
            "object": "validation_rules_assignment",
            "rule": {}
          }
        ],
        "total": 123
      },
      "category_id": "cat_0b688929a2476386a7",
      "categories": {
        "id": "<string>",
        "name": "<string>",
        "hierarchy": 1,
        "object": "category",
        "created_at": "2022-07-14T10:45:13.156Z",
        "updated_at": "2022-08-16T10:52:08.094Z"
      },
      "object": "campaign",
      "referral_program": {
        "conversion_event_type": "redemption",
        "custom_event": {
          "id": "ms_fi47Dcu5T0m3v3nT5ch3ma",
          "name": "<string>"
        },
        "referee_reward": {
          "related_object_parent": {
            "id": "<string>",
            "name": "<string>",
            "object": "<string>"
          },
          "type": "LOYALTY_CARD",
          "amount": "<string>"
        }
      }
    }
  ],
  "total": 123,
  "id": "qfl_dNZ3gWfKVNa8Zw15hn30uqdU",
  "created_at": "2023-04-04T13:13:03.119Z",
  "tracking_id": "<string>"
}

Authorizations

X-App-Id

string

header

required

X-App-Token

string

header

required

Authorization

string

header

required

The access token received from the authorization server in the OAuth 2.0 flow.

Query Parameters

audienceRulesOnly

boolean

This parameter set to true will ask only for verifying vouchers' validation rules only against conditions applied to audiences' attributes (belonging into segment and Customer metadata)

limit

integer

The number of campaigns to be qualified. The maximum number is 50.

Required range: 1 <= x <= 50

order

enum<string>

Sorts the results using one of the filtering options, where the dash - means sorting in a descending order.

Available options:

created_at,

-created_at,

updated_at,

-updated_at,

type,

-type,

code,

-code,

category,

-category,

campaign,

-campaign

Body

application/json

Request body schema for POST v1/campaigns/qualification.

customer

Customer ID · object

Customer's information.

Customer ID
Customer Source ID
Customer

Show child attributes

customer.id

string

The ID of an existing customer that will be linked to redemption in this request.

Example:

"cust_Vzck5i8U3OhcEUFY6MKhN9Rv"

order

Order ID · object

Order information. This object enables you to pass purchase transaction data. Read what properties you can use in the Order object.

Order ID
Order Source ID
Orders Create Request Body

Show child attributes

order.id

string

Unique ID assigned by Voucherify of an existing order that will be linked to the redemption of this request.

Response

200 - application/json

This operation returns the list of valid and active campaigns based on the qualification of a given context (e.g., customer profile, redemptions metadata, order).

Read about Qualification API limits before you start.

Response body schema for POST v1/campaigns/qualification.

object

string

default:list

The type of the object represented by JSON. This object stores information about campaigns in a dictionary.

data_ref

string

default:data

Identifies the name of the attribute that contains the array of campaign objects.

data

Campaign Object · object[]

Contains array of campaign objects.

Show child attributes

data.id

string

Unique campaign ID, assigned by Voucherify.

Example:

"camp_f7fBbQxUuTN7dI7tGOo5XMDA"

data.name

string

Campaign name.

data.description

string

An optional field to keep any extra textual information about the campaign such as a campaign description and details.

data.campaign_type

enum<string>

Type of campaign.

Available options:

GIFT_VOUCHERS,

DISCOUNT_COUPONS,

REFERRAL_PROGRAM

data.type

enum<string>

Defines whether the campaign can be updated with new vouchers after campaign creation.

AUTO_UPDATE: the campaign is dynamic, i.e. vouchers will generate based on set criteria
STATIC: vouchers need to be manually published

Available options:

AUTO_UPDATE,

STATIC

data.voucher

Discount Voucher · object

Schema model for a discount voucher.

Discount Voucher
Gift Card
Loyalty Card

Show child attributes

data.voucher.type

string

default:DISCOUNT_VOUCHER

Type of voucher.

data.voucher.discount

Amount · object

Defines the voucher discount type and details.

Amount
Percentage
Fixed
Unit, single item
Unit, multiple items
Shipping

Show child attributes

data.voucher.discount.type

string

default:AMOUNT

Applies an amount discount.

data.voucher.discount.amount_off

integer

Amount taken off the subtotal of a price. Value is multiplied by 100 to precisely represent 2 decimal places. For example, a $10 discount is written as 1000. In case of the amount being calculated by the formula, i.e. the amount_off_formula parameter is present in the amount definition, this value becomes the fallback value. Such that in a case where the formula cannot be calculated due to missing metadata, for example, this value will be used as the amount off.

Example:

100

data.voucher.discount.amount_off_formula

string

Formula used to dynamically calculate the discount.

data.voucher.discount.aggregated_amount_limit

integer

Maximum discount amount per order. Value is multiplied by 100 to precisely represent 2 decimal places. For example, a $6 maximum discount on the entire order is written as 600. This value is definable for the following discount effects:

APPLY_TO_ITEMS (each item subtotal is discounted equally)
APPLY_TO_ITEMS_BY_QUANTITY (each unit of matched products has the same discount value)

data.voucher.discount.effect

enum<string>

Defines how the discount is applied to the customer's order. The discount effects are defined as follows:

APPLY_TO_ORDER (discount applies to the total order amount)
APPLY_TO_ITEMS (each item subtotal is discounted equally)
APPLY_TO_ITEMS_PROPORTIONALLY (split discount proportionally to amount)
APPLY_TO_ITEMS_PROPORTIONALLY_BY_QUANTITY (split discount proportionally to quantity)
APPLY_TO_ITEMS_BY_QUANTITY (each unit of matched products has the same discount value)

Available options:

APPLY_TO_ORDER,

APPLY_TO_ITEMS,

APPLY_TO_ITEMS_PROPORTIONALLY,

APPLY_TO_ITEMS_PROPORTIONALLY_BY_QUANTITY,

APPLY_TO_ITEMS_BY_QUANTITY

data.voucher.redemption

object

Defines the redemption limits on vouchers.

Show child attributes

data.voucher.redemption.quantity

integer

How many times a voucher can be redeemed. A null value means unlimited.

data.voucher.code_config

object

Defines code's pattern (prefix, suffix, length, charset, etc).

Show child attributes

data.voucher.code_config.length

string

Number of characters in a generated code (excluding prefix and postfix).

data.voucher.code_config.charset

string

Characters that can appear in the code.

Examples:

Alphanumeric: 0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ
Alphabetic: abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ
Alphabetic Lowercase: abcdefghijklmnopqrstuvwxyz
Alphabetic Uppercase: ABCDEFGHIJKLMNOPQRSTUVWXYZ
Numbers: 0123456789
Custom: a custom character set

data.voucher.code_config.prefix

string

A text appended before the code.

data.voucher.code_config.postfix

string

A text appended after the code.

data.voucher.code_config.pattern

string

A pattern for codes where hashes (#) will be replaced with random characters. Overrides length.

data.voucher.is_referral_code

boolean

Flag indicating whether this voucher is a referral code; true for campaign type REFERRAL_PROGRAM.

data.auto_join

boolean

Indicates whether customers will be able to auto-join a loyalty campaign if any earning rule is fulfilled.

data.join_once

boolean

If this value is set to true, customers will be able to join the campaign only once.

data.use_voucher_metadata_schema

boolean

Flag indicating whether the campaign is to use the voucher's metadata schema instead of the campaign metadata schema.

data.validity_timeframe

Validity Timeframe · object

Set recurrent time periods when the earning rule is valid. For example, valid for 1 hour every other day.start_date required when including the validity_timeframe.

Show child attributes

data.validity_timeframe.duration

string

Defines the amount of time an earning rule will be active in ISO 8601 format. For example, an earning rule with a duration of PT1H will be valid for a duration of one hour.

Example:

"PT1H"

data.validity_timeframe.interval

string

Defines the intervening time between two time points in ISO 8601 format, expressed as a duration. For example, an earning rule with an interval of P2D will be valid every other day.

Example:

"P2D"

data.validity_day_of_week

enum<integer>[]

Integer array corresponding to the particular days of the week in which the voucher is valid.

0 Sunday
1 Monday
2 Tuesday
3 Wednesday
4 Thursday
5 Friday
6 Saturday

Available options:

0,

1,

2,

3,

4,

5,

6

data.validity_hours

Validity Hours · object

Determines the hours of validity, e.g. to create a happy hours scenario.

Show child attributes

data.validity_hours.daily

object[]

Defines the recurring period(s) when the resource is active. The periods should not overlap.

Show child attributes

data.validity_hours.daily.start_time

string<time>

Defines the starting hour of validity in the HH:mm format. The resource is inactive before this time.

Example:

"12:00"

data.validity_hours.daily.days_of_week

enum<integer>[]

Integer array corresponding to the particular days of the week in which the resource is valid.

0 Sunday
1 Monday
2 Tuesday
3 Wednesday
4 Thursday
5 Friday
6 Saturday

Available options:

0,

1,

2,

3,

4,

5,

6

data.validity_hours.daily.expiration_time

string<time>

Defines the ending hour of validity in the HH:mm format. The resource is inactive after this time.

Example:

"14:00"

data.activity_duration_after_publishing

string

Defines the amount of time the vouchers will be active after publishing. The value is shown in the ISO 8601 format. For example, a voucher with the value of P24D will be valid for a duration of 24 days.

data.vouchers_count

integer

Total number of unique vouchers in campaign.

data.start_date

string<date-time>

Activation timestamp defines when the campaign starts to be active in ISO 8601 format. Campaign is inactive before this date.

Example:

"2022-09-20T00:00:00.000Z"

data.expiration_date

string<date-time>

Expiration timestamp defines when the campaign expires in ISO 8601 format. Campaign is inactive after this date.

Example:

"2022-09-30T00:00:00.000Z"

data.active

boolean

A flag to toggle the campaign on or off. You can disable a campaign even though it's within the active period defined by the start_date and expiration_date.

true indicates an active campaign
false indicates an inactive campaign

data.metadata

object

The metadata object stores all custom attributes assigned to the campaign. A set of key/value pairs that you can attach to a campaign object. It can be useful for storing additional information about the campaign in a structured format.

data.created_at

string<date-time>

Timestamp representing the date and time when the campaign was created. The value is shown in the ISO 8601 format.

Example:

"2021-12-01T08:00:50.038Z"

data.updated_at

string<date-time>

Timestamp representing the date and time when the voucher was updated. The value is shown in the ISO 8601 format.

Example:

"2022-09-20T09:18:19.623Z"

data.category

string

Unique category name.

data.creation_status

enum<string>

Indicates the status of the campaign creation.

Available options:

DONE,

IN_PROGRESS,

FAILED,

DRAFT,

MODIFYING

data.vouchers_generation_status

enum<string>

Indicates the status of the campaign's vouchers.

Available options:

DONE,

IN_PROGRESS,

FAILED,

DRAFT

data.protected

boolean

Indicates whether the resource can be deleted.

data.validation_rules_assignments

object

Stores information about validation rules assigned to the campaign.

Show child attributes

data.validation_rules_assignments.object

string

default:list

The type of the object represented is by default list.

data.validation_rules_assignments.data_ref

string

default:data

Identifies the name of the attribute that contains the array of validation rule assignments.

data.validation_rules_assignments.data

object[]

Array of validation rule assignment objects. Each validation rule assignment object contains details about the rule.

Show child attributes

data.validation_rules_assignments.data.id

string

Assigned by the Voucherify API, identifies the validation rule assignment.

Example:

"asgm_N7t39epaQR2SkQcW"

data.validation_rules_assignments.data.rule_id

string

Assigned by the Voucherify API, identifies the validation rule.

Example:

"val_ssbxf1L9aKri"

ID of the object from which the rule originates.

Example:

"camp_AaP9MC1Y0GpBII84UTIuasvb"

Which object does the rule originate from: the voucher itself or inherited from its parent campaign.

Example:

"campaign"

data.validation_rules_assignments.data.created_at

string<date-time>

Timestamp representing the date and time when the validation rule was created. The value is shown in the ISO 8601 format.

Example:

"2022-02-14T15:12:06.817Z"

data.validation_rules_assignments.data.object

string

default:validation_rules_assignment

The type of resource represented by the object. Default is validation_rules_assignment.

data.validation_rules_assignments.data.rule

object

Describes the details of the rule.

data.validation_rules_assignments.total

integer

Total number of validation rules assigned to the campaign.

data.category_id

string

Unique category ID that this campaign belongs to.

Example:

"cat_0b688929a2476386a7"

data.categories

Category · object

This is an object representing a category.

Show child attributes

data.categories.id

string

required

Unique category ID assigned by Voucherify.

data.categories.name

string

required

Category name.

data.categories.hierarchy

integer

required

Category hierarchy. Categories with lower hierarchy are processed before categories with higher hierarchy value.

Required range: x >= 0

data.categories.object

enum<string>

default:category

required

The type of the object represented by the JSON. This object stores information about the category.

Available options:

category

data.categories.created_at

string<date-time>

required

Timestamp representing the date and time when the category was created. The value is shown in the ISO 8601 format.

Example:

"2022-07-14T10:45:13.156Z"

data.categories.updated_at

string<date-time>

Timestamp representing the date and time when the category was updated. The value is shown in the ISO 8601 format.

Example:

"2022-08-16T10:52:08.094Z"

data.object

string

default:campaign

The type of the object represented by JSON. This object stores information about the campaign.

data.referral_program

object

Defines the referee reward and the way a referral is triggered. Context: REFERRAL_PROGRAM.

Show child attributes

data.referral_program.conversion_event_type

enum<string>

How a referral is triggered.

Available options:

redemption,

custom_event

data.referral_program.custom_event

object

Contains details about the custom event.

Show child attributes

data.referral_program.custom_event.id

string

Unique custom event ID.

Example:

"ms_fi47Dcu5T0m3v3nT5ch3ma"

data.referral_program.custom_event.name

string

Custom event name.

data.referral_program.referee_reward

object

Defines the referee reward.

Show child attributes

Details of the resource from which the reward originates.

Show child attributes

Unique ID of the reward source.

Name of the reward source.

Type of resource represented by the source of the reward.

data.referral_program.referee_reward.type

enum<string>

Type of reward.

Available options:

LOYALTY_CARD,

GIFT_VOUCHER

data.referral_program.referee_reward.amount

string

The number of points to add to a loyalty card or credits to the balance on a gift card. In case of the gift card, the value is multiplied by 100 to precisely represent 2 decimal places. For example, $100 amount is written as 10000.

total

integer

Total valid and active campaigns matching the qualification criteria in given context.

string

Unique qualification ID.

Example:

"qfl_dNZ3gWfKVNa8Zw15hn30uqdU"

created_at

string<date-time>

Timestamp representing the date and time when the qualification was created. The value is shown in the ISO 8601 format.

Example:

"2023-04-04T13:13:03.119Z"

tracking_id

string

Hashed customer source ID.

Get Campaign Summary Promotion Tier Object

⌘I

Introduction

Endpoints

Events

Examine Campaign Qualification

What campaign types are included in the response?

What’s excluded?

Subsequent Steps

Sample use case

Authorizations

Query Parameters

Body

Response