> ## 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. # 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](/api-reference/qualifications/check-eligibility) 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](/api-reference/vouchers/examine-voucher-qualification) 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](/api-reference/publications/create-publication) 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](/guides/checking-eligibility) about Qualification API limits before you start. ## OpenAPI ````yaml /openapi/campaigns.json post /v1/campaigns/qualification openapi: 3.0.1 info: title: Voucherify API - Campaigns version: v2018-08-01 description: >- Voucherify promotion engine REST API. Please see https://docs.voucherify.io/docs for more details. contact: name: Voucherify Team url: https://www.voucherify.io/contact-support email: support@voucherify.io termsOfService: https://www.voucherify.io/legal/subscription-agreement license: name: MIT url: https://github.com/voucherifyio/voucherify-js-sdk/blob/main/LICENSE servers: - url: https://{cluster}.voucherify.io description: Base URL variables: cluster: default: api enum: - api - us1.api - as1.api - download - us1.download - as1.download security: [] paths: /v1/campaigns/qualification: post: tags: - Campaigns summary: Examine Campaign Qualification description: >- > ❗️ Deprecated > > This endpoint represents the deprecated version of the API responsible for qualification, and we do not recommend using it. The new [Qualifications API](/api-reference/qualifications/check-eligibility) 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](/api-reference/vouchers/examine-voucher-qualification) 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](/api-reference/publications/create-publication) 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](/guides/checking-eligibility) about Qualification API limits before you start. operationId: examine-campaign-qualification parameters: - schema: $ref: '#/components/schemas/ParameterBoolean' in: query name: audienceRulesOnly description: >- 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) - schema: $ref: '#/components/schemas/ParameterLimitExamineCampaignsQualification' in: query name: limit description: The number of campaigns to be qualified. The maximum number is 50. - schema: $ref: '#/components/schemas/ParameterOrderExamineCampaignsQualification' in: query name: order description: >- Sorts the results using one of the filtering options, where the dash `-` means sorting in a descending order. requestBody: content: application/json: schema: $ref: '#/components/schemas/2_req_examine_qualification' examples: Example: value: 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 required: true responses: '200': description: >- 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](/guides/checking-eligibility) about Qualification API limits before you start. content: application/json: schema: $ref: '#/components/schemas/2_res_examine_qualification' deprecated: true security: - X-App-Id: [] X-App-Token: [] - X-Voucherify-OAuth: - api - campaigns components: schemas: ParameterBoolean: type: boolean ParameterLimitExamineCampaignsQualification: type: integer maximum: 50 minimum: 1 ParameterOrderExamineCampaignsQualification: type: string enum: - created_at - '-created_at' - updated_at - '-updated_at' - type - '-type' - code - '-code' - category - '-category' - campaign - '-campaign' 2_req_examine_qualification: type: object title: Examine Qualification Request Body description: Request body schema for **POST** `v1/campaigns/qualification`. properties: customer: oneOf: - $ref: '#/components/schemas/6_req_validate_voucher_customer_id' - $ref: '#/components/schemas/6_req_validate_voucher_customer_source_id' - $ref: '#/components/schemas/9_req_create_customer' description: Customer's information. order: oneOf: - $ref: '#/components/schemas/6_req_validate_voucher_order_id' - $ref: '#/components/schemas/6_req_validate_voucher_order_source_id' - $ref: '#/components/schemas/OrdersCreateRequestBody' description: >- Order information. This object enables you to pass purchase transaction data. Read what properties you can use in the [Order object](/api-reference/orders/order-calculated-object). 2_res_examine_qualification: type: object title: Examine Qualification Response Body description: Response body schema for **POST** `v1/campaigns/qualification`. properties: object: type: string description: >- The type of the object represented by JSON. This object stores information about campaigns in a dictionary. default: list data_ref: type: string description: >- Identifies the name of the attribute that contains the array of campaign objects. default: data data: type: array description: Contains array of campaign objects. items: $ref: '#/components/schemas/2_obj_campaign_object_campaigns_qualification' total: type: integer description: >- Total valid and active campaigns matching the qualification criteria in given context. id: type: string description: Unique qualification ID. example: qfl_dNZ3gWfKVNa8Zw15hn30uqdU created_at: type: string format: date-time description: >- 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: type: string description: Hashed customer source ID. 6_req_validate_voucher_customer_id: title: Customer ID description: You can pass the unique customer ID that was assigned by Voucherify. type: object properties: id: type: string description: >- The ID of an existing customer that will be linked to redemption in this request. example: cust_Vzck5i8U3OhcEUFY6MKhN9Rv 6_req_validate_voucher_customer_source_id: title: Customer Source ID description: >- You can send the source ID that you used to create the customer in Voucherify. type: object properties: source_id: type: string description: >- A unique identifier of the customer who validates a voucher. It can be a customer ID or email from a CRM system, database, or a third-party service. If you also pass a customer ID (unique ID assigned by Voucherify), the source ID will be ignored. 9_req_create_customer: type: object title: Customer description: This is an object containing information about the customer. properties: source_id: type: string description: >- The merchant's customer ID if it is different from the Voucherify customer ID. It is really useful in case of an integration between multiple systems. It can be a customer ID from a CRM system, database or 3rd-party service. Please note that if you would like your data to sync based on the `source_id` of the customer, you need to define the `source_id` upfront. You will not be able to change or update the `source_id` later on. name: type: string description: Customer's first and last name. description: type: string description: An arbitrary string that you can attach to a customer object. email: type: string description: Customer's email address. phone: type: string description: >- Customer's phone number. This parameter is mandatory when you try to send out codes to customers via an SMS channel. address: type: object description: Customer's address. properties: city: type: string description: City state: type: string description: State line_1: type: string description: First line of address. line_2: type: string description: Second line of address. country: type: string description: Country. postal_code: type: string description: Postal code. birthdate: type: string description: Customer's birthdate; format `YYYY-MM-DD`. format: date birthday: type: string description: '`Deprecated`. ~~Customer''s birthdate; format `YYYY-MM-DD`~~.' format: date metadata: type: object description: >- A set of custom key/value pairs that you can attach to a customer. The metadata object stores all custom attributes assigned to the customer. It can be useful for storing additional information about the customer in a structured format. This metadata can be used for validating whether the customer qualifies for a discount or it can be used in building customer segments. 6_req_validate_voucher_order_id: title: Order ID description: You can pass the unique order ID that was assigned by Voucherify. type: object properties: id: type: string description: >- Unique ID assigned by Voucherify of an existing order that will be linked to the redemption of this request. 6_req_validate_voucher_order_source_id: title: Order Source ID description: >- You can send the source ID that you used to create the order in Voucherify. type: object properties: source_id: type: string description: >- Unique source ID of an existing order that will be linked to the redemption of this request. OrdersCreateRequestBody: title: Orders Create Request Body type: object description: Request body schema for **POST** `v1/orders`. allOf: - $ref: '#/components/schemas/Order' - title: Order Customer And Referrer Ids Objects type: object description: Order information. properties: created_at: type: string example: '2021-12-22T10:13:06.487Z' description: >- Timestamp representing the date and time when the order was created. The value is shown in the ISO 8601 format. format: date-time referrer_id: type: string nullable: true description: Unique referrer ID. example: cust_nM4jqPiaXUvQdVSA6vTRUnix customer: allOf: - $ref: '#/components/schemas/Customer' referrer: allOf: - $ref: '#/components/schemas/Referrer' 2_obj_campaign_object_campaigns_qualification: type: object title: Campaign Object description: This is an object representing a campaign. properties: id: type: string description: Unique campaign ID, assigned by Voucherify. example: camp_f7fBbQxUuTN7dI7tGOo5XMDA name: type: string description: Campaign name. description: type: string description: >- An optional field to keep any extra textual information about the campaign such as a campaign description and details. campaign_type: type: string enum: - GIFT_VOUCHERS - DISCOUNT_COUPONS - REFERRAL_PROGRAM description: Type of campaign. type: type: string description: >- 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 enum: - AUTO_UPDATE - STATIC voucher: oneOf: - $ref: >- #/components/schemas/2_obj_campaign_object_voucher_object_DISCOUNT - $ref: >- #/components/schemas/2_obj_campaign_object_voucher_object_GIFT_CARD - $ref: >- #/components/schemas/2_obj_campaign_object_voucher_object_LOYALTY_CARD auto_join: type: boolean description: >- Indicates whether customers will be able to auto-join a loyalty campaign if any earning rule is fulfilled. join_once: type: boolean description: >- If this value is set to `true`, customers will be able to join the campaign only once. use_voucher_metadata_schema: type: boolean description: >- Flag indicating whether the campaign is to use the voucher's metadata schema instead of the campaign metadata schema. validity_timeframe: $ref: '#/components/schemas/ValidityTimeframe' validity_day_of_week: $ref: '#/components/schemas/ValidityDayOfWeek' validity_hours: $ref: '#/components/schemas/ValidityHours' activity_duration_after_publishing: type: string description: >- 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. vouchers_count: type: integer description: Total number of unique vouchers in campaign. start_date: type: string format: date-time description: >- 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' expiration_date: type: string format: date-time description: >- Expiration timestamp defines when the campaign expires in ISO 8601 format. Campaign is *inactive after* this date. example: '2022-09-30T00:00:00.000Z' active: type: boolean description: >- 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 metadata: type: object description: >- 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. created_at: type: string format: date-time example: '2021-12-01T08:00:50.038Z' description: >- Timestamp representing the date and time when the campaign was created. The value is shown in the ISO 8601 format. updated_at: type: string format: date-time example: '2022-09-20T09:18:19.623Z' description: >- Timestamp representing the date and time when the voucher was updated. The value is shown in the ISO 8601 format. category: type: string description: Unique category name. creation_status: type: string enum: - DONE - IN_PROGRESS - FAILED - DRAFT - MODIFYING description: Indicates the status of the campaign creation. vouchers_generation_status: type: string description: Indicates the status of the campaign's vouchers. enum: - DONE - IN_PROGRESS - FAILED - DRAFT protected: type: boolean description: Indicates whether the resource can be deleted. validation_rules_assignments: type: object description: Stores information about validation rules assigned to the campaign. properties: object: type: string description: The type of the object represented is by default `list`. default: list data_ref: type: string description: >- Identifies the name of the attribute that contains the array of validation rule assignments. default: data data: type: array description: >- Array of validation rule assignment objects. Each validation rule assignment object contains details about the rule. items: type: object properties: id: type: string example: asgm_N7t39epaQR2SkQcW description: >- Assigned by the Voucherify API, identifies the validation rule assignment. rule_id: type: string example: val_ssbxf1L9aKri description: >- Assigned by the Voucherify API, identifies the validation rule. related_object_id: type: string example: camp_AaP9MC1Y0GpBII84UTIuasvb description: ID of the object from which the rule originates. related_object_type: type: string example: campaign description: >- Which object does the rule originate from: the `voucher` itself or inherited from its parent `campaign`. created_at: type: string example: '2022-02-14T15:12:06.817Z' description: >- Timestamp representing the date and time when the validation rule was created. The value is shown in the ISO 8601 format. format: date-time object: type: string default: validation_rules_assignment description: >- The type of resource represented by the object. Default is `validation_rules_assignment`. rule: type: object description: Describes the details of the rule. total: type: integer description: Total number of validation rules assigned to the campaign. category_id: type: string description: Unique category ID that this campaign belongs to. example: cat_0b688929a2476386a7 categories: $ref: '#/components/schemas/Category' object: type: string default: campaign description: >- The type of the object represented by JSON. This object stores information about the campaign. referral_program: type: object description: >- Defines the referee reward and the way a referral is triggered. Context: `REFERRAL_PROGRAM`. properties: conversion_event_type: type: string enum: - redemption - custom_event description: How a referral is triggered. custom_event: type: object description: Contains details about the custom event. properties: id: type: string example: ms_fi47Dcu5T0m3v3nT5ch3ma description: Unique custom event ID. name: type: string description: Custom event name. referee_reward: type: object description: Defines the referee reward. properties: related_object_parent: type: object description: Details of the resource from which the reward originates. properties: id: type: string description: Unique ID of the reward source. name: type: string description: Name of the reward source. object: type: string description: >- Type of resource represented by the source of the reward. type: type: string description: Type of reward. enum: - LOYALTY_CARD - GIFT_VOUCHER amount: type: string description: >- 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. Order: title: Order type: object description: Order information. allOf: - type: object properties: id: type: string description: >- Unique ID assigned by Voucherify of an existing order that will be linked to the redemption of this request. - $ref: '#/components/schemas/OrderBase' Customer: title: Customer allOf: - type: object title: Customer Id And Source Id properties: id: type: string description: The ID of an existing customer. source_id: type: string description: >- A unique identifier of the customer who validates a voucher. It can be a customer ID or email from a CRM system, database, or a third-party service. If you also pass a customer ID (unique ID assigned by Voucherify), the source ID will be ignored. - $ref: '#/components/schemas/CustomerBase' Referrer: title: Referrer allOf: - $ref: '#/components/schemas/Customer' 2_obj_campaign_object_voucher_object_DISCOUNT: type: object description: Schema model for a discount voucher. title: Discount Voucher properties: type: type: string default: DISCOUNT_VOUCHER description: Type of voucher. discount: oneOf: - $ref: '#/components/schemas/1_obj_voucher_object_discount_amount' - $ref: '#/components/schemas/1_obj_voucher_object_discount_percentage' - $ref: '#/components/schemas/1_obj_voucher_object_discount_fixed' - $ref: '#/components/schemas/1_obj_voucher_object_discount_unit_one' - $ref: '#/components/schemas/1_obj_voucher_object_discount_unit_multiple' - $ref: '#/components/schemas/1_obj_voucher_object_discount_shipping' description: Defines the voucher discount type and details. redemption: type: object description: Defines the redemption limits on vouchers. properties: quantity: type: integer description: >- How many times a voucher can be redeemed. A `null` value means unlimited. code_config: type: object description: 'Defines code''s pattern (prefix, suffix, length, charset, etc). ' properties: length: type: string description: >- Number of characters in a generated code (excluding prefix and postfix). charset: type: string description: >- 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 prefix: type: string description: A text appended before the code. postfix: type: string description: A text appended after the code. pattern: type: string description: >- A pattern for codes where hashes (#) will be replaced with random characters. Overrides `length`. is_referral_code: type: boolean description: >- Flag indicating whether this voucher is a referral code; `true` for campaign type `REFERRAL_PROGRAM`. 2_obj_campaign_object_voucher_object_GIFT_CARD: type: object description: Schema model for a gift card. title: Gift Card properties: type: type: string default: GIFT_VOUCHER description: Type of voucher. gift: description: Defines the gift card details. type: object properties: amount: type: integer description: >- Initial gift card income to be applied to the gift card at voucher generation. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `$100.00`. effect: type: string description: Defines how the credits are applied to the customer's order. enum: - APPLY_TO_ORDER - APPLY_TO_ITEMS redemption: type: object description: Defines the redemption limits on vouchers. properties: quantity: type: integer description: >- How many times a voucher can be redeemed. A `null` value means unlimited. code_config: type: object description: 'Defines code''s pattern (prefix, suffix, length, charset, etc). ' properties: length: type: string description: >- Number of characters in a generated code (excluding prefix and postfix). charset: type: string description: >- 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 prefix: type: string description: A text appended before the code. postfix: type: string description: A text appended after the code. pattern: type: string description: >- A pattern for codes where hashes (#) will be replaced with random characters. Overrides `length`. is_referral_code: type: boolean description: >- Flag indicating whether this voucher is a referral code; `true` for campaign type `REFERRAL_PROGRAM`. 2_obj_campaign_object_voucher_object_LOYALTY_CARD: type: object description: Schema model for a loyalty card. title: Loyalty Card properties: type: type: string default: LOYALTY_CARD description: Type of voucher. loyalty_card: description: Defines the loyalty card details. type: object properties: points: type: integer description: >- Initial loyalty card income in points to be applied to the loyalty card at voucher generation. expiration_rules: type: object description: Defines point expiration rules. properties: period_type: type: string default: MONTH enum: - MONTH description: The expiration period. period_value: type: integer description: How many periods should pass before the expiration occurs. rounding_type: type: string enum: - END_OF_MONTH - END_OF_QUARTER - END_OF_HALF_YEAR - END_OF_YEAR - PARTICULAR_MONTH description: Round up expiration till the end of the given period type. redemption: type: object description: Defines the redemption limits on vouchers. properties: quantity: type: integer description: >- How many times a voucher can be redeemed. A `null` value means unlimited. code_config: type: object description: 'Defines code''s pattern (prefix, suffix, length, charset, etc). ' properties: length: type: string description: >- Number of characters in a generated code (excluding prefix and postfix). charset: type: string description: >- 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 prefix: type: string description: A text appended before the code. postfix: type: string description: A text appended after the code. pattern: type: string description: >- A pattern for codes where hashes (#) will be replaced with random characters. Overrides `length`. is_referral_code: type: boolean description: >- Flag indicating whether this voucher is a referral code; `true` for campaign type `REFERRAL_PROGRAM`. ValidityTimeframe: title: Validity Timeframe type: object description: >- 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`. properties: duration: type: string description: >- 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 interval: type: string description: >- 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 ValidityDayOfWeek: title: Validity Day Of Week type: array description: >- 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 items: type: integer enum: - 0 - 1 - 2 - 3 - 4 - 5 - 6 ValidityHours: title: Validity Hours type: object description: Determines the hours of validity, e.g. to create a happy hours scenario. properties: daily: type: array description: >- Defines the recurring period(s) when the resource is active. The periods should not overlap. items: type: object description: Defines the recurring period(s) when the resource will be active. properties: start_time: type: string format: time description: >- Defines the starting hour of validity in the HH:mm format. The resource is *inactive before* this time. example: '12:00' days_of_week: type: array description: >- 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 items: type: integer enum: - 0 - 1 - 2 - 3 - 4 - 5 - 6 expiration_time: type: string format: time description: >- Defines the ending hour of validity in the HH:mm format. The resource is *inactive after* this time. example: '14:00' Category: title: Category description: This is an object representing a category. type: object properties: id: type: string description: Unique category ID assigned by Voucherify. name: type: string description: Category name. hierarchy: type: integer description: >- Category hierarchy. Categories with lower hierarchy are processed before categories with higher hierarchy value. minimum: 0 object: type: string default: category enum: - category description: >- The type of the object represented by the JSON. This object stores information about the category. created_at: type: string description: >- 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' format: date-time updated_at: type: string example: '2022-08-16T10:52:08.094Z' description: >- Timestamp representing the date and time when the category was updated. The value is shown in the ISO 8601 format. format: date-time required: - id - name - hierarchy - created_at - object OrderBase: title: Order Base type: object description: Order information. properties: source_id: type: string nullable: true description: >- Unique source ID of an existing order that will be linked to the redemption of this request. For validation and redemption, if `source_id` is used with an existing order, the original order data will be used, like `items`, `amount`, and so on, not the one sent in the new request. status: type: string description: The order status. enum: - CREATED - PAID - CANCELED - FULFILLED amount: type: integer description: >- A positive integer in the smallest currency unit (e.g. 100 cents for $1.00) representing the total amount of the order. This is the sum of the order items' amounts. initial_amount: type: integer description: >- A positive integer in the smallest currency unit (e.g. 100 cents for $1.00) representing the total amount of the order. This is the sum of the order items' amounts. discount_amount: type: integer description: >- Sum of all order-level discounts applied to the order. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for $1.00). items: type: array description: Array of items applied to the order. It can include up to 500 items. items: $ref: '#/components/schemas/OrderItem' metadata: type: object description: >- A set of custom key/value pairs that you can attach to an order. It can be useful for storing additional information about the order in a structured format. It can be used to define business validation rules or discount formulas. CustomerBase: title: Customer Base type: object properties: name: type: string description: Customer's first and last name. description: type: string description: An arbitrary string that you can attach to a customer object. email: type: string description: Customer's email address. phone: type: string description: >- Customer's phone number. This parameter is mandatory when you try to send out codes to customers via an SMS channel. birthday: type: string description: '`Deprecated`. ~~Customer''s birthdate; format YYYY-MM-DD~~.' format: date birthdate: type: string description: Customer's birthdate; format YYYY-MM-DD. format: date address: type: object nullable: true description: Customer's address. properties: city: type: string description: City state: type: string description: State line_1: type: string description: First line of address. line_2: type: string description: Second line of address. country: type: string description: Country. postal_code: type: string description: Postal code. metadata: type: object description: >- A set of custom key/value pairs that you can attach to a customer. The metadata object stores all custom attributes assigned to the customer. It can be useful for storing additional information about the customer in a structured format. This metadata can be used for validating whether the customer qualifies for a discount or it can be used in building customer segments. 1_obj_voucher_object_discount_amount: title: Amount type: object description: Amount discount type. properties: type: type: string default: AMOUNT description: Applies an amount discount. amount_off: type: integer example: 100 description: >- 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. amount_off_formula: type: string description: Formula used to dynamically calculate the discount. aggregated_amount_limit: type: integer description: >- 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) effect: type: string enum: - APPLY_TO_ORDER - APPLY_TO_ITEMS - APPLY_TO_ITEMS_PROPORTIONALLY - APPLY_TO_ITEMS_PROPORTIONALLY_BY_QUANTITY - APPLY_TO_ITEMS_BY_QUANTITY description: >- 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) 1_obj_voucher_object_discount_percentage: title: Percentage type: object description: Percentage discount type. properties: type: type: string default: PERCENT description: Applies a percentage discount. amount_limit: type: string description: >- Upper limit allowed to be applied as a discount per order line item. Value is multiplied by 100 to precisely represent 2 decimal places. For example, a $6 maximum discount is written as 600. aggregated_amount_limit: type: integer description: >- Maximum discount amount per order. This value is definable for the `APPLY_TO_ITEMS` discount effect. 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. percent_off: type: integer description: >- Percent taken off the subtotal amount. In case of the percent being calculated by the formula, i.e. the `percent_off_formula` parameter is present in the percent 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 percent off. minimum: 0 maximum: 100 percent_off_formula: type: string description: Formula used to dynamically calculate the discount. effect: type: string enum: - APPLY_TO_ORDER - APPLY_TO_ITEMS description: Defines how the discount is applied to the customer's order. 1_obj_voucher_object_discount_fixed: title: Fixed description: Fixed discount type. type: object properties: type: type: string default: FIXED description: >- Sets a fixed total on cart or item(s) and then calculates the discount to apply. fixed_amount: type: integer description: >- Sets a fixed value for an order total or the item price. The value is multiplied by 100 to precisely represent 2 decimal places. For example, a $10 discount is written as 1000. If the fixed amount is calculated by the formula, i.e. the `fixed_amount_formula` parameter is present in the fixed amount definition, this value becomes the **fallback value**. As a result, if the formula cannot be calculated due to missing metadata, for example, this value will be used as the fixed value. example: 1000 fixed_amount_formula: type: string description: >- Formula used to dynamically calculate the discounted price of an item or a new order total. effect: type: string enum: - APPLY_TO_ORDER - APPLY_TO_ITEMS description: >- | **Effect** | **Definition** | |:---|:---| | **APPLY_TO_ORDER** | Sets the order total amount to the value of the fixed amount. The discount value is calculated dynamically during the redemption as it's a difference between the total amount of the customer's order and the fixed amount. For example, if the fixed amount is set to equal $10 and the order amount equals $25, then the calculated discount will be $15. | | **APPLY_TO_ITEMS** | Sets a new price on items. The total discount amount is dynamically calculated during the redemption and it's a difference between the initial item price and the fixed amount. During the redemption, prices for items will change only if the new price is lower than the original price. If the new product price you set is different from the product price in a collection, then the new product price will be passed during the redemption. If a prodct is in more than one collection, the price is always changed to the lowest price. The new price for products with several SKUs will force the price change for SKUs if their original price is higher than the new price. | 1_obj_voucher_object_discount_unit_one: title: Unit, single item type: object description: Single item type. properties: type: type: string default: UNIT description: Applies a full value discount to item(s). unit_off: type: number description: >- Number of units to be granted a full value discount. In case of the unit being calculated by the formula, i.e. the `unit_off_formula` parameter is present in the unit 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 unit value. example: 1 format: float unit_off_formula: type: string description: Formula used to dynamically calculate the number of units. unit_type: type: string description: >- The product deemed as free, chosen from the product inventory (e.g. time, items). example: prod_f1r5Tpr0DuC7 effect: type: string enum: - ADD_NEW_ITEMS - ADD_MISSING_ITEMS default: ADD_MISSING_ITEMS description: Defines how the unit is added to the customer's order. 1_obj_voucher_object_discount_unit_multiple: title: Unit, multiple items type: object description: Multiple item types. properties: type: type: string default: UNIT description: Applies a full value discount to item(s). effect: type: string default: ADD_MANY_ITEMS description: Defines the effect for adding multiple item types. units: type: array description: >- Array of objects defining items to be offered for free. Each item type can have a different discount effect assigned. items: type: object description: Object defining a unit discount. properties: unit_off: type: integer description: >- Number of units to be granted a full value discount. In case of the unit being calculated by the formula, i.e. the `unit_off_formula` parameter is present in the unit 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 unit value. example: 1 unit_off_formula: type: string description: Formula used to dynamically calculate the number of units. unit_type: type: string description: >- The product deemed as free, chosen from the product inventory (e.g. time, items). example: prod_f1r5Tpr0DuC7 effect: type: string enum: - ADD_NEW_ITEMS - ADD_MISSING_ITEMS description: Defines how the unit is added to the customer's order. 1_obj_voucher_object_discount_shipping: title: Shipping description: Shipping discount type. type: object properties: type: type: string default: UNIT description: Applies a full value discount to item(s). unit_off: type: number format: float description: Subtracts 1 shipping item from the subtotal. default: 1 unit_type: type: string description: The shipping product deemed as free. default: prod_5h1pp1ng effect: type: string description: Defines how the unit is added to the customer's order. default: ADD_MISSING_ITEMS OrderItem: type: object title: Order Item properties: sku_id: type: string description: Unique identifier of the SKU. It is assigned by Voucherify. product_id: type: string description: Unique identifier of the product. It is assigned by Voucherify. related_object: type: string enum: - product - sku description: >- Used along with the source_id property, can be set to either sku or product. source_id: type: string description: >- The merchant's product/SKU ID (if it is different from the Voucherify product/SKU ID). It is useful in the integration between multiple systems. It can be an ID from an eCommerce site, a database, or a third-party service. quantity: type: integer description: The quantity of the particular item in the cart. discount_quantity: type: integer description: Number of dicounted items. initial_quantity: type: integer description: >- A positive integer in the smallest unit quantity representing the total amount of the order; this is the sum of the order items' quantity. amount: type: integer description: The total amount of the order item (price * quantity). discount_amount: type: integer description: Sum of all order-item-level discounts applied to the order. initial_amount: type: integer description: >- A positive integer in the smallest currency unit (e.g. 100 cents for $1.00) representing the total amount of the order. This is the sum of the order items' amounts. price: type: integer description: >- Unit price of an item. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `$100.00`. product: type: object description: An object containing details of the related product. properties: id: type: string description: >- A unique identifier that represents the product and is assigned by Voucherify. source_id: type: string description: >- The merchant's product ID (if it is different than Voucherify's product ID). It is really useful in case of integration between multiple systems. It can be an ID from an eCommerce site, a database or a 3rd party service. override: type: boolean description: >- The override set to `true` is used to store the product information in the system. If the product does not exist, it will be created with a source_id; if it does exist, the provided values for the name, price, and metadata will replace those already stored in the system. Override works only for endpoints that create an order in the database. name: type: string description: Product name. metadata: type: object description: >- A set of custom key/value pairs that you can attach to a product. It can be useful for storing additional information about the product in a structured format. It can be used to create product collections. price: type: number description: >- Product price. A positive integer in the smallest currency unit (e.g. 100 cents for $1.00). sku: type: object description: An object containing details of the related SKU. properties: id: type: string description: >- A unique identifier that represents the SKU and is assigned by Voucherify. source_id: type: string description: >- The merchant's SKU ID (if it is different than Voucherify's SKU ID). It is really useful in case of integration between multiple systems. It can be an ID from an eCommerce site, a database or a 3rd party service. override: type: boolean description: >- The override set to `true` is used to store the product information in the system. If the product does not exist, it will be created with a source_id; if it does exist, the provided values for the name, price, and metadata will replace those already stored in the system. sku: type: string description: The SKU name. price: type: number description: >- SKU price. A positive integer in the smallest currency unit (e.g. 100 cents for $1.00). metadata: type: object description: >- A set of custom key/value pairs that you can attach to an order item. It can be useful for storing additional information about the order item in a structured format. It can be used to create product collections. metadata: type: object description: >- A set of custom key/value pairs that you can attach to an order item. It can be useful for storing additional information about the order item in a structured format. It can be used to define business validation rules. required: - object securitySchemes: X-App-Id: type: apiKey name: X-App-Id in: header X-App-Token: type: apiKey name: X-App-Token in: header X-Voucherify-OAuth: type: oauth2 flows: implicit: authorizationUrl: https://api.voucherify.io/v1/oauth/token scopes: api: Gives access to whole server-side API. vouchers: >- Gives access to all endpoints and methods starting with `v1/vouchers`. client_api: Gives access to whole client-side API. client_vouchers: >- Gives access to all endpoints and methods starting with `/client/v1/vouchers`. promotions: >- Gives access to all endpoints and methods starting with `/v1/promotions`. client_promotions: >- Gives access to all endpoints and methods starting with `/client/v1/promotions` campaigns: >- Gives access to all endpoints and methods starting with `v1/campaigns`. client_publish: >- Gives access to all endpoints and methods starting with `/client/v1/publish`. exports: >- Gives access to all endpoints and methods starting with `/v1/exports`. publications: >- Gives access to all endpoints and methods starting with `/v1/publications`. client_validate: >- Gives access to all endpoints and methods starting with `/client/v1/validate`. validations: >- Gives access to all endpoints and methods starting with `/v1/validations`. client_validations: >- Gives access to all endpoints and methods starting with `/client/v1/validations`. qualifications: >- Gives access to all endpoints and methods starting with `/v1/qualifications`. client_qualifications: >- Gives access to all endpoints and methods starting with `/client/v1/qualifications`. client_redeem: >- Gives access to all endpoints and methods starting with `/client/v1/redeem redemptions: >- Gives access to all endpoints and methods starting with `/v1/redemptions`. client_redemptions: >- Gives access to all endpoints and methods starting with `/client/v1/redemptions` customers: >- Gives access to all endpoints and methods starting with `/v1/customers`. client_customers: >- Gives access to all endpoints and methods starting with `/client/v1/customers`. orders: >- Gives access to all endpoints and methods starting with `/v1/orders`. products: >- Gives access to all endpoints and methods starting with `/v1/products`. skus: >- Gives access to all endpoints and methods starting with `/v1/SKUs`. validation-rules: >- Gives access to all endpoints and methods starting with `/v1/validation-rules`. validation-rules-assignments: >- Gives access to all endpoints and methods starting with `/v1/validation-rules-assignments segments: >- Gives access to all endpoints and methods starting with `/v1/segments`. events: >- Gives access to all endpoints and methods starting with `/v1/events`. client_events: >- Gives access to all endpoints and methods starting with `client/v1/events`. rewards: >- Gives access to all endpoints and methods starting with `/v1/rewards`. assets: >- Gives access to all endpoints and methods starting with `/v1/assets`. task-results: >- Gives access to all endpoints and methods starting with `/v1/task-results`. loyalties: >- Gives access to all endpoints and methods starting with `/v1/loyalties`. client_consents: >- Gives access to all endpoints and methods starting with `client/v1/consents`. consents: >- Gives access to all endpoints and methods starting with `/v1/consents`. async-actions: >- Gives access to all endpoints and methods starting with `/v1/async-actions`. product-collections: >- Gives access to all endpoints and methods starting with `/v1/product-collections`. categories: >- Gives access to all endpoints and methods starting with `/v1/categories`. metadata-schemas: >- Gives access to all endpoints and methods starting with `/v1/metadata-schemas`. locations: >- Gives access to all endpoints and methods starting with `/v1/locations`. referrals: >- Gives access to all endpoints and methods starting with `/v1/referrals`. trash-bin: >- Gives access to all endpoints and methods starting with `/v1/trash-bin`. templates: >- Gives access to all endpoints and methods starting with `/v1/templates`. ````