# Analyze overview Source: https://docs.voucherify.io/analyze/analyze-overview Track campaign performance, voucher activity, redemption analytics, and project audit logs After you build, optimize, and orchestrate campaigns, use the Analyze section to measure how they perform. Track campaign and voucher activity, review redemption analytics, and audit project changes to refine your incentive strategy. ## What you can analyze Monitor campaign performance, customer activity, and incentive usage with dedicated dashboards for each campaign type. Inspect individual vouchers, gift cards, and loyalty cards. Review redemption history and transaction details. Review project-level redemptions, revenue impact, API usage, and team activity in the Dashboard and Settings. Track API requests, user actions, background tasks, exports, and webhook deliveries across your project. ## Why analysis matters Campaigns generate data with every validation, redemption, and customer interaction. Turning that data into insight lets you: * **Measure ROI**: See which campaigns drive revenue, repeat purchases, and customer retention. * **Spot issues early**: Use logs and activity feeds to debug failed validations, misconfigured rules, or webhook errors. * **Iterate faster**: Compare performance across segments, channels, and time periods to refine the next iteration. * **Stay accountable**: Audit logs give you a full history of who changed what and when. ## What's next? Start with [campaign tracking](/analyze/campaign-tracking) for a high-level view of campaign performance. Use [voucher tracking](/analyze/voucher-tracking) to inspect individual codes, [performance analytics](/analyze/performance-analytics) for project-wide analytics, and [audit log](/analyze/audit-logs) to investigate specific changes or troubleshoot integrations. # Audit log Source: https://docs.voucherify.io/analyze/audit-logs Learn what audit log is, what data it includes, and how to use it in Voucherify The **Audit log** gives you a full history of activity in your Voucherify project. You can use them to track API requests, user actions, and system processes. The **Audit log** consists of: * **Logs**: Lists API requests and responses. Use logs for troubleshooting and debugging. * **Background tasks**: Lists asynchronous operations. Use this tab to monitor imports and system jobs like campaign or voucher updates. * **Exports**: Lists exported data files. Use this to download and review data. * **Webhook sendouts**: Lists webhook deliveries. Use this to track and retry webhook sendouts. ## Logs Data retention **Logs** are stored for a limited time: * Shared regions: 6 months * Dedicated regions: 12 months Use **Logs** to troubleshoot API requests, check errors, and inspect request and response data. Each time a request is sent to Voucherify (in the dashboard, through the API, or from an SDK), a log entry is created. By default, logs display data from the last 24 hours. You can change the time range using filters. Use other filters to narrow down results. Click a log ID to open detailed information about the API call, including its request and response in a JSON format. If a log is related to a CSV import, you can download the original file used in the import. Export logs You can export logs based on filters applied in the **Logs** tab. To export logs: 1. Apply filters to narrow down results. 2. Click **Export**. 3. Download the file when it is ready. Larger exports may take longer to generate. Advanced filters (enterprise) In addition to standard filters, you can narrow down the log results by text contained in the request or response body. Example: Investigating a failed request To investigate a failed request: 1. Go to the **Logs** tab. 2. Filter by **Status**: **Failure**. 3. Open the log ID. 4. Review the request and response details. ## Background tasks Use **Background tasks** to monitor long-running operations such as imports, exports, or campaign updates. Asynchronous actions triggered through the API also appear here. You can see if the task is enqueued, in progress, done, or failed. **Background tasks** are stored indefinitely. Click a task ID to view detailed information about the operation. Use filters to narrow down results. ## Exports Use **Exports** to list, manage, and download exported data files. It shows the history of generated export files. Click an export ID to view details such as applied filters and parameters. Use filters to narrow down results. API log export: Dashboard browser For API log exports, you can open the file directly in Voucherify without downloading the file. Click **Browse data** on a ready export to open it in a browser view. This may take a moment to load. The data is displayed for the columns selected during the export. Use the browser to search across the dataset or open the request and response bodies as JSONs. Use filters to narrow down results. Browsing is available only for: * API log exports. * Files ready for download. * Files not older than 90 days. ## Webhook sendouts Use **Webhook sendouts** to track webhook delivery. You can check if the webhook has been sent successfully, is being retried, or has failed. Click the three-dot **⋮** menu to: * See the sent data in the JSON format. * See error (if any). * Retry the sendout. Use filters to narrow down results. ## Related features Explore other features that complement audit logs when monitoring, debugging, and exporting project activity. Use webhooks to receive event notifications in your application instead of searching the audit logs. The **Webhook sendouts** tab shows the delivery history of these webhooks. Learn more about webhooks: * [Introduction to Voucherify webhooks](/api-reference/introduction-to-webhooks): Overview of project- and distribution-level webhooks. * [Project settings webhooks](/api-reference/project-settings-webhooks): Configure webhooks for project events such as redemptions, customer changes, or order updates. * [Distribution webhooks](/api-reference/distribution-webhooks): Configure webhooks for distribution events such as voucher publication and message delivery. The **Exports** tab lists files generated from the dashboard or through the API. Use the export API to trigger and download exports programmatically. Learn more about the export API: * [Export object](/api-reference/exports/export-object): Structure of the export resource. * [Create export](/api-reference/exports/create-export): Start a new export job. * [List exports](/api-reference/exports/list-exports): Retrieve all exports in your project. * [Get export](/api-reference/exports/get-export): Check the status and result of an export. * [Download export](/api-reference/exports/download-export): Download the generated file. * [CSV export with API](/guides/csv-export): Guide to exporting vouchers, redemptions, publications, and customers through the API. The **Background tasks** tab tracks the progress of long-running jobs such as imports and bulk updates. Learn more about imports: * [Customer import](/prepare/customers#data-import-and-synchronization) * [Product import](/prepare/products#bulk-import-with-csv) * [Discount code import](/build/discount-code-import) * [Gift card import](/build/gift-card-import) * [Loyalty card import](/build/loyalty-card-import) * [Referral code import](/build/referral-code-import) Use these resources to correlate audit log entries with your integration code: * [API overview](/guides/api-overview): Authentication, rate limits, and request structure. * [Management API](/guides/management-api): Manage projects, users, and resources programmatically. * [Limits](/guides/limits): API rate limits and quotas that may surface as failed requests in the logs. You can use **Background tasks** in combination with the following async actions endpoints: * [List async actions](/api-reference/async-actions/list-async-actions) * [Get async action](/api-reference/async-actions/get-async-action) Use these endpoints to track the progress and status of all async actions or get details about the result of a specific async action, for example for debugging. # Campaign tracking Source: https://docs.voucherify.io/analyze/campaign-tracking Track campaign performance, customer activity, and incentive usage across Voucherify campaigns Use Voucherify dashboards and analytics to track campaign performance, customer activity, and incentive usage across all campaign types. ## Track campaign performance Monitor performance, usage, and configuration details of each campaign with their dedicated dashboards and tabs. The available details depend on the campaign type. Solving issues with campaigns The **Activity** tab in campaign details is a great tool for solving issues you have with campaign configuration. The events listed contain all data regarding changes to the campaign as well as the API request and response payloads of those changes. ### Discount coupons The campaign dashboard provides a high-level overview of coupon campaign performance and configuration. The campaign dashboard shows: * **Campaign details**: Overview of the campaign configuration. * **Distribution overview**: Distributions related to the campaign. * **Budget management**: Information about orders, values, and applied discounts. * **Total validations, redemptions, rollbacks, publications** chart. * **Total vouchers created/deleted** chart. * **Access settings**: Lists assigned areas and stores (enterprise feature available on demand). Additional tabs provide detailed insights: * **Vouchers**: Manage all vouchers in the campaign. * **Rules**: View and manage validation rules for the campaign. * **Redemptions**: Track all redemption events with status and details. * **Publications**: Track voucher publication history and delivery status. * **Distributions**: Monitor campaign distributions and message delivery. * **Metadata**: View custom attributes attached to the campaign. * **Activity**: Track campaign-related events in chronological order (for example, configuration changes). * **Analytics**: Analyze campaign performance with detailed charts. ### Gift cards The campaign dashboard provides an overview of gift card campaign setup and usage. The campaign dashboard shows: * **Campaign details**: Overview of the campaign configuration. * **Distribution overview**: Distributions related to the campaign. * **Budget management**: Information about orders, values, and applied discounts. * **Total validations, redemptions, rollbacks, publications** chart. * **Total vouchers created/deleted** chart. * **Access settings**: Lists assigned areas and stores (enterprise feature available on demand). Additional tabs provide detailed insights: * **Vouchers**: Manage all gift card codes and view their details. * **Rules**: View and manage validation rules for the campaign. * **Redemptions**: Track all redemption events with status and details. * **Publications**: Track gift card publication history and delivery status. * **Distributions**: View distributions related to the campaign. * **Metadata**: View custom attributes attached to the campaign. * **Activity**: Track campaign-related events in chronological order. * **Transactions**: Track all balance changes (top-ups and redemptions) across all gift cards in the campaign. You can export transaction data for external analysis. * **Analytics**: Analyze campaign performance with detailed charts. ### Loyalty programs The campaign dashboard provides an overview of loyalty program performance, participation, and configuration. The campaign dashboard shows: * **Campaign details**: Overview of the campaign configuration. * **Publications, messages delivered, redemptions by distributions**: Distribution performance. * **Campaign point expiration**: Point expiration rules. * **Total validations, redemptions, rollbacks, publications** chart. * **Total points**: Aggregated points earned, redeemed, expired, and more. * **Total vouchers created/deleted** chart. * **Access settings**: Lists assigned areas and stores (enterprise feature available on demand). Additional tabs provide detailed insights: * **Loyalty cards**: Manage all loyalty cards and view balances and details. * **Tiers**: View the setup of your program levels. * **Earning rules**: View and manage earning rules. * **Rewards catalog**: View available rewards and their point costs. * **Participants**: View all customers with assigned loyalty cards. * **Metadata**: View custom attributes attached to the campaign. * **Reward redemptions**: Track points-for-rewards exchanges. * **Distributions**: View distributions related to the campaign. * **Activity**: Track campaign-related configuration events (for example, changes to rules or rewards). * **Points expiration**: View upcoming point expirations and export the data as CSV. * **Pending points**: Manage points that are not yet redeemable. * **Transactions**: Track all point balance changes. You can export transaction data for external analysis. * **Analytics**: Analyze campaign performance with detailed charts. ### Referral programs The campaign dashboard provides an overview of referral performance, participants, and reward distribution. The campaign dashboard shows: * **Referral codes**: Number of created referral codes and general program details. * **Publications, messages delivered, redemptions by distributions**: Distribution performance. * **Conversion event**: The conversion event used in the campaign. * **Program in numbers**: Overview of referrals and participants. * **Total referred**: Total customers invited through the program, including a time-based chart. * **Referrers rewards summary**: Overview of rewards granted to referrers. * **Top 5 referrers**: Most successful advocates. * **Access settings**: Lists assigned areas and stores (enterprise feature available on demand). Additional tabs provide detailed insights: * **Rewards**: View the referral workflow and reward tiers. * **Referral codes**: Manage all referral codes and view their details. * **Rules**: View and manage validation and eligibility rules. * **Redemptions**: Track all redemption events with status and details. * **Referrers**: View all program participants and their codes. * **Referees**: View invited customers and their activity. * **Distributions**: View distributions related to the campaign. * **Reward redemptions**: Track referral reward redemptions by status. * **Metadata**: View custom attributes attached to the campaign. * **Activity**: Track campaign-related events in chronological order. ### Promotion campaigns The promotion campaign dashboard gives you a compact overview of the campaign setup, promotion tiers, and redemption activity. The campaign dashboard shows: * **Campaign details**: Basic campaign information, such as the assigned category. * **Access settings**: Assigned areas and stores, or a notice if the campaign is not assigned to any. * **Redemption values**: A summary of promotion tiers with their order discount amounts and application scope. * **Total validations, redemptions, rollbacks** chart: Campaign activity over time. Additional tabs provide detailed insights: * **Tiers**: View and manage all promotion tiers in the campaign. * **Redemptions**: Track all redemption events with status and details. * **Metadata**: View custom attributes attached to the campaign. * **Activity**: Track campaign-related events in chronological order. * **Analytics**: Analyze campaign performance with detailed charts. ## Track customer activity in campaigns You can track individual customer activity across campaigns to troubleshoot issues or analyze behavior. 1. In **Engagement** in the left panel, go **Customers** and click on a given customer to open their profile. 2. Open the **Activity** tab. 3. **Add filter** to select a specific campaign or view activities from all campaigns. 4. Optionally, filter by **Occurrence date** to define a time range. ## Use Campaign calendar The **Campaign calendar** provides a timeline view of all your campaigns. Go to **Marketer Hub** > **Campaign calendar** to see: * Active and scheduled campaigns * Campaign start and end dates * Campaign details when you select a campaign bar The Campaign calendar shows campaigns after you save them or save them as drafts. ## Related features Get better results when tracking your campaigns with the following ideas. You can use [Get campaign summary](/api-reference/campaigns/get-campaign-summary) API endpoint to return campaign performance data for analytics. The data covers publications, validations, redemptions, and other data that's specific to a given campaign type. You can programmatically manage transactions for loyalty and gift card campaigns with the following endpoints: * [List campaign transactions](/api-reference/campaigns/list-campaign-transactions) * [Export campaign transactions](/api-reference/campaigns/export-campaign-transactions) You can track campaign behavior programmatically with webhooks configured in **Project settings**. When you set up project-level webhooks, Voucherify sends automatic notifications to your endpoint whenever campaign events occur. Campaign-related webhook events you can subscribe to: * [Campaign created](/api-reference/campaign/created) * [Campaign updated](/api-reference/campaign/updated) * [Campaign enabled](/api-reference/campaign/enabled) * [Campaign disabled](/api-reference/campaign/disabled) * [Campaign deleted](/api-reference/campaign/deleted) * [Campaign voucher generation completed](/api-reference/campaign/vouchers-generation-completed) You can also track promotion tier changes within campaigns: * [Promotion tier created](/api-reference/campaign/promotion-tier-created) * [Promotion tier updated](/api-reference/campaign/promotion-tier-updated) * [Promotion tier enabled](/api-reference/campaign/promotion-tier-enabled) * [Promotion tier disabled](/api-reference/campaign/promotion-tier-disabled) * [Promotion tier deleted](/api-reference/campaign/promotion-tier-deleted) To configure webhooks, go to **Project settings** > **Webhooks** and select the events you want to receive. See [Project settings webhooks](/api-reference/project-settings-webhooks) for setup instructions and [Introduction to webhooks](/api-reference/introduction-to-webhooks) for authentication and payload details. # Performance analytics Source: https://docs.voucherify.io/analyze/performance-analytics Learn what analytics data Voucherify displays in the Dashboard, Team Settings, and Project Settings Voucherify provides analytics tools that help you monitor promotional performance and system usage. You can review data in three main places: * **Dashboard**: Project-level overview of redemptions, API calls, and campaign performance for marketers. * **Project Settings**: Project-specific usage analytics for project admins. * **Team Settings**: Organization-level usage analytics for account owners. ## Dashboard overview The home **Dashboard** shows a summary of activity in your project. You can select a time window in the top right corner. ### Key metrics At the top of the dashboard, there are indicators that help you understand promotional activity and overall platform usage: * **Total redemptions**: The total number of successful voucher and promotion redemptions in the selected period. * **Revenue impact**: The total discount value applied to orders. * **Active campaigns**: The number of campaigns that are currently running. * **Daily API calls**: The total number of API requests in the selected period. ### Redemption trends The **Redemption trends** chart shows how successful and failed redemptions change over time. This allows you to compare success and failure rates during the selected timeframe. Use this data to monitor campaign health, promotion tactics, and weak points in the customer journey. ### Top campaigns The Top campaigns table shows campaigns with the highest number of redemptions. The table includes: * Campaign name * Number of redemptions * Success rate * Trend indicator The trend indicator compares this period with the previous one to display the performance direction. ### Insights and alerts The **Insights & alerts** section displays important notifications related to your campaigns, for example, a campaign is about to expire. Each alert includes basic information and a direct action button, such as reviewing or extending a campaign. ## Project settings Required permissions By default, the account owner can access Project Settings. Users with proper access granted by the owner, such as users assigned the default Admin role, can also view and manage Project Settings. **Project settings** provide analytics for the current project environment. In the **API usage** tab, you can monitor: * API calls per hour in the current project * API calls during the subscription cycle * Integration webhook calls per day * Messages per day * Messages per month Some charts may show organization-level limits when those limits also apply to the project. ## Team settings Required permissions Only the account owner can view and manage **Team settings**. The **Subscription** tab in **Team settings** provides organization-level analytics across all projects in your account. This way you can track API call, message, and webhook usage. Go to **Team settings** > **Subscription** to view the following usage data: * **Management API calls per hour**: Monitor the frequency of management API requests across the entire account. Enterprise feature The Management API is an enterprise feature. Contact [Voucherify support](https://www.voucherify.io/contact-support) or your account manager to enable this functionality. * **API calls per hour in a project**: Track API traffic for specific projects. This chart displays the activity relative to the API limit defined in your current plan. * **API calls per subscription cycle**: View the total number of API calls used during the current billing period to ensure your account remains within plan limits. * **Integration webhook calls per day**: Analyze the volume of webhook traffic generated by external integrations connected to your Voucherify account. * **Messages per day and per month**: Monitor the total volume of distribution messages sent across all projects to track communication outreach. # Voucher tracking Source: https://docs.voucherify.io/analyze/voucher-tracking Track voucher activity and transactions for gift and loyalty cards Open a voucher's detail view to see how it's used and managed." The detailed view of a voucher shows its: * Details, like its parent campaign, voucher owner, and info specific to the voucher type. * Voucherify ID. * Barcode and QR code. * Redemption overview. From the detailed view, you can go to other tabs to track voucher usage, check any failures, and use the data to debug errors. ## Find vouchers Use the **Vouchers** view to browse and search all voucher types in one place. Go to **Campaign Hub** > **Campaigns** > **Vouchers** to see all your codes, including: * Discount coupons * Gift cards * Referral codes * Loyalty cards Use filters to narrow down the list of vouchers based on selected criteria. You can also use **Search codes** on the left bar to find a voucher by its code. ### Use categories Use **Categories** to organize vouchers and filter them faster. You can create a category when you create a campaign or add it later in the voucher details. To manage categories, go to **Campaigns** > **Categories**. Categories can also have a hierarchy. The lower the number, the higher the category priority in stacking rules. ## Redemptions and validations The **Redemptions** and **Validations** tabs list successful and unsuccessful redemption and validation attempts. **Add filter** to narrow down results. Click on ID to learn more about the event, access its log, and request and response payloads. You can also export redemption data to a CSV file. Validation data is stored for 30 days. **Logs** are stored for a limited time: * Shared regions: 6 months * Dedicated regions: 12 months ## Voucher activity The **Activity** tab lists all events related to the voucher, like creation, updates, or deactivation. **Add filter** to narrow down results. Click **Log** to learn more about the event, see related events, and request and response payloads. Solving issues with vouchers The **Activity** tab in voucher details is a great tool for solving issues you have with voucher configuration, validation, and redemption. The events listed contain all data regarding changes to the campaign as well as the API request and response payloads of those changes. ## Track gift and loyalty card transactions In the detailed view of a gift or loyalty card, use the **Transactions** tab to monitor balance changes. The **Transactions** tab lists: * Transaction type: For example, point or credit redemption. * Balance: Current number of points or credits * Creation date: When the transaction occurred. * Transaction details (**+** button), which show the transaction in a JSON format. ## Export for data tracking Use exports to download voucher and transaction data for reporting. The export tool looks similar for all exports. Choose which standard fields and custom attributes (metadata) to include in the exported CSV. The date and times of the exported data are in the UTC time zone. Once ready, **Export** your list. The file will be generated and delivered to your **Notifications Center**. You can also find all your exported files in **Audit log** > **Exports**. Larger exports may take longer to generate. ### Export vouchers Export voucher data to review or analyze voucher usage. To export all or filtered vouchers: 1. Go to **Vouchers**. 2. Apply filters (optional). 3. Click **Manage filtered vouchers**. 4. Click **Export filtered vouchers**. You can also export vouchers by going to a campaign and clicking the three-dot **⋮** menu > **Export to CSV**. This exports all vouchers, even if filters are applied. ### Export transactions Export transactions directly from the **Transactions** tab. Click **Export**, then choose which fields to include in the CSV file. You can export the following fields for gift card transactions: * ID: Unique Voucherify transaction ID. * Type: Type of the transaction, for example `CREDITS_ADDITION`. * Source ID: Optional source ID of the transaction. * Reason: Optional reason added to the transaction. * Balance: The number of available credits after the transaction. * Amount: The number of credits added or subtracted in the transaction. * Creation date: The date and time when the transaction was created (in UTC time zone). * Voucher ID: Unique Voucherify ID of the gift card. * Campaign ID: Unique Voucherify ID of the parent campaign. * Source: The origin of the transaction, for example Voucherify web UI. * Details: JSON payload of the transaction details. You can export the following fields for loyalty card transactions: * ID: Unique Voucherify transaction ID. * Type: Type of the transaction, for example `POINTS_ACCRUAL`. * Source ID: Optional source ID of the transaction. * Reason: Optional reason added to the transaction. * Balance: The number of available points after the transaction. * Amount: The number of points added or subtracted in the transaction. * Creation date: The date and time when the transaction was created (in UTC time zone). * Voucher ID: Unique Voucherify ID of the loyalty card. * Campaign ID: Unique Voucherify ID of the parent campaign. * Source: The origin of the transaction, for example Voucherify web UI. * Details: JSON payload of the transaction details. * Related transaction ID: Unique Voucherify transaction ID related to a receiver/donor card when points were transferred from/to another card. ### Export redemptions You can export redemptions from the main **Redemptions** tab or from a selected campaign. Use filters to narrow down the results. To export redemptions for a specific voucher or vouchers, use the **Voucher code** filter. ## Related features Learn more about features related to voucher tracking. For campaign performance and analytics, see [Campaign tracking](/analyze/campaign-tracking). Categories can be used to organize vouchers and campaigns, but they are primarily used for stacking rules. Stacking rules define how incentives like vouchers behave when they're redeemed together. Stacking rules can influence the order of application, which incentives can be used exclusively, how discounts are calculated together, and many other details. Learn more about [stacking rules and categories](/orchestrate/stacking-rules-overview). Track voucher activity programmatically with the Voucherify API. Use these endpoints to inspect redemptions, validations, gift card and loyalty card transactions. Redemptions: * [List redemptions](/api-reference/redemptions/list-redemptions): List all redemptions across the project, with filters for voucher, customer, campaign, result, and date range. * [Get voucher's redemptions](/api-reference/redemptions/get-vouchers-redemptions): List redemptions for a specific voucher code. * [Redemption object](/api-reference/redemptions/redemption-object): Schema reference for redemption payloads. * [Rollback redemption](/api-reference/redemptions/rollback-redemption) / [Rollback stackable redemptions](/api-reference/redemptions/rollback-stackable-redemptions): Reverse a redemption. Gift card and loyalty card transactions: * [List voucher transactions](/api-reference/vouchers/list-voucher-transactions): List credit or point transactions for a single voucher. * [Export voucher transactions](/api-reference/vouchers/export-voucher-transactions): Trigger a CSV export of transactions for a voucher. * [List campaign transactions](/api-reference/campaigns/list-campaign-transactions) / [Export campaign transactions](/api-reference/campaigns/export-campaign-transactions): Transactions across all vouchers in a campaign. Exports: * Use the [Exports API](/api-reference/exports/create-export) to generate CSV exports of vouchers, redemptions, and transactions. You can also subscribe to voucher events with webhooks (for example, `voucher.redeemed`, `voucher.updated`, `voucher.disabled`) to receive activity in real time. See: * [Introduction to webhooks](/api-reference/introduction-to-webhooks) * [Project settings webhooks](/api-reference/project-settings-webhooks) * [Distribution webhooks](/api-reference/distribution-webhooks) Learn more about the following voucher events: * [Voucher created](/api-reference/voucher/created) * [Voucher disabled](/api-reference/voucher/disabled) * [Voucher enabled](/api-reference/voucher/enabled) * [Voucher updated](/api-reference/voucher/updated) * [Voucher published](/api-reference/voucher/published) * [Voucher loyalty card pending points activated](/api-reference/voucher/loyalty-card-pending-points-activated) * [Voucher loyalty card pending points added](/api-reference/voucher/loyalty-card-pending-points-added) * [Voucher loyalty card pending points canceled](/api-reference/voucher/loyalty-card-pending-points-canceled) * [Voucher loyalty card pending points updated](/api-reference/voucher/loyalty-card-pending-points-updated) * [Voucher loyalty card points added](/api-reference/voucher/loyalty-card-points-added) * [Voucher loyalty card points expired](/api-reference/voucher/loyalty-card-points-expired) * [Voucher loyalty card transaction created](/api-reference/voucher/loyalty-card-transaction-created) * [Voucher gift transaction created](/api-reference/voucher/gift-transaction-created) * [Voucher gift balance added](/api-reference/voucher/gift-balance-added) * [Voucher deleted](/api-reference/voucher/deleted) # Async Action Object Source: https://docs.voucherify.io/api-reference/async-actions/async-action-object

Async Action

This is an object representing an asynchronous action.

All of:

Async Action Base

Attributes	Description
result	One of: CAMPAIGN.VOUCHERS\_IMPORT CAMPAIGN.VOUCHERS\_IMPORT\_CSV CAMPAIGN.VOUCHERS\_UPDATE CAMPAIGN.VOUCHERS\_DELETE CAMPAIGN.VOUCHERS\_GENERATE CAMPAIGNS.METADATA\_KEY\_PURGE CUSTOMERS.IMPORT\_CSV CUSTOMERS.BULK\_UPDATE CUSTOMERS.METADATA\_UPDATE CUSTOMERS.METADATA\_KEY\_PURGE PRODUCTS.BULK\_UPDATE PRODUCTS.METADATA\_UPDATE PRODUCTS.IMPORT\_CSV SKUS.IMPORT\_CSV PRODUCTS.METADATA\_KEY\_PURGE VOUCHERS.IMPORT VOUCHERS.IMPORT\_CSV VOUCHERS.BULK\_UPDATE VOUCHERS.METADATA\_UPDATE VOUCHERS.METADATA\_KEY\_PURGE ORDERS.IMPORT ORDERS.METADATA\_KEY\_PURGE

Attributes

Description

result

One of:

CAMPAIGN.VOUCHERS\_IMPORT
CAMPAIGN.VOUCHERS\_IMPORT\_CSV
CAMPAIGN.VOUCHERS\_UPDATE
CAMPAIGN.VOUCHERS\_DELETE
CAMPAIGN.VOUCHERS\_GENERATE
CAMPAIGNS.METADATA\_KEY\_PURGE
CUSTOMERS.IMPORT\_CSV
CUSTOMERS.BULK\_UPDATE
CUSTOMERS.METADATA\_UPDATE
CUSTOMERS.METADATA\_KEY\_PURGE
PRODUCTS.BULK\_UPDATE
PRODUCTS.METADATA\_UPDATE
PRODUCTS.IMPORT\_CSV
SKUS.IMPORT\_CSV
PRODUCTS.METADATA\_KEY\_PURGE
VOUCHERS.IMPORT
VOUCHERS.IMPORT\_CSV
VOUCHERS.BULK\_UPDATE
VOUCHERS.METADATA\_UPDATE
VOUCHERS.METADATA\_KEY\_PURGE
ORDERS.IMPORT
ORDERS.METADATA\_KEY\_PURGE

Async Action Base

Attributes	Description
id `string`	Async action unique ID. Example: aa\_0adad13d6f057f088e
type `string`	Type of async action. Available values: `CAMPAIGN.VOUCHERS\_IMPORT`, `CAMPAIGN.VOUCHERS\_IMPORT\_CSV`, `CAMPAIGN.VOUCHERS\_UPDATE`, `CAMPAIGN.VOUCHERS\_DELETE`, `CAMPAIGN.VOUCHERS\_GENERATE`, `CAMPAIGNS.METADATA\_KEY\_PURGE`, `CUSTOMERS.IMPORT\_CSV`, `CUSTOMERS.BULK\_UPDATE`, `CUSTOMERS.METADATA\_UPDATE`, `CUSTOMERS.METADATA\_KEY\_PURGE`, `PRODUCTS.BULK\_UPDATE`, `PRODUCTS.METADATA\_UPDATE`, `PRODUCTS.METADATA\_KEY\_PURGE`, `PRODUCTS.IMPORT\_CSV`, `SKUS.IMPORT\_CSV`, `VOUCHERS.IMPORT`, `VOUCHERS.IMPORT\_CSV`, `VOUCHERS.BULK\_UPDATE`, `VOUCHERS.METADATA\_UPDATE`, `VOUCHERS.METADATA\_KEY\_PURGE`, `ORDERS.IMPORT`, `ORDERS.METADATA\_KEY\_PURGE`
status `string`	Status of the async action. Informs you whether the async action has already been completed. Available values: `DONE`, `ENQUEUED`, `FAILED`, `IN\_PROGRESS`
operation\_status `string`	Status of async action processing. Informs about the async action status, whether it failed, succeeded, or the status is unknown. Available values: `FAILED`, `SUCCESS`, `UNKNOWN`
created\_at `string`	Timestamp representing the date and time when the async action was scheduled in ISO 8601 format. Example: 2022-06-23T11:21:45.578Z
updated\_at `string`	Timestamp representing the date and time when the async action was updated. The value is shown in the ISO 8601 format. Example: 2022-06-23T11:21:46.795Z
request\_id `string`	Unique request ID. Example: v-0b45cee140c3c9b5ca
processing\_time `integer`	The length of time it took to process the request in milliseconds. Example: 1217
progress `integer`	% progress to completion of the asynchronous action.
object `string`	The type of the object represented by JSON. This object stores information about the `async\_action`. Available values: `async\_action`

CAMPAIGN.VOUCHERS\_IMPORT

Attributes Description

message
string

A human-readable message providing a short description about the result.

failed
array

If any records failed during the process, this array shows the failure details.

Array of:

Attributes	Description
code `string`	Unique voucher code.
reason `string`	Detailed failure cause for the voucher code import.

done\_count
integer

Number of resources processed successfully.

failed\_count
integer

Number of resources failed to process.

CAMPAIGN.VOUCHERS\_IMPORT\_CSV

Attributes Description

message
string

A human-readable message providing a short description about the result.

failed
array

If any records failed during the process, this array shows the failure details.

Array of:

Attributes	Description
code `string`	Unique voucher code.
row `integer`	The CSV file row number where the code definition is recorded. The row counter excludes the file headers row.
reason `string`	Detailed failure cause for the voucher code import.

done\_count
integer

Number of resources processed successfully.

failed\_count
integer

Number of resources failed to process.

CAMPAIGN.VOUCHERS\_UPDATE

Attributes	Description
message `string`	A human-readable message providing a short description about the result.
done\_count `integer`	Number of resources processed successfully.

CAMPAIGN.VOUCHERS\_DELETE

Attributes	Description
message `string`	A human-readable message providing a short description about the result.
done\_count `integer`	Number of resources processed successfully.

CAMPAIGN.VOUCHERS\_GENERATE

Attributes	Description
message `string`	A human-readable message providing a short description about the result.
done\_count `integer`	Number of resources processed successfully.

CAMPAIGNS.METADATA\_KEY\_PURGE

Attributes	Description
message `string`	A human-readable message providing a short description about the result.
done\_count `integer`	Number of resources processed successfully.

CUSTOMERS.IMPORT\_CSV

Attributes Description

message
string

A human-readable message providing a short description about the result.

failed
array

If any records failed during the process, this array shows the failure details.

Array of:

Attributes	Description
source\_id `string`	Unique customer ID from your inventory system as indicated in the CSV file.
row `integer`	The CSV file row number where the customer is recorded. The row counter excludes the file headers row.
reason `string`	Detailed failure cause for the customer import.

done\_count
integer

Number of resources processed successfully.

failed\_count
integer

Number of resources failed to process.

CUSTOMERS.BULK\_UPDATE

All of:

Async Action Voucher Customer Product Bulk Update Result

Attributes Description

errors
array

List of errors encountered during processing.

Array of:

Attributes	Description
message `string`	A human-readable message providing a short description of the error.
details `string`	A human-readable message providing more details about the error.
key `string`	Short string describing the kind of error which occurred.
source\_id `string`	Source identifier of the customer for which the error occurred.

CUSTOMERS.METADATA\_UPDATE

Attributes Description

errors
array

List of errors encountered during processing.

Array of:

Attributes	Description
message `string`	A human-readable message providing a short description of the error.
details `string`	A human-readable message providing more details about the error.
key `string`	Short string describing the kind of error which occurred.

CUSTOMERS.METADATA\_KEY\_PURGE

Attributes	Description
message `string`	A human-readable message providing a short description about the result.
done\_count `integer`	Number of resources processed successfully.

PRODUCTS.BULK\_UPDATE

All of:

Async Action Voucher Customer Product Bulk Update Result

Attributes Description

errors
array

List of errors encountered during processing.

Array of:

Attributes	Description
message `string`	A human-readable message providing a short description of the error.
details `string`	A human-readable message providing more details about the error.
key `string`	Short string describing the kind of error which occurred.
source\_id `string`	Source identifier of the product for which the error occurred.

PRODUCTS.METADATA\_UPDATE

Attributes Description

errors
array

List of errors encountered during processing.

Array of:

Attributes	Description
message `string`	A human-readable message providing a short description of the error.
details `string`	A human-readable message providing more details about the error.
key `string`	Short string describing the kind of error which occurred.

PRODUCTS.IMPORT\_CSV

Attributes Description

message
string

A human-readable message providing a short description about the result.

failed
array

If any records failed during the process, this array shows the failure details.

Array of:

Attributes	Description
row `integer`	The CSV file row number where the product definition is recorded. The row counter excludes the file headers row.
source\_id `string`	The source identifier of the product that caused the error.
reason `string`	Detailed failure cause for the product import.

done\_count
integer

Number of resources processed successfully.

failed\_count
integer

Number of resources failed to process.

SKUS.IMPORT\_CSV

Attributes Description

message
string

A human-readable message providing a short description about the result.

Example: 2 sku(s) imported successfully, 6 failed.

failed
array

If any records failed during the process, this array shows the failure details.

Array of:

Attributes Description

row
integer

The CSV file row number where the SKU definition is recorded. The row counter excludes the file headers row.

Example: 2

reason
string

Detailed failure cause for the SKU import.

Example: Resource sku with id size-small is in use by products with ids \[prod\_0b0e3441c2462eff2c]

done\_count
integer

Number of resources processed successfully.

failed\_count
integer

Number of resources failed to process.

PRODUCTS.METADATA\_KEY\_PURGE

Attributes	Description
message `string`	A human-readable message providing a short description about the result.
done\_count `integer`	Number of resources updated successfully.

VOUCHERS.IMPORT

Attributes Description

message
string

A human-readable message providing a short description about the result.

failed
object

If any records failed during the process, this array shows the failure details.

Attributes	Description
code `string`	Unique voucher code.
reason `string`	Detailed failure cause for the voucher code import.

done\_count
integer

Number of resources processed successfully.

failed\_count
integer

Number of resources failed to process.

VOUCHERS.IMPORT\_CSV

Attributes Description

message
string

A human-readable message providing a short description about the result.

failed
array

If any records failed during the process, this array shows the failure details.

Array of:

Attributes	Description
code `string`	Unique voucher code.
row `integer`	The CSV file row number where the code definition is recorded. The row counter excludes the file headers row.
reason `string`	Detailed failure cause for the voucher code import.

done\_count
integer

Number of resources processed successfully.

failed\_count
integer

Number of resources failed to process.

VOUCHERS.BULK\_UPDATE

All of:

Async Action Voucher Customer Product Bulk Update Result

Attributes Description

errors
array

List of errors encountered during processing.

Array of:

Attributes	Description
message `string`	A human-readable message providing a short description of the error.
details `string`	A human-readable message providing more details about the error.
key `string`	Short string describing the kind of error which occurred.
code `string`	Code of the voucher for which the error occurred.

VOUCHERS.METADATA\_UPDATE

Attributes Description

errors
array

List of errors encountered during processing.

Array of:

Attributes	Description
message `string`	A human-readable message providing a short description of the error.
details `string`	A human-readable message providing more details about the error.
key `string`	Short string describing the kind of error which occurred.

VOUCHERS.METADATA\_KEY\_PURGE

Attributes	Description
message `string`	A human-readable message providing a short description about the result.
done\_count `integer`	Number of resources processed successfully.

ORDERS.IMPORT

Attributes Description

message
string

A human-readable message providing a short description about the result.

failed
object

If any records failed during the process, this array shows the failure details.

Attributes	Description
source\_id `string`	Unique order source ID.
reason `string`	Detailed failure cause for the voucher code import.

done\_count
integer

Number of resources processed successfully.

failed\_count
integer

Number of resources failed to process.

ORDERS.METADATA\_KEY\_PURGE

Attributes	Description
message `string`	A human-readable message providing a short description about the result.
done\_count `integer`	Number of resources processed successfully.

Async Action Voucher Customer Product Bulk Update Result

Attributes	Description
done\_count `integer`	Number of items successfully processed.
failed\_count `integer`	Number of items that failed to be processed.
reports `array`	List of URLs to report files.
reports\_available\_till `string`	Timestamp until the reports are available.

# Get Async Action Source: https://docs.voucherify.io/api-reference/async-actions/get-async-action /openapi/async-actions.json get /v1/async-actions/{asyncActionId} Check the result of a scheduled asynchronous operation. The table below lists the possible types of async actions. The types are different for each endpoint generating the async action. | **Types by Context** | **Endpoint** | |:---|:---| | **CAMPAIGN** | | | CAMPAIGN.VOUCHERS_IMPORT | **POST** [`/campaigns/{campaignId}/import`](/api-reference/campaigns/import-vouchers-to-campaign) | | CAMPAIGN.VOUCHERS_IMPORT_CSV | **POST** [`/campaigns/{campaignId}/importCSV`](/api-reference/campaigns/import-vouchers-to-campaign-by-csv) | | CAMPAIGN.VOUCHERS_UPDATE | **PUT** [`/campaigns/{campaignId}`](/api-reference/campaigns/update-campaign) | | CAMPAIGN.VOUCHERS_DELETE | **DELETE** [`/campaigns/{campaignId}`](/api-reference/campaigns/delete-campaign) | | CAMPAIGN.VOUCHERS_GENERATE |

**POST** [`/campaigns`](/api-reference/campaigns/create-campaign): asynchronous for campaigns with more than 1 voucher, synchronous for campaign with 1 voucher
**POST** [`/campaigns/{campaignId}/vouchers`](/api-reference/campaigns/add-vouchers-to-campaign)

**POST** [`/campaigns`](/api-reference/campaigns/create-campaign): asynchronous for campaigns with more than 1 voucher, synchronous for campaign with 1 voucher
**POST** [`/campaigns/{campaignId}/vouchers`](/api-reference/campaigns/add-vouchers-to-campaign)

| | **CUSTOMERS** | | | CUSTOMERS.IMPORT_CSV | **POST** [`/customers/importCSV`](/api-reference/customers/import-and-update-customers-using-csv) | | CUSTOMERS.BULK_UPDATE | **POST** [`/customers/bulk/async`](/api-reference/customers/update-customers-in-bulk) | | CUSTOMERS.METADATA_UPDATE | **POST** [`/customers/metadata/async`](/api-reference/customers/update-customers-metadata-in-bulk) | | **PRODUCTS** | | | PRODUCTS.BULK_UPDATE | **POST** [`/products/bulk/async`](/api-reference/products/update-products-in-bulk)
| | PRODUCTS.METADATA_UPDATE | **POST** [`/products/metadata/async`](/api-reference/products/update-products-metadata-in-bulk) | | PRODUCTS.IMPORT_CSV | **POST** [`/products/importCSV`](/api-reference/products/import-products-using-csv) | | SKUS.IMPORT_CSV | **POST** [`/skus/importCSV`](/api-reference/products/import-skus-using-csv) | | **VOUCHERS** | | | VOUCHERS.IMPORT | **POST** [`/vouchers/import`](/api-reference/vouchers/import-vouchers) | | VOUCHERS.IMPORT_CSV | **POST** [`/vouchers/importCSV`](/api-reference/vouchers/import-vouchers-using-csv) | | VOUCHERS.BULK_UPDATE | **POST** [`/vouchers/bulk/async`](/api-reference/vouchers/update-vouchers-in-bulk)
| | VOUCHERS.METADATA_UPDATE | **POST** [`/vouchers/metadata/async`](/api-reference/vouchers/update-vouchers-metadata-in-bulk) | | **ORDERS** | | | ORDERS.IMPORT | **POST** [`/orders/import`](/api-reference/orders/import-orders) | | **METADATA KEY PURGE** | | | CAMPAIGNS.METADATA_KEY_PURGE
CUSTOMERS.METADATA_KEY_PURGE
PRODUCTS.METADATA_KEY_PURGE
VOUCHERS.METADATA_KEY_PURGE
ORDERS.METADATA_KEY_PURGE | No API endpoint equivalent. You can perform this action through the Dashboard. See Dashboard documentation: Dashboard > [Project Settings](/prepare/metadata#maintenance) | # Activate benefit Source: https://docs.voucherify.io/api-reference/benefits/activate-benefit /openapi/loyalties-v2.json post /v2/loyalties/benefits/{benefitId}/activate Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Moves a benefit from `DRAFT` to `ACTIVE` status. No request body. Only the `DRAFT` -> `ACTIVE` transition is allowed; activating from any other state returns 400 `invalid_state_transition`. A points-based benefit cannot be activated when its connected card definition does not exist or is not ACTIVE (423 `resource_locked`). # Create benefit Source: https://docs.voucherify.io/api-reference/benefits/create-benefit /openapi/loyalties-v2.json post /v2/loyalties/benefits Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Creates a new benefit. Exactly one type-specific configuration object (`points`, `points_proportional`, `material`, or `digital`) is required, matching the `type`. When `status` is omitted the benefit is created in `DRAFT` status. When `stock` is omitted it defaults to `{ "type": "UNLIMITED" }`. Referenced resources are validated: the card definition (for points-based types) must exist and - when creating with `status: ACTIVE` - must be ACTIVE (423 `resource_locked` otherwise); the product/SKU (for `MATERIAL`) and campaign (for `DIGITAL`) must exist, and the campaign type must match the digital benefit type (`DISCOUNT_COUPONS` or `GIFT_VOUCHERS`). The benefit name must be unique per project (409 `duplicate_found`). # Delete benefit Source: https://docs.voucherify.io/api-reference/benefits/delete-benefit /openapi/loyalties-v2.json delete /v2/loyalties/benefits/{benefitId} Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Soft-deletes a benefit and returns the deleted benefit. A benefit that is used by any earning rule cannot be deleted (400 `resource_in_use`, with `related_object_ids` and `related_object_type: earning_rule` in the error body). # Get benefit Source: https://docs.voucherify.io/api-reference/benefits/get-benefit /openapi/loyalties-v2.json get /v2/loyalties/benefits/{benefitId} Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Returns a single benefit by its ID. # List benefit activities Source: https://docs.voucherify.io/api-reference/benefits/list-benefit-activities /openapi/loyalties-v2.json get /v2/loyalties/benefits/{benefitId}/activities Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Returns a cursor-paginated list of activities recorded for the benefit (created, updated, deleted, activated, drafted). Returns `404` when the benefit does not exist. Supports filtering by activity `id`, `type`, and `created_at`, ordering by `created_at` (default `-created_at`), and cursor-based pagination. # List benefits Source: https://docs.voucherify.io/api-reference/benefits/list-benefits /openapi/loyalties-v2.json get /v2/loyalties/benefits Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Returns a cursor-paginated list of benefits. Supports filtering by `id`, `name`, `status`, `type`, and `created_at`, ordering by `created_at`, `name`, and `type` (prefix with `-` for descending), and cursor-based pagination. Deleted benefits are excluded. Multiple filters are combined with the `junction` (`AND` by default). The same field cannot be ordered both ascending and descending at the same time. # Move benefit to draft Source: https://docs.voucherify.io/api-reference/benefits/move-benefit-to-draft /openapi/loyalties-v2.json post /v2/loyalties/benefits/{benefitId}/draft Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Moves a benefit from `ACTIVE` back to `DRAFT` status. No request body. Only the `ACTIVE` -> `DRAFT` transition is allowed; drafting from any other state returns 400 `invalid_state_transition`. A benefit assigned to an active earning rule cannot be moved to draft (423 `resource_locked`, key `connected_active_earning_rule`). # Update benefit Source: https://docs.voucherify.io/api-reference/benefits/update-benefit /openapi/loyalties-v2.json put /v2/loyalties/benefits/{benefitId} Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Updates a benefit. When the benefit is in `DRAFT` status all properties can be updated. When the benefit is `ACTIVE`, only `name` and `stock` may be updated (400 `invalid_payload` otherwise). Referenced resources (card definition, product/SKU, campaign) are validated the same way as on create; a points-based benefit can only reference an ACTIVE card definition (423 `resource_locked` otherwise). The benefit name must remain unique per project (409 `duplicate_found`). # Delete Bin Entry Source: https://docs.voucherify.io/api-reference/bin/delete-bin-entry /openapi/bin.json delete /v1/trash-bin/{binEntryId} Deletes permanently a bin entry with a given ID.The following resources can be moved to the bin and permanently deleted: - campaigns - vouchers - products - SKUs To use this endpoint and delete a given resource type, you must have the following permissions: - `vouchers.delete` to delete a voucher, - `campaigns.delete` to delete a campaign, - `products.delete` to delete a product or SKU. # List Bin Entries Source: https://docs.voucherify.io/api-reference/bin/list-bin-entries /openapi/bin.json get /v1/trash-bin Retrieves a list of resources moved to the bin. The following resources can be moved to the bin: - campaigns - vouchers - products - SKUs To use this endpoint, you must have the following permissions: - `vouchers.read` - `campaigns.read` - `products.read` # Created Source: https://docs.voucherify.io/api-reference/campaign/created openapi-events/events-campaign.json webhook EVENTS.CAMPAIGN.CREATED The `EVENTS.CAMPAIGN.CREATED` event indicates that a new campaign was created. The webhook provides, among others, the following details: * Campaign ID, * Campaign name * Campaign type, * Creation date, * Other relevant details. This event is used in a webhook configured in Project settings in Voucherify dashboard. This page documents only the event. If you need more details about the webhook payload data that includes this event, go to [Introduction to webhooks](/api-reference/introduction-to-webhooks "Introduction to webhooks v2024-01-01") page. # Deleted Source: https://docs.voucherify.io/api-reference/campaign/deleted openapi-events/events-campaign.json webhook EVENTS.CAMPAIGN.DELETED The `EVENTS.CAMPAIGN.DELETED` event indicates that a specific campaign was removed. This serves as a real-time notification about this event. This event is used in a webhook configured in Project settings in Voucherify dashboard. This page documents only the event. If you need more details about the webhook payload data that includes this event, go to [Introduction to webhooks](/api-reference/introduction-to-webhooks "Introduction to webhooks v2024-01-01") page. # Disabled Source: https://docs.voucherify.io/api-reference/campaign/disabled openapi-events/events-campaign.json webhook EVENTS.CAMPAIGN.DISABLED The `EVENTS.CAMPAIGN.DISABLED` event indicates that the campaign is temporarily or permanently inactive. It cannot be utilized during that period. This event is used in a webhook configured in Project settings in Voucherify dashboard. This page documents only the event. If you need more details about the webhook payload data that includes this event, go to [Introduction to webhooks](/api-reference/introduction-to-webhooks "Introduction to webhooks v2024-01-01") page. # Enabled Source: https://docs.voucherify.io/api-reference/campaign/enabled openapi-events/events-campaign.json webhook EVENTS.CAMPAIGN.ENABLED The `EVENTS.CAMPAIGN.ENABLED` event indicates that the campaign is now active and can be utilized for its intended purpose. This event is used in a webhook configured in Project settings in Voucherify dashboard. This page documents only the event. If you need more details about the webhook payload data that includes this event, go to [Introduction to webhooks](/api-reference/introduction-to-webhooks "Introduction to webhooks v2024-01-01") page. # Loyalty Tier Created Source: https://docs.voucherify.io/api-reference/campaign/loyalty-tier-created openapi-events/events-campaign.json webhook EVENTS.CAMPAIGN.LOYALTY_TIER.CREATED The `EVENTS.CAMPAIGN.LOYALTY_TIER.CREATED` event indicates that a specific campaign loyalty tier was created. This serves as a real-time notification about this event. For example, this event is triggered when a loyalty tier is added to a loyalty campaign and the campaign is then saved. This event is used in a webhook configured in Project settings in Voucherify dashboard. This page documents only the event. If you need more details about the webhook payload data that includes this event, go to [Introduction to webhooks](/api-reference/introduction-to-webhooks "Introduction to webhooks v2024-01-01") page. # Loyalty Tier Deleted Source: https://docs.voucherify.io/api-reference/campaign/loyalty-tier-deleted openapi-events/events-campaign.json webhook EVENTS.CAMPAIGN.LOYALTY_TIER.DELETED The `EVENTS.CAMPAIGN.LOYALTY_TIER.DELETED` event indicates that a specific campaign loyalty tier was deleted. This serves as a real-time notification about this event. For example, this event is triggered when a loyalty tier is deleted from a loyalty campaign and the campaign is then saved. This event is used in a webhook configured in Project settings in Voucherify dashboard. This page documents only the event. If you need more details about the webhook payload data that includes this event, go to [Introduction to webhooks](/api-reference/introduction-to-webhooks "Introduction to webhooks v2024-01-01") page. # Loyalty Tier Updated Source: https://docs.voucherify.io/api-reference/campaign/loyalty-tier-updated openapi-events/events-campaign.json webhook EVENTS.CAMPAIGN.LOYALTY_TIER.UPDATED The `EVENTS.CAMPAIGN.LOYALTY_TIER.UPDATED` event indicates that a specific campaign loyalty tier was updated. This serves as a real-time notification about this event. For example, this event is triggered when a loyalty tier has been updated in a loyalty campaign and the campaign is then saved. This event is used in a webhook configured in Project settings in Voucherify dashboard. This page documents only the event. If you need more details about the webhook payload data that includes this event, go to [Introduction to webhooks](/api-reference/introduction-to-webhooks "Introduction to webhooks v2024-01-01") page. # Promotion Tier Created Source: https://docs.voucherify.io/api-reference/campaign/promotion-tier-created openapi-events/events-campaign.json webhook EVENTS.CAMPAIGN.PROMOTION_TIER.CREATED The `EVENTS.CAMPAIGN.PROMOTION_TIER.CREATED` event indicates that the promotion tier was created. This event is used in a webhook configured in Project settings in Voucherify dashboard. This page documents only the event. If you need more details about the webhook payload data that includes this event, go to [Introduction to webhooks](/api-reference/introduction-to-webhooks "Introduction to webhooks v2024-01-01") page. # Promotion Tier Deleted Source: https://docs.voucherify.io/api-reference/campaign/promotion-tier-deleted openapi-events/events-campaign.json webhook EVENTS.CAMPAIGN.PROMOTION_TIER.DELETED The `EVENTS.CAMPAIGN.PROMOTION_TIER.DELETED` event indicates that the promotion tier was deleted. This event is used in a webhook configured in Project settings in Voucherify dashboard. This page documents only the event. If you need more details about the webhook payload data that includes this event, go to [Introduction to webhooks](/api-reference/introduction-to-webhooks "Introduction to webhooks v2024-01-01") page. # Promotion Tier Disabled Source: https://docs.voucherify.io/api-reference/campaign/promotion-tier-disabled openapi-events/events-campaign.json webhook EVENTS.CAMPAIGN.PROMOTION_TIER.DISABLED The `EVENTS.CAMPAIGN.PROMOTION_TIER.DISABLED` event indicates that the promotion tier was disabled. This event is used in a webhook configured in Project settings in Voucherify dashboard. This page documents only the event. If you need more details about the webhook payload data that includes this event, go to [Introduction to webhooks](/api-reference/introduction-to-webhooks "Introduction to webhooks v2024-01-01") page. # Promotion Tier Enabled Source: https://docs.voucherify.io/api-reference/campaign/promotion-tier-enabled openapi-events/events-campaign.json webhook EVENTS.CAMPAIGN.PROMOTION_TIER.ENABLED The `EVENTS.CAMPAIGN.PROMOTION_TIER.ENABLED` event indicates that the promotion tier was enabled. This event is used in a webhook configured in Project settings in Voucherify dashboard. This page documents only the event. If you need more details about the webhook payload data that includes this event, go to [Introduction to webhooks](/api-reference/introduction-to-webhooks "Introduction to webhooks v2024-01-01") page. # Promotion Tier Updated Source: https://docs.voucherify.io/api-reference/campaign/promotion-tier-updated openapi-events/events-campaign.json webhook EVENTS.CAMPAIGN.PROMOTION_TIER.UPDATED The `EVENTS.CAMPAIGN.PROMOTION_TIER.UPDATED` event indicates that the promotion tier was updated. This event is used in a webhook configured in Project settings in Voucherify dashboard. This page documents only the event. If you need more details about the webhook payload data that includes this event, go to [Introduction to webhooks](/api-reference/introduction-to-webhooks "Introduction to webhooks v2024-01-01") page. # Updated Source: https://docs.voucherify.io/api-reference/campaign/updated openapi-events/events-campaign.json webhook EVENTS.CAMPAIGN.UPDATED The `EVENTS.CAMPAIGN.UPDATED` event indicates that an existing campaign was modified within Voucherify. This event provides the campaign definition after the update, ensuring that relevant systems are informed in real-time. This event is used in a webhook configured in Project settings in Voucherify dashboard. This page documents only the event. If you need more details about the webhook payload data that includes this event, go to [Introduction to webhooks](/api-reference/introduction-to-webhooks "Introduction to webhooks v2024-01-01") page. # Vouchers Generation Completed Source: https://docs.voucherify.io/api-reference/campaign/vouchers-generation-completed openapi-events/events-campaign.json webhook EVENTS.CAMPAIGN.VOUCHERS.GENERATION.COMPLETED The `EVENTS.CAMPAIGN.VOUCHERS.GENERATION.COMPLETED` event indicates that voucher generation for a given campaign was completed. It includes details about the campaign for which voucher were generated, the number of generated vouchers, and the date when the process was completed. This event is used in a webhook configured in Project settings in Voucherify dashboard. This page documents only the event. If you need more details about the webhook payload data that includes this event, go to [Introduction to webhooks](/api-reference/introduction-to-webhooks "Introduction to webhooks v2024-01-01") page. # Add Voucher with Specific Code to Campaign Source: https://docs.voucherify.io/api-reference/campaigns/add-voucher-with-specific-code-to-campaign /openapi/campaigns.json post /v1/campaigns/{campaignId}/vouchers/{code} This method gives a possibility to add a new voucher to an existing campaign. The voucher definition will be inherited from the definition kept in the campaign profile. However, you are able to overwrite a few properties inherited from the campaign. # Add Vouchers to Campaign Source: https://docs.voucherify.io/api-reference/campaigns/add-vouchers-to-campaign /openapi/campaigns.json post /v1/campaigns/{campaignId}/vouchers This method gives the possibility to push new vouchers to an existing campaign. New vouchers will inherit properties from the campaign profile. However, it is possible to overwrite some of them in the request body. If you provide an optional `code_config` parameter with a voucher code configuration, then it will be used to generate new voucher codes. Otherwise, the voucher code configuration from the campaign will be used. This API request starts a process that affects Voucherify data in bulk. In case of small jobs (like bulk update) the request is put into a queue and processed once every other bulk request placed in the queue prior to this request is finished. However, when the job takes a longer time (like vouchers generation) then it is processed in small portions in a round-robin fashion. When there is a list of vouchers generation scheduled, then they will all have the `IN_PROGRESS` status shortly. This way, small jobs added just after scheduling big jobs of the same type will be processed in a short time window. The result will return the async ID. You can verify the status of your request via this [API request](/api-reference/async-actions/get-async-action). # Campaign Object Source: https://docs.voucherify.io/api-reference/campaigns/campaign-object

Campaign

All of:

Campaign Base

Campaign Additional Data

Attributes	Description
promotion	See: Promotion Tiers
validation\_rules\_assignments	See: Validation Rules Assignments List

Campaign Base

Attributes	Description
id `string`	Unique campaign ID, assigned by Voucherify. Example: camp\_f7fBbQxUuTN7dI7tGOo5XMDA
name `string`	Campaign name.
description `string`	An optional field to keep any extra textual information about the campaign such as a campaign description and details.
campaign\_type `string`	Type of campaign. Available values: `LOYALTY\_PROGRAM`, `GIFT\_VOUCHERS`, `DISCOUNT\_COUPONS`, `PROMOTION`, `REFERRAL\_PROGRAM`
type `string`	Defines whether the campaign can be updated with new vouchers after campaign creation or if the campaign consists of generic (standalone) vouchers. `AUTO\_UPDATE` : the campaign is dynamic, i.e. vouchers will generate based on set criteria `STATIC` : vouchers need to be manually published `STANDALONE` : campaign for single vouchers Available values: `AUTO\_UPDATE`, `STATIC`, `STANDALONE`
voucher	See: Campaign Voucher
auto\_join `boolean`	Indicates whether customers will be able to auto-join a loyalty campaign if any earning rule is fulfilled.
join\_once `boolean`	If this value is set to `true`, customers will be able to join the campaign only once. It is always `false` for generic (standalone) vouchers campaigns and it cannot be changed in them. It is always `true` for loyalty campaigns and it cannot be changed in them.
use\_voucher\_metadata\_schema `boolean`	Flag indicating whether the campaign is to use the voucher's metadata schema instead of the campaign metadata schema.
validity\_timeframe	See: Validity Timeframe
validity\_day\_of\_week	See: Validity Day Of Week
validity\_hours	See: Validity Hours
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.
vouchers\_count `integer`	Total number of unique vouchers in campaign.
start\_date `string`	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 `string`	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 `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
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.
created\_at `string`	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
updated\_at `string`	Timestamp representing the date and time when the campaign was last updated in ISO 8601 format. Example: 2022-09-20T09:18:19.623Z
category `string`	Unique category name.
creation\_status `string`	Indicates the status of the campaign creation. Available values: `DONE`, `IN\_PROGRESS`, `FAILED`, `DRAFT`, `MODIFYING`
vouchers\_generation\_status `string`	Indicates the status of the campaign's voucher generation. Available values: `DONE`, `IN\_PROGRESS`, `FAILED`, `DRAFT`, `MODIFYING`
readonly `boolean`	Indicates whether the campaign can be only read by a restricted user in the Areas and Stores enterprise feature. It is returned only to restricted users; this field is not returned for users with other roles. It is also not returned for restricted users who use the GET Campaign summary endpoint.
protected `boolean`	Indicates whether the resource can be deleted.
category\_id `string`, `null`	Unique category ID that this campaign belongs to. Example: cat\_0b688929a2476386a7
categories `array`	Contains details about the campaign category. For the GET List campaigns endpoint, this is returned only if the `expand=category` query parameter is passed in the request. Otherwise, it is returned as an empty array. For GET Campaign summary endpoint, it is always returned as an empty array. Array of Category
object `string`	The type of the object represented by JSON. This object stores information about the campaign.
referral\_program	See: Referral Program
loyalty\_tiers\_expiration	See: Loyalty Tiers Expiration
access\_settings\_assignments	See: Access Settings Campaign Assignments List

Promotion Tiers

Attributes	Description
object `string`	The type of the object represented by JSON. This object stores information about promotion tiers in a dictionary.
data\_ref `string`	Identifies the name of the attribute that contains the array of promotion tier objects.
tiers `array`	Contains array of promotion tier objects. Array of Promotion Tier
total `integer`	Total number of promotion tiers.
has\_more `boolean`	As query results are always limited (by the limit parameter), the `has\_more` flag indicates if there are more records for given filter parameters. This lets you know if you can run another request to get more records returned in the results.

Validation Rules Assignments List

Attributes	Description
object `string`	The type of the object represented by JSON. This object stores information about validation rules assignments. Available values: `list`
data\_ref `string`	Identifies the name of the attribute that contains the array of validation rules assignments. Available values: `data`
data `array`	Contains array of validation rules assignments. Array of Business Validation Rule Assignment
total `integer`	Total number of validation rules assignments.

Campaign Voucher

Attributes Description

type
string

Type of voucher.

discount

Defines the voucher discount type and details.

Discount

gift

Defines the voucher gift details.

Gift

loyalty\_card

Defines the voucher loyalty card details.

Campaign Loyalty Card

redemption
object

Defines the redemption limits on vouchers.

Attributes	Description
quantity `integer`, `null`	How many times a voucher can be redeemed. A `null` value means unlimited.

code\_config

Code Config

is\_referral\_code
boolean

Flag indicating whether this voucher is a referral code; true for campaign type REFERRAL\_PROGRAM.

start\_date
string

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
string

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

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

validity\_timeframe

See: Validity Timeframe

validity\_day\_of\_week

See: Validity Day Of Week

validity\_hours

See: Validity Hours

Validity Timeframe

Attributes Description

Attributes	Description
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
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

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

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

Validity Day Of Week

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

Validity Hours

Attributes Description

daily
array

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

Array of:

Attributes Description

start\_time
string

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

Example: 12:00

days\_of\_week
array

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

expiration\_time
string

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

Example: 14:00

Category

Attributes	Description
id `string`	Unique category ID assigned by Voucherify.
name `string`	Category name.
hierarchy `integer`	Category hierarchy. Categories with lower hierarchy are processed before categories with higher hierarchy value.
object `string`	The type of the object represented by the JSON. This object stores information about the category. Available values: `category`
created\_at `string`	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
updated\_at `string`	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

Referral Program

Attributes Description

conversion\_event\_type
string

Define how a referral is triggered.

Available values: redemption, custom\_event

custom\_event
object

Contains details about the custom event.

Attributes Description

id
string

Unique custom event ID.

Example: ms\_Ll9enAm2BCN0M1s4VxWobLFM

name
string

Custom event name.

referee\_reward
object

Defines the referee reward.

Attributes Description

related\_object\_parent
object

Details of the resource from which the reward originates.

Attributes Description

id
string

Unique ID of the reward source.

Example: camp\_kdxp3vf1clQ9CFs1jpqv3tZe

name
string

Name of the reward source.

object
string

Type of resource represented by the source of the reward.

Available values: CAMPAIGN

type
string

Type of reward.

Available values: LOYALTY\_CARD, GIFT\_VOUCHER

amount
integer

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

Loyalty Tiers Expiration

Attributes Description

qualification\_type
string

Tier qualification.

BALANCE : Points balance is based on the customer's current points balance. Customers qualify for the tier if their points balance is in the points range of the tier.
POINTS\_IN\_PERIOD : A customer qualifies for the tier only if the sum of the accumulated points in a defined time interval reaches the tier threshold.

Available values: BALANCE, POINTS\_IN\_PERIOD

qualification\_period
string

Customers can qualify for the tier if they collected enough points in a given time period. So, in addition to the customer having to reach a points range, they also need to have collected the points within a set time period.

Period	Definition
Calendar Month	Points collected in one calendar month January, February, March, etc.
Calendar Quarter	Points collected in the quarter \- January - March \- April - June \- July - September \- October - December
Calendar Half-year	Points collected in the half-year \- January - June \- July - December
Calendar Year	Points collected in one calendar year January - December

Available values: MONTH, QUARTER, HALF\_YEAR, YEAR

start\_date
object

Defines the conditions for the start date of the tier.

Attributes Description

type
string

What triggers the tier to be valid for a customer.
IMMEDIATE : After reaching the minimum required points.
NEXT\_PERIOD : When the next qualification period starts.

Available values: IMMEDIATE, NEXT\_PERIOD

expiration\_date
object

Defines the conditions for the expiration date of a tier.

Attributes Description

type
string

What triggers the tier to expire for a customer.
END\_OF\_PERIOD : Expire tier at the end of the period.
END\_OF\_NEXT\_PERIOD : Expire tier at the end of the next period.
BALANCE\_DROP : Tier expires when the points balance drops below the required range of the tier.
CUSTOM : Tier expires after a certain time period passes following the instance the points balance drops below the required range of the tier.

Available values: END\_OF\_PERIOD, END\_OF\_NEXT\_PERIOD, BALANCE\_DROP, CUSTOM

extend
string

Extend the expiration by adding extra months or days in ISO 8601 format. The tier will remain active even though it reaches its expiration time period. For example, a tier with a duration of P3M will be valid for an additional duration of 3 months and a tier with a duration of P1D will be valid for an additional duration of 1 day.

rounding

Defines the rounding mechanism for tier expiration.

Access Settings Campaign Assignments List

Attributes	Description
object `string`	The type of the object represented by JSON. Default is `list`. This object stores information about campaign assignments to areas and stores Available values: `list`
data\_ref `string`	Identifies the name of the attribute that contains the array of campaign assignments. Available values: `data`
data `array`	Contains an array of campaign assignments. Array of Areas and Stores Campain Assignment
total `integer`	Total number of areas and stores to which the campaign is assigned.

Promotion Tier

Attributes Description

id
string

Unique promotion tier ID.

Example: promo\_63fYCt81Aw0h7lzyRkrGZh9p

created\_at
string

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

Example: 2021-12-15T11:34:01.333Z

updated\_at
string

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

Example: 2022-02-09T09:20:05.603Z

name
string

Name of the promotion tier.

banner
string

Text to be displayed to your customers on your website.

action
object

Contains details about the discount applied by the promotion tier.

Attributes	Description
discount	See: Discount

metadata
object

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

hierarchy
integer

The promotions hierarchy defines the order in which the discounts from different tiers will be applied to a customer's order. If a customer qualifies for discounts from more than one tier, discounts will be applied in the order defined in the hierarchy.

promotion\_id
string

Promotion unique ID.

campaign
object

Contains details about promotion tier's parent campaign.

Attributes	Description
id `string`	Unique campaign ID.
start\_date `string`	Activation timestamp defines when the campaign starts to be active in ISO 8601 format. Campaign is inactive before this date. Example: 2022-09-22T00:00:00.000Z
expiration\_date `string`	Expiration timestamp defines when the campaign expires in ISO 8601 format. Campaign is inactive after this date. Example: 2022-09-30T00:00:00.000Z
validity\_timeframe	See: Validity Timeframe
validity\_day\_of\_week	See: Validity Day Of Week
validity\_hours	See: Validity Hours
active `boolean`	A flag indicating whether the campaign is active or not active. A campaign can be disabled even though it's within the active period defined by the `start\_date` and `expiration\_date` using the Disable Campaign endpoint. `true` indicates an active campaign `false` indicates an inactive campaign
category\_id `string`	Unique category ID that this campaign belongs to. Example: cat\_0b688929a2476386a6
object `string`	The type of the object represented by the campaign object. This object stores information about the campaign.

campaign\_id
string

Promotion tier's parent campaign's unique ID.

active
boolean

A flag to toggle the promotion tier on or off. You can disable a promotion tier even though it's within the active period defined by the start\_date and expiration\_date.

true indicates an active promotion tier
false indicates an inactive promotion tier

start\_date
string

Activation timestamp defines when the promotion tier starts to be active in ISO 8601 format. Promotion tier is inactive before this date.

Example: 2022-09-23T00:00:00.000Z

expiration\_date
string

Activation timestamp defines when the promotion tier expires in ISO 8601 format. Promotion tier is inactive after this date.

Example: 2022-09-26T00:00:00.000Z

validity\_timeframe

See: Validity Timeframe

validity\_day\_of\_week

See: Validity Day Of Week

validity\_hours

See: Validity Hours

summary
object

Contains statistics about promotion tier redemptions and orders.

Attributes Description

redemptions
object

Contains statistics about promotion tier redemptions.

Attributes	Description
total\_redeemed `integer`	Number of times the promotion tier was redeemed.

orders
object

Contains statistics about orders related to the promotion tier.

Attributes	Description
total\_amount `integer`	Sum of order totals.
total\_discount\_amount `integer`	Sum of total discount applied using the promotion tier.

object
string

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

validation\_rule\_assignments

See: Validation Rule Assignments List

category\_id
string

Promotion tier category ID.

Example: cat\_0c9da30e7116ba6bba

categories
array

Array of Category

Business Validation Rule Assignment

Attributes	Description
id `string`	The unique identifier for a assignment
rule\_id `string`	The unique identifier for a rule
related\_object\_id `string`	The unique identifier for a related object
related\_object\_type `string`	The type of related object
created\_at `string`	Timestamp representing the date and time when the object was created. The value is shown in the ISO 8601 format. Example: 2022-03-09T11:19:04.819Z
updated\_at `string`	Timestamp representing the date and time when the object was last updated in ISO 8601 format. Example: 2022-03-09T11:19:04.819Z
object `string`	The type of the object represented by JSON. Available values: `validation\_rules\_assignment`
validation\_status `string`	The validation status of the assignment Available values: `VALID`, `PARTIALLY\_VALID`, `INVALID`
validation\_omitted\_rules `array`	The list of omitted rules

Discount

Contains information about discount.

One of:

Amount
Unit
Unit Multiple
Percent
Fixed

Gift

Attributes	Description
amount `number`	Total gift card income over the lifetime of the card. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `\$100.00`.
subtracted\_amount `integer`	Total amount of subtracted credits over the gift card lifetime.
balance `number`	Available funds. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `\$100.00`. `balance` \= `amount` \- `subtracted\_amount` \- `redemption.redeemed\_amount`.
effect `string`	Defines how the credits are applied to the customer's order. Available values: `APPLY\_TO\_ORDER`, `APPLY\_TO\_ITEMS`

Campaign Loyalty Card

Attributes Description

points
integer

The initial number of points to assign to the loyalty card. This is the current loyalty card score i.e. the number of loyalty points on the card.

expiration\_rules
object

Defines the loyalty point expiration rule. This expiration rule applies when there are no expiration\_rules defined for an earning rule.

Attributes	Description
period\_type `string`	Type of period. Can be set for `MONTH` or `FIXED\_DAY\_OF\_YEAR`. `MONTH` requires the `period\_value` field. `FIXED\_DAY\_OF\_YEAR` requires the `fixed\_month` and `fixed\_day` fields. Available values: `FIXED\_DAY\_OF\_YEAR`, `MONTH`
period\_value `integer`	Value of the period. Required for the `period\_type: MONTH`.
rounding\_type `string`	Type of rounding of the expiration period. Optional for the `period\_type: MONTH`. Available values: `END\_OF\_MONTH`, `END\_OF\_QUARTER`, `END\_OF\_HALF\_YEAR`, `END\_OF\_YEAR`, `PARTICULAR\_MONTH`
rounding\_value `integer`	Value of rounding of the expiration period. Required for the `rounding\_type`.
fixed\_month `integer`	Determines the month when the points expire; `1` is January, `2` is February, and so on. Required for the `period\_type: FIXED\_DAY\_OF\_YEAR`.
fixed\_day `integer`	Determines the day of the month when the points expire. Required for the `period\_type: FIXED\_DAY\_OF\_YEAR`.

Code Config

Attributes	Description
length `number`	Number of characters in a generated code (excluding prefix and postfix).
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
prefix `string`	A text appended before the code.
postfix `string`	A text appended after the code.
pattern `string`	A pattern for codes where hashes (#) will be replaced with random characters. Overrides `length`.
initial\_count `integer`	Internal value, does not change anything if provided.

Areas and Stores Campain Assignment

Attributes	Description
id `string`	Unique identifier of the campaign assignment. Example: arsca\_0ef5ee192117ae2416
area\_id `string`	Unique identifier of the area to which the campaign is assigned. Example: ar\_0ea6cd7b781b8f857f
all\_stores `boolean`	Determines if the campaign is assigned to all of the stores in the area, i.e. if an area ID is passed in the `access\_settings.assign.area\_all\_stores\_ids` in the request.
area\_store\_id `string`	Unique identifier of the store to which the campaign is assigned. Example: ars\_0ec347e2016bed85f4
created\_at `string`	Date and time when the assignment was made. The value is shown in the ISO 8601 format. Example: 2024-06-25T19:04:16.260Z
object `string`	The type of the object represented by JSON. This object stores information about the campaign assignment to areas or stores. Available values: `area\_store\_campaign\_assignment`

Validation Rule Assignments List

Attributes	Description
object `string`	The type of the object represented by JSON. This object stores information about validation rule assignments.
data\_ref `string`	Identifies the name of the JSON property that contains the array of validation rule assignments.
data `array`	A dictionary that contains an array of validation rule assignments. Array of Validation Rule Assignment
total `integer`	Total number of validation rule assignments.

Amount

Attributes	Description
type `string`	Defines the type of the voucher. Available values: `AMOUNT`
amount\_off `number`	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.
amount\_off\_formula `string`	Formula used to dynamically calculate the discount.
aggregated\_amount\_limit `integer`	Maximum discount amount per order.
effect	Defines how the discount is applied to the customer's order. Discount Amount Vouchers Effect Types
is\_dynamic `boolean`	Flag indicating whether the discount was calculated using a formula.

Unit

Attributes	Description
type `string`	Discount type. Available values: `UNIT`
unit\_off `integer`	Number of units to be granted a full value discount.
unit\_off\_formula `string`	Formula used to dynamically calculate the number of units.
effect	Defines how the unit is added to the customer's order. Discount Unit Vouchers Effect Types
unit\_type `string`	The product deemed as free, chosen from product inventory (e.g. time, items).
product	Contains information about the product. Simple Product Discount Unit
sku	See: Simple Sku Discount Unit
is\_dynamic `boolean`	Flag indicating whether the discount was calculated using a formula.

Unit Multiple

Attributes Description

type
string

Discount type.

Available values: UNIT

effect
string

Defines how the discount is applied to the customer's order.

Available values: ADD\_MANY\_ITEMS

units
array

Array of One Unit

Percent

Attributes	Description
type `string`	Defines the type of the voucher. Available values: `PERCENT`
percent\_off `number`	The percent discount that the customer will receive.
percent\_off\_formula `string`	Formula used to dynamically calculate the discount.
amount\_limit `number`	Upper limit allowed to be applied as a discount. Value is multiplied by 100 to precisely represent 2 decimal places. For example, a \$6 maximum discount is written as 600.
aggregated\_amount\_limit `integer`	Maximum discount amount per order.
effect	Defines how the discount is applied to the customer's order. Discount Percent Vouchers Effect Types
is\_dynamic `boolean`	Flag indicating whether the discount was calculated using a formula.

Fixed

Attributes	Description
type `string`	Defines the type of the voucher. Available values: `FIXED`
fixed\_amount `number`	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.
fixed\_amount\_formula `string`	Formula used to dynamically calculate the discount.
effect	Defines how the discount is applied to the customer's order. Discount Fixed Vouchers Effect Types
is\_dynamic `boolean`	Flag indicating whether the discount was calculated using a formula.

Validation Rule Assignment

Attributes	Description
id `string`	Validation rule assignment ID. Example: asgm\_74F7QZoYbUoljwQO
rule\_id `string`	Validation rule ID. Example: val\_4j7DCRm2IS59
related\_object\_id `string`	The resource ID to which the validation rule was assigned. Example: v\_JtWunK6jUo7X2qOFj0SyRHq4p9tgENlT
related\_object\_type `string`	The type of resource to which the validation rule was assigned. Available values: `voucher`, `campaign`, `earning\_rule`, `reward\_assignment`, `promotion\_tier`, `distribution`
created\_at `string`	Timestamp representing the date and time when the validation rule assignment was created. The value is shown in the ISO 8601 format. Example: 2022-02-17T08:18:15.085Z
object `string`	The type of the object represented by the ID. Available values: `validation\_rules\_assignment`

Discount Amount Vouchers Effect Types

Available values: APPLY\_TO\_ORDER, APPLY\_TO\_ITEMS, APPLY\_TO\_ITEMS\_PROPORTIONALLY, APPLY\_TO\_ITEMS\_PROPORTIONALLY\_BY\_QUANTITY, APPLY\_TO\_ITEMS\_BY\_QUANTITY

Discount Unit Vouchers Effect Types

Available values: ADD\_MISSING\_ITEMS, ADD\_NEW\_ITEMS, ADD\_MANY\_ITEMS, ADD\_SAME\_ITEMS

Simple Product Discount Unit

Attributes	Description
id `string`	Unique product ID, assigned by Voucherify.
source\_id `string`	Product's source ID.
name `string`	Product name.

Simple Sku Discount Unit

Attributes	Description
id `string`	Unique SKU ID, assigned by Voucherify.
source\_id `string`	Product variant's source ID.
name `string`	Sku name

One Unit

Attributes	Description
unit\_off `number`	Number of units to be granted a full value discount.
unit\_off\_formula `string`	Formula used to dynamically calculate the number of units.
effect `string`	Defines how the unit is added to the customer's order. Available values: `ADD\_NEW\_ITEMS`, `ADD\_MISSING\_ITEMS`
unit\_type `string`	The product deemed as free, chosen from product inventory (e.g. time, items).
product	Contains information about the product. Simple Product Discount Unit
sku	Contains information about the sku. Simple Sku Discount Unit

Discount Percent Vouchers Effect Types

Available values: APPLY\_TO\_ORDER, APPLY\_TO\_ITEMS

Discount Fixed Vouchers Effect Types

Available values: APPLY\_TO\_ORDER, APPLY\_TO\_ITEMS

# Create Campaign Source: https://docs.voucherify.io/api-reference/campaigns/create-campaign /openapi/campaigns.json post /v1/campaigns Method to create a batch of vouchers aggregated in one campaign. You can choose a variety of voucher types and define a unique pattern for generating codes. Global uniqueness All campaign codes are unique across the whole project. Voucherify will not allow you to generate 2 campaigns with the same coupon code. Code generation status This is an asynchronous action; you can't read or modify a newly created campaign until the code generation is completed. See the `creation_status` field in the [campaign object](/api-reference/campaigns/campaign-object) description. # Delete Campaign Source: https://docs.voucherify.io/api-reference/campaigns/delete-campaign /openapi/campaigns.json delete /v1/campaigns/{campaignId} Deletes a campaign and all related vouchers. This action cannot be undone. Also, this method immediately removes any redemptions on the voucher. If the `force` parameter is set to `false` or not set at all, the campaign and all related vouchers will be moved to [the bin](/api-reference/bin/list-bin-entries). This API request starts a process that affects Voucherify data in bulk. In case of small jobs (like bulk update) the request is put into a queue and processed once every other bulk request placed in the queue prior to this request is finished. However, when the job takes a longer time (like vouchers generation) then it is processed in small portions in a round-robin fashion. When there is a list of vouchers generation scheduled, then they will all have the `IN_PROGRESS` status shortly. This way, small jobs added just after scheduling big jobs of the same type will be processed in a short time window. The result will return the async ID. You can verify the status of your request via this [API request](/api-reference/async-actions/get-async-action). # Disable Campaign Source: https://docs.voucherify.io/api-reference/campaigns/disable-campaign /openapi/campaigns.json post /v1/campaigns/{campaignId}/disable Sets campaign state to **inactive**. The vouchers in this campaign can no longer be redeemed. # Enable Campaign Source: https://docs.voucherify.io/api-reference/campaigns/enable-campaign /openapi/campaigns.json post /v1/campaigns/{campaignId}/enable Sets campaign state to **active**. The vouchers in this campaign can be redeemed - only if the redemption occurs after the start date of the campaign and voucher and the voucher and campaign are not expired. # Examine Campaign Qualification Source: https://docs.voucherify.io/api-reference/campaigns/examine-campaign-qualification /openapi/campaigns.json post /v1/campaigns/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. # Export Campaign Transactions Source: https://docs.voucherify.io/api-reference/campaigns/export-campaign-transactions /openapi/campaigns.json post /v1/campaigns/{campaignId}/transactions/export Export transactions is an asynchronous process that generates a CSV file with the data about credit movements on all gift cards or point movements on all loyalty cards in a given campaign. To export transactions: 1. In the export request, use parameters to select which fields will be exported, in what order, and which data will be filtered. 2. Use the returned `id` to track the export status with the [GET Export](/api-reference/exports/get-export) method. 3. In the GET Export method, when the returned `status` field has the `DONE` value, the export file has been generated. 4. Use the URL in the `result` property to download the file. You must be logged to your Voucherify account on a given cluster in the browser to be able to download the file. An export request will almost always result in a single file being generated by the system. However, when the data volume is large, the system may split the results into multiple files. An example export file can look as follows: | **Field** | **Definition** | **Example Export** | |:---|:---|:---| | `id` | Unique transaction ID. | `vtx_0cb7811f1c07765800` | | `type` | Transaction type. |**Gift cards**:
- `CREDITS_REMOVAL`
- `CREDITS_ADDITION`
- `CREDITS_REFUND`
- `CREDITS_REDEMPTION`
**Loyalty cards**:
- `POINTS_ACCRUAL`
- `POINTS_REDEMPTION`
- `POINTS_REFUND`
- `POINTS_ADDITION`
- `POINTS_REMOVAL`
- `POINTS_EXPIRATION`
- `POINTS_TRANSFER_IN`
- `POINTS_TRANSFER_OUT` | | `source_id` | Unique transaction source ID. Optional and only in manual operations: `CREDITS_ADDITION`, `CREDITS_REMOVAL`, `POINTS_ADDITION`, `POINTS_REMOVAL`, `POINTS_TRANSFER_OUT`. | 8638 | | `reason` | Contains the reason for the transaction if one was included originally. Optional and only in the following manual operations: `CREDITS_ADDITION`, `CREDITS_REMOVAL`, `POINTS_ADDITION`, `POINTS_REMOVAL`, `POINTS_TRANSFER_OUT`, `POINTS_TRANSFER_IN`. | `Apology for sending a broken item` | | `balance` | The gift card or loyalty card balance after the transaction. | | | `amount` | The amount of gift card or loyalty card credits being allocated during the transaction. This value can either be negative or positive depending on the nature of the transaction. | | | `created_at` | Timestamp in ISO 8601 format representing the date and time when the transaction was created. | `2024-10-09T09:16:32.521Z` | | `voucher_id` | Unique voucher ID. | `v_dky7ksKfPX50Wb2Bxvcoeb1xT20b6tcp` | | `source`| Channel through which the transaction was initiated. | `API` | | `details` | More detailed information stored in the form of JSON. | Provides more details related to the transaction in the form of an object. | | `related_transaction_id` | Unique transaction ID related to a receiver/donor card in the case of a points transfer from/to another card. | `vtx_0c9afe802593b34b80` | Export Loyalty Campaign Transactions For loyalty campaigns, this method works in the same way the [POST Export Loyalty Campaign Transactions](/api-reference/loyalties/export-loyalty-campaign-transactions) does. # Get Campaign Source: https://docs.voucherify.io/api-reference/campaigns/get-campaign /openapi/campaigns.json get /v1/campaigns/{campaignId} Retrieves the campaign with the given campaign ID or campaign name. # Get Campaign Summary Source: https://docs.voucherify.io/api-reference/campaigns/get-campaign-summary /openapi/campaigns.json get /v1/campaigns/{campaignId}/summary Returns data for campaign analytics, covering validations, redemptions, publications, and other details specific to a given campaign type. Use `start_date` and `end_date` to narrow down the data to specific periods. Campaigns created before 17 June 2025 This endpoint returns analytics data for campaigns that were created after 17 June 2025. Older campaigns return empty data. # Import Vouchers to Campaign Source: https://docs.voucherify.io/api-reference/campaigns/import-vouchers-to-campaign /openapi/campaigns.json post /v1/campaigns/{campaignId}/import Imports vouchers to an **existing** campaign. This API request starts a process that affects Voucherify data in bulk. In case of small jobs (like bulk update) the request is put into a queue and processed once every other bulk request placed in the queue prior to this request is finished. However, when the job takes a longer time (like vouchers generation) then it is processed in small portions in a round-robin fashion. When there is a list of vouchers generation scheduled, then they will all have the `IN_PROGRESS` status shortly. This way, small jobs added just after scheduling big jobs of the same type will be processed in a short time window. The result will return the async ID. You can verify the status of your request via this [API request](/api-reference/async-actions/get-async-action). # Import Vouchers to Campaign by CSV Source: https://docs.voucherify.io/api-reference/campaigns/import-vouchers-to-campaign-by-csv /openapi/campaigns.json post /v1/campaigns/{campaignId}/importCSV Imports vouchers to an **existing** campaign. The CSV file has to include headers in the first line. Curl Example ```cURL curl -X **POST** \ https://api.voucherify.io/v1/campaigns/TEST-CAMPAIGN/importCSV \ -F file=@/path/to/campaigns.csv \ -H "X-App-Id: c70a6f00-cf91-4756-9df5-47628850002b" \ -H "X-App-Token: 3266b9f8-e246-4f79-bdf0-833929b1380c" ``` You can import values for the following fields: `Code` (**required**), `Category`, `Active`. In a gift cards import, you can also include the current card balance using the `Gift Amount` header and the amount that was redeemed using the `Redeemed Amount` header. In a loyalty cards import, you can also include the current loyalty card score in points using the `Loyalty Points` header. Remaining CSV columns will be mapped to metadata properties. Discount type, time limits, and validation rules will be taken from the [campaign object](/api-reference/campaigns/campaign-object) settings. | **Active** | **Code** | **Loyalty Points** | **Gift Amount** | **Redeemed Amount** | **Redeemed Quantity** | **Category** | **Custom_metadata_property** | |---|---|---|---|---|---|---|---| | Use `true` or `false` to enable or disable the voucher; this flag can be used to turn off the ability to redeem a voucher even though it is within the campaign's start/end validity timeframe. | The unique voucher code. | The number of points to be added to the loyalty card. If you leave this undefined, then the initial number of points will be set according to the campaign settings.
Context: `LOYALTY_PROGRAM` | The initial gift card balance.
Context: `GIFT_VOUCHERS` | The amount that was redeemed from the available balance on a gift card. | The number of times the voucher has been redeemed. | A custom tag for the voucher to help you filter codes; you can either import the category name or a unique Voucherify-assigned category ID. | Any additional data that you would like to store for the given loyalty card as a Custom attribute. Remember to define the metadata schema in the Dashboard prior to importing codes. | | Active The CSV file is allowed in two versions; either with or without a column titled `Active`. It indicates whether the voucher is enabled after the import event. This API request starts a process that affects Voucherify data in bulk. In case of small jobs (like bulk update) the request is put into a queue and processed once every other bulk request placed in the queue prior to this request is finished. However, when the job takes a longer time (like vouchers generation) then it is processed in small portions in a round-robin fashion. When there is a list of vouchers generation scheduled, then they will all have the `IN_PROGRESS` status shortly. This way, small jobs added just after scheduling big jobs of the same type will be processed in a short time window. The result will return the async ID. You can verify the status of your request via this [API request](/api-reference/async-actions/get-async-action). # List Campaign Transactions Source: https://docs.voucherify.io/api-reference/campaigns/list-campaign-transactions /openapi/campaigns.json get /v1/campaigns/{campaignId}/transactions Retrieves all transactions for the campaign with the given campaign ID or campaign name. The `id` filter denotes the unique transaction identifier. The endpoint works only for gift card and loyalty campaigns. # List Campaigns Source: https://docs.voucherify.io/api-reference/campaigns/list-campaigns /openapi/campaigns.json get /v1/campaigns Retrieve a list of campaigns in a project. The campaigns are returned sorted by creation date, with the most recent campaigns appearing first. When you get a list of campaigns, you can optionally specify query parameters to customize the amount of campaigns returned per call using `limit`, which page of campaigns to return using `page`, sort the campaigns using the `order` query parameter and filter the results by the `campaign_type`. This method will return an error when trying to return a limit of more than 100 campaigns. # Update Campaign Source: https://docs.voucherify.io/api-reference/campaigns/update-campaign /openapi/campaigns.json put /v1/campaigns/{campaignId} Updates the specified campaign by setting the values of the parameters passed in the request body. Any parameters not provided in the payload will be left unchanged. Fields other than the ones listed in the request body won't be modified. Even if provided, they will be silently skipped. Vouchers will be affected This method will update vouchers aggregated in the campaign. It will affect all vouchers that are not published or redeemed yet. # Activate Card Definition Source: https://docs.voucherify.io/api-reference/card-definitions/activate-card-definition /openapi/loyalties-v2.json post /v2/loyalties/card-definitions/{cardDefinitionId}/activate Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Transitions the card definition from `DRAFT` to `ACTIVE`. No request body. Activating from any other state results in an invalid state transition error (409). # Create Card Definition Source: https://docs.voucherify.io/api-reference/card-definitions/create-card-definition /openapi/loyalties-v2.json post /v2/loyalties/card-definitions Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Creates a new card definition. Only `name` and `type` are required; all other sections default server-side as follows: - `code_config`: 10-character alphanumeric code pattern (`##########`) - `points_expiration`: `NO_EXPIRATION` - `pending_points`: `IMMEDIATE` - `earning_limits`: global `NO_LIMIT`, transactions `NO_LIMIT` - `spending_limits`: global `NO_LIMIT`, transactions `NO_LIMIT` - `refunds`: spent points `NONE`, earned points `NONE` - `balance_settings`: `allow_negative: false` - `pay_with_points`: `NO_PAYMENTS` Cross-field rules: - `balance_settings.allow_negative` can only be `true` when `points_expiration.type` is `NO_EXPIRATION`. Additionally, the earned points refund mode `REVOKE_BELOW_ZERO` requires `balance_settings.allow_negative` to be `true`. - The earned points refund method `REVOKE_FROM_PENDING` requires `pending_points.type` to be one of `PERIOD_BASED`, `FIXED_DATES`, `EVENT_BASED`. # Delete Card Definition Source: https://docs.voucherify.io/api-reference/card-definitions/delete-card-definition /openapi/loyalties-v2.json delete /v2/loyalties/card-definitions/{cardDefinitionId} Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Deletes a card definition. Returns the deleted card definition. # Draft Card Definition Source: https://docs.voucherify.io/api-reference/card-definitions/draft-card-definition /openapi/loyalties-v2.json post /v2/loyalties/card-definitions/{cardDefinitionId}/draft Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Transitions the card definition from `ACTIVE` back to `DRAFT`. No request body. Drafting from any other state results in an invalid state transition error (409). # Get Card Definition Source: https://docs.voucherify.io/api-reference/card-definitions/get-card-definition /openapi/loyalties-v2.json get /v2/loyalties/card-definitions/{cardDefinitionId} Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Returns a single card definition by its ID. # List Card Definition Activities Source: https://docs.voucherify.io/api-reference/card-definitions/list-card-definition-activities /openapi/loyalties-v2.json get /v2/loyalties/card-definitions/{cardDefinitionId}/activities Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Returns a cursor-paginated list of activities recorded for the card definition (creation, updates, deletion, state transitions and program assignments). Returns `404` when the card definition does not exist. # List Card Definitions Source: https://docs.voucherify.io/api-reference/card-definitions/list-card-definitions /openapi/loyalties-v2.json get /v2/loyalties/card-definitions Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Returns a cursor-paginated list of card definitions. Filtering is supported through the `filters` deep-object query parameter, e.g. `filters[name][conditions][$is]=Standard%20Card`. The same field cannot be requested in both ascending and descending order at the same time. # Update Card Definition Source: https://docs.voucherify.io/api-reference/card-definitions/update-card-definition /openapi/loyalties-v2.json put /v2/loyalties/card-definitions/{cardDefinitionId} Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Updates a card definition. All properties are optional; only provided sections are updated. `type` and `status` cannot be changed through this endpoint (status transitions are performed via the activate/draft endpoints). When the card definition is in use (e.g. assigned to a program with existing cards), updates to restricted sections may be rejected with a resource-locked error; only `name`, `metadata` and `pay_with_points` are always updatable. # Category Object Source: https://docs.voucherify.io/api-reference/categories/category-object

Category

Attributes	Description
id `string`	Unique category ID assigned by Voucherify.
name `string`	Category name.
hierarchy `integer`	Category hierarchy. Categories with lower hierarchy are processed before categories with higher hierarchy value.
object `string`	The type of the object represented by the JSON. This object stores information about the category. Available values: `category`
created\_at `string`	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
updated\_at `string`	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

# Create Category Source: https://docs.voucherify.io/api-reference/categories/create-category /openapi/categories.json post /v1/categories Create category with a specific name and hierarchy. # Delete Category Source: https://docs.voucherify.io/api-reference/categories/delete-category /openapi/categories.json delete /v1/categories/{categoryId} Delete a category by the category ID. # Get Category Source: https://docs.voucherify.io/api-reference/categories/get-category /openapi/categories.json get /v1/categories/{categoryId} Retrieve a category by the category ID. # List Categories Source: https://docs.voucherify.io/api-reference/categories/list-categories /openapi/categories.json get /v1/categories List all categories. # Update Category Source: https://docs.voucherify.io/api-reference/categories/update-category /openapi/categories.json put /v1/categories/{categoryId} Update a category using the category ID. # Check Eligibility (client-side) Source: https://docs.voucherify.io/api-reference/client-side/check-eligibility-client-side /openapi/client-side.json post /client/v1/qualifications Generate a list of redeemables that are applicable in the context of the customer and order. The new qualifications method is an improved version of [Campaign Qualifications](/api-reference/campaigns/examine-campaign-qualification), [Voucher Qualifications](/api-reference/vouchers/examine-voucher-qualification) API requests. The new qualification method introduces the following improvements: - Qualification results are returned faster - No limit on the number of returned redeemables - Introduces new qualification scenarios, not available in the previous version Scenario Guide Read our dedicated guide to learn about some use cases this endpoint can cover [here](/guides/checking-eligibility). ## Paging The Voucherify Qualifications API request will return to you all of the redeemables available for the customer in batches of up to 50 redeemables per page. To get the next batch of redeemables, you need to use the `starting_after` cursor. To process of paging the redeemables works in the following manner: - You send the first API request for Qualifications without the `starting_after` parameter. - The response will contain a parameter named `has_more`. If the parameter's value is set to `true`, then more redeemables are available. - Get the value of the `created_at` parameter of the last returned redeemable. The value of this parameter will be used as a cursor to retrieve the next page of redeemables. - Send another API request for Qualification with the `starting_after` parameter set to the value taken from the `created_at` parameter from the last returned redeemable. - Voucherify will return the next page of redeemables. - If the `has_more` parameter is set to `true`, apply steps 3-5 to get the next page of redeemables. ## Caching Qualification has a 5-minute cache for the returned results. If you change your campaign settings or validation rules, the changes will apply to qualification results after the cache refreshes. # Create Publication (client-side) Source: https://docs.voucherify.io/api-reference/client-side/create-publication-client-side /openapi/client-side.json post /client/v1/publish This method selects vouchers that are suitable for publication, adds a publish entry and returns the publication. A voucher is suitable for publication when it's active and hasn't been published yet. Clearly define the source of the voucher You must clearly define which source you want to publish the voucher code from. It can either be a code from a campaign or a specific voucher identified by a code. Publish multiple vouchers In case you want to publish multiple vouchers within a single publication, you need to specify the campaign name and number of vouchers you want to publish. Auto-update campaign In case you want to ensure the number of publishable codes increases automatically with the number of customers, you should use an **auto-update** campaign. # List Promotion Tiers (client-side) Source: https://docs.voucherify.io/api-reference/client-side/list-promotion-tiers-client-side /openapi/client-side.json get /client/v1/promotions/tiers This method enables you to list promotion tiers. # Redeem Stackable Discounts (client-side) Source: https://docs.voucherify.io/api-reference/client-side/redeem-stackable-discounts-client-side /openapi/client-side.json post /client/v1/redemptions This method is accessible through public keys which you can use in client side requests coming from mobile and web browser applications. ## How API returns calculated discounts and order amounts in the response In the table below, you can see the logic the API follows to calculate discounts and amounts: | **Field** | **Calculation** | **Description** | |:---|:---|:---| | amount | N/A | This field shows the order amount before applying any discount | | total_amount | `total_amount` = `amount` - `total_discount_amount` | This field shows the order amount after applying all the discounts | | discount_amount | `discount_amount` = `previous_discount_amount` + `applied_discount_amount` | This field sums up all order-level discounts up to and including the specific discount being calculated for the stacked redemption. | | items_discount_amount | sum(items, i => i.discount_amount) | This field sums up all product-specific discounts | | total_discount_amount | `total_discount_amount` = `discount_amount` + `items_discount_amount` | This field sums up all order-level and all product-specific discounts | | applied_discount_amount | N/A | This field shows the order-level discount applied in a particular request | | items_applied_discount_amount | sum(items, i => i.applied_discount_amount) | This field sums up all product-specific discounts applied in a particular request | | total_applied_discount_amount | `total_applied_discount_amount` = `applied_discount_amount` + `items_applied_discount_amount` | This field sums up all order-level and all product-specific discounts applied in a particular request | Rollbacks You can't roll back a child redemption. When you call rollback on a stacked redemption, all child redemptions will be rolled back. You need to refer to a parent redemption ID in your [rollback request](/api-reference/redemptions/rollback-stackable-redemptions). # Redeem Voucher (client-side) Source: https://docs.voucherify.io/api-reference/client-side/redeem-voucher-client-side /openapi/client-side.json post /client/v1/redeem Deprecated This endpoint represents the deprecated version of the API responsible for voucher redemption, and we do not recommend using it. The new [Stackable Discounts API](/api-reference/client-side/redeem-stackable-discounts-client-side) introduces additional features and improvements while maintaining backward compatibility, including applying a combination of coupon codes and promotion tiers. 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. To redeem a voucher, you need to create a redemption object. It increments the redemption counter and updates the history of the voucher. This method is accessible through public keys, which you can use in client-side apps (mobile and web browser apps). The client-side redemption works similar to the server-side [voucher redemption](/api-reference/redemptions/redeem-voucher) endpoint. The difference lies in the authorization. For the client-side, you can use client-side keys. Opt-in By default this feature is disabled. If you want to use it, you will need to enable the function explicitly in **Project Settings**. Security Threat Be careful if you want to include the voucher redemption functionality directly on your client side (website or mobile app). In this configuration, there is a chance that discounts can be modified before being sent to the server. ### Expand Response You may expand the response by adding the following object to your request body. The expanded response will include the category details of the voucher. ```json { "options": { "expand": [ "category" ] } } ``` # Track Custom Event (client-side) Source: https://docs.voucherify.io/api-reference/client-side/track-custom-event-client-side /openapi/client-side.json post /client/v1/events To track a custom event, you create an event object. The event object must be linked to the customer who performs the action. If a customer doesn't exist in Voucherify, the customer will be created. # Validate Stackable Discounts (client-side) Source: https://docs.voucherify.io/api-reference/client-side/validate-stackable-discounts-client-side /openapi/client-side.json post /client/v1/validations Verify redeemables provided in the request. This method is accessible through public keys which you can use in client side requests coming from mobile and web browser applications. # Validate Voucher (client-side) Source: https://docs.voucherify.io/api-reference/client-side/validate-voucher-client-side /openapi/client-side.json get /client/v1/validate Deprecated This endpoint represents the deprecated version of the API responsible for voucher validation, and we do not recommend using it. The new [Stackable Discounts API](/api-reference/client-side/validate-stackable-discounts-client-side) introduces additional features and improvements while maintaining backward compatibility, including applying a combination of coupon codes and promotion tiers. 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. To verify a voucher code given by customer, you can use this method. It is designed for client side integration which means that is accessible only through public keys. This method is designed to be run directly either in web browsers or mobile apps. Specifying gift credits and loyalty points This endpoint does not support specifying the specific amount of gift credits to apply to an order nor the specific amount of loyalty points to an order. It calculates the amount that is available on the card and applies as much credits or points as possible to cover the total amount. ### Set customer identity (optional) Voucherify can help you track anonymous customers. Once you integrate Voucherify into your web app and call the validate method, Voucherify will return a tracking ID and the script will store it in a cookie. Each subsequent validate call will use the same tracking ID. Voucherify tracks a user using a tracking ID to see if the user who is validating vouchers is the same as the one who consuming them. Voucherify does this by setting up an identity for the user. A `tracking_id` will be generated on the server side, unless you specify your own `tracking_id`. In both cases, you will receive the `tracking_id` in the validation response. The returned `tracking_id` field should be used as the customer `source_id` in subsequent redemption requests. Moreover, the `tracking_id` returned from Validation API is encoded. Voucherify will recognize both values for identifying customer - the one before encryption sent as a query parameter to the **GET** `v1/validate` request, and the version encrypted and returned as part of the validation request. ### Sample workflow Customer tracking workflow in a nutshell: **Client-side:** * A customer visits your website. * A customer validates a voucher code. That triggers a validate request to be sent to Voucherify. In the request, you pass the tracking_id or customer.source_id. As a result, the API call to this endpoint returns an **encoded** `tracking_id`. **Backend:** * Once the customer finishes the checkout process, your website passes the `tracking_id` to your backend during a redemption call. The `tracking_id` is sent as a value assigned to the property *source_id* in a customer object. * A customer object is created and within the redemption response, you get a customer `id`. * You can use the customer `id` or the customer `source_id` to fetch or modify the customer details. A customer is created (upserted) automatically with a redemption call. Alternatively, you can create a new profile by creating a customer via a dedicated API method. Take a look at the customer object to understand the [entity's structure](/api-reference/customers/customer-object). Customer identifier The source id of the customer may either be an already hashed version of the `tracking_id`, which you received in a response from a validation request or a custom ID you predefined (i.e. an email address). Nevertheless, we recommend using identifiers delivered by Voucherify API. ### Examples with Query Parameters | **Query Parameters** | **Example URL** | |:---|:---| | Shortcut - `customer` query param instead of `customer[source_id]` | `https://api.voucherify.io/client/v1/validate?code=sKKFCKLZ&amount=10100&customer=customer_id` | | Pass `customer`'s and `redemption`'s context `metadata` in query parameters | `https://api.voucherify.io/client/v1/validate?code=sKKFCKLZ&amount=10100&customer=sure_he_is_new&metadata[shop]=1&customer[metadata][propsy]=2&metadata[test]=true` | | Use `tracking_id` instead of `source_id` | `https://api.voucherify.io/client/v1/validate?code=IKU-mvS-JOG&amount=10100&tracking_id=sure_he_is_new_5&metadata[shop]=1&metadata[test]=true` | ### Reasons why a validation might fail Voucher validation might fail because of one of these reasons: * `voucher not found` - voucher doesn't exist or was [deleted](/api-reference/vouchers/delete-voucher) * `voucher expired` - voucher is out of [start date - expiration date] timeframe * `voucher is disabled` - learn more about [disabled vouchers](/api-reference/vouchers/disable-voucher) * `customer does not match segment rules` - learn more about [customer tracking](/api-reference/customers/customer-object) * `order does not match validation rules` - learn more about [validation rules](/api-reference/validations/validation-object) # Created Source: https://docs.voucherify.io/api-reference/customer/created openapi-events/events-customer.json webhook EVENTS.CUSTOMER.CREATED The `EVENTS.CUSTOMER.CREATED` event indicates that a new customer was successfully created in Voucherify. This event is used in a webhook configured in Project settings in Voucherify dashboard. This page documents only the event. If you need more details about the webhook payload data that includes this event, go to [Introduction to webhooks](/api-reference/introduction-to-webhooks "Introduction to webhooks v2024-01-01") page. # Custom Event Source: https://docs.voucherify.io/api-reference/customer/custom-event openapi-events/events-customer.json webhook EVENTS.CUSTOMER.CUSTOM_EVENT The `EVENTS.CUSTOMER.CUSTOM_EVENT` event indicates that a custom event has occurred and it involved a customer. When the event is used in a "Custom event" distribution webhook, the `data` object always contains the following required objects: * `event`, * `event_schema`, * `customer`, * `referral`, * `loyalty`. Additional objects are also sent depending on the purpose: * "Notify customers about promotion" sends also the following objects: * `campaign`, * `promotion_tier`, * "Send and publish unique codes from campaign" sends also the following objects: * `campaign`, * `voucher`, * `publication`, * "Send plain message to customers" sends only the basic objects listed above. This event is used in a webhook configured in Distributions in Voucherify dashboard. This page documents only the event. If you need more details about the webhook payload data that includes this event, go to [Introduction to webhooks](/api-reference/introduction-to-webhooks "Introduction to webhooks v2024-01-01") page. # Deleted Source: https://docs.voucherify.io/api-reference/customer/deleted openapi-events/events-customer.json webhook EVENTS.CUSTOMER.DELETED The `EVENTS.CUSTOMER.DELETED` event indicates that a customer was successfully deleted in Voucherify. This event is used in a webhook configured in Project settings in Voucherify dashboard. This page documents only the event. If you need more details about the webhook payload data that includes this event, go to [Introduction to webhooks](/api-reference/introduction-to-webhooks "Introduction to webhooks v2024-01-01") page. # Holder Assignment Created Source: https://docs.voucherify.io/api-reference/customer/holder-assignment-created openapi-events/events-customer.json webhook EVENTS.CUSTOMER.HOLDER.ASSIGNMENT.CREATED The `EVENTS.CUSTOMER.HOLDER.ASSIGNMENT.CREATED` event indicates that a customer has been assigned to a redeemable. This event is used in a webhook configured in Project settings in Voucherify dashboard. This event can be viewed in Voucherify logs or as part of events listed under the [List Customer Activity](/api-reference/customers/list-customer-activity) endpoint. This page documents only the event. If you need more details about the webhook payload data that includes this event, go to [Introduction to webhooks](/api-reference/introduction-to-webhooks "Introduction to webhooks v2024-01-01") page. # Holder Assignment Deleted Source: https://docs.voucherify.io/api-reference/customer/holder-assignment-deleted openapi-events/events-customer.json webhook EVENTS.CUSTOMER.HOLDER.ASSIGNMENT.DELETED The `EVENTS.CUSTOMER.HOLDER.ASSIGNMENT.DELETED` event indicates that a customer has been unassigned from a redeemable. This event is used in a webhook configured in Project settings in Voucherify dashboard. This event can be viewed in Voucherify logs or as part of events listed under the [List Customer Activity](/api-reference/customers/list-customer-activity) endpoint. This page documents only the event. If you need more details about the webhook payload data that includes this event, go to [Introduction to webhooks](/api-reference/introduction-to-webhooks "Introduction to webhooks v2024-01-01") page. # Loyalty Tier Downgraded Source: https://docs.voucherify.io/api-reference/customer/loyalty-tier-downgraded openapi-events/events-customer.json webhook EVENTS.CUSTOMER.LOYALTY.TIER.DOWNGRADED The `EVENTS.CUSTOMER.LOYALTY.TIER.DOWNGRADED` event indicates that a customer has moved to a lower tier or a specific tier in a loyalty campaign. This event is used in a webhook configured in Distributions in Voucherify dashboard. This page documents only the event. If you need more details about the webhook payload data that includes this event, go to [Introduction to webhooks](/api-reference/introduction-to-webhooks "Introduction to webhooks v2024-01-01") page. # Loyalty Tier Joined Source: https://docs.voucherify.io/api-reference/customer/loyalty-tier-joined openapi-events/events-customer.json webhook EVENTS.CUSTOMER.LOYALTY.TIER.JOINED The `EVENTS.CUSTOMER.LOYALTY.TIER.JOINED` event indicates that a customer has entered a loyalty campaign tier structure or a specific tier. This event is used in a webhook configured in Distributions in Voucherify dashboard. This page documents only the event. If you need more details about the webhook payload data that includes this event, go to [Introduction to webhooks](/api-reference/introduction-to-webhooks "Introduction to webhooks v2024-01-01") page. # Loyalty Tier Left Source: https://docs.voucherify.io/api-reference/customer/loyalty-tier-left openapi-events/events-customer.json webhook EVENTS.CUSTOMER.LOYALTY.TIER.LEFT The `EVENTS.CUSTOMER.LOYALTY.TIER.LEFT` event indicates that a customer has exited a loyalty campaign tier structure or a specific tier. This event is used in a webhook configured in Distributions in Voucherify dashboard. This page documents only the event. If you need more details about the webhook payload data that includes this event, go to [Introduction to webhooks](/api-reference/introduction-to-webhooks "Introduction to webhooks v2024-01-01") page. # Loyalty Tier Prolonged Source: https://docs.voucherify.io/api-reference/customer/loyalty-tier-prolonged openapi-events/events-customer.json webhook EVENTS.CUSTOMER.LOYALTY.TIER.PROLONGED The `EVENTS.CUSTOMER.LOYALTY.TIER.PROLONGED` event indicates that a customer has remained on a loyalty tier or a specific tier in a loyalty campaign under campaign rules even though they no longer qualify for it. This event is used in a webhook configured in Distributions in Voucherify dashboard. This page documents only the event. If you need more details about the webhook payload data that includes this event, go to [Introduction to webhooks](/api-reference/introduction-to-webhooks "Introduction to webhooks v2024-01-01") page. # Loyalty Tier Upgraded Source: https://docs.voucherify.io/api-reference/customer/loyalty-tier-upgraded openapi-events/events-customer.json webhook EVENTS.CUSTOMER.LOYALTY.TIER.UPGRADED The `EVENTS.CUSTOMER.LOYALTY.TIER.UPGRADED` event indicates that a customer has moved to a higher tier or a specific tier in a loyalty campaign. This event is used in a webhook configured in Distributions in Voucherify dashboard. This page documents only the event. If you need more details about the webhook payload data that includes this event, go to [Introduction to webhooks](/api-reference/introduction-to-webhooks "Introduction to webhooks v2024-01-01") page. # Order Canceled Source: https://docs.voucherify.io/api-reference/customer/order-canceled openapi-events/events-customer.json webhook EVENTS.CUSTOMER.ORDER.CANCELED The `EVENTS.CUSTOMER.ORDER.CANCELED` event indicates that a customer-related order has been canceled. When the event is used in an "Order canceled" distribution webhook, the `data` object always contains the following required objects: * `customer`, * `referrer`, * `order`, * `redemption`. Additional objects are also sent depending on the purpose: * "Notify customers about promotion" sends also the following objects: * `campaign`, * `promotion_tier`, * "Send and publish unique codes from campaign" sends also the following objects: * `campaign`, * `voucher`, * `publication`, * "Send plain message to customers" sends only the basic objects listed above. This event is used in a webhook configured in Distributions in Voucherify dashboard. This page documents only the event. If you need more details about the webhook payload data that includes this event, go to [Introduction to webhooks](/api-reference/introduction-to-webhooks "Introduction to webhooks v2024-01-01") page. # Order Created Source: https://docs.voucherify.io/api-reference/customer/order-created openapi-events/events-customer.json webhook EVENTS.CUSTOMER.ORDER.CREATED The `EVENTS.CUSTOMER.ORDER.CREATED` event indicates that a customer-related order has been created. When the event is used in an "Order creation" distribution webhook, the `data` object always contains the following required objects: * `customer`, * `referrer`, * `order`, * `redemption`. Additional objects are also sent depending on the purpose: * "Notify customers about promotion" sends also the following objects: * `campaign`, * `promotion_tier`, * "Send and publish unique codes from campaign" sends also the following objects: * `campaign`, * `voucher`, * `publication`, * "Send plain message to customers" sends only the basic objects listed above. This event is used in a webhook configured in Distributions in Voucherify dashboard. This page documents only the event. If you need more details about the webhook payload data that includes this event, go to [Introduction to webhooks](/api-reference/introduction-to-webhooks "Introduction to webhooks v2024-01-01") page. # Order Paid Source: https://docs.voucherify.io/api-reference/customer/order-paid openapi-events/events-customer.json webhook EVENTS.CUSTOMER.ORDER.PAID The `EVENTS.CUSTOMER.ORDER.PAID` event indicates that a customer-related order has been paid. When the event is used in an "Order has been paid" distribution webhook, the `data` object always contains the following required objects: * `customer`, * `referrer`, * `order`, * `redemption`. Additional objects are also sent depending on the purpose: * "Notify customers about promotion" sends also the following objects: * `campaign`, * `promotion_tier`, * "Send and publish unique codes from campaign" sends also the following objects: * `campaign`, * `voucher`, * `publication`, * "Send plain message to customers" sends only the basic objects listed above. This event is used in a webhook configured in Distributions in Voucherify dashboard. This page documents only the event. If you need more details about the webhook payload data that includes this event, go to [Introduction to webhooks](/api-reference/introduction-to-webhooks "Introduction to webhooks v2024-01-01") page. # Order Updated Source: https://docs.voucherify.io/api-reference/customer/order-updated openapi-events/events-customer.json webhook EVENTS.CUSTOMER.ORDER.UPDATED The `EVENTS.CUSTOMER.ORDER.UPDATED` event indicates that a customer-related order has been updated. When the event is used in an "Order update" distribution webhook, the `data` object always contains the following required objects: * `customer`, * `referrer`, * `order`, * `redemption`. Additional objects are also sent depending on the purpose: * "Notify customers about promotion" sends also the following objects: * `campaign`, * `promotion_tier`, * "Send and publish unique codes from campaign" sends also the following objects: * `campaign`, * `voucher`, * `publication`, * "Send plain message to customers" sends only the basic objects listed above. This event is used in a webhook configured in Distributions in Voucherify dashboard. This page documents only the event. If you need more details about the webhook payload data that includes this event, go to [Introduction to webhooks](/api-reference/introduction-to-webhooks "Introduction to webhooks v2024-01-01") page. # Publication Succeeded Source: https://docs.voucherify.io/api-reference/customer/publication-succeeded openapi-events/events-customer.json webhook EVENTS.CUSTOMER.PUBLICATION.SUCCEEDED The `EVENTS.CUSTOMER.PUBLICATION.SUCCEEDED` event indicates that a voucher code was successfully published to a customer. This event serves as a real-time notification mechanism and it can notify other systems or applications that a voucher was assigned. As a result, the systems can react by, for example, sending a notification about an assignment to a customer. This event is used in a webhook configured in Distributions in Voucherify dashboard. This page documents only the event. If you need more details about the webhook payload data that includes this event, go to [Introduction to webhooks](/api-reference/introduction-to-webhooks "Introduction to webhooks v2024-01-01") page. # Redemption Rollback Succeeded Source: https://docs.voucherify.io/api-reference/customer/redemption-rollback-succeeded openapi-events/events-customer.json webhook EVENTS.CUSTOMER.REDEMPTION.ROLLBACK.SUCCEEDED The `EVENTS.CUSTOMER.REDEMPTION.ROLLBACK.SUCCEEDED` event indicates a redemption was successfully reversed for a customer. This occurs when a previously redeemed voucher code or promotional tier has been rolled back or undone. This event is used in a webhook configured in Distributions in Voucherify dashboard. This page documents only the event. If you need more details about the webhook payload data that includes this event, go to [Introduction to webhooks](/api-reference/introduction-to-webhooks "Introduction to webhooks v2024-01-01") page. # Redemption Succeeded Source: https://docs.voucherify.io/api-reference/customer/redemption-succeeded openapi-events/events-customer.json webhook EVENTS.CUSTOMER.REDEMPTION.SUCCEEDED The `EVENTS.CUSTOMER.REDEMPTION.SUCCEEDED` event indicates that the redemption process was successful with regard to a customer. It confirms that the associated voucher codes and promotional tiers have been effectively applied. This event is used in a webhook configured in Distributions in Voucherify dashboard. This page documents only the event. If you need more details about the webhook payload data that includes this event, go to [Introduction to webhooks](/api-reference/introduction-to-webhooks "Introduction to webhooks v2024-01-01") page. # Reward Redemptions Completed Source: https://docs.voucherify.io/api-reference/customer/reward-redemptions-completed openapi-events/events-customer.json webhook EVENTS.CUSTOMER.REWARD_REDEMPTIONS.COMPLETED The `EVENTS.CUSTOMER.REWARD_REDEMPTIONS.COMPLETED` event indicates that redemption of a reward has been completed. If this event is sent as a notification in a Loyalty campaign, it is also sent with the `publication` object. This page documents only the event. If you need more details about the webhook payload data that includes this event, go to [Introduction to webhooks](/api-reference/introduction-to-webhooks "Introduction to webhooks v2024-01-01") page. # Reward Redemptions Created Source: https://docs.voucherify.io/api-reference/customer/reward-redemptions-created openapi-events/events-customer.json webhook EVENTS.CUSTOMER.REWARD_REDEMPTIONS.CREATED The `EVENTS.CUSTOMER.REWARD_REDEMPTIONS.CREATED` event indicates that redemption of a reward has been created. This event is used in a webhook configured in Project settings in Voucherify dashboard. This page documents only the event. If you need more details about the webhook payload data that includes this event, go to [Introduction to webhooks](/api-reference/introduction-to-webhooks "Introduction to webhooks v2024-01-01") page. # Reward Redemptions Pending Source: https://docs.voucherify.io/api-reference/customer/reward-redemptions-pending openapi-events/events-customer.json webhook EVENTS.CUSTOMER.REWARD_REDEMPTIONS.PENDING The `EVENTS.CUSTOMER.REWARD_REDEMPTIONS.PENDING` event indicates that redemption of a reward is in progress. This event is used in a webhook configured in Project settings in Voucherify dashboard. This page documents only the event. If you need more details about the webhook payload data that includes this event, go to [Introduction to webhooks](/api-reference/introduction-to-webhooks "Introduction to webhooks v2024-01-01") page. # Rewarded Source: https://docs.voucherify.io/api-reference/customer/rewarded openapi-events/events-customer.json webhook EVENTS.CUSTOMER.REWARDED The `EVENTS.CUSTOMER.REWARDED` event indicates that a customer received a reward in exchange for points in a loyalty campaign. The action is usually a manual process started by the customer. This event is used in a webhook configured in Distributions in Voucherify dashboard. This page documents only the event. If you need more details about the webhook payload data that includes this event, go to [Introduction to webhooks](/api-reference/introduction-to-webhooks "Introduction to webhooks v2024-01-01") page. # Rewarded Loyalty Points Source: https://docs.voucherify.io/api-reference/customer/rewarded-loyalty-points openapi-events/events-customer.json webhook EVENTS.CUSTOMER.REWARDED.LOYALTY_POINTS The `EVENTS.CUSTOMER.REWARDED.LOYALTY_POINTS` event indicates that a customer received loyalty points on one of their loyalty cards. The webhook contains the details of the number of points the customer received. If this event is sent as a notification in a Loyalty campaign, it is also sent with the `publication` object. This page documents only the event. If you need more details about the webhook payload data that includes this event, go to [Introduction to webhooks](/api-reference/introduction-to-webhooks "Introduction to webhooks v2024-01-01") page. # Segment Entered Source: https://docs.voucherify.io/api-reference/customer/segment-entered openapi-events/events-customer.json webhook EVENTS.CUSTOMER.SEGMENT.ENTERED The `EVENTS.CUSTOMER.SEGMENT.ENTERED` event indicates that a customer has joined a customer segment. It returns details about the customer and the segment. When the event is used in a "Customer entered segment" distribution webhook, the `data` object always contains the following required objects: * `customer`, * `segment`. Additional objects are also sent depending on the purpose: * "Notify customers about promotion" sends also the following objects: * `campaign`, * `promotion_tier`, * "Send and publish unique codes from campaign" sends also the following objects: * `campaign`, * `voucher`, * `publication`, * "Send plain message to customers" sends only the basic objects listed above. This event is used in a webhook configured in Distributions in Voucherify dashboard. This page documents only the event. If you need more details about the webhook payload data that includes this event, go to [Introduction to webhooks](/api-reference/introduction-to-webhooks "Introduction to webhooks v2024-01-01") page. # Segment Left Source: https://docs.voucherify.io/api-reference/customer/segment-left openapi-events/events-customer.json webhook EVENTS.CUSTOMER.SEGMENT.LEFT The `EVENTS.CUSTOMER.SEGMENT.LEFT` event indicates that a customer has left a customer segment. It returns details about the customer and the segment. When the event is used in a "Customer left segment" distribution webhook, the `data` object always contains the following required objects: * `customer`, * `segment`. Additional objects are also sent depending on the purpose: * "Notify customers about promotion" sends also the following objects: * `campaign`, * `promotion_tier`, * "Send and publish unique codes from campaign" sends also the following objects: * `campaign`, * `voucher`, * `publication`, * "Send plain message to customers" sends only the basic objects listed above. This event is used in a webhook configured in Distributions in Voucherify dashboard. This page documents only the event. If you need more details about the webhook payload data that includes this event, go to [Introduction to webhooks](/api-reference/introduction-to-webhooks "Introduction to webhooks v2024-01-01") page. # Updated Source: https://docs.voucherify.io/api-reference/customer/updated openapi-events/events-customer.json webhook EVENTS.CUSTOMER.UPDATED The `EVENTS.CUSTOMER.UPDATED` event indicates that a customer was successfully updated in Voucherify. This event is used in a webhook configured in Project settings in Voucherify dashboard. The following API endpoints can update customer data, but don't trigger customer update webhooks: * POST `v1/customers/metadata/async` * POST `v1/customers/bulk/async` * POST `v1/customers/importCSV` This page documents only the event. If you need more details about the webhook payload data that includes this event, go to [Introduction to webhooks](/api-reference/introduction-to-webhooks "Introduction to webhooks") page. # Voucher Gift Balance Added Source: https://docs.voucherify.io/api-reference/customer/voucher-gift-balance-added openapi-events/events-customer.json webhook EVENTS.CUSTOMER.VOUCHER.GIFT.BALANCE_ADDED The `EVENTS.CUSTOMER.VOUCHER.GIFT.BALANCE_ADDED` event indicates that additional balance has been successfully added to a customer's gift voucher. It provides real-time notification that the gift voucher's balance has been increased. This event is used in a webhook configured in Distributions in Voucherify dashboard. This page documents only the event. If you need more details about the webhook payload data that includes this event, go to [Introduction to webhooks](/api-reference/introduction-to-webhooks "Introduction to webhooks v2024-01-01") page. # Voucher Loyalty Card Pending Points Activated Source: https://docs.voucherify.io/api-reference/customer/voucher-loyalty-card-pending-points-activated openapi-events/events-customer.json webhook EVENTS.CUSTOMER.VOUCHER.LOYALTY_CARD.PENDING_POINTS.ACTIVATED The `EVENTS.CUSTOMER.VOUCHER.LOYALTY_CARD.PENDING_POINTS.ACTIVATED` event indicates that loyalty pending points have been successfully activated and added to a customer's loyalty card associated with a voucher. The pending points can be activated automatically after a predefined time set in days or manually with the [**POST** Activate Member Pending Points](api-reference/loyalties/activate-member-pending-points) endpoint. This event is used in a webhook configured in Distributions in Voucherify dashboard. This page documents only the event. If you need more details about the webhook payload data that includes this event, go to [Introduction to webhooks](/api-reference/introduction-to-webhooks "Introduction to webhooks v2024-01-01") page. # Voucher Loyalty Card Pending Points Added Source: https://docs.voucherify.io/api-reference/customer/voucher-loyalty-card-pending-points-added openapi-events/events-customer.json webhook EVENTS.CUSTOMER.VOUCHER.LOYALTY_CARD.PENDING_POINTS.ADDED The `EVENTS.CUSTOMER.VOUCHER.LOYALTY_CARD.PENDING_POINTS.ADDED` event indicates that loyalty pending points have been successfully added to a customer's loyalty card associated with a voucher. The pending points activate automatically after a predefined time set in days or they can be activated manually with the [**POST** Activate Member Pending Points](api-reference/loyalties/activate-member-pending-points) endpoint. The pending points can be also canceled manually with the [**POST** Cancel Member Pending Points](/api-reference/loyalties/cancel-member-pending-points) endpoint. This event is used in a webhook configured in Distributions in Voucherify dashboard. This page documents only the event. If you need more details about the webhook payload data that includes this event, go to [Introduction to webhooks](/api-reference/introduction-to-webhooks "Introduction to webhooks v2024-01-01") page. # Voucher Loyalty Card Pending Points Canceled Source: https://docs.voucherify.io/api-reference/customer/voucher-loyalty-card-pending-points-canceled openapi-events/events-customer.json webhook EVENTS.CUSTOMER.VOUCHER.LOYALTY_CARD.PENDING_POINTS.CANCELED The `EVENTS.CUSTOMER.VOUCHER.LOYALTY_CARD.PENDING_POINTS.CANCELED` event indicates that loyalty pending points have been successfully canceled for a customer's loyalty card associated with a voucher. The pending points can be canceled manually with the [**POST** Cancel Member Pending Points](/api-reference/loyalties/cancel-member-pending-points) endpoint. This event is used in a webhook configured in Distributions in Voucherify dashboard. This page documents only the event. If you need more details about the webhook payload data that includes this event, go to [Introduction to webhooks](/api-reference/introduction-to-webhooks "Introduction to webhooks v2024-01-01") page. # Voucher Loyalty Card Pending Points Updated Source: https://docs.voucherify.io/api-reference/customer/voucher-loyalty-card-pending-points-updated openapi-events/events-customer.json webhook EVENTS.CUSTOMER.VOUCHER.LOYALTY_CARD.PENDING_POINTS.UPDATED The `EVENTS.CUSTOMER.VOUCHER.LOYALTY_CARD.PENDING_POINTS.UPDATED` event indicates that loyalty pending points have been updated on a customer's loyalty card associated with a voucher. The pending points can be updated by adding or subtracting points. This event is used in a webhook configured in Distributions in Voucherify dashboard. This page documents only the event. If you need more details about the webhook payload data that includes this event, go to [Introduction to webhooks](/api-reference/introduction-to-webhooks "Introduction to webhooks v2024-01-01") page. # Voucher Loyalty Card Points Added Source: https://docs.voucherify.io/api-reference/customer/voucher-loyalty-card-points-added openapi-events/events-customer.json webhook EVENTS.CUSTOMER.VOUCHER.LOYALTY_CARD.POINTS_ADDED The `EVENTS.CUSTOMER.VOUCHER.LOYALTY_CARD.POINTS_ADDED` event indicates that loyalty points have been successfully added to a customer's loyalty card. It informs about the accumulation of loyalty points. This event is used in a webhook configured in Distributions in Voucherify dashboard. This page documents only the event. If you need more details about the webhook payload data that includes this event, go to [Introduction to webhooks](/api-reference/introduction-to-webhooks "Introduction to webhooks v2024-01-01") page. # Voucher Loyalty Card Points Expired Source: https://docs.voucherify.io/api-reference/customer/voucher-loyalty-card-points-expired openapi-events/events-customer.json webhook EVENTS.CUSTOMER.VOUCHER.LOYALTY_CARD.POINTS_EXPIRED The `EVENTS.CUSTOMER.VOUCHER.LOYALTY_CARD.POINTS_EXPIRED` event indicates that loyalty points have expired on a customer's loyalty card. It informs about the loyalty points that were removed under the expiration rules set in the loyalty campaign. This event is used in a webhook configured in Distributions in Voucherify dashboard. This page documents only the event. If you need more details about the webhook payload data that includes this event, go to [Introduction to webhooks](/api-reference/introduction-to-webhooks "Introduction to webhooks v2024-01-01") page. # Create Customer Source: https://docs.voucherify.io/api-reference/customers/create-customer /openapi/customers.json post /v1/customers Creates a customer object. Upsert Mode If you pass an `id` or a `source_id` that already exists in the customer database, Voucherify will return a related customer object with updated fields. # Customer Activity Object Source: https://docs.voucherify.io/api-reference/customers/customer-activity-object

Customer Activity

Attributes Description

id
string

Unique event ID, assigned by Voucherify.

Example: evcus\_0c150c51730c6b60b1

type
string

Event type.

Available values: customer.confirmed, customer.created, customer.updated, customer.deleted, customer.referred, customer.custom\_event, customer.segment.entered, customer.segment.left, customer.sms.sent, customer.sms.recovered, customer.sms.failed, customer.email.sent, customer.email.recovered, customer.email.failed, customer.activecampaign.sent, customer.activecampaign.recovered, customer.activecampaign.failed, customer.braze.sent, customer.braze.recovered, customer.braze.failed, customer.mailchimp.sent, customer.mailchimp.recovered, customer.mailchimp.failed, customer.intercom.sent, customer.intercom.recovered, customer.intercom.failed, customer.shopify.sent, customer.shopify.recovered, customer.shopify.failed, customer.klaviyo.sent, customer.klaviyo.recovered, customer.klaviyo.failed, customer.batch.sent, customer.batch.recovered, customer.batch.failed, customer.rewarded, customer.rewarded.loyalty\_points, customer.voucher.gift.balance\_added, customer.voucher.loyalty\_card.pending\_points.activated, customer.voucher.loyalty\_card.pending\_points.added, customer.voucher.loyalty\_card.pending\_points.canceled, customer.voucher.loyalty\_card.pending\_points.updated, customer.voucher.loyalty\_card.points\_activated, customer.voucher.loyalty\_card.points\_added, customer.voucher.loyalty\_card.points\_transferred, customer.voucher.loyalty\_card.points\_expired, customer.voucher.deleted, customer.publication.succeeded, customer.publication.failed, customer.validation.succeeded, customer.validation.failed, customer.redemption.failed, customer.redemption.succeeded, customer.redemption.rollback.failed, customer.redemption.rollback.succeeded, customer.order.canceled, customer.order.created, customer.order.fulfilled, customer.order.paid, customer.order.processing, customer.order.updated, customer.reward\_redemptions.created, customer.reward\_redemptions.pending, customer.reward\_redemptions.completed, customer.reward\_redemptions.rolledback, customer.loyalty.updated, customer.loyalty.tier.upgraded, customer.loyalty.tier.downgraded, customer.loyalty.tier.prolonged, customer.loyalty.tier.expiration.changed, customer.loyalty.tier.joined, customer.loyalty.tier.left, customer.holder.assignment.created, customer.holder.assignment.deleted

data
object

Contains details about the event. The objects that are returned in the data attribute differ based on the context of the event type.

Attributes	Description
data	See: Customer Activity Data
event\_source	See: Event Source

created\_at
string

Timestamp representing the date and time when the customer activity occurred in ISO 8601 format.

Example: 2022-08-30T09:14:07.660Z

group\_id
string

Unique identifier of the request that caused the event.

Example: v-1f36113948e50fc4ge

Customer Activity Data

Event data object schema.

One of:

Event Customer Confirmed
Event Customer Created
Event Customer Updated
Event Customer Deleted
Event Customer Referred
Event Customer Custom Event
Event Customer Segment Entered
Event Customer Segment Left
Event Customer SMS Sent
Event Customer SMS Recovered
Event Customer SMS Failed
Event Customer Email Sent
Event Customer Email Recovered
Event Customer Email Failed
Event Customer ActiveCampaign Sent
Event Customer ActiveCampaign Recovered
Event Customer ActiveCampaign Failed
Event Customer Braze Sent
Event Customer Braze Recovered
Event Customer Braze Failed
Event Customer Mailchimp Sent
Event Customer Mailchimp Recovered
Event Customer Mailchimp Failed
Event Customer Intercom Sent
Event Customer Intercom Recovered
Event Customer Intercom Failed
Event Customer Shopify Sent
Event Customer Shopify Recovered
Event Customer Shopify Failed
Event Customer Klaviyo Sent
Event Customer Klaviyo Recovered
Event Customer Klaviyo Failed
Event Customer Batch Sent
Event Customer Batch Recovered
Event Customer Batch Failed
Event Customer Rewarded
Event Customer Rewarded Loyalty Points
Event Customer Gift Voucher Balance Added
Event Customer Loyalty Card Pending Points Activated
Event Customer Loyalty Card Pending Points Added
Event Customer Loyalty Card Pending Points Canceled
Event Customer Loyalty Card Pending Points Updated
Event Customer Loyalty Card Points Added
Event Customer Loyalty Card Points Transferred
Event Customer Loyalty Card Points Expired
Event Customer Voucher Deleted
Event Customer Publication Succeeded
Event Customer Publication Failed
Event Customer Validation Succeeded
Event Customer Validation Failed
Event Customer Redemption Succeeded
Event Customer Redemption Failed
Event Customer Redemption Rollback Succeeded
Event Customer Redemption Rollback Failed
Event Customer Order Canceled
Event Customer Order Created
Event Customer Order Fulfilled
Event Customer Order Paid
Event Customer Order Processing
Event Customer Order Updated
Event Customer Reward Redemptions Created
Event Customer Reward Redemptions Pending
Event Customer Reward Redemptions Completed
Event Customer Reward Redemptions Rolled Back
Event Customer Loyalty Updated
Event Customer Loyalty Tier Upgraded
Event Customer Loyalty Tier Downgraded
Event Customer Loyalty Tier Prolonged
Event Customer Loyalty Tier Expiration Changed
Event Customer Loyalty Tier Joined
Event Customer Loyalty Tier Left
Event Customer Holder Assignment Created
Event Customer Holder Assignment Deleted

Event Source

Attributes Description

channel
string

Determines the channel that initiated the event.

Available values: USER\_PORTAL, API, CLIENT\_API, INTERNAL

Example: API

user
object

Determines the Voucherify user who triggered the event.

Attributes Description

id
string

Unique identifier of the user.

Example: user\_xyzfghSTprSTUVWXYlk6tuvXYst7FGH7

api\_key
object

Determines the API key used to initiate the event.

Attributes Description

name
string

Channel name in the application keys.

app\_id
string

Contains the application ID from the Voucherify API key pair.

Example: 1XXXX5XX-0XXX-XXXb-X7XX-XX2XXaXXX6XX

Event Customer Confirmed

Attributes Description

customer

See: Customer With Summary Loyalty Referrals

unconfirmed\_customer
object

Attributes	Description
id `string`	Example: ucust\_1qa70mVfYkl11Ab0ZxDPdWNa

Event Customer Created

Attributes	Description
customer	See: Customer With Summary Loyalty Referrals

Event Customer Updated

Attributes	Description
customer	See: Customer With Summary Loyalty Referrals

Event Customer Deleted

Attributes	Description
customer	See: Customer With Summary Loyalty Referrals

Event Customer Referred

Attributes	Description
customer	See: Simple Customer
referrer	See: Simple Customer
campaign	See: Simple Campaign
voucher	See: Simple Voucher
custom\_event	See: Custom Event
redemption	See: Redemption Internal

Event Customer Custom Event

Attributes Description

event

See: Custom Event

event\_schema

See: Simple Custom Event

customer

See: Simple Customer

referral
object, null

Details about the referral.

Attributes	Description
referrer	Details about the referrer. Simple Customer
voucher	Details about the referral code. Simple Voucher
campaign	Details about the referral campaign. Simple Campaign

loyalty
object, null

Details about the loyalty activity.

Attributes	Description
voucher	Details about the loyalty code. Simple Voucher
campaign	Details about the loyalty campaign. Simple Campaign

Event Customer Segment Entered

Attributes	Description
customer	See: Customer With Summary Loyalty Referrals
segment	See: Simple Segment

Event Customer Segment Left

Attributes	Description
customer	See: Customer With Summary Loyalty Referrals
segment	See: Simple Segment

See: Simple Customer

holder

See: Simple Customer

voucher

See: Simple Voucher

campaign

See: Simple Campaign

redemption

See: Redemption Internal

reward

See: Simple Redemption Reward Result

referral\_tier

See: Simple Referral Tier

balance
object, null

Balance changed by the event. The amount property details a change in a gift card. The points property details a change in a loyalty card.

Attributes	Description
amount `integer`
points `integer`

custom\_event

See: Custom Event

customer\_event
object, null

Attributes	Description
segment	See: Simple Segment
event\_type `string`	Type of activity that triggered the event.

Event Customer Rewarded Loyalty Points

Attributes Description

customer

See: Simple Customer

holder

See: Simple Customer

voucher

See: Simple Voucher

campaign

See: Simple Campaign

loyalty\_tier

See: Loyalty Tier

earning\_rule

See: Earning Rule

balance

See: Voucher Balance

order

All of:

Order Calculated No Customer Data

Attributes	Description
items `array`	Array of items applied to the order. It can include up to 500 items. Array of Order Item Calculated

event

See: Simple Event

Event Customer Gift Voucher Balance Added

Attributes Description

customer

See: Simple Customer

campaign

See: Simple Campaign

voucher

See: Simple Voucher

balance

See: Voucher Balance

transaction

All of:

Voucher Transaction Base

Attributes Description

details
object

Contains the detailed information about the transaction.

Attributes Description

balance

See: Voucher Balance

order
object

Contains information about the original order.

Attributes	Description
id `string`	Unique order ID.
source\_id `string`	The merchant's order ID if it is different from the Voucherify order ID. It is really useful in case of integration between multiple systems. It can be an order ID from CRM, database or 3rd party service.

event
object

Contains information about the event that triggers the point accrual.

Attributes	Description
id `string`	Unique event ID.
type `string`	Type of event.

earning\_rule
object

Contains information about the earning rule.

Attributes Description

id
string

Unique identifier of an earning rule, assigned by Voucherify.

source
object

Contains the custom earning rule name.

Attributes	Description
banner `string`	Name of the earning rule. This is displayed as a header for the earning rule in the Dashboard.

segment
object

Contains information about the segment.

Attributes	Description
id `string`
name `string`

loyalty\_tier
object

Contains information about the loyalty tier.

Attributes	Description
id `string`	Unique identifier of the loyalty tier, assigned by Voucherify.
name `string`	User-defined name of the loyalty tier.

redemption
object

Contains information about the original redemption.

Attributes	Description
id `string`	Unique redemption ID.

rollback
object

Contains information about the redemption rollback.

Attributes	Description
id `string`	Unique redemption rollback ID.

custom\_event
object

Contains information about the custom event that triggers the point accrual.

Attributes	Description
id `string`	Unique event ID.
type `string`	Type of custom event.

event\_schema
object

Contains information about the custom event metadata schema.

Attributes	Description
id `string`	Unique metadata schema ID.
name `string`	Type of custom event.

reward
object

Contains information about the pay with points reward.

Attributes	Description
id `string`	Unique reward ID.
name `string`	Reward name.

source\_voucher

Contains information on how the balance on the donor loyalty card was affected by the transaction.

Simple Voucher

destination\_voucher

Contains information on how the balance on the receiving loyalty card was affected by the transaction.

Simple Voucher

type
string

Transaction type concerning gift card credits.

Available values: CREDITS\_ADDITION

Event Customer Loyalty Card Pending Points Activated

Attributes	Description
customer	See: Simple Customer
campaign	See: Simple Campaign
voucher	See: Simple Voucher
balance	See: Voucher Balance
order	See: Simple Order
transaction	See: Voucher Transaction
pending\_points	See: Loyalty Pending Point Entry

Event Customer Loyalty Card Pending Points Added

Attributes	Description
customer	See: Simple Customer
campaign	See: Simple Campaign
voucher	See: Simple Voucher
voucher\_pending\_points\_balance	See: Voucher Balance
order	See: Simple Order
pending\_points	See: Loyalty Pending Point Entry

Event Customer Loyalty Card Pending Points Canceled

Attributes	Description
customer	See: Simple Customer
campaign	See: Simple Campaign
voucher	See: Simple Voucher
voucher\_pending\_points\_balance	See: Voucher Balance
order	See: Simple Order
pending\_points	See: Loyalty Pending Point Entry

Event Customer Loyalty Card Pending Points Updated

Attributes	Description
customer	See: Simple Customer
campaign	See: Simple Campaign
voucher	See: Simple Voucher
voucher\_pending\_points\_balance	See: Voucher Balance
order	See: Simple Order
pending\_points	See: Loyalty Pending Point Entry

Event Customer Loyalty Card Points Added

Attributes Description

customer

See: Simple Customer

campaign

See: Simple Campaign

voucher

See: Simple Voucher

balance

See: Voucher Balance

transaction

All of:

Voucher Transaction Base

Attributes Description

details
object

Contains the detailed information about the transaction.

Attributes Description

balance

See: Voucher Balance

order
object

Contains information about the original order.

Attributes	Description
id `string`	Unique order ID.
source\_id `string`	The merchant's order ID if it is different from the Voucherify order ID. It is really useful in case of integration between multiple systems. It can be an order ID from CRM, database or 3rd party service.

event
object

Contains information about the event that triggers the point accrual.

Attributes	Description
id `string`	Unique event ID.
type `string`	Type of event.

earning\_rule
object

Contains information about the earning rule.

Attributes Description

id
string

Unique identifier of an earning rule, assigned by Voucherify.

source
object

Contains the custom earning rule name.

Attributes	Description
banner `string`	Name of the earning rule. This is displayed as a header for the earning rule in the Dashboard.

segment
object

Contains information about the segment.

Attributes	Description
id `string`
name `string`

loyalty\_tier
object

Contains information about the loyalty tier.

Attributes	Description
id `string`	Unique identifier of the loyalty tier, assigned by Voucherify.
name `string`	User-defined name of the loyalty tier.

redemption
object

Contains information about the original redemption.

Attributes	Description
id `string`	Unique redemption ID.

rollback
object

Contains information about the redemption rollback.

Attributes	Description
id `string`	Unique redemption rollback ID.

custom\_event
object

Contains information about the custom event that triggers the point accrual.

Attributes	Description
id `string`	Unique event ID.
type `string`	Type of custom event.

holder\_loyalty\_tier
object

Loyalty tier of the loyalty card holder at the moment when the transaction occurred. The loyalty tier is the tier in which the holder was before the loyalty point balance changed.

Attributes	Description
id `string`	Unique identifier of the loyalty tier, assigned by Voucherify.
name `string`	User-defined name of the loyalty tier.

event\_schema
object

Contains information about the custom event metadata schema.

Attributes	Description
id `string`	Unique metadata schema ID.
name `string`	Type of custom event.

reward
object

Contains information about the pay with points reward.

Attributes	Description
id `string`	Unique reward ID.
name `string`	Reward name.

source\_voucher

Contains information on how the balance on the donor loyalty card was affected by the transaction.

Simple Voucher

destination\_voucher

Contains information on how the balance on the receiving loyalty card was affected by the transaction.

Simple Voucher

type
string

Transaction type concerning loyalty card points.

Available values: POINTS\_ACCRUAL

Event Customer Loyalty Card Points Transferred

Attributes Description

customer

See: Simple Customer

campaign

See: Simple Campaign

voucher

See: Simple Voucher

source\_voucher

See: Simple Voucher

destination\_voucher

See: Simple Voucher

balance

See: Voucher Balance

transaction

All of:

Voucher Transaction Base

Attributes Description

details
object

Contains the detailed information about the transaction.

Attributes Description

balance

See: Voucher Balance

order
object

Contains information about the original order.

Attributes	Description
id `string`	Unique order ID.
source\_id `string`	The merchant's order ID if it is different from the Voucherify order ID. It is really useful in case of integration between multiple systems. It can be an order ID from CRM, database or 3rd party service.

event
object

Contains information about the event that triggers the point accrual.

Attributes	Description
id `string`	Unique event ID.
type `string`	Type of event.

earning\_rule
object

Contains information about the earning rule.

Attributes Description

id
string

Unique identifier of an earning rule, assigned by Voucherify.

source
object

Contains the custom earning rule name.

Attributes	Description
banner `string`	Name of the earning rule. This is displayed as a header for the earning rule in the Dashboard.

segment
object

Contains information about the segment.

Attributes	Description
id `string`
name `string`

loyalty\_tier
object

Contains information about the loyalty tier.

Attributes	Description
id `string`	Unique identifier of the loyalty tier, assigned by Voucherify.
name `string`	User-defined name of the loyalty tier.

redemption
object

Contains information about the original redemption.

Attributes	Description
id `string`	Unique redemption ID.

rollback
object

Contains information about the redemption rollback.

Attributes	Description
id `string`	Unique redemption rollback ID.

custom\_event
object

Contains information about the custom event that triggers the point accrual.

Attributes	Description
id `string`	Unique event ID.
type `string`	Type of custom event.

event\_schema
object

Contains information about the custom event metadata schema.

Attributes	Description
id `string`	Unique metadata schema ID.
name `string`	Type of custom event.

holder\_loyalty\_tier
object

Loyalty tier of the loyalty card holder at the moment when the transaction occurred. The loyalty tier is the tier in which the holder was before the loyalty point balance changed.

Attributes	Description
id `string`	Unique identifier of the loyalty tier, assigned by Voucherify.
name `string`	User-defined name of the loyalty tier.

reward
object

Contains information about the pay with points reward.

Attributes	Description
id `string`	Unique reward ID.
name `string`	Reward name.

source\_voucher

Contains information on how the balance on the donor loyalty card was affected by the transaction.

Simple Voucher

destination\_voucher

Contains information on how the balance on the receiving loyalty card was affected by the transaction.

Simple Voucher

type
string

Transaction type concerning loyalty card points.

Available values: POINTS\_TRANSFER\_IN, POINTS\_TRANSFER\_OUT

Event Customer Loyalty Card Points Expired

Attributes Description

customer

See: Simple Customer

campaign

See: Simple Campaign

voucher

See: Simple Voucher

points
integer

The number of expired points.

buckets
array

Array of Loyalty Point Bucket

transaction

All of:

Voucher Transaction Base

Attributes Description

details
object

Contains the detailed information about the transaction.

Attributes Description

balance

See: Voucher Balance

order
object

Contains information about the original order.

Attributes	Description
id `string`	Unique order ID.
source\_id `string`	The merchant's order ID if it is different from the Voucherify order ID. It is really useful in case of integration between multiple systems. It can be an order ID from CRM, database or 3rd party service.

event
object

Contains information about the event that triggers the point accrual.

Attributes	Description
id `string`	Unique event ID.
type `string`	Type of event.

earning\_rule
object

Contains information about the earning rule.

Attributes Description

id
string

Unique identifier of an earning rule, assigned by Voucherify.

source
object

Contains the custom earning rule name.

Attributes	Description
banner `string`	Name of the earning rule. This is displayed as a header for the earning rule in the Dashboard.

segment
object

Contains information about the segment.

Attributes	Description
id `string`
name `string`

loyalty\_tier
object

Contains information about the loyalty tier.

Attributes	Description
id `string`	Unique identifier of the loyalty tier, assigned by Voucherify.
name `string`	User-defined name of the loyalty tier.

redemption
object

Contains information about the original redemption.

Attributes	Description
id `string`	Unique redemption ID.

rollback
object

Contains information about the redemption rollback.

Attributes	Description
id `string`	Unique redemption rollback ID.

custom\_event
object

Contains information about the custom event that triggers the point accrual.

Attributes	Description
id `string`	Unique event ID.
type `string`	Type of custom event.

event\_schema
object

Contains information about the custom event metadata schema.

Attributes	Description
id `string`	Unique metadata schema ID.
name `string`	Type of custom event.

holder\_loyalty\_tier
object

Loyalty tier of the loyalty card holder at the moment when the transaction occurred. The loyalty tier is the tier in which the holder was before the loyalty point balance changed.

Attributes	Description
id `string`	Unique identifier of the loyalty tier, assigned by Voucherify.
name `string`	User-defined name of the loyalty tier.

reward
object

Contains information about the pay with points reward.

Attributes	Description
id `string`	Unique reward ID.
name `string`	Reward name.

source\_voucher

Contains information on how the balance on the donor loyalty card was affected by the transaction.

Simple Voucher

destination\_voucher

Contains information on how the balance on the receiving loyalty card was affected by the transaction.

Simple Voucher

type
string

Transaction type concerning loyalty card points.

Available values: POINTS\_EXPIRATION

Event Customer Voucher Deleted

Attributes	Description
customer	See: Simple Customer
campaign	See: Simple Campaign
voucher	See: Simple Voucher

Event Customer Publication Succeeded

Attributes	Description
customer	See: Simple Customer
campaign	See: Simple Campaign
publication	See: Valid Single Voucher

Event Customer Publication Failed

Attributes	Description
customer	See: Simple Customer
campaign	See: Simple Campaign
publication	See: Valid Single Voucher

Event Customer Validation Succeeded

Attributes	Description
customer	See: Simple Customer
validation	See: Validation Entity

Event Customer Validation Failed

Attributes	Description
customer	See: Simple Customer
validation	See: Validation Entity

Event Customer Redemption Succeeded

Event data object schema for customer.redemption.succeeded.

Event Customer Redemption

Event Customer Redemption Failed

Event data object schema for customer.redemption.failed.

Event Customer Redemption

Event Customer Redemption Rollback Succeeded

Event data object schema for customer.redemption.rollback.succeeded.

All of:

Event Customer Redemption

Attributes	Description
redemption\_rollback	See: Simple Redemption

Event Customer Redemption Rollback Failed

Event data object schema for customer.redemption.rollback.failed.

All of:

Event Customer Redemption

Attributes	Description
redemption\_rollback	See: Simple Redemption

Event Customer Loyalty Updated

Attributes	Description
customer	See: Simple Customer
campaign	See: Simple Campaign
loyalty `object`
created\_at `string`	Example: 2022-02-25T13:32:08.734Z

Event Customer Loyalty Tier Upgraded

Event data object schema for customer.loyalty.tier.upgraded.

All of:

Event Customer Loyalty Tier Base

Loyalty Tier Upgraded

Attributes	Description
loyalty\_tier\_from	See: Loyalty Tier
loyalty\_tier\_to	See: Loyalty Tier
created\_at `string`	Example: 2022-02-25T13:32:08.734Z

Event Customer Loyalty Tier Downgraded

Event data object schema for customer.loyalty.tier.downgraded.

All of:

Event Customer Loyalty Tier Base

Loyalty Tier Downgraded

Attributes	Description
loyalty\_tier\_from	See: Loyalty Tier
loyalty\_tier\_to	See: Loyalty Tier
created\_at `string`	Example: 2022-02-25T13:32:08.734Z

Event Customer Loyalty Tier Prolonged

Event data object schema for customer.loyalty.tier.prolonged.

All of:

Event Customer Loyalty Tier Base

Loyalty Tier Prolonged

Attributes	Description
loyalty\_tier	See: Loyalty Tier
created\_at `string`	Example: 2022-02-25T13:32:08.734Z

Event Customer Loyalty Tier Expiration Changed

Event data object schema for customer.loyalty.tier.expiration.changed.

All of:

Event Customer Loyalty Tier Base

Loyalty Tier Expiration Changed

Attributes	Description
loyalty\_tier	See: Loyalty Tier
created\_at `string`	Example: 2022-02-25T13:32:08.734Z
expiration\_date `string`	Example: 2022-02-25T13:32:08.734Z

Event Customer Loyalty Tier Joined

Event data object schema for customer.loyalty.tier.joined.

All of:

Event Customer Loyalty Tier Base

Loyalty Tier Joined

Attributes	Description
loyalty\_tier	See: Loyalty Tier
created\_at `string`	Example: 2022-02-25T13:32:08.734Z

Event Customer Loyalty Tier Left

Event data object schema for customer.loyalty.tier.left.

All of:

Event Customer Loyalty Tier Base

Loyalty Tier Left

Attributes	Description
loyalty\_tier	See: Loyalty Tier
created\_at `string`	Example: 2022-02-25T13:32:08.734Z

Event Customer Holder Assignment Created

Attributes	Description
holder	See: Redeemable Holder
voucher	See: Simple Voucher
campaign	See: Simple Campaign
customer	See: Simple Customer

Event Customer Holder Assignment Deleted

Attributes	Description
holder	See: Redeemable Holder
voucher	See: Simple Voucher
campaign	See: Simple Campaign
customer	See: Simple Customer

Customer With Summary Loyalty Referrals

All of:

Customer Response Data

Attributes Description

id
string

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

source\_id
string

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.

summary

Customer Summary

loyalty

Customer Loyalty

referrals

Customer Referrals

system\_metadata
object

Object used to store system metadata information.

created\_at
string

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

Example: 2022-08-30T06:32:07.380Z

updated\_at
string

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

Example: 2022-08-31T06:32:07.380Z

assets
object

Contains information about the customer's cockpit.

⚠️ Warning: Customer cockpits were removed. The customer cockpit URLs redirect to customer preference center.

Attributes	Description
cockpit\_url `string`	URL address to customer preference center. Previously, a customer's cockpit URL address.
cockpit\_preference\_center\_url `string`	URL address to customer preference center.

object
string

The type of the object represented by JSON.

Available values: customer

Customer Base

Simple Customer

Attributes	Description
id `string`	Unique identifier of an existing customer. It is assigned by Voucherify.
name `string`	Customer's first and last name.
email `string`	Customer's email address.
source\_id `string`	A unique identifier of the customer. It can be a customer ID or email from a CRM system, database, or a third-party service.
metadata `object`	A set of custom key/value pairs that are attached to the customer. It stores all custom attributes assigned to the customer.
object `string`	The type of the object represented by JSON. Available values: `customer`

Simple Campaign

Attributes	Description
id `string`	Campaign ID.
name `string`	Campaign name.
campaign\_type `string`	Type of campaign.
type `string`	Defines whether the campaign can be updated with new vouchers after campaign creation or if the campaign consists of generic (standalone) vouchers. `AUTO\_UPDATE` : the campaign is dynamic, i.e. vouchers will generate based on set criteria `STATIC` : vouchers need to be manually published `STANDALONE` : campaign for single vouchers Available values: `AUTO\_UPDATE`, `STATIC`, `STANDALONE`
is\_referral\_code `boolean`	Flag indicating whether this voucher is a referral code; `true` for campaign type `REFERRAL\_PROGRAM`.
voucher	See: Simple Campaign Voucher
referral\_program	See: Referral Program
auto\_join `boolean`	Indicates whether customers will be able to auto-join the campaign if any earning rule is fulfilled.
join\_once `boolean`	If this value is set to `true`, customers will be able to join the campaign only once. It is always `false` for generic (standalone) vouchers campaigns and it cannot be changed in them. It is always `true` for loyalty campaigns and it cannot be changed in them.
active `boolean`	Indicates whether the campaign is active.
category\_id `string`, `null`	The unique category ID that this campaign belongs to.
category `string`	Unique category name.
categories `array`	Contains details about the category. Array of Category
metadata `object`	A set of custom key/value pairs that you can attach to a campaign. The metadata object stores all custom attributes assigned to the campaign.
start\_date `string`	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 `string`	Expiration timestamp defines when the campaign expires in ISO 8601 format. Campaign is inactive after this date. Example: 2022-09-30T00:00:00.000Z
description `string`	An optional field to keep extra textual information about the campaign such as a campaign description and details.
created\_at `string`	Timestamp representing the date and time when the campaign was created. The value is shown in the ISO 8601 format. Example: 2024-01-01T11:11:11.111Z
updated\_at `string`	Timestamp representing the date and time when the campaign was updated in the ISO 8601 format. Example: 2024-01-01T11:11:11.111Z
object `string`	The type of the object represented by JSON. This object stores information about the campaign. Available values: `campaign`

Simple Voucher

Attributes Description

id
string

A unique identifier that represents the voucher assigned by Voucherify.

code
string

Voucher code.

gift

Gift object response.

Gift

discount

See: Discount

loyalty\_card
object

Defines the loyalty card details.

Simple Loyalty Card

type
string

Type of the voucher.

Available values: DISCOUNT\_VOUCHER, LOYALTY\_CARD, GIFT\_VOUCHER

campaign
string

Campaign name.

campaign\_id
string

Campaign unique ID.

is\_referral\_code
boolean

Flag indicating whether this voucher is a referral code; true for campaign type REFERRAL\_PROGRAM.

holder\_id
string

Unique customer identifier of the redeemable holder. It equals to the customer ID assigned by Voucherify.

Example: cust\_eWgXlBBiY6THFRJwX45Iakv4

referrer\_id
string

Unique identifier of the referrer assigned by Voucherify.

Example: cust\_nM4jqPiaXUvQdVSA6vTRUnix

category\_id
string, null

Unique identifier of the category that this voucher belongs to.

Example: cat\_0b6152ce12414820dc

categories
array

Contains details about the category.

Array of Category

active
boolean

Shows whether the voucher is on or off. true indicates an active voucher and false indicates an inactive voucher.

created\_at
string

Timestamp representing the date and time when the order was created in the ISO 8601 format.

Example: 2021-12-22T10:13:06.487Z

updated\_at
string

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

Example: 2024-01-01T11:11:11.111Z

redemption
object

Defines the redemption limits on vouchers.

Attributes Description

quantity
integer, null

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

redeemed\_quantity
integer

How many times a voucher has already been redeemed.

Example: 1

redeemed\_points
integer

Total loyalty points redeemed.

start\_date
string

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

Example: 2021-12-01T00:00:00.000Z

expiration\_date
string

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

Example: 2021-12-31T00:00:00.000Z

metadata
object

A set of custom key/value pairs that you can attach to a voucher. The metadata object stores all custom attributes assigned to the voucher.

object
string

The type of the object represented by JSON.

Available values: voucher

Custom Event

Attributes Description

id
string

Unique custom event ID.

object
string

The object represented is an event.

Available values: event

type
string

The event name.

customer

A simple customer object

Customer Object Required Object Type

referral
object

Referral object.

Attributes Description

referrer\_id
string

Unique referrer ID.

Example: cust\_nM4jqPiaXUvQdVSA6vTRUnix

code
string

Voucher code.

id
string

Unique voucher ID.

loyalty
object

Loyalty object.

Attributes	Description
code `string`	Loyalty card code.

metadata
object

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

created\_at
string

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

Example: 2021-12-22T10:13:06.487Z

Redemption Internal

Attributes Description

id
string

Unique redemption ID.

Example: r\_0bc92f81a6801f9bca

object
string

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

created\_at
string

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

Example: 2021-12-22T10:13:06.487Z

tracking\_id
string

Hashed customer source ID.

metadata
object

The metadata object stores all custom attributes assigned to the redemption.

channel\_type
string

The source of the channel for the redemption rollback. A USER corresponds to the Voucherify Dashboard and an API corresponds to the API.

Available values: USER, API

channel\_id
string

Unique channel ID of the user performing the redemption. This is either a user ID from a user using the Voucherify Dashboard or an X-APP-Id of a user using the API.

Example: user\_g24UoRO3Caxu7FCT4n5tpYEa3zUG0FrH

failure\_code
string

If the result is FAILURE, this parameter will provide a generic reason as to why the redemption failed.

Example: customer\_rules\_violated

failure\_message
string

If the result is FAILURE, this parameter will provide a more expanded reason as to why the redemption failed.

order

All of:

Order Calculated No Customer Data

Attributes	Description
items `array`	Array of items applied to the order. It can include up to 500 items. Array of Order Item Calculated

previous\_order

All of:

Order Calculated No Customer Data

Attributes	Description
items `array`	Array of items applied to the order. It can include up to 500 items. Array of Order Item Calculated

reward

See: Redemption Reward Result

amount
integer

For gift cards, this is a positive integer in the smallest currency unit (e.g. 100 cents for \$1.00) representing the number of redeemed credits.
For loyalty cards, this is the number of loyalty points used in the transaction.

Example: 10000

reason
string

System generated cause for the redemption being invalid in the context of the provided parameters.

result
string

Redemption result.

Available values: SUCCESS, FAILURE

status
string

Redemption status.

Available values: SUCCEEDED, FAILED

related\_redemptions
object

Attributes Description

rollbacks
array

Array of:

Redemption Internal Related Redemptions Rollbacks Item

Attributes Description

id
string

Unique rollback redemption ID.

Example: rr\_0bc92f81a6801f9bca

date
string

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

Example: 2021-12-22T10:13:06.487Z

redemptions
array

Array of:

Redemption Internal Related Redemptions Item

Attributes Description

id
string

Unique redemption ID.

Example: r\_0bc92f81a6801f9bca

date
string

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

Example: 2021-12-22T10:13:06.487Z

parent\_redemption\_id
string

Unique redemption ID of the parent redemption.

Example: r\_0c656311b5878a2031

redemption
string

Unique redemption ID of the parent redemption.

Example: r\_0c656311b5878a2031

customer

See: Simple Customer

customer\_id
string, null

Unique customer ID of the redeeming customer.

Example: cust\_i8t5Tt6eiKG5K79KQlJ0Vs64

related\_object\_type
string

Defines the related object.

Available values: voucher, promotion\_tier

related\_object\_id
string

Unique related object ID assigned by Voucherify, i.e. v\_lfZi4rcEGe0sN9gmnj40bzwK2FH6QUno for a voucher.

related\_object\_parent\_id
string

Unique related parent object ID assigned by Voucherify, i.e. v\_lfZi4rcEGe0sN9gmnj40bzwK2FH6QUno for a voucher.

campaign\_name
string

Campaign name

voucher

Defines the details of the voucher being redeemed.

All of:

Voucher
Voucher Holder

promotion\_tier

Contains details of the promotion tier and the parent campaign.

Promotion Tier

Simple Custom Event

Attributes	Description
id `string`	Unique identifier of the custom event.
name `string`	Name of the custom event.

Simple Segment

Attributes Description

id
string

Unique segment ID.

Example: seg\_DNAOhUtJffvX0f57ajLMFBYR

name
string

Segment name.

object
string

The type of the object represented by the ID.

Available values: segment

Event Customer Sent

Attributes Description

customer

See: Simple Customer

distribution
object

sent\_at
string

Timestamp representing the date and time when the distribution was sent in ISO 8601 format.

Example: 2021-12-22T10:13:06.487Z

Event Customer Recovered

Attributes Description

customer

See: Simple Customer

distribution
object

recovered\_at
string

Timestamp representing the date and time when the distribution was recovered in ISO 8601 format.

Example: 2021-12-22T10:13:06.487Z

Event Customer Failed

Attributes Description

customer

See: Simple Customer

distribution
object

failed\_at
string

Timestamp representing the date and time when the distribution failed in ISO 8601 format.

Example: 2021-12-22T10:13:06.487Z

Simple Redemption Reward Result

Attributes	Description
customer	See: Simple Customer
assignment\_id `string`	Unique reward assignment ID assigned by Voucherify.
voucher	Simple Voucher
product	Simple Product
sku	Simple Sku
loyalty\_tier\_id `string`	Unique loyalty tier ID assigned by Voucherify.
id `string`	Unique reward ID, assigned by Voucherify. Example: rew\_nIy4gHpQHle2c3pNMwuj7G6j
object `string`	The type of the object represented by the JSON. This object stores information about the reward. Available values: `reward`
name `string`	Reward name.
created\_at `string`	Timestamp representing the date and time when the reward was created. The value is shown in the ISO 8601 format. Example: 2024-01-01T11:11:11.111Z
updated\_at `string`, `null`	Timestamp representing the date and time when the reward was updated. The value is shown in the ISO 8601 format. Example: 2024-01-01T11:11:11.111Z
parameters `object`	Defines how the reward is generated. Reward type
metadata `object`	A set of custom key/value pairs that you can attach to a reward. The metadata object stores all custom attributes assigned to the reward.
type `string`	Reward type. Available values: `CAMPAIGN`, `COIN`, `MATERIAL`

Simple Referral Tier

Attributes	Description
id `string`	Unique referral tier ID. Example: seg\_DNAOhUtJffvX0f57ajLMFBYR
campaign\_id `string`	Campaign Id.
banner `string`	Text to be displayed to your customers on your website.
parameters `object`	Referral tier parameters

Loyalty Tier

All of:

Loyalty Tier Base

Attributes Description

id
string

Unique loyalty tier ID.

campaign\_id
string

Unique parent campaign ID.

metadata
object, null

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

created\_at
string

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

updated\_at
string, null

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

config
object

Defines loyalty tier range in points.

Attributes Description

points
object

Defines range of loyalty tier in points.

Attributes	Description
from `integer`	Bottom points threshold value.
to `integer`	Top points threshold value.

expiration

See: Loyalty Tier Expiration

object
string

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

Available values: loyalty\_tier

Earning Rule

All of:

EarningRuleBase

Attributes Description

validation\_rule\_id
string, null

A unique validation rule identifier assigned by the Voucherify API. The validation rule is verified before points are added to the balance.

updated\_at
string, null

Timestamp representing the date and time when the earning rule was last updated in ISO 8601 format.

active
boolean

A flag to toggle the earning rule on or off. You can disable an earning rule even though it's within the active period defined by the start\_date and expiration\_date of the campaign or the earning rule's own start\_date and expiration\_date.

true indicates an active earning rule
false indicates an inactive earning rule

Voucher Balance

Attributes Description

type
string

The type of voucher whose balance is being adjusted due to the transaction.

Available values: loyalty\_card, gift\_voucher

total
integer

The number of all points or credits accumulated on the card as affected by add or subtract operations.

object
string

The type of the object represented by the JSON.

Available values: balance

amount
integer

Credits added or subtracted on a gift card.

points
integer

Points added or subtracted in the transaction of a loyalty card.

balance
integer

The available points or credits on the card after the transaction as affected by redemption or rollback.

operation\_type
string

The type of the operation being performed. The operation type is AUTOMATIC if it is an automatic redemption.

Available values: MANUAL, AUTOMATIC

related\_object
object

Defines the resource that is being modified with the values that are returned in the balance object.

Attributes Description

id
string

Identifies the voucher that is being modified. The ID is assigned by the Voucherify API.

type
string

The object being modified, i.e. voucher.

Available values: voucher

Order Calculated No Customer Data

Attributes Description

id
string

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

source\_id
string, null

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

status
string

The order status.

Available values: CREATED, PAID, CANCELED, FULFILLED

amount
integer

This is the sum of the order items' amounts. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for \$1.00).

initial\_amount
integer

This is the sum of the order items' amounts before any discount or other effect (e.g. add missing units) is applied. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for \$1.00).

discount\_amount
integer

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\_discount\_amount
integer

Sum of all product-specific discounts applied to the order. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for \$1.00).

total\_discount\_amount
integer

Sum of all order-level AND all product-specific discounts applied to the order. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for \$1.00).

total\_amount
integer

Order amount after undoing all the discounts through the rollback redemption. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for \$1.00).

applied\_discount\_amount
integer

This field shows the order-level discount applied. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for \$1.00).

items\_applied\_discount\_amount
integer

Sum of all product-specific discounts applied in a particular request. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for \$1.00).
sum(items, i =>i.applied\_discount\_amount)

total\_applied\_discount\_amount
integer

Sum of all order-level AND all product-specific discounts applied in a particular request. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for \$1.00).
total\_applied\_discount\_amount \= applied\_discount\_amount \+ items\_applied\_discount\_amount

metadata
object

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.

object
string

The type of the object represented by JSON.

Available values: order

created\_at
string

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

Example: 2021-12-22T10:13:06.487Z

updated\_at
string, null

Timestamp representing the date and time when the order was last updated in ISO 8601 format.

Example: 2021-12-22T10:14:45.316Z

customer\_id
string, null

Unique customer identifier of the customer making the purchase. The ID is assigned by Voucherify.

Example: cust\_7iUa6ICKyU6gH40dBU25kQU1

referrer\_id
string, null

Unique referrer ID.

Example: cust\_nM4jqPiaXUvQdVSA6vTRUnix

customer

Customer Id

referrer

Referrer Id

redemptions
object

Attributes	Description
\[propertyName]	See: Order Redemptions

Order Item Calculated

Attributes Description

id
string

Unique identifier of the order line item.

sku\_id
string

Unique identifier of the SKU. It is assigned by Voucherify.

product\_id
string

Unique identifier of the product. It is assigned by Voucherify.

related\_object
string

Used along with the source\_id property, can be set to either sku or product.

Available values: product, sku

source\_id
string

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
integer

The quantity of the particular item in the cart.

discount\_quantity
integer

Number of dicounted items.

initial\_quantity
integer

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
integer

The total amount of the order item (price \* quantity).

discount\_amount
integer

Sum of all order-item-level discounts applied to the order.

applied\_discount\_amount
integer

This field shows the order-level discount applied.

applied\_discount\_quantity
integer

Number of the discounted items applied in the transaction.

applied\_quantity
integer

Quantity of items changed by the application of a new quantity items. It can be positive when an item is added or negative if an item is replaced.

applied\_quantity\_amount
integer

Amount for the items changed by the application of a new quantity items. It can be positive when an item is added or negative if an item is replaced.

initial\_amount
integer

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
integer

Unit price of an item. The value is multiplied by 100 to represent 2 decimal places. For example 10000 cents for \$100.00.

subtotal\_amount
integer

Final order item amount after the applied item-level discount. If there are no item-level discounts applied, this item is equal to the amount.
subtotal\_amount \= amount \- applied\_discount\_amount

product
object

An object containing details of the related product.

Attributes	Description
id `string`	A unique identifier that represents the product and is assigned by Voucherify.
source\_id `string`	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 `boolean`	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.
name `string`	Product name.
metadata `object`	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 `number`	Product price. A positive integer in the smallest currency unit (e.g. 100 cents for \$1.00).

sku
object

An object containing details of the related SKU.

Attributes	Description
id `string`	A unique identifier that represents the SKU and is assigned by Voucherify.
source\_id `string`	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 `boolean`	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 `string`	The SKU name.
price `number`	SKU price. A positive integer in the smallest currency unit (e.g. 100 cents for \$1.00).
metadata `object`	A set of custom key/value pairs that you can attach to an SKU. It can be useful for storing additional information about the SKU in a structured format. It can be used to create product collections.

object
string

The type of the object represented by JSON.

Available values: order\_item

metadata
object

A set of custom key/value pairs that you can attach to an item object. It can be useful for storing additional information about the item in a structured format. It can be used to define business validation rules or discount formulas.

Simple Event

Attributes	Description
id `string`	Unique identifier assigned by Voucherify that will be linked to the this event. Example: evcus\_0e3070fef399b70b00
type `string`	Type of the triggering event. Example: customer.order.paid
category `string`	Type of the event. Available values: `EFFECT`, `ACTION`
entity\_id `string`	ID of the entity that initiated the event. Example: cust\_ADqZIwGvWFvugWXVbrHwXRHO
created\_at `string`	Timestamp representing the date and time when the event was created in the ISO 8601 format. Example: 2024-01-01T11:11:11.111Z
group\_id `string`	Unique identifier of the request that triggered the event. Example: v-1f36113948e50fc4ge

Voucher Transaction Base

Attributes	Description
id `string`	Unique transaction ID.
source\_id `string`, `null`	The merchant's transaction ID if it is different from the Voucherify transaction ID. It is really useful in case of an integration between multiple systems. It can be a transaction ID from a CRM system, database or 3rd-party service. In case of a redemption, this value is null.
voucher\_id `string`	Unique voucher ID.
campaign\_id `string`	Unqiue campaign ID of the voucher's parent campaign if it is part of campaign that generates bulk codes.
source `string`, `null`	The channel through which the transaction took place, whether through the API or the Dashboard. In case of a redemption, this value is null.
reason `string`, `null`	Reason why the transaction occurred. In case of a redemption, this value is null.
related\_transaction\_id `string`, `null`	The related transaction ID on the receiving card.
created\_at `string`	Timestamp representing the date and time when the transaction was created. The value is shown in the ISO 8601 format.

Simple Order

Attributes	Description
id `string`	Unique identifier of an existing order that will be linked to the redemption of this request.
source\_id `string`	Unique source identifier of an existing order that will be linked to the redemption of this request.
status `string`	The order status. Available values: `CREATED`, `PAID`, `CANCELED`, `FULFILLED`
customer\_id `string`, `null`	Unique customer identifier of the customer making the purchase. The ID is assigned by Voucherify. Example: cust\_7iUa6ICKyU6gH40dBU25kQU1
referrer\_id `string`, `null`	Unique identifier of the referrer assigned by Voucherify. Example: cust\_nM4jqPiaXUvQdVSA6vTRUnix
amount `integer`	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 `integer`	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).
applied\_discount\_amount `integer`	This field shows the order-level discount applied. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for \$1.00).
items\_discount\_amount `integer`	Sum of all product-specific discounts applied to the order. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for \$1.00).
items\_applied\_discount\_amount `integer`	Sum of all product-specific discounts applied in a particular request. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for \$1.00). `sum(items, i =>i.applied\_discount\_amount)`
total\_discount\_amount `integer`	Sum of all order-level AND all product-specific discounts applied to the order. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for \$1.00).
total\_applied\_discount\_amount `integer`	Sum of all order-level AND all product-specific discounts applied in a particular request. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for \$1.00). `total\_applied\_discount\_amount` \= `applied\_discount\_amount` \+ `items\_applied\_discount\_amount`
total\_amount `integer`	Order amount after undoing all the discounts through the rollback redemption. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for \$1.00).
items `array`	Array of items applied to the order. It can include up to 500 items. Array of Simple Order Item
metadata `object`	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.
object `string`	The type of the object represented by JSON. Available values: `order`

Voucher Transaction

All of:

Voucher Transaction Base

Attributes Description

details
object

Contains the detailed information about the transaction.

Attributes Description

balance

See: Voucher Balance

order
object

Contains information about the original order.

Attributes	Description
id `string`	Unique order ID.
source\_id `string`	The merchant's order ID if it is different from the Voucherify order ID. It is really useful in case of integration between multiple systems. It can be an order ID from CRM, database or 3rd party service.

event
object

Contains information about the event that triggers the point accrual.

Attributes	Description
id `string`	Unique event ID.
type `string`	Type of event.

earning\_rule
object

Contains information about the earning rule.

Attributes Description

id
string

Unique identifier of an earning rule, assigned by Voucherify.

source
object

Contains the custom earning rule name.

Attributes	Description
banner `string`	Name of the earning rule. This is displayed as a header for the earning rule in the Dashboard.

segment
object

Contains information about the segment.

Attributes	Description
id `string`	Unique identifier of the segment.
name `string`	Name of the segment.

loyalty\_tier
object

Contains information about the loyalty tier that is mapped for the earning rule and used in the transaction.

Attributes	Description
id `string`	Unique identifier of the loyalty tier, assigned by Voucherify.
name `string`	User-defined name of the loyalty tier.

redemption
object

Contains information about the original redemption.

Attributes	Description
id `string`	Unique redemption ID.

rollback
object

Contains information about the redemption rollback.

Attributes	Description
id `string`	Unique identifier of the redemption rollback.

custom\_event
object

Contains information about the custom event that triggers the point accrual.

Attributes	Description
id `string`	Unique identifier of the event.
type `string`	Type of the custom event.

event\_schema
object

Contains information about the custom event metadata schema.

Attributes	Description
id `string`	Unique identifier of the metadata schema.
name `string`	Type of the custom event.

holder\_loyalty\_tier
object

Loyalty tier of the loyalty card holder at the moment when the transaction occurred. The loyalty tier is the tier in which the holder was before the loyalty point balance changed.

Attributes	Description
id `string`	Unique identifier of the loyalty tier, assigned by Voucherify.
name `string`	User-defined name of the loyalty tier.

pending\_points

See: Loyalty Pending Point Entry

reward
object

Contains information about the pay with points reward.

Attributes	Description
id `string`	Unique reward ID.
name `string`	Reward name.

source\_voucher

Contains information on how the balance on the donor loyalty card was affected by the transaction.

Simple Voucher

destination\_voucher

Contains information on how the balance on the receiving loyalty card was affected by the transaction.

Simple Voucher

type

One of:

Gift Card Transactions Type
Loyalty Card Transactions Type

Loyalty Pending Point Entry

Attributes	Description
id `string`	Unique identifier of the pending point entry, assigned by Voucherify. Example: lopp\_0ffd593d5ad207ba6b
voucher\_id `string`	Unique identifier of the loyalty card, assigned by Voucherify. Example: v\_abCdEfghI1JKLMNPqRS2Tu3vWXyza4bc
campaign\_id `string`	Unique campaign identifier, assigned by Voucherify. Example: camp\_weer1c3p5ZgktqfW56RfoNaG
customer\_id `string`	Unique customer identifier, assigned by Voucherify. Example: cust\_IdgAFZxYwwHctOk9ppZMu319
order\_id `string`	Unique order identifier, assigned by Voucherify. Example: ord\_0ffc0fa65f15d2df17
points `integer`	Number of points in the pending state.
activates\_at `string`	Date when the pending points are activated and added to the customer's loyalty card.
details	See: Pending Point Details
created\_at `string`	Timestamp representing the date and time when the pending point entry was created. The value is shown in the ISO 8601 format.
updated\_at `string`	Timestamp representing the date and time when the pending point entry was modified. The value is shown in the ISO 8601 format.

Loyalty Point Bucket

Attributes Description

id
string

Unique identifier of the loyalty points bucket.

voucher\_id
string

Unique identifier of the parent loyalty card.

campaign\_id
string

Unique identifier of the parent campaign.

bucket
object

Defines the number of points stored in this loyalty point bucket.

Attributes	Description
total\_points `integer`	Total number of points in the loyalty point bucket.

status
string

Loyalty point bucket status.

expires\_at
string

Date when the number of points defined in the bucket object are due to expire.

created\_at
string

Timestamp representing the date and time when the loyalty point bucket object was created in ISO 8601 format.

updated\_at
string

Timestamp representing the date and time when the loyalty point bucket object was updated in ISO 8601 format.

object
string

The type of the object represented by JSON. This object stores information about the loyalty point bucket.

Available values: loyalty\_points\_bucket

Valid Single Voucher

All of:

List Publications Item Base

Attributes Description

result
string

Status of the publication attempt.

Available values: SUCCESS

voucher

See: List Publications Item Voucher

Validation Entity

Attributes Description

id
string

Unique validation id.

session\_id
string

Unique session id.

status
string

The validation status

Available values: VALID, INVALID

created\_at
string

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

Example: 2021-12-22T10:13:06.487Z

customer\_id
string

Unique customer identifier of the customer making the purchase. The ID is assigned by Voucherify.

Example: cust\_7iUa6ICKyU6gH40dBU25kQU1

redeemables
array

Lists validation results of each redeemable.

Array of:

Attributes Description

id
string

Unique identifier of the redeemable, assigned by Voucherify.

type
string

Type of the redeemable.

Available values: voucher, promotion\_tier

skipped\_redeemables
array

Lists validation results of each redeemable.

Array of:

Attributes Description

id
string

Unique identifier of the redeemable, assigned by Voucherify.

type
string

Type of the redeemable.

Available values: voucher, promotion\_tier

inapplicable\_redeemables
array

Lists validation results of each redeemable.

Array of:

Attributes Description

id
string

Unique identifier of the redeemable, assigned by Voucherify.

type
string

Type of the redeemable.

Available values: voucher, promotion\_tier

Event Customer Redemption

Attributes	Description
customer	See: Simple Customer
order	See: Simple Order
campaign	See: Simple Campaign
voucher	See: Simple Voucher
holder	See: Simple Customer
promotion\_tier	See: Simple Promotion Tier
promotion\_stack	See: Simple Promotion Stack
redemption	See: Simple Redemption

Simple Redemption

Attributes Description

id
string

Unique redemption ID.

Example: r\_0bc92f81a6801f9bca

customer\_id
string, null

Unique customer ID of the redeeming customer.

Example: cust\_i8t5Tt6eiKG5K79KQlJ0Vs64

tracking\_id
string

Hashed customer source ID.

date
string

Timestamp representing the date and time when the redemption was created in the ISO 8601 format.

Example: 2021-12-22T10:13:06.487Z

amount
integer

Example: 10000

order

See: Simple Order

reward

See: Simple Redemption Reward Result

customer

See: Simple Customer

result
string

Redemption result.

Available values: SUCCESS, FAILURE

status
string, null

Available values: SUCCEEDED, FAILED, ROLLED BACK

voucher

Defines the details of the voucher being redeemed.

Simple Voucher

promotion\_tier

See: Simple Promotion Tier

redemption
string

Unique redemption ID of the parent redemption.

Example: r\_0c656311b5878a2031

metadata
object

The metadata object stores all custom attributes in the form of key/value pairs assigned to the redemption.

failure\_code
string

If the result is FAILURE, this parameter will provide a generic reason as to why the redemption failed.

Example: customer\_rules\_violated

failure\_message
string

If the result is FAILURE, this parameter will provide an expanded reason as to why the redemption failed.

reason
string

The reason for the redemption rollback.

channel
object

Defines the details of the channel through which the redemption was issued.

Attributes Description

channel\_id
string

Unique channel ID of the user performing the redemption. This is either a user ID from a user using the Voucherify Dashboard, an X-APP-Id of a user using the API, or the reward assignment ID for automatic reward redemption.

channel\_type
string

The source of the channel for the redemption:
USER \- the redemption was made in the Voucherify Dashboard by a user,
API \- redemption was made through the API,
AUTO\_REDEEM \- the redemption was made automatically for a reward.

Available values: API, AUTO\_REDEEM, USER

object
string

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

Event Customer Order

Attributes Description

customer

See: Simple Customer

referrer

See: Simple Customer

order

All of:

Order Calculated No Customer Data

Attributes	Description
items `array`	Array of items applied to the order. It can include up to 500 items. Array of Order Item Calculated

redemption

See: Redemption Internal

Event Customer Reward Redemptions

Attributes	Description
customer	See: Simple Customer
holder	See: Simple Customer
voucher	See: Simple Voucher
campaign	See: Simple Campaign
reward\_redemption `object`
reward	See: Simple Redemption Reward Result
reward\_assignment	See: Reward Assignment
source `string`
balance `integer`

Event Customer Loyalty Tier Base

Attributes	Description
customer	See: Simple Customer
campaign	See: Simple Campaign

Redeemable Holder

Attributes	Description
id `string`	Unique identifier of the redeemable holder. Example: rh\_0e7b8db4700106a852
created\_at `string`	Timestamp representing the date and time when the redeemable was assigned. The value is shown in the ISO 8601 format. Example: 2024-03-22T17:48:25.910Z
redeemable\_id `string`	Identifier of the redeemable item. Example: v\_GXVguPhq2khgFxH7GrRXWA91gDr1LiA1
redeemable\_object `string`	Type of the redeemable. Available values: `voucher` Example: voucher
campaign\_id `string`	Unique identifier of the campaign as assigned by Voucherify. Example: camp\_weer1c3p5ZgktqfW56RfoNaG
campaign\_type `string`	Defines the type of the campaign. Available values: `REFERRAL\_PROGRAM` Example: REFERRAL\_PROGRAM
voucher\_type `string`	Defines the type of the voucher. Available values: `GIFT\_VOUCHER`, `DISCOUNT\_VOUCHER`, `LOYALTY\_CARD` Example: DISCOUNT\_VOUCHER
publication\_id `string`, `null`	Unique identifier of the publication.
customer\_id `string`	Unique identifier of the customer. Example: cust\_p1ufreYbVbwZ1x70nFkH9rF9
holder\_role `string`	Role of the holder. Available values: `OWNER`, `REFERRER`, `REFEREE` Example: REFERRER
object `string`	The type of the object represented by JSON. Available values: `redeemable\_holder`

Customer Summary

Attributes	Description
redemptions	See: Customer Summary Redemptions
orders	See: Customer Summary Orders

Customer Loyalty

Attributes Description

points
integer

Customer's loyalty points minus expired for all loyalty cards which the customer has.

referred\_customers
integer

Total number of customers referred by the customer.

campaigns
object

Contains campaigns with details about point balances and how many customers were referred by the customer.

Attributes Description

\[propertyName]
object

Contains details about the point balances left on loyalty cards and the number of referred customers in each campaign.

Attributes Description

points
integer

Remaining point balance in campaign.

loyalty\_tier
string

Customer's loyalty tier within the campaign.

Example: ltr\_UJ5Q54Q0OvEhua87Qfv2Ki5x

referred\_customers
integer

Number of customers referred by the customer in campaign.

Customer Referrals

Attributes Description

total
integer

Total number of times this customer received a referral, i.e. was referred by another customer.

campaigns
array

Contains an array of campaigns that served as the source of a referral for the customer.

Array of:

Customer Referrals Campaigns Item

Attributes	Description
campaign\_id `string`	Unique campaign ID, assigned by Voucherify. Example: camp\_rRsfatlwN7unSeUIJDCYedal
referrer\_id `string`	Unique referrer ID, assigned by Voucherify. This is the customer ID of a customer that is referring this customer. Example: cust\_sehkNIi8Uq2qQuRqSr7xn4Zi
related\_object\_id `string`	Related object id Example: r\_0b9d4cc4aa164dd073
related\_object\_type `string`	Related object type, i.e. `redemption`.
date `string`	Timestamp representing the date and time when the customer was referred in ISO 8601 format. Example: 2022-08-30T10:19:39.196Z

Customer Base

Attributes Description

name
string

Customer's first and last name.

description
string

An arbitrary string that you can attach to a customer object.

email
string

Customer's email address.

phone
string

Customer's phone number. This parameter is mandatory when you try to send out codes to customers via an SMS channel.

birthday
string

Deprecated. ~~Customer's birthdate; format YYYY-MM-DD~~.

birthdate
string

Customer's birthdate; format YYYY-MM-DD.

address
object, null

Customer's address.

Attributes	Description
city `string`	City
state `string`	State
line\_1 `string`	First line of address.
line\_2 `string`	Second line of address.
country `string`	Country.
postal\_code `string`	Postal code.

metadata
object

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.

Simple Campaign Voucher

Attributes Description

type
string

Type of the voucher.

Available values: DISCOUNT\_VOUCHER, LOYALTY\_CARD, GIFT\_VOUCHER

discount

Defines the voucher discount type and details.

Discount

gift

Defines the voucher gift details.

Gift

loyalty\_card

Defines the voucher loyalty card details.

Campaign Loyalty Card

redemption
object

Defines the redemption limits on vouchers.

Attributes Description

quantity
integer, null

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

redeemed\_quantity
integer

How many times a voucher has already been redeemed.

Example: 1

code\_config

Code Config

Referral Program

Attributes Description

conversion\_event\_type
string

Define how a referral is triggered.

Available values: redemption, custom\_event

custom\_event
object

Contains details about the custom event.

Attributes Description

id
string

Unique custom event ID.

Example: ms\_Ll9enAm2BCN0M1s4VxWobLFM

name
string

Custom event name.

referee\_reward
object

Defines the referee reward.

Attributes Description

related\_object\_parent
object

Details of the resource from which the reward originates.

Attributes Description

id
string

Unique ID of the reward source.

Example: camp\_kdxp3vf1clQ9CFs1jpqv3tZe

name
string

Name of the reward source.

object
string

Type of resource represented by the source of the reward.

Available values: CAMPAIGN

type
string

Type of reward.

Available values: LOYALTY\_CARD, GIFT\_VOUCHER

amount
integer

Category

Attributes	Description
id `string`	Unique category ID assigned by Voucherify.
name `string`	Category name.
hierarchy `integer`	Category hierarchy. Categories with lower hierarchy are processed before categories with higher hierarchy value.
object `string`	The type of the object represented by the JSON. This object stores information about the category. Available values: `category`
created\_at `string`	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
updated\_at `string`	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

Gift

Attributes	Description
amount `number`	Total gift card income over the lifetime of the card. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `\$100.00`.
subtracted\_amount `integer`	Total amount of subtracted credits over the gift card lifetime.
balance `number`	Available funds. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `\$100.00`. `balance` \= `amount` \- `subtracted\_amount` \- `redemption.redeemed\_amount`.
effect `string`	Defines how the credits are applied to the customer's order. Available values: `APPLY\_TO\_ORDER`, `APPLY\_TO\_ITEMS`

Discount

Contains information about discount.

One of:

Amount
Unit
Unit Multiple
Percent
Fixed

Simple Loyalty Card

Attributes	Description
points `integer`	Total number of points added to the loyalty card over its lifespan.
balance `integer`	Points available for reward redemption. This is calculated as follows: `balance` \= `points` \- `expired\_points` \- `subtracted\_points` \- `redemption.redeemed\_points`.
next\_expiration\_date `string`	The next closest date when the next set of points are due to expire.
next\_expiration\_points `integer`	The amount of points that are set to expire next.
pending\_points `integer`	Shows the number of pending points that will be added to the loyalty card when they are activated automatically or manually.
expired\_points `integer`	Shows the total number of expired points over the lifetime of the loyalty card.
subtracted\_points `integer`	Shows the total number of subtracted points over the lifetime of the loyalty card.

Customer Object Required Object Type

Attributes	Description
id `string`	The unique ID of a customer that is assigned by Voucherify. Example: cust\_CSnYd37MXmrbS19XCrghjBsv
source\_id `string`	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.
name `string`	Customer's first and last name.
email `string`	Customer's email address.
metadata `object`	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.
object `string`	The type of the object represented by the JSON. This object stores information about the customer.

Redemption Reward Result

Attributes Description

customer

Simple Customer

assignment\_id
string, null

Unique reward assignment ID assigned by Voucherify.

voucher

Voucher

product

Product

sku

SKU Object

loyalty\_tier\_id
string, null

Unique loyalty tier ID assigned by Voucherify.

id
string

Unique reward ID.

Example: rew\_0bc92f81a6801f9bca

name
string

Name of the reward.

Example: Reward Name

object
string

The type of the object represented by the JSON

Available values: reward

created\_at
string

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

Example: 2021-12-22T10:13:06.487Z

updated\_at
string

Timestamp in ISO 8601 format indicating when the reward was updated.

Example: 2022-10-03T12:24:58.008Z

parameters
object

These are parameters representing a material reward.

Attributes Description

campaign
object

Defines the product redeemed as a reward.

Attributes Description

id
string

Campaign unique ID.

Example: camp\_13BbZ0kQsNinhqsX3wUts2UP

balance
integer

Points available for reward redemption. This is calculated as follows: balance \= points \- expired\_points \- subtracted\_points \- redemption.redeemed\_points.

type
string

Defines the type of the campaign.

product
object

Defines the product redeemed as a reward.

Attributes Description

id
string

Unique product ID, assigned by Voucherify.

Example: prod\_0b7d7dfb05cbe5c616

sku\_id
string

Unique identifier of the SKU. It is assigned by Voucherify.

Example: sku\_0a41e31c7b41c28358

coin
object

Defines the ratio by mapping the number of loyalty points in points\_ratio to a predefined cash amount in exchange\_ratio.

Attributes	Description
exchange\_ratio `integer`	The cash equivalent of the points defined in the `points\_ratio` property.
points\_ratio `integer`	The number of loyalty points that will map to the predefined cash amount defined by the `exchange\_ratio` property.

metadata
object

A set of custom key/value pairs that you can attach to a reward. The metadata object stores all custom attributes assigned to the reward.

type
string

Reward type.

Available values: CAMPAIGN, COIN, MATERIAL

Voucher

This is an object representing a voucher with categories and validation rules assignments.

All of:

Voucher Base

Attributes	Description
categories `array`	Contains details about the category. Array of Category
validation\_rules\_assignments	See: Validation Rules Assignments List

Voucher Holder

Attributes	Description
holder	See: Simple Customer

Promotion Tier

Attributes Description

id
string

Unique promotion tier ID.

Example: promo\_63fYCt81Aw0h7lzyRkrGZh9p

created\_at
string

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

Example: 2021-12-15T11:34:01.333Z

updated\_at
string

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

Example: 2022-02-09T09:20:05.603Z

name
string

Name of the promotion tier.

banner
string

Text to be displayed to your customers on your website.

action
object

Contains details about the discount applied by the promotion tier.

Attributes	Description
discount	See: Discount

metadata
object

hierarchy
integer

promotion\_id
string

Promotion unique ID.

campaign
object

Contains details about promotion tier's parent campaign.

Attributes	Description
id `string`	Unique campaign ID.
start\_date `string`	Activation timestamp defines when the campaign starts to be active in ISO 8601 format. Campaign is inactive before this date. Example: 2022-09-22T00:00:00.000Z
expiration\_date `string`	Expiration timestamp defines when the campaign expires in ISO 8601 format. Campaign is inactive after this date. Example: 2022-09-30T00:00:00.000Z
validity\_timeframe	See: Validity Timeframe
validity\_day\_of\_week	See: Validity Day Of Week
validity\_hours	See: Validity Hours
active `boolean`	A flag indicating whether the campaign is active or not active. A campaign can be disabled even though it's within the active period defined by the `start\_date` and `expiration\_date` using the Disable Campaign endpoint. `true` indicates an active campaign `false` indicates an inactive campaign
category\_id `string`	Unique category ID that this campaign belongs to. Example: cat\_0b688929a2476386a6
object `string`	The type of the object represented by the campaign object. This object stores information about the campaign.

campaign\_id
string

Promotion tier's parent campaign's unique ID.

active
boolean

A flag to toggle the promotion tier on or off. You can disable a promotion tier even though it's within the active period defined by the start\_date and expiration\_date.

true indicates an active promotion tier
false indicates an inactive promotion tier

start\_date
string

Activation timestamp defines when the promotion tier starts to be active in ISO 8601 format. Promotion tier is inactive before this date.

Example: 2022-09-23T00:00:00.000Z

expiration\_date
string

Activation timestamp defines when the promotion tier expires in ISO 8601 format. Promotion tier is inactive after this date.

Example: 2022-09-26T00:00:00.000Z

validity\_timeframe

See: Validity Timeframe

validity\_day\_of\_week

See: Validity Day Of Week

validity\_hours

See: Validity Hours

summary
object

Contains statistics about promotion tier redemptions and orders.

Attributes Description

redemptions
object

Contains statistics about promotion tier redemptions.

Attributes	Description
total\_redeemed `integer`	Number of times the promotion tier was redeemed.

orders
object

Contains statistics about orders related to the promotion tier.

Attributes	Description
total\_amount `integer`	Sum of order totals.
total\_discount\_amount `integer`	Sum of total discount applied using the promotion tier.

object
string

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

validation\_rule\_assignments

See: Validation Rule Assignments List

category\_id
string

Promotion tier category ID.

Example: cat\_0c9da30e7116ba6bba

categories
array

Array of Category

Simple Product

Attributes	Description
id `string`	Unique product ID.
source\_id `string`	Product source id.
name `string`	Product name.

Simple Sku

Attributes	Description
id `string`	Unique sku ID.
source\_id `string`	Sku source id.
sku `string`	Sku name.

Reward type

One of:

Digital
Pay with Points
Material

Loyalty Tier Base

Attributes Description

name
string

Loyalty Tier name.

earning\_rules
object

Contains a list of earning rule IDs and their points mapping for the given earning rule.

Attributes	Description
\[propertyName]	See: MappingPoints

rewards
object

Contains a list of reward IDs and their points mapping for the given reward.

Attributes	Description
\[propertyName]	See: MappingPoints

points
object

Defines range of loyalty tier in points.

Attributes	Description
from `integer`	Bottom points threshold value.
to `integer`	Top points threshold value.

Loyalty Tier Expiration

Attributes	Description
customer\_id `string`	Unique customer identifier of the customer making the purchase. The ID is assigned by Voucherify. Example: cust\_7iUa6ICKyU6gH40dBU25kQU1
campaign\_id `string`	Unique campaign ID, assigned by Voucherify. Example: camp\_rRsfatlwN7unSeUIJDCYedal
tier\_id `string`	Unique tier ID, assigned by Voucherify.
start\_date `string`	Activation timestamp defines when the loyalty tier starts to be active in ISO 8601 format. Loyalty tier is inactive before this date.
expiration\_date `string`	Expiration timestamp defines when the loyalty tier expires in ISO 8601 format. Loyalty tier is inactive after this date.
created\_at `string`	Timestamp representing the date and time when the loyalty tier was created. The value is shown in the ISO 8601 format. Example: 2021-12-22T10:13:06.487Z
updated\_at `string`	Timestamp representing the date and time when the loyalty tier was updated. The value is shown in the ISO 8601 format. Example: 2021-12-22T10:13:06.487Z

EarningRuleBase

Attributes Description

id
string

Assigned by the Voucherify API, identifies the earning rule object.

created\_at
string

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

loyalty

One of:

Define fixed amount of points
Calculate points proportionally

event

Defines the event which triggers the earning rule to add points to a loyalty card.

Earning Rule Event

custom\_event
object

Contains details about the custom event.

Attributes	Description
schema\_id `string`	Unique identifier of the custom event schema

segment
object

Contains the ID of a customer segment. Required for the customer.segment.entered option in the event.

Attributes	Description
id `string`	Contains a unique identifier of a customer segment. Assigned by the Voucherify API.

loyalty\_tier
object

Defines the tier associated with the earning rule definition.

Attributes Description

id
string

Unique loyalty tier ID associated with the earning rule.

**ANY** : any loyalty tier within the campaign

Example: ltr\_pudTGWasuIqxdiDM0go31OV1

pending\_points
object

Defines the configuration for pending points. Pending points can be used only with the order.paid event.

Attributes Description

period\_type
string

Defines the type of the period during which the points are in the pending state. Currently, only DAY value is accepted.

Available values: DAY

period\_value
integer

Defines for how long the points are in the pending state. The minimum value is 1, maximum is 90.

source
object

Contains the custom earning rule name and parent campaign.

Attributes Description

banner
string

Name of the earning rule. This is displayed as a header for the earning rule in the Dashboard.

object\_id
string

A unique campaign identifier assigned by the Voucherify API.

object\_type
string

Defines the object associated with the earning rule. Defaults to campaign.

Available values: campaign

object
string

The type of the object represented by JSON. Default is earning\_rule.

Available values: earning\_rule

automation\_id
string

For internal use by Voucherify.

start\_date
string

Start date defines when the earning rule starts to be active. Activation timestamp is presented in the ISO 8601 format. The earning rule is inactive before this date. If you do not define the start date for an earning rule, it will inherit the campaign start date by default.

expiration\_date
string

Expiration date defines when the earning rule expires. Expiration timestamp is presented in the ISO 8601 format. The earning rule is inactive after this date. If you do not define the expiration date for an earning rule, it will inherit the campaign expiration date by default.

validity\_timeframe

See: Validity Timeframe

validity\_day\_of\_week

See: Validity Day Of Week

validity\_hours

See: Validity Hours

metadata
object

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

expiration\_rules

See: Earning Rule Expiration Rules

Customer Id

Attributes Description

id
string

A unique identifier of an existing customer.

object
string

The type of the object represented by JSON.

Available values: customer

Referrer Id

Customer Id

Order Redemptions

Attributes	Description
date `string`	Timestamp representing the date and time when the redemption was created. The value is shown in the ISO 8601 format. Example: 2022-09-02T17:06:56.649Z
rollback\_id `string`	Unique ID of the redemption rollback. Example: rr\_0c63c84eb78ee0a6c0
rollback\_date `string`	Timestamp representing the date and time when the redemption rollback was created. The value is shown in the ISO 8601 format. Example: 2023-01-31T14:18:37.150Z
related\_object\_type `string`	The source of the incentive.
related\_object\_id `string`	Unique ID of the parent redemption. Example: r\_0ba186c4824e4881e1
related\_object\_parent\_id `string`	Represent's the campaign ID of the voucher if the redemption was based on a voucher that was part of bulk codes generated within a campaign. In case of a promotion tier, this represents the campaign ID of the promotion tier's parent campaign.
stacked `array`	Contains a list of unique IDs of child redemptions, which belong to the stacked incentives.
rollback\_stacked `array`	Lists the rollback redemption IDs of the particular child redemptions.

Simple Order Item

Attributes	Description
id `string`	Unique identifier of the order line item.
object `string`	The type of the object represented by JSON. This object stores information about the `order\_item`. Available values: `order\_item`
source\_id `string`	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.
related\_object `string`	Used along with the `source\_id` property, can be set to either SKU or product. Available values: `product`, `sku`
product\_id `string`	Unique identifier of the product. It is assigned by Voucherify.
sku\_id `string`	Unique identifier of the SKU. It is assigned by Voucherify.
quantity `integer`	Quantity of the particular item in the cart.
applied\_quantity `integer`	Quantity of items changed by the application of a new quantity items. It can be positive when an item is added or negative if an item is replaced.
applied\_quantity\_amount `integer`	Amount for the items changed by the application of a new quantity items. It can be positive when an item is added or negative if an item is replaced.
discount\_quantity `integer`	Number of discounted items.
applied\_discount\_quantity `integer`	Number of the discounted items applied in the transaction.
amount `integer`	Total amount of the order item (price \* quantity).
discount\_amount `integer`	Sum of all order-item-level discounts applied to the order.
applied\_discount\_amount `integer`	Order-level discount amount applied in the transaction.
price `integer`	Unit price of an item. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `\$100.00`.
subtotal\_amount `integer`	Final order item amount after the applied item-level discount. If there are no item-level discounts applied, this item is equal to the `amount`. `subtotal\_amount` \= `amount` \- `discount\_amount`

Gift Card Transactions Type

Transaction types concerning gift card credits.

Available values: CREDITS\_REDEMPTION, CREDITS\_REFUND, CREDITS\_ADDITION, CREDITS\_REMOVAL

Loyalty Card Transactions Type

Transaction types concerning loyalty points.

Available values: PENDING\_POINTS\_ACTIVATION, POINTS\_ACCRUAL, POINTS\_REDEMPTION, POINTS\_REFUND, POINTS\_ADDITION, POINTS\_REMOVAL, POINTS\_EXPIRATION, POINTS\_TRANSFER\_IN, POINTS\_TRANSFER\_OUT

Pending Point Details

Attributes Description

loyalty\_tier
object

The loyalty tier that is mapped for the earning rule and used in the pending point transaction.

Attributes	Description
id `string`	Unique identifier of the loyalty tier, assigned by Voucherify.
name `string`	User-defined name of the loyalty tier.

holder\_loyalty\_tier
object

Loyalty tier of the loyalty card holder at the moment when the transaction occurred. The loyalty tier is the tier in which the holder was at the moment pending points were created.

Attributes	Description
id `string`	Unique identifier of the loyalty tier, assigned by Voucherify.
name `string`	User-defined name of the loyalty tier.

event
object

Details about the event that created pending points.

Attributes	Description
id `string`	Unique event identifier, assigned by Voucherify.
type `string`	Type of the event that triggered the creation of pending points. Available values: `customer.order.paid`
group\_id `string`	Unique identifier of the request that triggered the event, assigned by Voucherify.
entity\_id `string`	Unique identifier of the entity that triggered the event, assigned by Voucherify. For pending points, it is the `customer\_id` of the customer who paid for the order.
created\_at `string`	Timestamp representing the date and time when the event occurred. The value is shown in the ISO 8601 format.
category `string`	Type of the event. Available values: `ACTION`, `EFFECT`
event\_source	See: Event Source

earning\_rule
object

Contains information about the earning rule.

Attributes Description

id
string

Unique identifier of an earning rule, assigned by Voucherify.

source
object

Contains the custom earning rule name.

Attributes	Description
banner `string`	Name of the earning rule. This is displayed as a header for the earning rule in the Dashboard.

order
object

Details about the order that caused adding pending points.

Attributes	Description
id `string`	Unique order identifier, assigned by Voucherify.
source\_id `string`, `null`	User-defined order identifier.

List Publications Item Base

Attributes Description

id
string

Unique publication ID, assigned by Voucherify.

Example: pub\_BbjAXnmm8e0SIm3zG8qvvFCP0KuLywtp

object
string

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

Available values: publication

created\_at
string

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

Example: 2022-09-23T09:57:00.434Z

customer\_id
string

Unique customer ID of the customer receiving the publication.

Example: cust\_eWgXlBBiY6THFRJwX45Iakv4

tracking\_id
string

Customer's source\_id.

metadata
object

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

Attributes	Description
source\_type `string`	Defines the type of the distribution source.
source\_id `string`	Unique identifier of the distribution source.
distribution\_id `string`	Unique identifier of the distribution.

channel
string

How the publication was originated. It can be your own custom channel or an example value provided here.

source\_id
string, null

The merchant's publication ID if it is different from the Voucherify publication ID. It's an optional tracking identifier of a publication. It is really useful in case of an integration between multiple systems. It can be a publication ID from a CRM system, database or 3rd-party service.

customer

See: Customer With Summary Loyalty Referrals

vouchers
array

Contains the voucher IDs that was assigned by Voucherify.

vouchers\_id
array

Contains the unique internal voucher IDs that was assigned by Voucherify.

List Publications Item Voucher

Attributes	Description
code `string`	Voucher code.
object `string`	The type of the object represented by JSON. Available values: `voucher`
campaign `string`	Campaign name
gift	Gift object response Gift
loyalty\_card `object`	Defines the loyalty card details.
discount	See: Discount
is\_referral\_code `boolean`	Flag indicating whether this voucher is a referral code; `true` for campaign type `REFERRAL\_PROGRAM`.

Simple Promotion Tier

Attributes Description

id
string

Unique promotion tier ID.

Example: promo\_63fYCt81Aw0h7lzyRkrGZh9p

name
string

Name of the promotion tier.

banner
string

Text to be displayed to your customers on your website.

campaign
object

Contains details about promotion tier's parent campaign.

Attributes	Description
id `string`	Unique campaign ID.

metadata
object

A set of custom key/value pairs that you can attach to a promotion tier. The metadata object stores all custom attributes assigned to the promotion tier.

Simple Promotion Stack

Attributes Description

id
string

Unique identifier of the promotion stack.

name
string

Name of the promotion stack.

category\_id
string

Unique identifier of the category of the promotion stack.

campaign
object

Represents simplified promotion stack campaign data.

Attributes	Description
id `string`	Unique identifier of the campaign.

tiers
object

Contains the tier configuration. A promotion stack can include up to 30 tiers.

Attributes	Description
ids `array`	Contains the list of tiers in a pre-defined sequence.
hierarchy\_mode `string`	Available values: `MANUAL`

Reward Assignment

All of:

Reward Assignment Base
Digital or Material Reward - Parameters

Customer Summary Redemptions

Attributes Description

total\_redeemed
integer

Total number of redemptions made by the customer.

total\_failed
integer

Total number of redemptions that failed.

total\_succeeded
integer

Total number of redemptions that succeeded.

total\_rolled\_back
integer

Total number of redemptions that were rolled back for the customer.

total\_rollback\_failed
integer

Total number of redemption rollbacks that failed.

total\_rollback\_succeeded
integer

Total number of redemption rollbacks that succeeded.

gift
object

Summary of gift card credits.

Attributes	Description
redeemed\_amount `integer`	Total amount of gift card credits redeemed by customer. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `\$100.00`.
amount\_to\_go `integer`	Remaining gift card balance across all gift cards. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `\$100.00`.

loyalty\_card
object

Summary of loyalty points.

Attributes	Description
redeemed\_points `integer`	Total number of loyalty points redeemed by the customer.
points\_to\_go `integer`	Sum of remaining available point balance across all loyalty cards.

Customer Summary Orders

Attributes	Description
total\_amount `integer`	The total amount spent by the customer. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `\$100.00`.
total\_count `integer`	Total number of orders made by the customer.
average\_amount `integer`	Average amount spent on orders. `total\_amount` ÷ `total\_count`. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `\$100.00`.
last\_order\_amount `integer`	Amount spent on last order. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `\$100.00`.
last\_order\_date `string`	Timestamp representing the date and time of the customer's last order in ISO 8601 format. Example: 2022-08-30T11:51:08.029Z

Campaign Loyalty Card

Attributes Description

points
integer

The initial number of points to assign to the loyalty card. This is the current loyalty card score i.e. the number of loyalty points on the card.

expiration\_rules
object

Defines the loyalty point expiration rule. This expiration rule applies when there are no expiration\_rules defined for an earning rule.

Attributes	Description
period\_type `string`	Type of period. Can be set for `MONTH` or `FIXED\_DAY\_OF\_YEAR`. `MONTH` requires the `period\_value` field. `FIXED\_DAY\_OF\_YEAR` requires the `fixed\_month` and `fixed\_day` fields. Available values: `FIXED\_DAY\_OF\_YEAR`, `MONTH`
period\_value `integer`	Value of the period. Required for the `period\_type: MONTH`.
rounding\_type `string`	Type of rounding of the expiration period. Optional for the `period\_type: MONTH`. Available values: `END\_OF\_MONTH`, `END\_OF\_QUARTER`, `END\_OF\_HALF\_YEAR`, `END\_OF\_YEAR`, `PARTICULAR\_MONTH`
rounding\_value `integer`	Value of rounding of the expiration period. Required for the `rounding\_type`.
fixed\_month `integer`	Determines the month when the points expire; `1` is January, `2` is February, and so on. Required for the `period\_type: FIXED\_DAY\_OF\_YEAR`.
fixed\_day `integer`	Determines the day of the month when the points expire. Required for the `period\_type: FIXED\_DAY\_OF\_YEAR`.

Code Config

Attributes	Description
length `number`	Number of characters in a generated code (excluding prefix and postfix).
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
prefix `string`	A text appended before the code.
postfix `string`	A text appended after the code.
pattern `string`	A pattern for codes where hashes (#) will be replaced with random characters. Overrides `length`.
initial\_count `integer`	Internal value, does not change anything if provided.

Amount

Attributes	Description
type `string`	Defines the type of the voucher. Available values: `AMOUNT`
amount\_off `number`	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.
amount\_off\_formula `string`	Formula used to dynamically calculate the discount.
aggregated\_amount\_limit `integer`	Maximum discount amount per order.
effect	Defines how the discount is applied to the customer's order. Discount Amount Vouchers Effect Types
is\_dynamic `boolean`	Flag indicating whether the discount was calculated using a formula.

Unit

Attributes	Description
type `string`	Discount type. Available values: `UNIT`
unit\_off `integer`	Number of units to be granted a full value discount.
unit\_off\_formula `string`	Formula used to dynamically calculate the number of units.
effect	Defines how the unit is added to the customer's order. Discount Unit Vouchers Effect Types
unit\_type `string`	The product deemed as free, chosen from product inventory (e.g. time, items).
product	Contains information about the product. Simple Product Discount Unit
sku	See: Simple Sku Discount Unit
is\_dynamic `boolean`	Flag indicating whether the discount was calculated using a formula.

Unit Multiple

Attributes Description

type
string

Discount type.

Available values: UNIT

effect
string

Defines how the discount is applied to the customer's order.

Available values: ADD\_MANY\_ITEMS

units
array

Array of One Unit

Percent

Attributes	Description
type `string`	Defines the type of the voucher. Available values: `PERCENT`
percent\_off `number`	The percent discount that the customer will receive.
percent\_off\_formula `string`	Formula used to dynamically calculate the discount.
amount\_limit `number`	Upper limit allowed to be applied as a discount. Value is multiplied by 100 to precisely represent 2 decimal places. For example, a \$6 maximum discount is written as 600.
aggregated\_amount\_limit `integer`	Maximum discount amount per order.
effect	Defines how the discount is applied to the customer's order. Discount Percent Vouchers Effect Types
is\_dynamic `boolean`	Flag indicating whether the discount was calculated using a formula.

Fixed

Attributes	Description
type `string`	Defines the type of the voucher. Available values: `FIXED`
fixed\_amount `number`	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.
fixed\_amount\_formula `string`	Formula used to dynamically calculate the discount.
effect	Defines how the discount is applied to the customer's order. Discount Fixed Vouchers Effect Types
is\_dynamic `boolean`	Flag indicating whether the discount was calculated using a formula.

Product

This is an object representing a product.

This entity should be used to map product items from your inventory management system. The aim of products is to build which reflect product-specific campaigns.

All of:

Product without Skus Object

Attributes	Description
skus	See: Skus List For Product

SKU Object

Attributes	Description
id `string`	A unique identifier that represents the SKU and is assigned by Voucherify. Example: sku\_0b1621b319d248b79f
source\_id `string`, `null`	A unique SKU identifier from your inventory system. Example: sku\_source\_id\_4
product\_id `string`	The parent product's unique ID. Example: prod\_0b15f6b9f650c16990
sku `string`, `null`	Unique user-defined SKU name. Example: Large Pink Shirt
price `integer`, `null`	Unit price. It is represented by a value multiplied by 100 to accurately reflect 2 decimal places, such as `\$100.00` being expressed as `10000`.
currency `string`, `null`	SKU price currency. Example: USD
attributes `object`	The attributes object stores values for all custom attributes inherited by the SKU from the parent product. A set of key/value pairs that are attached to a SKU object and are unique to each SKU within a product family.
image\_url `string`, `null`	The HTTPS URL pointing to the .png or .jpg file that will be used to render the SKU image.
metadata `object`	The metadata object stores all custom attributes assigned to the SKU. A set of key/value pairs that you can attach to a SKU object. It can be useful for storing additional information about the SKU in a structured format. It can be used to create product collections.
created\_at `string`	Timestamp representing the date and time when the SKU was created. The value is shown in the ISO 8601 format. Example: 2022-05-17T10:36:30.187Z
updated\_at `string`, `null`	Timestamp representing the date and time when the SKU was updated. The value is shown in the ISO 8601 format. Example: 2022-05-17T10:55:09.137Z
object `string`	The type of the object represented by JSON. This object stores information about the `SKU`. Available values: `sku`

Voucher Base

Attributes Description

id
string

Assigned by the Voucherify API, identifies the voucher.

Example: v\_mkZN9v7vjYUadXnHrMza8W5c34fE5KiV

code
string

A code that identifies a voucher. Pattern can use all letters of the English alphabet, Arabic numerals, and special characters.

Example: WVPblOYX

campaign
string

A unique campaign name, identifies the voucher's parent campaign.

Example: Gift Card Campaign

campaign\_id
string

Assigned by the Voucherify API, identifies the voucher's parent campaign.

Example: camp\_FNYR4jhqZBM9xTptxDGgeNBV

category
string

Tag defining the category that this voucher belongs to. Useful when listing vouchers using the List Vouchers endpoint.

category\_id
string

Unique category ID assigned by Voucherify.

Example: cat\_0bb343dee3cdb5ec0c

type
string

Defines the type of the voucher.

Available values: GIFT\_VOUCHER, DISCOUNT\_VOUCHER, LOYALTY\_CARD

discount

See: Discount

gift
object

Object representing gift parameters. Child attributes are present only if type is GIFT\_VOUCHER. Defaults to null.

Attributes	Description
amount `integer`	Total gift card income over the lifetime of the card. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `\$100.00`. Example: 10000
subtracted\_amount `integer`	Total amount of subtracted credits over the gift card lifetime. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `\$100.00`.
balance `integer`	Available funds. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `\$100.00`. Example: 500
effect `string`	Defines how the credits are applied to the customer's order. Available values: `APPLY\_TO\_ORDER`, `APPLY\_TO\_ITEMS`

loyalty\_card
object

Object representing loyalty card parameters. Child attributes are present only if type is LOYALTY\_CARD. Defaults to null.

Attributes	Description
points `integer`	Total number of points added to the loyalty card over its lifespan. Example: 7000
balance `integer`	Points available for reward redemption. This is calculated as follows: `balance` \= `points` \- `expired\_points` \- `subtracted\_points` \- `redemption.redeemed\_points`. Example: 6970
next\_expiration\_date `string`	The next closest date when the next set of points are due to expire. Example: 2023-05-30
next\_expiration\_points `integer`	The amount of points that are set to expire next.
pending\_points `integer`	Shows the number of pending points that will be added to the loyalty card when they are activated automatically or manually.
expired\_points `integer`	Shows the total number of expired points over the lifetime of the loyalty card.
subtracted\_points `integer`	Shows the total number of subtracted points over the lifetime of the loyalty card.

start\_date
string

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

Example: 2021-12-01T00:00:00.000Z

expiration\_date
string

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

Example: 2021-12-31T00:00:00.000Z

validity\_timeframe

See: Validity Timeframe

validity\_day\_of\_week

See: Validity Day Of Week

validity\_hours

See: Validity Hours

active
boolean, null

A flag to toggle the voucher on or off. You can disable a voucher even though it's within the active period defined by the start\_date and expiration\_date.

true indicates an active voucher
false indicates an inactive voucher

additional\_info
string

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

metadata
object

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

assets

See: Voucher Assets

is\_referral\_code
boolean, null

Flag indicating whether this voucher is a referral code; true for campaign type REFERRAL\_PROGRAM.

created\_at
string

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

Example: 2021-12-22T10:13:06.487Z

updated\_at
string

Timestamp representing the date and time when the voucher was last updated in ISO 8601 format.

Example: 2021-12-22T10:14:45.316Z

holder\_id
string

Unique customer identifier of the redeemable holder. It equals to the customer ID assigned by Voucherify.

Example: cust\_eWgXlBBiY6THFRJwX45Iakv4

referrer\_id
string

Unique identifier of the referring person.

Example: cust\_Vzck5i8U3OhcEUFY6MKhN9Rv

object
string

The type of the object represented by JSON. Default is voucher.

publish
object

Stores a summary of publication events: an event counter and endpoint to return details of each event. Publication is an assignment of a code to a customer, e.g. through a distribution.

Attributes Description

object
string

The type of the object represented is by default list. To get this list, you need to make a call to the endpoint returned in the url attribute.

count
integer

Publication events counter.

Example: 0

url
string

The endpoint where this list of publications can be accessed using a GET method. /v1/vouchers//publications

Example: /v1/vouchers/WVPblOYX/publications?page=1\&limit=10

redemption
object

Stores a summary of redemptions that have been applied to the voucher.

Attributes	Description
quantity `integer`	How many times a voucher can be redeemed. A `null` value means unlimited.
redeemed\_quantity `integer`	How many times a voucher has already been redeemed. Example: 1
redeemed\_points `integer`	Total loyalty points redeemed. Example: 100000
object `string`	The type of the object represented is by default `list`. To get this list, you need to make a call to the endpoint returned in the url attribute.
url `string`	The endpoint where this list of redemptions can be accessed using a GET method. `/v1/vouchers//redemptions` Example: /v1/vouchers/WVPblOYX/redemptions?page=1\&limit=10

Validation Rules Assignments List

Attributes	Description
object `string`	The type of the object represented by JSON. This object stores information about validation rules assignments. Available values: `list`
data\_ref `string`	Identifies the name of the attribute that contains the array of validation rules assignments. Available values: `data`
data `array`	Contains array of validation rules assignments. Array of Business Validation Rule Assignment
total `integer`	Total number of validation rules assignments.

Validity Timeframe

Attributes Description

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

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

Validity Day Of Week

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

Validity Hours

Attributes Description

daily
array

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

Array of:

Attributes Description

start\_time
string

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

Example: 12:00

days\_of\_week
array

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

expiration\_time
string

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

Example: 14:00

Validation Rule Assignments List

Attributes	Description
object `string`	The type of the object represented by JSON. This object stores information about validation rule assignments.
data\_ref `string`	Identifies the name of the JSON property that contains the array of validation rule assignments.
data `array`	A dictionary that contains an array of validation rule assignments. Array of Validation Rule Assignment
total `integer`	Total number of validation rule assignments.

Digital

Attributes Description

campaign
object

Objects stores information about the campaign related to the reward.

Attributes Description

id
string

Unique campaign ID, assigned by Voucherify.

balance
integer

The number of points to be added to a loyalty card or the amount to be added to the current balance on the gift card.

For gift cards, the value is multiplied by 100 to precisely represent 2 decimal places. For example, \$100 amount is written as 10000.

type
string

Campaign type.

Available values: DISCOUNT\_COUPONS, GIFT\_VOUCHERS, LOYALTY\_PROGRAM

Pay with Points

Attributes Description

coin
object

Defines the ratio by mapping the number of loyalty points in points\_ratio to a predefined cash amount in exchange\_ratio.

Attributes	Description
exchange\_ratio `number`	The cash equivalent of the points defined in the points\_ratio property.
points\_ratio `integer`	The number of loyalty points that will map to the predefined cash amount defined by the exchange\_ratio property.

Material

Attributes Description

product
object

Contains information about the product given as a reward.

Attributes Description

id
string

Unique product ID, assigned by Voucherify.

Example: prod\_0b7d7dfb05cbe5c616

sku\_id
string, null

Unique SKU ID, assigned by Voucherify, of the SKU given as a reward.

Example: sku\_0b7d7dfb090be5c619

MappingPoints

One of:

MappingMultiply
MappingFixed

Define fixed amount of points

Attributes Description

type
string

The number of points to be added to the loyalty card.

Available values: FIXED

points
integer

Defines how the points will be added to the loyalty card. FIXED adds a fixed number of points.

points\_formula
string

Formula used to dynamically calculate the rewarded points.

Calculate points proportionally

One of:

Define amount of points proportional to the order
Define amount of points proportional to order items
Define amount of points proportional to customer metadata
Earning Rule Proportional Custom Event

Earning Rule Event

Earning Rule Expiration Rules

Attributes	Description
period\_type `string`	Type of period. Can be set for `MONTH` or `FIXED\_DAY\_OF\_YEAR`. `MONTH` requires the `period\_value` field. `FIXED\_DAY\_OF\_YEAR` requires the `fixed\_month` and `fixed\_day` fields. Available values: `FIXED\_DAY\_OF\_YEAR`, `MONTH`
period\_value `integer`	Value of the period. Required for the `period\_type: MONTH`.
rounding\_type `string`	Type of rounding of the expiration period. Optional for the `period\_type: MONTH`. Available values: `END\_OF\_MONTH`, `END\_OF\_QUARTER`, `END\_OF\_HALF\_YEAR`, `END\_OF\_YEAR`, `PARTICULAR\_MONTH`
rounding\_value `integer`	Value of rounding of the expiration period. Required for the `rounding\_type`.
fixed\_month `integer`	Determines the month when the points expire; `1` is January, `2` is February, and so on. Required for the `period\_type: FIXED\_DAY\_OF\_YEAR`.
fixed\_day `integer`	Determines the day of the month when the points expire. Required for the `period\_type: FIXED\_DAY\_OF\_YEAR`.

Reward Assignment Base

Attributes	Description
id `string`	Unique reward assignment ID, assigned by Voucherify. Example: rewa\_PbIRoMXpwe5QhobW4JKu0VjH
reward\_id `string`	Associated reward ID. Example: rew\_C7wS9eHFDN4CIbXI5PpLSkGY
created\_at `string`	Timestamp representing the date and time when the reward assignment was created. The value is shown in the ISO 8601 format. Example: 2022-08-11T14:49:22.586Z
updated\_at `string`, `null`	Timestamp representing the date and time when the reward assignment was updated. The value is shown in the ISO 8601 format. Example: 2022-08-11T16:01:34.885Z
object `string`	The type of the object represented by the JSON. This object stores information about the reward assignment. Available values: `reward\_assignment`
related\_object\_id `string`	Related object ID to which the reward was assigned. Example: camp\_wciTvaOfYmAa3EmIIW3QpXXZ
related\_object\_type `string`	Related object type to which the reward was assigned. Available values: `campaign`

Digital or Material Reward - Parameters

Attributes Description

parameters
object

Defines the cost of the reward.

Attributes Description

loyalty
object

Defines the equivalent points value of the reward.

Attributes	Description
points `integer`	The number of points required to redeem the reward.
auto\_redeem `boolean`, `null`	Determines if the reward is redeemed automatically when the customer reaches the sufficient number of points to redeem it. Value `true` means that the automatic reward redemption is active. Only one reward can be set to be redeemed automatically in a loyalty campaign, i.e. only one can have the value `true`.

Discount Amount Vouchers Effect Types

Available values: APPLY\_TO\_ORDER, APPLY\_TO\_ITEMS, APPLY\_TO\_ITEMS\_PROPORTIONALLY, APPLY\_TO\_ITEMS\_PROPORTIONALLY\_BY\_QUANTITY, APPLY\_TO\_ITEMS\_BY\_QUANTITY

Discount Unit Vouchers Effect Types

Available values: ADD\_MISSING\_ITEMS, ADD\_NEW\_ITEMS, ADD\_MANY\_ITEMS, ADD\_SAME\_ITEMS

Simple Product Discount Unit

Attributes	Description
id `string`	Unique product ID, assigned by Voucherify.
source\_id `string`	Product's source ID.
name `string`	Product name.

Simple Sku Discount Unit

Attributes	Description
id `string`	Unique SKU ID, assigned by Voucherify.
source\_id `string`	Product variant's source ID.
name `string`	Sku name

One Unit

Attributes	Description
unit\_off `number`	Number of units to be granted a full value discount.
unit\_off\_formula `string`	Formula used to dynamically calculate the number of units.
effect `string`	Defines how the unit is added to the customer's order. Available values: `ADD\_NEW\_ITEMS`, `ADD\_MISSING\_ITEMS`
unit\_type `string`	The product deemed as free, chosen from product inventory (e.g. time, items).
product	Contains information about the product. Simple Product Discount Unit
sku	Contains information about the sku. Simple Sku Discount Unit

Discount Percent Vouchers Effect Types

Available values: APPLY\_TO\_ORDER, APPLY\_TO\_ITEMS

Discount Fixed Vouchers Effect Types

Available values: APPLY\_TO\_ORDER, APPLY\_TO\_ITEMS

Product without Skus Object

Attributes	Description
id `string`	Unique product ID assigned by Voucherify. Example: prod\_0b1da8105693710357
source\_id `string`, `null`	Unique product source ID. Example: productSourceID16
name `string`, `null`	Unique user-defined product name. Example: T-shirt
price `integer`, `null`	Unit price. It is represented by a value multiplied by 100 to accurately reflect 2 decimal places, such as `\$100.00` being expressed as `10000`.
attributes `array`	A list of product attributes whose values you can customize for given SKUs: `\["color","size","ranking"]`. Each child SKU can have a unique value for a given attribute.
metadata `object`	The metadata object stores all custom attributes assigned to the product. A set of key/value pairs that you can attach to a product object. It can be useful for storing additional information about the product in a structured format. It can be used to create product collections.
image\_url `string`, `null`	The HTTPS URL pointing to the .png or .jpg file that will be used to render the product image. Example: [https://images.com/original.jpg](https://images.com/original.jpg)
created\_at `string`	Timestamp representing the date and time when the product was created. The value is shown in the ISO 8601 format. Example: 2022-05-23T06:52:55.008Z
updated\_at `string`, `null`	Timestamp representing the date and time when the product was updated. The value is shown in the ISO 8601 format. Example: 2022-05-23T09:24:07.405Z
object `string`	The type of the object represented by JSON. This object stores information about the product. Available values: `product`

Skus List For Product

Attributes	Description
object `string`	The type of the object represented by JSON. This object stores information about SKUs.
data\_ref `string`	Identifies the name of the JSON property that contains the array of SKUs.
data `array`	A dictionary that contains an array of SKUs. Array of SKU Object
total `integer`	Total number of SKUs in the product.

Voucher Assets

Attributes Description

qr
object

Stores Quick Response (QR) representation of encrypted code.

Attributes Description

id
string

Encrypted voucher code ID.

Example: U2FsdGVkX19ucFhvVmBVpVYG5KoswTsjSIaqoKg5L9ie4BK+t4pp7U7oFzjGJzj9q/bmuMOj9mEFiVKDMIkSaruKedMvHbKoPX5Sg+BaZk5QwXMf8k/OzSlOEVybpwSq+AiqPoNtjeuqtIgkDyvT6Q==

url
string

URL to QR code

Optional: Attach query parameters to base URL to customize the image of the encrypted voucher code.

size : integer value from 1 to 100
format : string, either png (default) or svg

Example: [https://dev.dl.voucherify.io/api/v1/assets/qr/U2FsdGVkX19ucFhvVmBVpVYG5KoswTsjSIaqoKg5L9ie4BK%2Bt4pp7U7oFzjGJzj9q%2FbmuMOj9mEFiVKDMIkSaruKedMvHbKoPX5Sg%2BBaZk5QwXMf8k%2FOzSlOEVybpwSq%2BAiqPoNtjeuqtIgkDyvT6Q%3D%3D](https://dev.dl.voucherify.io/api/v1/assets/qr/U2FsdGVkX19ucFhvVmBVpVYG5KoswTsjSIaqoKg5L9ie4BK%2Bt4pp7U7oFzjGJzj9q%2FbmuMOj9mEFiVKDMIkSaruKedMvHbKoPX5Sg%2BBaZk5QwXMf8k%2FOzSlOEVybpwSq%2BAiqPoNtjeuqtIgkDyvT6Q%3D%3D)

barcode
object

Stores barcode representation of encrypted code.

Attributes Description

id
string

Encrypted voucher code ID.

Example: U2FsdGVkX19eJhGfWwUrH9+tulBkON+AnMktic+N6CVWzZ9+fHVxuVx22WakrzxiWXy0skuvvEHSeZIw9HlgyIJ+kJ1iPdUKpyENuNYJKzoZlO0mmTf6WQM6/pFs61apEn9SJx32ttCF6d3oxKISQQ==

url
string

URL to barcode

Optional: Attach query parameters to base URL to customize the image of the encrypted voucher code.

size : integer value from 1 to 100
format : string, either png (default) or svg

Example: [https://dev.dl.voucherify.io/api/v1/assets/barcode/U2FsdGVkX19eJhGfWwUrH9%2BtulBkON%2BAnMktic%2BN6CVWzZ9%2BfHVxuVx22WakrzxiWXy0skuvvEHSeZIw9HlgyIJ%2BkJ1iPdUKpyENuNYJKzoZlO0mmTf6WQM6%2FpFs61apEn9SJx32ttCF6d3oxKISQQ%3D%3D](https://dev.dl.voucherify.io/api/v1/assets/barcode/U2FsdGVkX19eJhGfWwUrH9%2BtulBkON%2BAnMktic%2BN6CVWzZ9%2BfHVxuVx22WakrzxiWXy0skuvvEHSeZIw9HlgyIJ%2BkJ1iPdUKpyENuNYJKzoZlO0mmTf6WQM6%2FpFs61apEn9SJx32ttCF6d3oxKISQQ%3D%3D)

Business Validation Rule Assignment

Attributes	Description
id `string`	The unique identifier for a assignment
rule\_id `string`	The unique identifier for a rule
related\_object\_id `string`	The unique identifier for a related object
related\_object\_type `string`	The type of related object
created\_at `string`	Timestamp representing the date and time when the object was created. The value is shown in the ISO 8601 format. Example: 2022-03-09T11:19:04.819Z
updated\_at `string`	Timestamp representing the date and time when the object was last updated in ISO 8601 format. Example: 2022-03-09T11:19:04.819Z
object `string`	The type of the object represented by JSON. Available values: `validation\_rules\_assignment`
validation\_status `string`	The validation status of the assignment Available values: `VALID`, `PARTIALLY\_VALID`, `INVALID`
validation\_omitted\_rules `array`	The list of omitted rules

Validation Rule Assignment

Attributes	Description
id `string`	Validation rule assignment ID. Example: asgm\_74F7QZoYbUoljwQO
rule\_id `string`	Validation rule ID. Example: val\_4j7DCRm2IS59
related\_object\_id `string`	The resource ID to which the validation rule was assigned. Example: v\_JtWunK6jUo7X2qOFj0SyRHq4p9tgENlT
related\_object\_type `string`	The type of resource to which the validation rule was assigned. Available values: `voucher`, `campaign`, `earning\_rule`, `reward\_assignment`, `promotion\_tier`, `distribution`
created\_at `string`	Timestamp representing the date and time when the validation rule assignment was created. The value is shown in the ISO 8601 format. Example: 2022-02-17T08:18:15.085Z
object `string`	The type of the object represented by the ID. Available values: `validation\_rules\_assignment`

MappingMultiply

Attributes Description

type
string

Type of calculation.

Available values: MULTIPLY

multiplier
number

Multiplication factor used to multiply the points to obtain the mapped points.

MappingFixed

Attributes Description

type
string

Type of calculation.

Available values: CUSTOM

points
integer

Fixed number of points to be applied.

Define amount of points proportional to the order

One of:

Order Amount
Order Total Amount
Order Metadata

Define amount of points proportional to order items

One of:

Order Items Quantity
Order Items Amount
Order Items Subtotal Amount

Define amount of points proportional to customer metadata

Attributes Description

type
string

Defines how the points will be added to the loyalty card.PROPORTIONAL adds points based on a pre-defined ratio.

Available values: PROPORTIONAL

calculation\_type
string

CUSTOMER\_METADATA: Customer Metadata (X points for every Y in metadata attribute, defined in the property key under the customer.metadata object)

Available values: CUSTOMER\_METADATA

customer
object

Attributes Description

metadata
object

Defines the ratio based on the property defined in the calculation\_type parameter. For every given increment of value (1, 10, etc) defined in the every parameter for the property defined in calculation\_type, give the customer the number of points defined in the points parameter. In other words, for every order metadata property value, give points.

Attributes	Description
every `integer`	For how many increments of the customer metadata property to grant points for.
points `integer`	Number of points to be awarded, i.e. how many points to be added to the loyalty card.
points\_formula `string`	Formula used to dynamically calculate the rewarded points.
property `string`	Customer metadata property.

Earning Rule Proportional Custom Event

Attributes Description

type
string

Defines how the points will be added to the loyalty card.PROPORTIONAL adds points based on a pre-defined ratio.

Available values: PROPORTIONAL

calculation\_type
string

CUSTOM\_EVENT\_METADATA: Custom event metadata (X points for every Y in metadata attribute).

Available values: CUSTOM\_EVENT\_METADATA

custom\_event
object

Attributes Description

metadata
object

Attributes	Description
every `integer`	For how many increments of the customer metadata property to grant points for.
points `integer`	Number of points to be awarded, i.e. how many points to be added to the loyalty card.
points\_formula `string`	Formula used to dynamically calculate the rewarded points.
property `string`	Custom event metadata property.

Order Amount

Attributes Description

type
string

Defines how the points will be added to the loyalty card.PROPORTIONAL adds points based on a pre-defined ratio.

Available values: PROPORTIONAL

calculation\_type
string

ORDER\_AMOUNT : Pre-discount order amount (X points for every Y spent excluding discounts)

Available values: ORDER\_AMOUNT

order
object

Attributes Description

amount
object

Defines the ratio based on the property defined in the calculation\_type parameter. For every set of value (1, 10, etc) defined in the every parameter for the property defined in calculation\_type, give the customer the number of points defined in the points parameter. In other words, for every calculation\_type, give points.

Attributes	Description
every `integer`	Value is multiplied by 100 to precisely represent 2 decimal places. For example, a \$10 order amount is written as 1000.
points `integer`	Number of points to be awarded, i.e. how many points to be added to the loyalty card.
points\_formula `string`	Formula used to dynamically calculate the rewarded points.

Order Total Amount

Attributes Description

type
string

Defines how the points will be added to the loyalty card.PROPORTIONAL adds points based on a pre-defined ratio.

Available values: PROPORTIONAL

calculation\_type
string

ORDER\_TOTAL\_AMOUNT : Total order amount (X points for every Y spent including discount)

Available values: ORDER\_TOTAL\_AMOUNT

order
object

Attributes Description

total\_amount
object

Attributes	Description
every `integer`	Value is multiplied by 100 to precisely represent 2 decimal places. For example, a \$10 order amount is written as 1000.
points `integer`	Number of points to be awarded, i.e. how many points to be added to the loyalty card.
points\_formula `string`	Formula used to dynamically calculate the rewarded points.

Order Metadata

Attributes Description

type
string

Defines how the points will be added to the loyalty card.PROPORTIONAL adds points based on a pre-defined ratio.

Available values: PROPORTIONAL

calculation\_type
string

ORDER\_METADATA : Order Metadata (X points for every Y in metadata attribute, defined in the property key under the order.metadata object)

Available values: ORDER\_METADATA

order
object

Defines the formula for calculating points proportionally.

Attributes Description

metadata
object

Attributes	Description
every `integer`	For how many increments of the order metadata property to grant points for.
points `integer`	Number of points to be awarded, i.e. how many points to be added to the loyalty card.
points\_formula `string`	Formula used to dynamically calculate the rewarded points.
property `string`	Order metadata property.

Order Items Quantity

Attributes Description

type
string

Defines how the points will be added to the loyalty card.PROPORTIONAL adds points based on a pre-defined ratio.

Available values: PROPORTIONAL

calculation\_type
string

ORDER\_ITEMS\_QUANTITY : Quantity of items defined in the order\_items.quantity.applicable\_to array or order\_items.quantity.object & .id (X points for every Y items excluding free items).

Available values: ORDER\_ITEMS\_QUANTITY

order\_items
object

Attributes Description

quantity
object

Attributes Description

every
integer

Value is multiplied by 100 to precisely represent 2 decimal places. For example, a \$10 order amount is written as 1000.

points
integer

Number of points to be awarded, i.e. how many points to be added to the loyalty card.

points\_formula
string

Formula used to dynamically calculate the rewarded points.

object
string

Type of object which will be covered by the earning rule. This is required together with id. Can be replaced by the applicable\_to array. In response, the value of the first object is returned even if applicable\_to array was used.

Available values: products\_collection, product, sku

id
string

Unique ID of the resource assigned by Voucherify. This is required together with object. Can be replaced by the applicable\_to array. In response, the value of the first object is returned even if applicable\_to array was used. Values are, for example, pc\_75U0dHlr7u75BJodrW1AE3t6 for product collection, prod\_0bae32322150fd0546 for a product, or sku\_0b7d7dfb090be5c619 for a SKU.

applicable\_to
array

Defines products, SKUs, or product collections covered by the earning rule. Can be replaced by object and id to define only one object.

Array of:

Attributes Description

object
string

Type of object which will be covered by the earning rule.

Available values: products\_collection, product, sku

id
string

Unique ID of the resource assigned by Voucherify. Values are, for example, pc\_75U0dHlr7u75BJodrW1AE3t6 for product collection, prod\_0bae32322150fd0546 for a product, or sku\_0b7d7dfb090be5c619 for a SKU.

Order Items Amount

Attributes Description

type
string

Defines how the points will be added to the loyalty card.PROPORTIONAL adds points based on a pre-defined ratio.

Available values: PROPORTIONAL

calculation\_type
string

ORDER\_ITEMS\_AMOUNT; Pre-discount amount spent on items defined in the order\_items.quantity.applicable\_to array or order\_items.quantity.object & .id (X points for every Y spent on items excluding discounts)

Available values: ORDER\_ITEMS\_AMOUNT

order\_items
object

Attributes Description

amount
object

Attributes Description

every
integer

Value is multiplied by 100 to precisely represent 2 decimal places. For example, a \$10 order amount is written as 1000.

points
integer

Number of points to be awarded, i.e. how many points to be added to the loyalty card.

points\_formula
string

Formula used to dynamically calculate the rewarded points.

object
string

Available values: products\_collection, product, sku

id
string

applicable\_to
array

Defines products, SKUs, or product collections covered by the earning rule. Can be replaced by object and id to define only one object.

Array of:

Attributes Description

object
string

Type of object which will be covered by the earning rule.

Available values: products\_collection, product, sku

id
string

Order Items Subtotal Amount

Attributes Description

type
string

Defines how the points will be added to the loyalty card.PROPORTIONAL adds points based on a pre-defined ratio.

Available values: PROPORTIONAL

calculation\_type
string

ORDER\_ITEMS\_SUBTOTAL\_AMOUNT; Amount spent on items defined in the order\_items.subtotal\_amount.object & .id (X points for every Y spent on items including discounts)

Available values: ORDER\_ITEMS\_SUBTOTAL\_AMOUNT

order\_items
object

Attributes Description

subtotal\_amount
object

Attributes Description

every
integer

Value is multiplied by 100 to precisely represent 2 decimal places. For example, a \$10 order amount is written as 1000.

points
integer

Number of points to be awarded, i.e. how many points to be added to the loyalty card.

points\_formula
string

Formula used to dynamically calculate the rewarded points.

object
string

Available values: products\_collection, product, sku

id
string

applicable\_to
array

Defines products, SKUs, or product collections covered by the earning rule. Can be replaced by object and id to define only one object.

Array of:

Attributes Description

object
string

Type of object which will be covered by the earning rule.

Available values: products\_collection, product, sku

id
string

# Customer Object Source: https://docs.voucherify.io/api-reference/customers/customer-object

Customer With Summary Loyalty Referrals

All of:

Customer Response Data

Attributes Description

id
string

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

source\_id
string

summary

Customer Summary

loyalty

Customer Loyalty

referrals

Customer Referrals

system\_metadata
object

Object used to store system metadata information.

created\_at
string

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

Example: 2022-08-30T06:32:07.380Z

updated\_at
string

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

Example: 2022-08-31T06:32:07.380Z

assets
object

Contains information about the customer's cockpit.

⚠️ Warning: Customer cockpits were removed. The customer cockpit URLs redirect to customer preference center.

Attributes	Description
cockpit\_url `string`	URL address to customer preference center. Previously, a customer's cockpit URL address.
cockpit\_preference\_center\_url `string`	URL address to customer preference center.

object
string

The type of the object represented by JSON.

Available values: customer

Customer Base

Customer Summary

Attributes	Description
redemptions	See: Customer Summary Redemptions
orders	See: Customer Summary Orders

Customer Loyalty

Attributes Description

points
integer

Customer's loyalty points minus expired for all loyalty cards which the customer has.

referred\_customers
integer

Total number of customers referred by the customer.

campaigns
object

Contains campaigns with details about point balances and how many customers were referred by the customer.

Attributes Description

\[propertyName]
object

Contains details about the point balances left on loyalty cards and the number of referred customers in each campaign.

Attributes Description

points
integer

Remaining point balance in campaign.

loyalty\_tier
string

Customer's loyalty tier within the campaign.

Example: ltr\_UJ5Q54Q0OvEhua87Qfv2Ki5x

referred\_customers
integer

Number of customers referred by the customer in campaign.

Customer Referrals

Attributes Description

total
integer

Total number of times this customer received a referral, i.e. was referred by another customer.

campaigns
array

Contains an array of campaigns that served as the source of a referral for the customer.

Array of:

Customer Referrals Campaigns Item

Attributes	Description
campaign\_id `string`	Unique campaign ID, assigned by Voucherify. Example: camp\_rRsfatlwN7unSeUIJDCYedal
referrer\_id `string`	Unique referrer ID, assigned by Voucherify. This is the customer ID of a customer that is referring this customer. Example: cust\_sehkNIi8Uq2qQuRqSr7xn4Zi
related\_object\_id `string`	Related object id Example: r\_0b9d4cc4aa164dd073
related\_object\_type `string`	Related object type, i.e. `redemption`.
date `string`	Timestamp representing the date and time when the customer was referred in ISO 8601 format. Example: 2022-08-30T10:19:39.196Z

Customer Base

Attributes Description

name
string

Customer's first and last name.

description
string

An arbitrary string that you can attach to a customer object.

email
string

Customer's email address.

phone
string

Customer's phone number. This parameter is mandatory when you try to send out codes to customers via an SMS channel.

birthday
string

Deprecated. ~~Customer's birthdate; format YYYY-MM-DD~~.

birthdate
string

Customer's birthdate; format YYYY-MM-DD.

address
object, null

Customer's address.

Attributes	Description
city `string`	City
state `string`	State
line\_1 `string`	First line of address.
line\_2 `string`	Second line of address.
country `string`	Country.
postal\_code `string`	Postal code.

metadata
object

Customer Summary Redemptions

Attributes Description

total\_redeemed
integer

Total number of redemptions made by the customer.

total\_failed
integer

Total number of redemptions that failed.

total\_succeeded
integer

Total number of redemptions that succeeded.

total\_rolled\_back
integer

Total number of redemptions that were rolled back for the customer.

total\_rollback\_failed
integer

Total number of redemption rollbacks that failed.

total\_rollback\_succeeded
integer

Total number of redemption rollbacks that succeeded.

gift
object

Summary of gift card credits.

Attributes	Description
redeemed\_amount `integer`	Total amount of gift card credits redeemed by customer. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `\$100.00`.
amount\_to\_go `integer`	Remaining gift card balance across all gift cards. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `\$100.00`.

loyalty\_card
object

Summary of loyalty points.

Attributes	Description
redeemed\_points `integer`	Total number of loyalty points redeemed by the customer.
points\_to\_go `integer`	Sum of remaining available point balance across all loyalty cards.

Customer Summary Orders

Attributes	Description
total\_amount `integer`	The total amount spent by the customer. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `\$100.00`.
total\_count `integer`	Total number of orders made by the customer.
average\_amount `integer`	Average amount spent on orders. `total\_amount` ÷ `total\_count`. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `\$100.00`.
last\_order\_amount `integer`	Amount spent on last order. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `\$100.00`.
last\_order\_date `string`	Timestamp representing the date and time of the customer's last order in ISO 8601 format. Example: 2022-08-30T11:51:08.029Z

# Delete Customer Source: https://docs.voucherify.io/api-reference/customers/delete-customer /openapi/customers.json delete /v1/customers/{customerId} This method deletes a customer. # Delete Customer Permanently Source: https://docs.voucherify.io/api-reference/customers/delete-customer-permanently /openapi/customers.json post /v1/customers/{customerId}/permanent-deletion The organization user can remove consumer data permanently from the Voucherify system by using this API method. It deletes all customer data and connected resources. It makes the customer profile forgotten by Voucherify. # Get Customer Source: https://docs.voucherify.io/api-reference/customers/get-customer /openapi/customers.json get /v1/customers/{customerId} Retrieves details of a given customer by customer's `id` or `source_id`. # Import and Update Customers using CSV Source: https://docs.voucherify.io/api-reference/customers/import-and-update-customers-using-csv /openapi/customers.json post /v1/customers/importCSV This API method lets you import or update customer data. To get a proper and valid response, please send a CSV file with data separated by commas. ## Request Example ```cURL curl -X **POST** \ https://api.voucherify.io/v1/customers/importCSV \ -F file=@/path/to/customers.csv \ -H "X-App-Id: c70a6f00-cf91-4756-9df5-47628850002b" \ -H "X-App-Token: 3266b9f8-e246-4f79-bdf0-833929b1380c" ``` ## CSV File Format The CSV file has to include headers in the first line. All properties which cannot be mapped to standard customer fields will be added to the metadata object. Standard customer fields mapping **No spaces allowed in field names** `Id`, `Name`, `Email`, `Phone`, `Birthdate`, `Source_id`, `Address_line_1`, `Address_line_2`, `Address_Postal_Code`, `Address_City`, `Address_State`, `Address_Country`, `Description`, `Metadata_name_1`, `Metadata_name_2` ## Update Customers using CSV If you would like to update customer's data, you can do it using the CSV file with new data. However, remember to include a `source_id` in your CSV file to manage the update successfully. This API request starts a process that affects Voucherify data in bulk. In case of small jobs (like bulk update) the request is put into a queue and processed once every other bulk request placed in the queue prior to this request is finished. However, when the job takes a longer time (like vouchers generation) then it is processed in small portions in a round-robin fashion. When there is a list of vouchers generation scheduled, then they will all have the `IN_PROGRESS` status shortly. This way, small jobs added just after scheduling big jobs of the same type will be processed in a short time window. The result will return the async ID. You can verify the status of your request via this [API request](/api-reference/async-actions/get-async-action). # List Customer Activities Source: https://docs.voucherify.io/api-reference/customers/list-customer-activities /openapi/customers.json get /v1/customers/{customerId}/activities Deprecated This endpoint represents the deprecated version of the API responsible for listing customer activities and we do not recommend using it. 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. Retrieve customer activities. # List Customer Activity Source: https://docs.voucherify.io/api-reference/customers/list-customer-activity /openapi/customers.json get /v1/customers/{customerId}/activity Retrieves activity details of a given customer by customer's `id` or `source_id`. # List Customers Source: https://docs.voucherify.io/api-reference/customers/list-customers /openapi/customers.json get /v1/customers Returns a list of customers. # List Customer's Redeemables Source: https://docs.voucherify.io/api-reference/customers/list-customers-redeemables /openapi/customers.json get /v1/customers/{customerId}/redeemables Retrieves all the redeemables that have been assigned to the customer. To use this endpoint, you must have the following permissions: - Read Customers (`customers.details.read`) # List Customer's Segments Source: https://docs.voucherify.io/api-reference/customers/list-customers-segments /openapi/customers.json get /v1/customers/{customerId}/segments Returns the list of segments IDs to which the customer belongs to. If you pass a `customerId` which is not stored and recognized by Voucherify as an existing customer in the system, the response will generate a list of segments that the customer would potentialy qualify for if they were to become a customer tracked in the system. # Update Customer Source: https://docs.voucherify.io/api-reference/customers/update-customer /openapi/customers.json put /v1/customers/{customerId} Updates the specified customer by setting the values of the parameters passed in the request body. Any parameters not provided in the payload will be left unchanged. # Update Customers in Bulk Source: https://docs.voucherify.io/api-reference/customers/update-customers-in-bulk /openapi/customers.json post /v1/customers/bulk/async Updates customers in one asynchronous operation. The request can include up to **10 MB** of data. The response returns a unique asynchronous action ID. Use this ID in the query paramater of the [GET Async Action](/api-reference/async-actions/get-async-action) endpoint to check, e.g.: - The status of your request (in queue, in progress, done, or failed) - Resources that failed to be updated - The report file with details about the update If a customer object is not found, it is **upserted**. This is shown in the report file in the **GET** Async Action endpoint. The upserted resources have value `false` in the `found` column and `true` in the `updated` column. This API request starts a process that affects Voucherify data in bulk. In the case of small jobs (like bulk update), the request is put into a queue and processed when every other bulk request placed in the queue prior to this request is finished. # Update Customers' Metadata in Bulk Source: https://docs.voucherify.io/api-reference/customers/update-customers-metadata-in-bulk /openapi/customers.json post /v1/customers/metadata/async Updates metadata parameters for a list of customers. Every resource in the list will receive the metadata defined in the request. The request can include up to **10 MB** of data. The response returns a unique asynchronous action ID. Use this ID in the query paramater of the [GET Async Action](/api-reference/async-actions/get-async-action) endpoint to check, e.g.: - The status of your request (in queue, in progress, done, or failed) - Resources that failed to be updated - The report file with details about the update If a customer object is not found, it is **upserted**. This is shown in the report file in the **GET** Async Action endpoint. The upserted resources have value `false` in the `found` column and `true` in the `updated` column. This API request starts a process that affects Voucherify data in bulk. In the case of small jobs (like bulk update), the request is put into a queue and processed when every other bulk request placed in the queue prior to this request is finished. # Distribution webhooks Source: https://docs.voucherify.io/api-reference/distribution-webhooks Use webhooks to get notified about distribution events in Voucherify Distribution-based webhooks in Voucherify let your application automatically receive notifications related to distribution events. They help you track the results of distributions and quickly respond when certain actions occur. For example, your application can be notified when a voucher is successfully published, a scheduled campaign message is delivered, or when a customer enters or leaves a specific customer segment. ## Configuring distribution webhooks 1. In Voucherify dashboard, go to Distributions in the Engagement section. 2. Click Create distribution. 3. Select the appropriate [trigger](#webhooks-available-in-distributions "Distribution webhooks") that creates a send out. 4. In Action, define what kind of distribution action you want to create. 5. In Channels, add Webhook. You can add many channels within one distribution. 6. In the webhook channel, provide the event name, URL, and any optional HTTP headers. 7. Select the attributes to add them to the webhook payload. Optionally, map the attributes to your own keys. To edit, pause, activate, or delete a distribution, click the three dots icon located on the far right of each row in the Distributions list view. **You can also add distribution webhooks while creating a loyalty or referral programs. The process follows similar pattern.** ## Payload designer Use the **Raw payload** checkbox to choose if the webhook payload is sent at the root level or inside the `data` object. The Show output panel displays an example payload and updates dynamically based on the selected trigger context, so you see only the variables that apply to that specific trigger type. You can paste any existing payload or write it from scratch. Each key in the payload can have a value that is static, dynamic, or nested: * Static values are fixed values you define, such as text, numbers, or boolean. * Dynamic values come from Voucherify keys in the webhook payload. Use double curly braces `{{}}` to search for Voucherify keys. You can also mix static and dynamic values, for example `"Hello {{customer.name}}"`. * Nested objects can be created with dots in the key name, such as `{{order.status}}`. If you want a value to be a string, wrap it in quotes `("")`. When the type of a value is unknown, also wrap it in quotes `("")` to ensure it is treated as a string. Here are two examples showing how the sent payload changes between the output and raw payload: ```json Sample output theme={null} { "id": "whs_000000000000000000", "project_id": "proj_YaEcEOLM", "created_at": "2000-01-01T00:00:00.000Z", "type": "", "source": { "id": "distr_000000000000000000", "object": "distribution", "target_url": "https://00000000-0000-0000-0000-000000000000" }, "event": { "id": "evcus_000000000000000000", "type": "customer.publication.succeeded", "created_at": "2000-01-01T00:00:00.000Z", "entity_id": "entity_id_000000000000000000", "group_id": "v-000000000000000000", "event_source": { "channel": "INTERNAL" } }, "data": { "To": "john.smith@example.com", "From": "examplepayload@yourcompany.com", "Subject": "Thank you for your order, John Smith", "Body": "Hello John Smith. Here's your discount code: SUMMER-2024-A7B9." } } ``` ```json Raw payload theme={null} { "To": "john.smith@example.com", "From": "examplepayload@yourcompany.com", "Subject": "Thank you for your order, John Smith", "Body": "Hello John Smith. Here's your discount code: SUMMER-2024-A7B9." } ``` Available Voucherify webhook keys The available keys supported by Voucherify are limited to a given distribution event that is used in the webhook. For example, if you create a webhook payload for the [Customer entered segment](/api-reference/customer/segment-entered), you can use all the keys available in that event, like `customer.name` or `segment.name`. However, you can't use objects that aren't available in that webhook, like `redemption.date`. Read [Webhooks available in Distributions](#webhooks-available-in-distributions) to learn which webhooks are available. Go to specific webhook pages to learn more about their payloads. ### Example: Customer summary with dynamic values This payload builds a customer summary. All values are taken dynamically from the webhook. ```json theme={null} { "customer_profile": { "ID": "{{customer.id}}", "name": "{{customer.name}}", "email": "{{customer.email}}" } } ``` ### Example: Order confirmation with mixed values This payload mixes static and dynamic values. The currency is fixed, while the order details and greeting come from Voucherify. ```json theme={null} { "order": { "orderId": "{{order.id}}", "total": {{order.total_amount}}, "currency": "USD", "message": "Thank you for your order, {{customer.name}}!" } } ``` ## Re-enabling a webhook To re-enable a paused webhook: 1. Go to the Distribution Manager. 2. Click the distribution that has been paused. 3. Click the set live icon in the upper right corner. ## Webhooks available in Distributions These webhooks are triggered by the events which cause distribution. Some distribution events, for example Customer entered segment, have different purposes: * Notify customers about promotion * Send and publish unique codes from campaign * Send plain message to customers The table below shows which distributions support webhooks: | Related Activity | Event | Notify customers about promotion | Send and publish unique codes from campaign | Send plain message to customers | | ----------------------------- | --------------------------------------- | -------------------------------- | ------------------------------------------- | ------------------------------- | | Segment | Customer entered segment | ✅ | ✅ | ✅ | | Segment | Customer left segment | ✅ | ✅ | ✅ | | Cart | Order update | ✅ | ✅ | ✅ | | Cart | Order has been paid | ✅ | ✅ | ✅ | | Cart | Order creation | ✅ | ✅ | ✅ | | Cart | Order cancelled | ✅ | ✅ | ✅ | | Voucher | Gift credits adjusted | ❌ | ❌ | ✅ | | Voucher | Loyalty points adjusted | ❌ | ❌ | ✅ | | Voucher | Loyalty points expired | ❌ | ❌ | ✅ | | Voucher | Loyalty pending points adjusted | ❌ | ❌ | ✅ | | Voucher | Loyalty pending points updated | ❌ | ❌ | ✅ | | Voucher | Loyalty pending points activated | ❌ | ❌ | ✅ | | Voucher | Loyalty pending points canceled | ❌ | ❌ | ✅ | | Voucher | Voucher redeemed | ❌ | ❌ | ✅ | | Voucher | Voucher redemption rolled back | ❌ | ❌ | ✅ | | Customer rewards | Reward redemption | ❌ | ❌ | ✅ | | Manual messages | One or bulk messages | ✅ | ✅ | ❌ | | Publishing codes | Successfully published | ❌ | ❌ | ✅ | | Custom events | Custom event | ✅ | ✅ | ✅ | | Loyalty tier related activity | Customer entered loyalty tier structure | ❌ | ❌ | ✅ | | Loyalty tier related activity | Customer left loyalty tier structure | ❌ | ❌ | ✅ | | Loyalty tier related activity | Customer loyalty tier upgraded | ❌ | ❌ | ✅ | | Loyalty tier related activity | Customer loyalty tier downgraded | ❌ | ❌ | ✅ | | Loyalty tier related activity | Customer loyalty tier prolonged | ❌ | ❌ | ✅ | | Loyalty tier related activity | Customer rewarded loyalty points | ❌ | ❌ | ✅ | | Referral related activity | Customer was referred | ❌ | ❌ | ✅ | * Custom events: * [Custom event](/api-reference/customer/custom-event "Customer custom event documentation") * Segment related activities: * [Customer entered segment](/api-reference/customer/segment-entered "Customer entered segment event documentation") * [Customer left segment](/api-reference/customer/segment-left "Customer left segment event documentation") * Manual messages: * Notify customers about promotion – covered by [the MANUAL\_DISTRIBUTION\_SCHEDULE event](/api-reference/distribution/manual-distribution-schedule "Manual distribution schedule event documentation") * Send and publish unique codes from a campaign – covered by [the MANUAL\_DISTRIBUTION\_SCHEDULE event](/api-reference/distribution/manual-distribution-schedule "Manual distribution schedule event documentation") * Send a plain message to customers – does not support webhooks as a distribution channel * Cart related activities: * [Order updated](/api-reference/customer/order-updated "Order updated event documentation") * [Order paid](/api-reference/customer/order-paid "Order paid event documentation") * [Order created](/api-reference/customer/order-created "Order created event documentation") * [Order canceled](/api-reference/customer/order-canceled "Order canceled event documentation") * Publishing codes: * [Successfully published](/api-reference/customer/publication-succeeded "Code published event documentation") * Voucher related activities: * [Gift credits added](/api-reference/customer/voucher-gift-balance-added "Gift credits added event documentation") * [Loyalty points added](/api-reference/customer/voucher-loyalty-card-points-added "Loyalty points added event documentation") * [Loyalty card points expired](/api-reference/customer/voucher-loyalty-card-points-expired "Customer loyalty card points expired event documentation") * [Loyalty pending points added](/api-reference/customer/voucher-loyalty-card-pending-points-added "Customer loyalty card pending points added") * [Loyalty pending points updated](/api-reference/customer/voucher-loyalty-card-pending-points-updated "Voucher loyalty card pending points update event documentation") * [Loyalty pending points activated](/api-reference/customer/voucher-loyalty-card-pending-points-activated "Customer loyalty card pending points activated") * [Loyalty pending points canceled](/api-reference/customer/voucher-loyalty-card-pending-points-canceled "Customer loyalty card pending points canceled") * [Voucher redeemed](/api-reference/customer/redemption-succeeded "Voucher redeemed event documentation") * [Voucher redemption rolled back](/api-reference/customer/redemption-rollback-succeeded "Voucher redemption rolled back event documentation") * Customer rewards: * [Reward redeemed](/api-reference/customer/rewarded "Customer rewarded documentation") * Loyalty tier related activities: * [Customer entered loyalty tier structure](/api-reference/customer/loyalty-tier-joined "Customer entered loyalty tier structure event documentation") * [Customer left loyalty tier structure](/api-reference/customer/loyalty-tier-left "Customer left loyalty tier structure event documentation") * [Customer loyalty tier upgraded](/api-reference/customer/loyalty-tier-upgraded "Customer loyalty tier upgraded event documentation") * [Customer loyalty tier downgraded](/api-reference/customer/loyalty-tier-downgraded "Customer loyalty tier downgraded event documentation") * [Customer loyalty tier prolonged](/api-reference/customer/loyalty-tier-prolonged "Customer loyalty tier prolonged event documentation") * [Customer rewarded loyalty points](/api-reference/customer/rewarded-loyalty-points "Customer rewarded loyalty points documentation") * Referral related activities: * Customer was referred ### Loyalty and referral campaign Distributions The following campaigns can also trigger webhook send outs as a distribution: * Loyalty campaigns: * [Send loyalty program code](/api-reference/customer/publication-succeeded) * [Loyalty points gained](/api-reference/customer/rewarded-loyalty-points) * [Reward redeemed](/api-reference/customer/reward-redemptions-completed) * Referral campaigns: * [Send referral code to the referrer](/api-reference/customer/publication-succeeded) * Customer referred (documentation in progress) ### Distribution webhook payload The list shows a general structure of a webhook payload set in Distributions. Indented bullet points mean that an object contains further properties or objects. The list shows the complete, unedited payload. If you customize it with the Payload editor, your data may include fewer fields. * `id` (`string`): Unique identifier of the send out for this webhook. **Example:** `whs_0e16e42bc6e0c65b57` * `project_id` (`string`): Unique identifier of the Voucherify project. **Example:** `proj_5T4Rpl4T1nuM` * `created_at` (`string`): The exact moment when the webhook was created. **Example:** `2024-01-01T11:11:11.111Z` * `type` (`string`): Displays the name entered in the `Event name` field in the distribution creator. * `data` (`object`): Payload depends on the event that triggered the webhook send out. Distributions cover the following events: * [customer.custom\_event](/api-reference/customer/custom-event) * [customer.loyalty.tier.downgraded](/api-reference/customer/loyalty-tier-downgraded) * [customer.loyalty.tier.joined](/api-reference/customer/loyalty-tier-joined) * [customer.loyalty.tier.left](/api-reference/customer/loyalty-tier-left) * [customer.loyalty.tier.prolonged](/api-reference/customer/loyalty-tier-prolonged) * [customer.loyalty.tier.upgraded](/api-reference/customer/loyalty-tier-upgraded) * [customer.order.canceled](/api-reference/customer/order-canceled) * [customer.order.created](/api-reference/customer/order-created) * [customer.order.paid](/api-reference/customer/order-paid) * [customer.order.updated](/api-reference/customer/order-updated) * [customer.publication.succeeded](/api-reference/customer/publication-succeeded) * [customer.redemption.rollback.succeeded](/api-reference/customer/redemption-rollback-succeeded) * [customer.redemption.succeeded](/api-reference/customer/redemption-succeeded) * customer.referred * [customer.reward\_redemptions.completed](/api-reference/customer/reward-redemptions-completed) * [customer.rewarded](/api-reference/customer/rewarded) * [customer.rewarded.loyalty\_points](/api-reference/customer/rewarded-loyalty-points) * [customer.segment.entered](/api-reference/customer/segment-entered) * [customer.segment.left](/api-reference/customer/segment-left) * [customer.voucher.gift.balance\_added](/api-reference/customer/voucher-gift-balance-added) * [customer.voucher.loyalty\_card.pending\_points.activated](/api-reference/customer/voucher-loyalty-card-pending-points-activated) * [customer.voucher.loyalty\_card.pending\_points.added](/api-reference/customer/voucher-loyalty-card-pending-points-added) * [customer.voucher.loyalty\_card.pending\_points.canceled](/api-reference/customer/voucher-loyalty-card-pending-points-canceled) * [customer.voucher.loyalty\_card.pending\_points.updated](/api-reference/customer/voucher-loyalty-card-pending-points-updated) * [customer.voucher.loyalty\_card.points\_added](/api-reference/customer/voucher-loyalty-card-points-added) * [customer.voucher.loyalty\_card.points\_expired](/api-reference/customer/voucher-loyalty-card-points-expired) * [manual\_distribution\_schedule](/api-reference/distribution/manual-distribution-schedule) * `source` (`object`): Contains details about the source of the webhook send out. Properties: * `id` (`string`): Unique identifier of the distribution that sent the webhook. **Example:** `distr_TrJj0lHV44EMt6HvLa2pyNlHTF` * `object` (`string`): Determines the type of the object. Available values: `distribution` **Example:** `distribution` * `target_url` (`string`): The address where the webhook will be sent. * `event` (`object`): Contains other data of the event that triggered the send out. Properties: * `id` (`string`): Unique identifier of the event that triggered the send out. **Example:** `evred_1f3611301g3127begb` * `type` (`string`): Determines the type of the event. **Example:** * `customer.custom_event` * `customer.loyalty.tier.downgraded` * `customer.loyalty.tier.joined` * `customer.loyalty.tier.left` * `customer.loyalty.tier.prolonged` * `customer.loyalty.tier.upgraded` * `customer.order.canceled` * `customer.order.created` * `customer.order.paid` * `customer.order.updated` * `customer.publication.succeeded` * `customer.redemption.rollback.succeeded` * `customer.redemption.succeeded` * `customer.referred` * `customer.reward_redemptions.completed` * `customer.rewarded` * `customer.rewarded.loyalty_points` * `customer.segment.entered` * `customer.segment.left` * `customer.voucher.gift.balance_added` * `customer.voucher.loyalty_card.pending_points.activated` * `customer.voucher.loyalty_card.pending_points.added` * `customer.voucher.loyalty_card.pending_points.canceled` * `customer.voucher.loyalty_card.points_added` * `customer.voucher.loyalty_card.points_expired` * `loyalty_card.pending_points.updated` * `manual_distribution_schedule` * `created_at` (`string`): The exact moment when the event was created. **Example:** `2024-01-01T11:11:11.111Z` * `entity_id` (`string`): Unique identifier of the entity that triggered the send out. **Example:** `r_1f3611302bf107befb` * `group_id` (`string`): Unique identifier of the request that triggered the event. **Example:** `v-1f36113948e50fc4ge` * `event_source` (`object`): Contains the source of the object that triggered the send out. Properties: * `channel` (`string`): Determines the channel that triggered the send out. Available values: `USER_PORTAL`, `API`, `CLIENT_API`, `INTERNAL` **Example:** `API` * `user` (`object`): Defines the user who triggered the event. * `id` (`string`): ID of the user who triggered the event. * `api_key` (`object`): Determines the API key used to initiate the send out. * `name` (`string`): Channel name in the application keys. * `app_id` (`string`): Contains the application ID from the Voucherify API key pair. **Example:** `1XXXX5XX-0XXX-XXXb-X7XX-XX2XXaXXX6XX` ```JSON Customer voucher redeemed example theme={null} { "id": "whs_ID", "project_id": "proj_ID", "created_at": "2025-10-16T16:54:11.816Z", "type": "Voucher-redeemed", "data": { "customer": { "id": "cust_ID", "name": "Alex Doe", "email": "alex.doe@doe.alex.io", "source_id": "4lx-d03", "metadata": { "acquisition_channel": "Website" }, "object": "customer" }, "order": { "id": "ord_ID", "source_id": null, "status": "PAID", "customer_id": "cust_ID", "referrer_id": null, "amount": 4198, "applied_discount_amount": 0, "total_applied_discount_amount": 0, "total_amount": 4198, "items": [ { "id": "ordli_IDD", "object": "order_item", "product_id": "prod_IDD", "quantity": 1, "amount": 199, "price": 199, "subtotal_amount": 199 }, { "id": "ordli_ID", "object": "order_item", "product_id": "prod_ID", "quantity": 1, "amount": 3999, "price": 3999, "subtotal_amount": 3999 } ], "metadata": {}, "created_at": "2025-10-16T16:54:11.785Z", "object": "order" }, "campaign": { "id": "camp_ID", "name": "Autumn-2025", "campaign_type": "DISCOUNT_COUPONS", "type": "STANDALONE", "is_referral_code": false, "voucher": { "type": "DISCOUNT_VOUCHER", "discount": { "type": "AMOUNT", "amount_off": 100, "units": null, "effect": "APPLY_TO_ITEMS" }, "redemption": { "quantity": null, "redeemed_quantity": 0 }, "code_config": { "pattern": "########", "length": 8, "charset": "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ", "prefix": "", "postfix": "", "min_desired": 1 } }, "auto_join": false, "join_once": false, "active": true, "category_id": null, "category": null, "metadata": {}, "start_date": null, "expiration_date": null, "description": null, "created_at": "2025-10-14T08:45:08.857Z", "updated_at": "2025-10-16T16:51:09.275Z", "object": "campaign" }, "voucher": { "id": "v_ID", "code": "kUs7oM-cOD3", "discount": { "type": "AMOUNT", "amount_off": 100, "effect": "APPLY_TO_ITEMS" }, "type": "DISCOUNT_VOUCHER", "campaign": "Autumn-2025", "campaign_id": "camp_ID", "is_referral_code": false, "holder_id": "cust_ID", "category_id": null, "active": true, "created_at": "2025-10-16T16:02:41.255Z", "updated_at": "2025-10-16T16:54:11.804Z", "redemption": { "quantity": null, "redeemed_quantity": 1 }, "start_date": null, "expiration_date": null, "metadata": {}, "object": "voucher" }, "holder": { "id": "cust_ID", "name": "Alex Doe", "email": "alex.doe@doe.alex.io", "source_id": "4lx-d03", "metadata": { "acquisition_channel": "Website" }, "object": "customer" }, "promotion_tier": null, "promotion_stack": null, "redemption": { "id": "r_ID", "customer_id": "cust_ID", "tracking_id": "track_ID", "date": "2025-10-16T16:54:11.816Z", "order": { "id": "ord_ID", "source_id": null, "status": "PAID", "customer_id": "cust_ID", "referrer_id": null, "amount": 4198, "applied_discount_amount": 0, "total_applied_discount_amount": 0, "total_amount": 4198, "items": [ { "id": "ordli_IDD", "object": "order_item", "product_id": "prod_IDD", "quantity": 1, "amount": 199, "price": 199, "subtotal_amount": 199 }, { "id": "ordli_ID", "object": "order_item", "product_id": "prod_ID", "quantity": 1, "amount": 3999, "price": 3999, "subtotal_amount": 3999 } ], "metadata": {}, "created_at": "2025-10-16T16:54:11.785Z", "object": "order" }, "customer": { "id": "cust_ID", "name": "Alex Doe", "email": "alex.doe@doe.alex.io", "source_id": "4lx-d03", "metadata": { "acquisition_channel": "Website" }, "object": "customer" }, "result": "SUCCESS", "status": "SUCCEEDED", "voucher": { "id": "v_ID", "code": "kUs7oM-cOD3", "discount": { "type": "AMOUNT", "amount_off": 100, "effect": "APPLY_TO_ITEMS" }, "type": "DISCOUNT_VOUCHER", "campaign": "Autumn-2025", "campaign_id": "camp_ID", "is_referral_code": false, "holder_id": "cust_ID", "category_id": null, "active": true, "created_at": "2025-10-16T16:02:41.255Z", "updated_at": "2025-10-16T16:54:11.804Z", "redemption": { "quantity": null, "redeemed_quantity": 1 }, "start_date": null, "expiration_date": null, "metadata": {}, "object": "voucher" }, "metadata": {}, "channel": { "channel_id": "user_ID", "channel_type": "USER" }, "object": "redemption" } }, "source": { "id": "distr_ID", "object": "distribution", "target_url": "https://your.website.io" }, "event": { "id": "evcus_115d38459e5318ae94", "type": "customer.redemption.succeeded", "created_at": "2025-10-16T16:54:11.816Z", "entity_id": "cust_ID", "group_id": "v-115d384583cfba443b", "event_source": { "channel": "USER_PORTAL", "user": { "id": "user_ID" } } } } ``` # Manual Distribution Schedule Source: https://docs.voucherify.io/api-reference/distribution/manual-distribution-schedule openapi-events/events-distribution.json webhook EVENTS.DISTRIBUTION.MANUAL_DISTRIBUTION_SCHEDULE The `MANUAL_DISTRIBUTION_SCHEDULE` event indicates that the distribution is a result of a scheduled distribution. When the event is used in a "Manual message" distribution webhook, the `data` object always contains the following required objects: * `distribution`. Additional objects are also sent depending on the purpose: * "Notify customers about promotion" sends also the following objects: * `campaign`, * `customer`, * `promotion_tier`, * "Send and publish unique codes from campaign" sends also the following objects: * `campaign`, * `voucher`, * `customer`, * `publication`, * "Send plain message to customers" is unavailable for this distribution webhook. This event is used in a webhook configured in Distributions in Voucherify dashboard. This page documents only the event. If you need more details about the webhook payload data that includes this event, go to [Introduction to webhooks](/api-reference/introduction-to-webhooks "Introduction to webhooks v2024-01-01") page. # Activate earning rule Source: https://docs.voucherify.io/api-reference/earning-rules/activate-earning-rule /openapi/loyalties-v2.json post /v2/loyalties/earning-rules/{earningRuleId}/activate Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Moves the earning rule to `ACTIVE` status. No request body. Allowed transitions: `DRAFT -> ACTIVE`, `INACTIVE -> ACTIVE`. Invalid transitions are rejected with a conflict error. # Create earning rule Source: https://docs.voucherify.io/api-reference/earning-rules/create-earning-rule /openapi/loyalties-v2.json post /v2/loyalties/earning-rules Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Creates a new earning rule. When `status` is omitted the rule is created as `DRAFT`. When `validity_hours` is omitted it defaults to `{ "type": "ANY_TIME" }`. When `trigger_limits` is omitted it defaults to `{ "cooldown": { "type": "NO_COOLDOWN" }, "frequency": { "type": "NO_LIMIT" } }`. # Deactivate earning rule Source: https://docs.voucherify.io/api-reference/earning-rules/deactivate-earning-rule /openapi/loyalties-v2.json post /v2/loyalties/earning-rules/{earningRuleId}/deactivate Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Moves the earning rule to `INACTIVE` status. No request body. Allowed transition: `ACTIVE -> INACTIVE`. Invalid transitions are rejected with a conflict error. # Delete earning rule Source: https://docs.voucherify.io/api-reference/earning-rules/delete-earning-rule /openapi/loyalties-v2.json delete /v2/loyalties/earning-rules/{earningRuleId} Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Soft-deletes an earning rule and returns its last state. # Get earning rule Source: https://docs.voucherify.io/api-reference/earning-rules/get-earning-rule /openapi/loyalties-v2.json get /v2/loyalties/earning-rules/{earningRuleId} Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Returns a single earning rule by its ID. # List earning rule activities Source: https://docs.voucherify.io/api-reference/earning-rules/list-earning-rule-activities /openapi/loyalties-v2.json get /v2/loyalties/earning-rules/{earningRuleId}/activities Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Returns a cursor-paginated list of activities (audit trail) for a single earning rule. The same field cannot be used in both ascending and descending order at once. Default order is `-created_at`. # List earning rules Source: https://docs.voucherify.io/api-reference/earning-rules/list-earning-rules /openapi/loyalties-v2.json get /v2/loyalties/earning-rules Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Returns a cursor-paginated list of earning rules. The same field cannot be used in both ascending and descending order at once (e.g. `order=name&order=-name` is rejected). Default order is `-created_at`; `id` is always appended as a tie-breaker. # Move earning rule to draft Source: https://docs.voucherify.io/api-reference/earning-rules/move-earning-rule-to-draft /openapi/loyalties-v2.json post /v2/loyalties/earning-rules/{earningRuleId}/draft Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Moves the earning rule back to `DRAFT` status. No request body. Allowed transition: `ACTIVE -> DRAFT`. Invalid transitions are rejected with a conflict error. # Update earning rule Source: https://docs.voucherify.io/api-reference/earning-rules/update-earning-rule /openapi/loyalties-v2.json put /v2/loyalties/earning-rules/{earningRuleId} Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Updates an earning rule. All properties are optional; `status` cannot be changed through this endpoint (use the activate/deactivate/draft endpoints). For rules that are not in `DRAFT` status, only the following properties may effectively change: name, earnings, error, validity_hours, start_date, end_date, trigger_limits, metadata. Earnings items may carry an `id` (`lernei_...`) to update an existing earning item; items without an `id` are created. # Errors Source: https://docs.voucherify.io/api-reference/errors Learn about the errors returned to responses and how you can customize them to improve your customer experience The Voucherify API uses conventional HTTP status codes to indicate success or failure. Responses with a status code starting with 4xx or 5xx can be considered as failed. The API returns errors in a JSON format in the following structure: ```json Error structure theme={null} { "code": 405, "message": "HTTP Method Not Allowed", "details": "PUT is not supported by this endpoint. Did you mean GET or POST?" } ``` **Developer-friendly API** Voucherify attempts to provide a developer-friendly API, hence sometimes you can find a hint on how to fix an error right in its details (like in the example above). | Attributes | Description | | ---------- | ------------------------------------------------------------------------------------------------------------------------ | | `code` | The HTTP status code of error returned. Possible values are variants of: `2xx`, `4xx`, or `5xx`. | | `key` | For API object errors, a short string from the list on the right hand side, describing the kind of error which occurred. | | `message` | A human-readable message providing a short description about the error. | | `details` | A human-readable message providing more details about the error. | ## HTTP status code summary | HTTP Status Code | Text | Description | | ---------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 400 | Bad Request | The request was invalid. It may occur for various reasons - a malformed JSON or a violated rule (e.g. an attempt to redeem an expired voucher). | | 401 | Unauthorized | Authentication has failed or has not been provided yet. | | 402 | Payment Required | The request exceeded your current pricing plan (we send friendly reminders first). | | 404 | Not Found | The requested resource could not be found. | | 405 | Method Not Allowed | The request used a method (GET, POST, etc.) that is not available for a given resource. Error details include a hint on which methods are allowed. | | 406 | Not Acceptable | The API is unable to produce a response in a format specified by the `Accept` header. In most cases the only available response format is `application/json`. | | 409 | Duplicated resource found | A resource with similar parameters has been found, so the request couldn't be processed. For example, a request was sent to create a voucher with a name that was already in use. | | 415 | Unsupported Media Type | The API is unable to consume a request in a format specified by the `Content-Type` header. | | 423 | Locked | The resource exists, but its current state blocks the operation. Loyalty v2 examples include an inactive program (`non_active_program`) or a loyalty card with zero balance (`zero_card_balance`). | | 429 | API limit reached | Error occurs when you exceed your limit of API calls or when your subscription plan has ended. | | 500 | Internal Server Error | An internal API error occurred. Don't worry, we track and verify all such errors and try to react as asap as possible. | ## Error messages The table below shows a list of errors that may be returned along with a brief description of the reason why it occurs. **Customize Error Messages** A subset of the messages returned for the errors listed below can be customized in the UI. Go to **Project Settings** > Error Messages to customize an error message. Then click on *Create new translations group* to create specific error messages. [Read more here](/manage/project-settings#error-messages). | **Error** | **Reason** | | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `already_rolled_back` | redemption was rolled back before the current operation start time | | `customer_rules_violated` | customer did not match to the segment | | `duplicate_found` | resource with the same identifier was found | | `duplicate_resource_key` | resource identifier is in use | | `gift_amount_exceeded` | gift amount has been exceeded | | `invalid_add_balance_params` | balance object was specified incorrectly | | `invalid_amount` | order amount was specified incorrectly | | `invalid_campaign_params` | campaign object was specified incorrectly | | `invalid_code_config` | voucher code configuration object was specified incorrectly | | `invalid_customer` | customer object was specified incorrectly | | `invalid_export_params` | export object was specified incorrectly | | `invalid_gift` | gift object was specified incorrectly | | `invalid_order` | order object was specified incorrectly | | `invalid_payload` | a request body is invalid and cannot be processed | | `invalid_product` | product object was specified incorrectly | | `invalid_publish_params` | publication object was specified incorrectly | | `invalid_query_params` | input request query parameters are invalid | | `invalid_rollback_params` | redemption rollback object was specified incorrectly | | `invalid_sku` | SKU object was specified incorrectly | | `invalid_validation_rules` | validation rules object was specified incorrectly | | `invalid_voucher` | voucher object was specified incorrectly (e.g., `gift` or `discount` is missing) | | `loyalty_card_points_exceeded` | loyalty card points were exceeded | | `missing_amount` | order amount was not specified | | `missing_customer` | customer was not specified | | `missing_order` | order is missing | | `missing_order_items` | order items were not specified | | `missing_order_items_amount` | missing order item's amount(s) | | `missing_reward` | reward is missing | | `member_already_exists` | the customer is already a member of the loyalty v2 program | | `multiple_requests` | multiple requests detected; i.e. when a redemption is in progress and a session lock is in place, then an attempt to validate the voucher will result in this error because it is unknown whether the voucher can or cannot be used | | `non_active_program` | the loyalty v2 program is not in `ACTIVE` status for an operation that requires an active program | | `zero_card_balance` | the loyalty card has no points available for a spend operation such as pay with points | | `no_voucher_suitable_for_publication` | lack of vouchers suitable for publication | | `not_found` | resource with given ID/code does not exist | | `order_rules_violated` | order did not match validation rules | | `promotion_inactive` | promotion is inactive | | `promotion_not_active_now` | promotion is not active in the given time frame | | `quantity_exceeded` | voucher's redemptions limit has been exceeded | | `query_too_large` | request body payload too large or query string too large | | `redemption_rules_violated` | the redemption did not match validation rules | | `referrer_not_permitted_to_redeem` | the referral code is being redeemed by the referrer | | `resource_not_found` | voucher with given code does not exist | | `voucher_disabled` | voucher has been disabled (active: false) | | `voucher_expired` | voucher has already expired (after expiration date) | | `voucher_not_active` | voucher is not active yet (before start date) | | `voucher_not_active_now` | voucher is not active in the given time frame | ## Custom error messages with Validation Rules Voucherify allows you to define your custom error message per Validation Rule; such message is going to be returned in API Response when validation or redemption of your promotion campaign or code fails due to not meeting requirements of that rule. Additionally, you can specify a fallback error message that should be used when there is no error message defined for the rule. You can define your custom error message both from the API or your Dashboard. The content of custom error message is going to be returned in `error` object under `message` property. If you do not specify any error message for your Validation Rule then `error` property will not be included in the API response. ### Example Let's assume that you create a new Validation Rule via API and would like to have a custom error message "You can't get a discount because you are not new customer" returned from API. The second condition says that your customer who is validating a voucher is not a new one (for that, we are going to use a segment represented by ID: `seg_n3vVcU5t0m3rs4rEPr3C1oU5`). Additionally, you wish that the customer cart must contain an iPhone (`prod_f1r5Tpr0DuC7` is our iPhone), and if not, then a fallback error message should be used: "You must buy iPhone and be our new customer to get a discount." Let's examine how a request for creating such Validation Rule would look like, later we are also going to explore in details how API response is going to look: ```json Example theme={null} { "name": "My validation rule", "error": { "message": "You must buy IPhone and be our new customer in order to get a discount" }, "rules": { "1": { "name": "customer.segment", "conditions": { "$is": ["seg_n3vVcU5t0m3rs4rEPr3C1oU5"] }, "error": { "message": "You can't get discount because you are not a new customer" }, "rules": {} }, "2": { "name": "product.id", "conditions": { "$is": [{ "id": "prod_f1r5Tpr0DuC7" }] }, "rules": {} }, "logic": "1 AND 2" } } ``` As you can see in request body above, there is an `error` property defined at the top level which is going to serve as a fallback. There is also an `error` message set per rule which is going to be returned in the API response when validation / redemption fail due to that specific rule. Let's see below how the API Response is going to look in different scenarios with validation voucher: **Provided required iPhone in order but the customer does not belong to required segment:** ```json Error example 1 theme={null} { "code": "MY-TEST-CODE", "valid": false, "reason": "customer does not match segment rules", "tracking_id": "track_BRR0eIl/xcEftRmZCj65AQ==", "metadata": {}, "error": { "message": "You can't get discount because you are not a new customer" } } ``` **Provided customer belongs to required segment, but the iPhone was not specified in the order:** ```json Error example 2 theme={null} { "code": "MY-TEST-CODE", "valid": false, "reason": "order does not match validation rules", "tracking_id": "track_BRR0eIl/xcFGi+qDwBt2E8W3LQP5W8Np", "metadata": {}, "error": { "message": "You must buy IPhone and be our new customer in order to get a discount" } } ``` **Passing both checks - providing customer who belongs to the required segment and items list with iPhone:** ```json Valid theme={null} { "code": "MY-TEST-CODE", "valid": true, "discount": { "type": "AMOUNT", "amount_off": 10000 }, "order": { "object": "order", "items": [ { "object": "order_item", "product_id": "prod_f1r5Tpr0DuC7", "quantity": 1 } ] }, "tracking_id": "track_BRR0eIl/xcFGi+qDwBt2E8W3LQP5W8Np", "metadata": {} } ``` # Event Object Source: https://docs.voucherify.io/api-reference/events/event-object

Events Create Request Body

Attributes Description

event
string

Event name. This is the same name that you used to define a custom event in the Dashboard > Project Settings > Event Schema.

customer

Customer's information.

Customer

referral
object

If a conversion event for a referral program is set to a custom event, then you need to send the referral code in the payload to make a record of the conversion event.

Attributes Description

code
string

A code through which a new visitor has been referred to a service.

referrer\_id
string

Unique ID of the referring person - it is optional and not required if the referral code is provided.

Example: cust\_Vzck5i8U3OhcEUFY6MKhN9Rv

loyalty
object

If an earning rule in a loyalty program is based on a custom event. This objects let's you specify the loyalty card to which the custom event should be attributed to.

Attributes Description

code
string

Code of the loyalty card to receive points based on the calculation method defined in the related earning rule. An earning rule is triggered for the loyalty card when the event passed in the event parameter of the request payload gets sent along with this loyalty card code.

Example: L-CARD-BUHuH6g

metadata
object

The metadata object stores all custom attributes assigned to the event. A set of key/value pairs that you can attach to an event object. It can be useful for storing additional information about the event in a structured format. Event metadata schema is defined in the Dashboard > Project Settings > Event Schema > Edit particular event > Metadata property definition.

Customer

All of:

Customer Id And Source Id

Attributes	Description
id `string`	The ID of an existing customer.
source\_id `string`	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.

Customer Base

Customer Base

Attributes Description

name
string

Customer's first and last name.

description
string

An arbitrary string that you can attach to a customer object.

email
string

Customer's email address.

phone
string

Customer's phone number. This parameter is mandatory when you try to send out codes to customers via an SMS channel.

birthday
string

Deprecated. ~~Customer's birthdate; format YYYY-MM-DD~~.

birthdate
string

Customer's birthdate; format YYYY-MM-DD.

address
object, null

Customer's address.

Attributes	Description
city `string`	City
state `string`	State
line\_1 `string`	First line of address.
line\_2 `string`	Second line of address.
country `string`	Country.
postal\_code `string`	Postal code.

metadata
object

# Track Custom Event Source: https://docs.voucherify.io/api-reference/events/track-custom-event /openapi/events.json post /v1/events To track a custom event, you create an event object. The event object must be linked to the customer who performs the action. If a customer doesn't exist in Voucherify, the customer will be created. # Examine earning rules Source: https://docs.voucherify.io/api-reference/examine/examine-earning-rules /openapi/loyalties-v2.json post /v2/loyalties/examine/earning-rules Estimates earning opportunities for a customer without triggering any actual earning for loyalty v2 earning rules. The `trigger` selects whether all trigger events or one specific event is examined. When a specific event is selected, exactly one matching context object is required: `customer_order_paid` for `customer.order.paid`, `customer_segment_entered` for `customer.segment.entered`, and `customer_custom_event` for `customer.custom_event`. The other context objects must not be present. This endpoint can examine earning rules for all loyalty programs the customer belongs to by using `customer_identification` with `customer_id` or `customer_source_id`. To examine earning rules only for one program, use `member_id` in `customer_identification`, as `member_id` is loyalty program-specific. # Examine rewards Source: https://docs.voucherify.io/api-reference/examine/examine-rewards /openapi/loyalties-v2.json post /v2/loyalties/examine/rewards Evaluates rewards assigned to a customer's active Loyalty v2 program memberships. Applies temporary customer and member metadata overrides without updating stored data. Returns reward availability by card, including points costs and applicable unavailability reasons. This endpoint can examine rewards for all loyalty programs the customer belongs to by using `customer_identification` with `customer_id` or `source_id`. To examine rewards only for one program, use `member_id` in `customer_identification`, as `member_id` is loyalty program-specific. # Create Export Source: https://docs.voucherify.io/api-reference/exports/create-export /openapi/exports.json post /v1/exports Create export object. The export can be any of the following types: `voucher`, `redemption`, `publication`, `customer`, `order`, `points_expiration`, `voucher_transactions`, `product`, or `sku`. ## Defaults If you only specify the object type in the request body without specifying the fields, the API will return the following fields per export object: | **Export Object** | **Default fields returned** | |:---|:---| | order | `id`, `source_id`, `status` | | voucher | `code`, `voucher_type`, `value`, `discount_type` | | publication | `code`, `customer_id`, `date`, `channel` | | redemption | `id`, `object`, `voucher_code`, `customer_id`, `date`, `result` | | customer | `name`, `source_id` | | points_expiration | `id`, `campaign_id`, `voucher_id`, `status`, `expires_at`, `points` | | voucher_transactions | `id`, `type`, `source_id`, `status`, `reason`, `source`, `balance`, `amount`, `created_at` | | products | `id`, `name`, `price`, `image_url`, `source_id`, `attributes`, `created_at`| | SKU | `id`, `sku`, `product_id`, `currency`, `price`, `image_url`, `source_id`, `attributes`, `created_at`| Date and time in the export API The exported date and times are always provided in the UTC time zone. ## Fetching particular data sets Using the `parameters` body parameter, you can narrow down which fields to export and how to filter the results. The fields are an array of strings containing the data that you would like to export. These fields define the headers in the CSV file. The array can be a combination of any of the following available fields: ## Orders | **Field** | **Definition** | **Example Export** | |:---|:---|:---| | id | Unique order ID. | ord_A69RIxEdRsPuC6i8gFGVHUft | | source_id | Unique order source ID. | 8638 | | created_at | Timestamp in ISO 8601 format representing the date and time when the order was created. | 2022-03-09T09:16:32.521Z | | updated_at | Timestamp in ISO 8601 format representing the date and time when the order was last updated. | 2022-03-09T09:16:33.331Z | | status | Order status. | `PAID`, `CREATED`, `FULFILLED`, `CANCELED` | | amount | Total amount of order items. | 7700 | | discount_amount | Represents total amount of the discount applied to whole cart. | 500 | | items_discount_amount | Represents total amount of the discount applied to order line items. | 100 | | total_discount_amount | All discounts applied to the order including discounts applied to particular order line items and discounts applied to the whole cart. | 600 | | total_amount | Total order amount after applying all discounts. | 7100 | | customer_id | Customer unique ID. | cust_2G4fUQdCXUqp35nXNleav7bO | | referrer_id | Referrer unique ID. | cust_IkrTR674vvQvr9a4rDMiqglY | | metadata | Order metadata; expressed as metadata.X, where X is the name of the custom metadata property. | 1 | ## Vouchers | **Field** | **Definition** | **Example Export** | |:---|:---|:---| | id | Unique voucher ID. | v_HSnGD2vNIHYighTQxwcB4dtVAv8VOmZD | | code | Unique voucher code. | WELCOME100 | | voucher_type | Type of voucher. | `DISCOUNT_VOUCHER`, `GIFT_VOUCHER`, `LOYALTY_CARD` | | value | Value of voucher. | `DISCOUNT_VOUCHER` : amount, percent, unit
`GIFT_VOUCHER`: amount left to spend
`LOYALTY_CARD`: available usable points | | discount_type | The type of discount for a `DISCOUNT_VOUCHER`. | `AMOUNT`, `PERCENT`, `UNIT`, `FIXED` | | campaign | Unique campaign name. | Summer Discounts 20% off | | category | Tag defining the category that this voucher belongs to. | | | start_date | Start date defines when the code starts to be active. Activation timestamp is presented in the ISO 8601 format. Voucher is _inactive_ before this date. | 2020-12-10T23:00:00.000Z | | expiration_date | Expiration date defines when the code expires. Expiration timestamp is presented in the ISO 8601 format. Voucher is _inactive_ after this date. | 2023-12-31T23:00:00.000Z | | gift_balance | Amount left to spend. | 1000 | | loyalty_balance | Available usable points. | 2000 | | redemption_quantity | Maximum number of times a voucher can be redeemed. | 2 | | redemption_count | Total redemptions. | 59 | | active | Boolean indicating whether the voucher is available for use. | `true`, `false` | | qr_code | URL to QR representation of encrypted code. | | | bar_code | URL to barcode representation of encrypted code. | | | metadata | Custom voucher metadata. | | | is_referral_code | Boolean indicating whether the voucher is a referral code. | `true`, `false` | | created_at | Timestamp in ISO 8601 format representing the date and time when the voucher was created. | 2022-04-14T09:55:46.814Z | | updated_at | Timestamp in ISO 8601 format representing the date and time when the voucher was last updated. | 2022-04-14T10:02:18.036Z | | validity_timeframe_interval | Defines the intervening time between two time points in ISO 8601 format, expressed as a duration. For example, a voucher with an interval of `P2D` will be active every other day. | P2D | | validity_timeframe_duration | Defines the amount of time the voucher will be active in ISO 8601 format. For example, a voucher with a duration of `PT1H` will be valid for a duration of one hour. | PT1H | | validity_day_of_week | Array corresponding to the particular days of the week in which the voucher is valid. | "1,2,3,4,5" | | discount_amount_limit | For `PERCENT` discount type, this is the maximum threshold allowed to be deducted. | 50 | | campaign_id | Parent campaign ID. | camp_7s3uXI44aKfIk5IhmeOPr6ic | | additional_info | An optional field to keep any extra textual information about the code such as a code description and details. | | | customer_id | Unique customer ID of the assigned owner to whom the voucher was published. | cust_7iUa6ICKyU6gH40dBU25kQU1 | | discount_unit_type | For `UNIT` discount type, either a shipping or product ID for a `UNIT` discount with one product. | prod_5h1pp1ng, prod_0a9f9aeddb019a42db | | discount_unit_effect | `UNIT` discount effect. | `ADD_MANY_ITEMS`, `ADD_MISSING_ITEMS`,`ADD_NEW_ITEMS` | | customer_source_id | Unique customer source id of the assigned owner to whom the voucher was published. | name.lastname@email.com | ## Publications | **Field** | **Definition** | **Example Export** | |:---|:---|:---| | voucher_code | Unique voucher code. | WELCOME100 | | customer_id | Customer unique ID. | cust_7iUa6ICKyU6gH40dBU25kQU1 | | customer_source_id | Unique customer source id of the assigned owner to whom the voucher was published. | name.lastname@email.com | | date | Timestamp in ISO 8601 format representing the date and time when the voucher was published. | 2022-04-28T10:19:30.792Z | | channel | Publication channel. | voucherify-website | | campaign | Unique campaign name. | Summer Discounts 20% off | | is_winner | | | | metadata | Custom publication metadata. | | ## Redemptions | **Field** | **Definition** | **Example Export** | |:---|:---|:---| | id | Unique redemption ID. | r_0acf3a6dae00e679c8, rf_0acf3a495740e679b8 | | object | Object being exported; by default `redemption`. | redemption | | date | Timestamp in ISO 8601 format representing the date and time when the voucher was redeemed. | 2022-03-23T08:52:24.867Z | | voucher_code | Unique voucher code redeemed. | WELCOME100 | | campaign | Parent campaign name of voucher if applicable. | Summer Discounts 20% off | | promotion_tier_id | | promo_Mwy9XpA0TLctSGriM5kum0qp | | customer_id | Unique customer ID of redeeming customer. | cust_nk0N1uNQ1YnupAoJGOgvsODC | | customer_source_id | Unique source ID of redeeming customer. | name.lastname@email.com | | customer_name | Customer name. | John Smith | | tracking_id | | track_Pw6r3ejnml43kIwNS4Zj09KZ67xOfLUy | | order_amount | Total order amount before applying all discounts. | 1000 | | gift_amount | Gift credits used for redemption. | 10 | | loyalty_points | | 12 | | result | Tells you whether the redemption succeeded. | `SUCCESS`, `FAILURE` | | failure_code | Internal Voucherify code for reason why redemption failed. | invalid_customer | | failure_message | A human-readable message providing a short description explaining why the redemption failed. | Customer must be a holder of a loyalty card. | | metadata | Custom redemption metadata. | | ## Customers | **Field** | **Definition** | **Example Export** | |:---|:---|:---| | name | Customer name. | John Smith | | id | Unique customer ID. | cust_J1CDUdbqn5Exva8ASWk1Fq0j | | description | An arbitrary string that you can attach to a customer object. | Customer requesting to be added to VIP tier. | | email | Customer's email. | name.lastname@email.com | | source_id | Unique custom customer identifier. | name.lastname@email.com | | created_at | Timestamp in ISO 8601 format representing the date and time when the customer was created. | 2022-02-03T13:10:11.928Z | | address_city | City | Houston | | address_state | State | TX | | address_line_1 | First line of customer's address. | 72738 Main St | | address_line_2 | Second line of customer's address. | Bld 2, Apt 4 | | address_country | Country | United States of America | | address_postal_code | Postal code (ZIP code) | 77042-4143 | | redemptions_total_redeemed | Total customer redemptions. | 5 | | redemptions_total_failed | Total customer failed redemptions. | 2 | | redemptions_total_succeeded | Total customer succeeded redemptions. | 3 | | redemptions_total_rolled_back | Total customer redemptions that were rolled back. | 3 | | redemptions_total_rollback_failed | Total customer redemptions that were unsuccessfully rolled back. | 2 | | redemptions_total_rollback_succeeded | Total customer redemptions that were successfully rolled back. | 1 | | orders_total_amount | Total sum of order amounts over customer lifetime. Value is multiplied by 100 to precisely represent 2 decimal places. | 10000 (represents $100) | | orders_total_count | Total number of customer orders. | 2 | | orders_average_amount | Average amount spent on orders. Value is multiplied by 100 to precisely represent 2 decimal places. | 5000 (represents $50) | | orders_last_order_amount | How much did the customer spend on their last order. Value is multiplied by 100 to precisely represent 2 decimal places. | 5000 (represents $50) | | orders_last_order_date | When was the last customer order; timestamp in ISO 8601 format representing the date and time. | 2022-02-03T13:17:30.630Z | | loyalty_points | Sum of customer's loyalty points to go across all loyalty cards. | 2000 | | loyalty_referred_customers | How many customers were referred by this customer. | 3 | | updated_at | Timestamp in ISO 8601 format representing the date and time when the customer was updated. | 2022-02-14T14:10:14.305Z | | phone | Customer's phone number. | +1 (294) 752-1846 | | birthday | `Deprecated`. ~~Customer's birthday~~. | 2022-01-01 | | metadata | Customer metadata. | All metadata fields defined in Metadata Schema for the Customer object. | | birthdate | Customer's birthdate. | 2022-01-01 | ## Points Expirations | **Field** | **Definition** | **Example Export** | |:---|:---|:---| | id | Loyalty points bucket ID. | lopb_Wl1o3EjJIHSNjvO5BDLy4z1n | | campaign_id | Campaign ID of the parent loyalty campaign. | camp_7s3uXI44aKfIk5IhmeOPr6ic | | voucher_id | Voucher ID of the parent loyalty card. | v_YLn0WVWXSXbUfDvxgrgUbtfJ3SQIY655 | | status | Status of the loyalty point bucket. | `ACTIVE` or `EXPIRED` | | expires_at | Timestamp in ISO 8601 format representing the date when the points expire. | 2022-06-30 | | points | Number of points. | 1000 | ## Gift Card Transactions | **Field** | **Definition** | **Example Export** | |:---|:---|:---| | id | Unique transaction ID. | vtx_0cb7811f1c07765800 | | type | Transaction type. | - `CREDITS_REMOVAL`
- `CREDITS_ADDITION`
- `CREDITS_REFUND`
- `CREDITS_REDEMPTION` | | source_id | Unique transaction source ID. | 8638 | | reason | Contains the reason for the transaction if one was included originally. | | | balance | The gift card or loyalty card balance after the transaction. | | | amount | The amount of gift card or loyalty card credits being allocated during the transaction. This value can either be negative or positive depending on the nature of the transaction. | | | created_at | Timestamp in ISO 8601 format representing the date and time when the transaction was created. | 2022-03-09T09:16:32.521Z | | voucher_id | Unique Voucher ID. | v_dky7ksKfPX50Wb2Bxvcoeb1xT20b6tcp | | campaign_id | Parent campaign ID. | camp_FNYR4jhqZBM9xTptxDGgeNBV | | source| Channel through which the transaction was initiated. | API | | details | More detailed information stored in the form of a JSON. | Provides more details related to the transaction in the form of an object. | ## Loyalty Card Transactions | **Field** | **Definition** | **Example Export** | |:---|:---|:---| | id | Unique transaction ID assigned by Voucherify. | vtx_0cb7811f1c07765800 | | type | Transaction type. | - `POINTS_EXPIRATION`
- `POINTS_ADDITION`
- `POINTS_REMOVAL`
- `POINTS_TRANSFER_OUT`
- `POINTS_ACCRUAL`
- `POINTS_REFUND`
- `POINTS_REDEMPTION` | | source_id | Custom source ID of the transaction if one was included originally. | source_id_custom | | reason | Contains the reason for the transaction if one was included originally. | | | balance | The loyalty card balance after the transaction. | | | amount | The amount of loyalty points being allocated during the transaction. This value can either be negative or positive depending on the nature of the transaction. | | | created_at | Timestamp in ISO 8601 format representing the date and time when the transaction was created. | 2022-03-09T09:16:32.521Z | | voucher_id | Unique Voucher ID. | v_dky7ksKfPX50Wb2Bxvcoeb1xT20b6tcp | | campaign_id | Parent campaign ID. | camp_FNYR4jhqZBM9xTptxDGgeNBV | | source| Channel through which the transaction was initiated. | - `API`
- `voucherify-web-ui`
- `Automation` | | details | More detailed information stored in the form of a JSON. | Provides more details related to the transaction in the form of an object. | | related_transaction_id | Unique transaction ID related to a receiver/donor card in the case of a points transfer from/to another card. | vtx_0c9afe802593b34b80 | # Delete Export Source: https://docs.voucherify.io/api-reference/exports/delete-export /openapi/exports.json delete /v1/exports/{exportId} This method deletes a previously created export object. # Download Export Source: https://docs.voucherify.io/api-reference/exports/download-export /openapi/exports.json get /v1/exports/{export_Id} Download the contents of the exported CSV file. Important notes **Base URL:** - `https://download.voucherify.io` (Europe) - `https://us1.download.voucherify.io` (US) - `https://as1.download.voucherify.io` (Asia) **Token:** Can be found within the `result` parameter of the [Get Export](/api-reference/exports/get-export) method response. # Export Object Source: https://docs.voucherify.io/api-reference/exports/export-object

Export

One of:

Export Voucher
Export Redemption
Export Customers
Export Publication
Export Orders
Export Points Expiration
Export Vouchers Transactions

Export Voucher

All of:

Export Base
Export Vouchers

Export Redemption

All of:

Export Base
Export Redemptions

Export Customers

All of:

Export Base
Export Customers

Export Publication

All of:

Export Base
Export Publications

Export Orders

All of:

Export Base
Export Orders

Export Points Expiration

All of:

Export Base
Export Points Expirations

Export Vouchers Transactions

All of:

Export Base
Export Vouchers Transactions

Export Base

Attributes Description

id
string

Unique export ID.

object
string

The type of object being represented. This object stores information about the export.

Available values: export

created\_at
string

Timestamp representing the date and time when the export was scheduled in ISO 8601 format.

status
string

Status of the export. Informs you whether the export has already been completed, i.e. indicates whether the file containing the exported data has been generated.

Available values: SCHEDULED, IN\_PROGRESS, DONE, ERROR

channel
string

The channel through which the export was triggered.

result
object, null

Contains the URL of the CSV file.

Attributes	Description
url `string`	URL of the CSV file location. It contains the token used for authorization in the Download export method.

user\_id
string, null

Identifies the specific user who initiated the export through the Voucherify Dashboard; returned when the channel value is WEBSITE.

Export Vouchers

Attributes Description

exported\_object
string

The type of object to be exported.

Available values: voucher

parameters
object

Attributes	Description
order	How the export is filtered, where the dash - preceding a sorting option means sorting in a descending order. Export Voucher Order
fields `array`	Array of strings containing the data in the export. These fields define the headers in the CSV file. Array of Export Voucher Fields
filters	Filter conditions. Export Voucher Filters
campaign\_id `string`	Unique identifier of the campaign. It is assigned by Voucherify. The campaign ID defines the campaign for which the voucher export will be triggered. Example: camp\_0dJG7cCAjquzcxWmZ634bA0C

Export Redemptions

Attributes Description

exported\_object
string

The type of object to be exported.

Available values: redemption

parameters
object

List of available fields and filters that can be exported with an order along with the sorting order of the returned data.

Attributes	Description
order	How the export is filtered, where the dash - preceding a sorting option means sorting in a descending order. Export Redemption Order
fields `array`	Array of strings containing the data in the export. These fields define the headers in the CSV file. Array of Export Redemption Fields
filters	Filter conditions. Export Redemption Filters

Export Customers

Attributes Description

exported\_object
string

The type of object to be exported.

Available values: customer

parameters
object

List of available fields and filters that can be exported with an order along with the sorting order of the returned data.

Attributes	Description
order	How the export is filtered, where the dash - preceding a sorting option means sorting in a descending order. Export Customer Order
fields `array`	Array of strings containing the data in the export. These fields define the headers in the CSV file. Array of Export Customer Fields
filters	Filter conditions. Export Customer Filters

Export Publications

Attributes Description

exported\_object
string

The type of object to be exported.

Available values: publication

parameters
object

List of available fields and filters that can be exported with an order along with the sorting order of the returned data.

Attributes	Description
order	How the export is filtered, where the dash - preceding a sorting option means sorting in a descending order. Export Publication Order
fields `array`	Array of strings containing the data in the export. These fields define the headers in the CSV file. Array of Export Publication Fields
filters	Filter conditions. Export Publication Filters

Export Orders

Attributes Description

exported\_object
string

The type of object to be exported.

Available values: order

parameters
object

List of available fields and filters that can be exported with an order along with the sorting order of the returned data.

Attributes	Description
order	How the export is filtered, where the dash - preceding a sorting option means sorting in a descending order. Export Order Order
fields `array`	Array of strings containing the data in the export. These fields define the headers in the CSV file. Array of Export Order Fields
filters	Filter conditions. Export Order Filters

Export Points Expirations

Attributes Description

exported\_object
string

The type of object to be exported.

Available values: points\_expiration

parameters
object

List of available fields and filters that can be exported with an order along with the sorting order of the returned data.

Attributes	Description
order	How the export is filtered, where the dash - preceding a sorting option means sorting in a descending order. Export Points Expiration Order
fields `array`	Array of strings containing the data in the export. These fields define the headers in the CSV file. Array of Export Points Expiration Fields
filters	Filter conditions. Export Points Expiration Filters

Export Vouchers Transactions

Attributes Description

exported\_object
string

The type of object to be exported.

Available values: voucher\_transactions

parameters
object

List of available fields and filters that can be exported with an order along with the sorting order of the returned data.

Attributes	Description
order	How the export is filtered, where the dash - preceding a sorting option means sorting in a descending order. Export Voucher Transactions Order
fields `array`	Array of strings containing the data in the export. These fields define the headers in the CSV file. Array of Export Voucher Transactions Fields
filters	Filter conditions. Export Voucher Transactions Filters

Export Voucher Order

Available values: -created\_at, created\_at, -updated\_at, updated\_at, -code, code

Export Voucher Fields

Available values: code, voucher\_type, value, formula, discount\_type, campaign, category, start\_date, expiration\_date, gift\_balance, loyalty\_balance, redemption\_quantity, redemption\_count, active, qr\_code, bar\_code, metadata, id, is\_referral\_code, created\_at, updated\_at, validity\_timeframe\_interval, validity\_timeframe\_duration, validity\_day\_of\_week, discount\_amount\_limit, campaign\_id, additional\_info, customer\_id, discount\_effect, discount\_unit\_type, discount\_unit\_effect, validation\_rules\_id, customer\_source\_id

Export Voucher Filters

Attributes	Description
junction	Filter by conditions set on the junction parameter indicating how the conditions should be accounted for in the query. An AND is an all-inclusive logical operator, meaning the AND operator displays a record if ALL the conditions separated by AND are TRUE, while an OR operator displays a record if ANY of the conditions separated by OR is TRUE. Junction
created\_at	See: Field Conditions
updated\_at	See: Field Conditions
created\_date	See: Field Conditions
active	See: Field Conditions
redemption\_status	See: Field Conditions
start\_date	See: Field Conditions
expiration\_date	See: Field Conditions
validity\_day\_of\_week	See: Field Conditions
code	See: Field Conditions
categories	See: Field Conditions
vouchers	See: Field Conditions
holder\_id	See: Field Conditions
is\_referral\_code	See: Field Conditions
published\_for\_customer\_id	See: Field Conditions
validity\_timeframe	See: Field Conditions
category\_ids	See: Field Conditions
\[propertyName]	See: Field Conditions

Export Redemption Order

Available values: -id, id, -voucher\_code, voucher\_code, -tracking\_id, tracking\_id, -customer\_id, customer\_id, -created\_at, created\_at

Export Redemption Fields

Available values: id, object, date, voucher\_code, campaign, promotion\_tier\_id, customer\_id, customer\_source\_id, customer\_name, tracking\_id, order\_id, order\_amount, gift\_amount, loyalty\_points, result, failure\_code, failure\_message, metadata

Export Redemption Filters

Attributes Description

junction

See: Junction

created\_at
object

Attributes Description

conditions
object

Filters Condition

Attributes	Description
\$after	See: Any
\$before	See: Any

campaign
object

Attributes Description

conditions
object

Filters Condition

Attributes	Description
\$is	See: Any

customer
object

Attributes Description

conditions
object

Filters Condition

Attributes	Description
\$is	See: Any

voucher
object

Attributes Description

conditions
object

Filters Condition

Attributes	Description
\$is	See: Any

related\_object
object

Attributes Description

conditions
object

Filters Condition

Attributes	Description
\$in	See: Any

voucher\_code

See: Field Conditions

related\_object\_id

See: Field Conditions

related\_object\_parent\_id

See: Field Conditions

parent\_redemption\_id

See: Field Conditions

failure\_code

See: Field Conditions

result

See: Field Conditions

object

See: Field Conditions

customer\_id

See: Field Conditions

campaign\_name

See: Field Conditions

user\_login

See: Field Conditions

status

See: Field Conditions

\[propertyName]

See: Field Conditions

Export Customer Order

Available values: -name, name, -id, id, -email, email, -source\_id, source\_id, -created\_at, created\_at, -updated\_at, updated\_at

Export Customer Fields

Available values: name, id, description, email, source\_id, created\_at, address\_city, address\_state, address\_line\_1, address\_line\_2, address\_country, address\_postal\_code, redemptions\_total\_redeemed, redemptions\_total\_failed, redemptions\_total\_succeeded, redemptions\_total\_rolled\_back, redemptions\_total\_rollback\_failed, redemptions\_total\_rollback\_succeeded, orders\_total\_amount, orders\_total\_count, orders\_average\_amount, orders\_last\_order\_amount, orders\_last\_order\_date, loyalty\_points, loyalty\_referred\_customers, updated\_at, phone, birthday, metadata, birthdate

Export Customer Filters

Attributes Description

junction

See: Junction

created\_at
object

Attributes Description

conditions
object

Filters Condition

Attributes	Description
\$after	See: Any
\$before	See: Any

updated\_at
object

Attributes Description

conditions
object

Filters Condition

Attributes	Description
\$after `array`
\$before `array`
\$is `array`

See: Field Conditions

name

See: Field Conditions

city
object

Attributes Description

conditions
object

Filters Condition

Attributes	Description
\$is	See: Any

phone

See: Field Conditions

birthday

See: Field Conditions

source\_id

See: Field Conditions

publications.created\_at

See: Field Conditions

publications.related\_object\_id

See: Field Conditions

\[propertyName]

See: Field Conditions

Export Publication Order

Available values: -id, id, -voucher\_code, voucher\_code, -tracking\_id, tracking\_id, -customer\_id, customer\_id, -created\_at, created\_at, -channel, channel

Export Publication Fields

Available values: voucher\_code, customer\_id, customer\_source\_id, date, channel, campaign, is\_winner, metadata

Export Publication Filters

Attributes Description

junction

See: Junction

created\_at
object

Attributes Description

conditions
object

Filters Condition

Attributes	Description
\$after	See: Any
\$before	See: Any

campaign
object

Attributes Description

conditions
object

Filters Condition

Attributes	Description
\$is	See: Any

customer
object

Attributes Description

conditions
object

Filters Condition

Attributes	Description
\$is	See: Any

voucher
object

Attributes Description

conditions
object

Filters Condition

Attributes	Description
\$is	See: Any

failure\_code

See: Field Conditions

result

See: Field Conditions

customer\_id

See: Field Conditions

campaign\_name

See: Field Conditions

voucher\_type

See: Field Conditions

is\_referral\_code

See: Field Conditions

parent\_object\_id

See: Field Conditions

related\_object\_id

See: Field Conditions

source\_id

See: Field Conditions

\[propertyName]

See: Field Conditions

Export Order Order

Available values: -created\_at, created\_at, -updated\_at, updated\_at, -status, status

Export Order Fields

Available values: id, source\_id, created\_at, updated\_at, status, amount, discount\_amount, items\_discount\_amount, total\_discount\_amount, total\_amount, customer\_id, referrer\_id, metadata

Export Order Filters

Attributes Description

junction

See: Junction

created\_at
object

Attributes Description

conditions
object

Filters Condition

Attributes	Description
\$after	See: Any
\$before	See: Any

updated\_at
object

Attributes Description

conditions
object

Filters Condition

Attributes	Description
\$after	See: Any
\$before	See: Any

status

See: Field Conditions

source\_id

See: Field Conditions

amount

See: Field Conditions

total\_amount

See: Field Conditions

discount\_amount

See: Field Conditions

total\_discount\_amount

See: Field Conditions

items\_discount\_amount

See: Field Conditions

\[propertyName]

See: Field Conditions

Export Points Expiration Order

Available values: -expires\_at, expires\_at

Export Points Expiration Fields

Available values: id, campaign\_id, voucher\_id, points, status, expires\_at

Export Points Expiration Filters

Attributes	Description
junction	See: Junction
campaign\_id	See: Field Conditions
voucher\_id	See: Field Conditions

Export Voucher Transactions Order

Available values: -created\_at, created\_at

Export Voucher Transactions Fields

Available values: id, campaign\_id, voucher\_id, type, source\_id, reason, source, balance, amount, related\_transaction\_id, created\_at, details

Export Voucher Transactions Filters

Attributes	Description
junction	See: Junction
created\_at	See: Field Conditions
voucher\_id	See: Field Conditions
campaign\_id	See: Field Conditions

Junction

Logical Operator Between Filters. Filter by conditions set on the junction parameter indicating how the conditions should be accounted for in the query. An AND is an all-inclusive logical operator, meaning the AND operator displays a record if ALL the conditions separated by AND are TRUE, while an OR operator displays a record if ANY of the conditions separated by OR is TRUE.

Available values: and, or

Field Conditions

Attributes	Description
conditions	Data filters used to narrow down the data records to be returned in the result. Filters Condition

Any

Array any of:

string
string
string
number
object

Filters Condition

Attributes	Description
\$in	See: Any
\$not\_in	See: Any
\$is	See: Any
\$is\_days\_ago	See: Any
\$is\_days\_in\_future	See: Any
\$is\_not	See: Any
\$has\_value	See: Any
\$is\_unknown	See: Any
\$contains	See: Any
\$not\_contain	See: Any
\$starts\_with	See: Any
\$ends\_with	See: Any
\$more\_than	See: Any
\$less\_than	See: Any
\$more\_than\_ago	See: Any
\$less\_than\_ago	See: Any
\$more\_than\_future	See: Any
\$less\_than\_future	See: Any
\$more\_than\_equal	See: Any
\$less\_than\_equal	See: Any
\$after	See: Any
\$before	See: Any
\$count	See: Any
\$count\_less	See: Any
\$count\_more	See: Any

# Get Export Source: https://docs.voucherify.io/api-reference/exports/get-export /openapi/exports.json get /v1/exports/{exportId} Retrieves the URL of the downloadable file, which was generated via the [Create Export](/api-reference/exports/create-export) method. # List Exports Source: https://docs.voucherify.io/api-reference/exports/list-exports /openapi/exports.json get /v1/exports List all exports. # Introduction Source: https://docs.voucherify.io/api-reference/introduction-api What is Voucherify API? The Voucherify API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, such as HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application Never expose your secret API key in any public website's client-side code. JSON is returned by all API responses, including errors. However, Voucherify API libraries convert responses to appropriate language-specific objects. To make the API as explorable as possible, this documentation has a test mode. You can test all methods at no cost. Click **Try it** in an endpoint page to open a playground and configure your request. Fields that are necessary in the request are marked as `required`. Fields that will always be returned in the response are also marked as `required`. In general the API consists of 3 sets: * **Application API** - full capability, designed to be accessed from your server application * **Client API** - limited capability, designed to be accessed from your website or mobile application * **Management API** - endpoints designed to manage Voucherify projects within organization. Enterprise feature only - contact [Voucherify sales team](https://www.voucherify.io/contact-sales "Contact Voucherify Sales") for more details. Find out more about how to [authenticate your application](/guides/authentication) to access the API. # Introduction to Voucherify webhooks Source: https://docs.voucherify.io/api-reference/introduction-to-webhooks Use webhooks to get notified about project and distribution events in Voucherify Webhooks in Voucherify are automated messages sent from Voucherify to your application when specific events happen. For example, when a voucher is redeemed, Voucherify can instantly notify your app about it. You set up webhooks by providing a URL (endpoint) in Voucherify, and Voucherify sends event notifications directly to this URL. Voucherify offers two types of webhooks: * [Project-level webhooks](/api-reference/project-settings-webhooks) – triggered by general events across your entire project (like voucher redemption, customer updates, or order events). * [Distribution-based webhooks](/api-reference/distribution-webhooks) – triggered specifically by voucher distribution events (for example, when a voucher is successfully sent or fails to send). You can set up each webhook separately based on your application's needs. ## Voucherify webhook structure The Voucherify webhooks share the same data structure, consisting of the following keys: * `id` * `project_id` * `created_at` * `type` * `data` * `source` * `event` The values for the `type` and `data` depend on the event that triggers the webhook. Go to [Project Setting Webhook Payload](/api-reference/project-settings-webhooks#webhooks-available-in-project-settings) and [Distribution Webhook Payload](/api-reference/distribution-webhooks#webhooks-available-in-distributions) to learn more about their payloads. ## Authentication Once your server is configured to receive payloads, it will listen for any payload sent to the endpoint you configured. For security reasons, you may want to limit requests to those coming from Voucherify. To do so, you should copy a secret token and validate the information. You can generate a secret key in the Project Settings in the Webhooks section. Each webhook sent from Voucherify contains the `x-voucherify-signature` of the webhook in the header field. Then, you can validate the signature by reconstructing it and comparing it to the one sent in the webhook header field. Reconstruct it using the keyed-hash message authentication code HMAC. It is built with the cryptographic hash function **sha256** and the secret cryptographic key taken from the Project settings. You can add optional additional HTTP headers when setting up a webhook distribution. In Additional HTTP headers, you can multiple add key-value pairs for your custom headers. Each header must have a name and a value. The names must be unique. See the following examples for Java and the `verifySignature` method in the [NodeJS SDK](https://github.com/voucherifyio/voucherify-nodejs-sdk/blob/c63f738c5a53ecb9a5006a04d80d612ee70bdeae/src/utils.js#L102). ```java Java theme={null} import java.security.InvalidKeyException; import java.security.NoSuchAlgorithmException; import javax.crypto.Mac; import javax.crypto.spec.SecretKeySpec; import java.nio.charset.StandardCharsets; class HelloWorld { public static void main(String[] args) throws InvalidKeyException, NoSuchAlgorithmException { byte[] secretKey = "secretKey".getBytes(StandardCharsets.UTF_8); // when payload is JSON object - whitespaces must be removed String signature1 = "a17d2ac229d1ebbb5f10e839c7985c4818e5986eab297f7e5979196d4d7d3ed2"; System.out.println(verifySignature(removeWhitespaces("{\n \"a\": 1\n}"), signature1, secretKey)); System.out.println(verifySignature(removeWhitespaces("{\"a\":1}"), signature1, secretKey)); String signature2 = "f7cf97814a03146abedb9793f56e1dec34f618f82d10395310d053f749483ffb"; System.out.println(verifySignature(removeWhitespaces("{\n \"a\\\"b\": 1\n}"), signature2, secretKey)); // when payload is directly a String String signature3 = "53ff92957e1427ce23ad5bda9d0c5f2f4ff384d0806b83eeacb510c842d3a358"; System.out.println(verifySignature(" message ", signature3, secretKey)); } public static String removeWhitespaces(String json) { boolean quoted = false; boolean escaped = false; String out = ""; for (Character c : json.toCharArray()) { if (escaped) { out += c; escaped = false; continue; } if (c == '"') { quoted = !quoted; } else if (c == '\\') { escaped = true; } if (Character.isWhitespace(c) && !quoted) { continue; } out += c; } return out; } public static boolean verifySignature(String payload, String signature, byte[] secretKey) throws InvalidKeyException, NoSuchAlgorithmException { Mac mac = Mac.getInstance("HmacSHA256"); mac.init(new SecretKeySpec(secretKey, "HmacSHA256")); byte[] hash = mac.doFinal(payload.getBytes(StandardCharsets.UTF_8)); String generatedSignature = bytesToHex(hash); return generatedSignature.equals(signature); } private static String bytesToHex(byte[] bytes) { StringBuilder sb = new StringBuilder(bytes.length * 2); for (byte b : bytes) { sb.append(String.format("%02x", b)); } return sb.toString(); } } ``` ```javascript NodeJS theme={null} const crypto = require('crypto') verifySignature: function (signature, message, secretKey) { return crypto.createHmac('sha256', secretKey) .update(isString(message) && message || JSON.stringify(message)) .digest('hex') === signature } ``` ## IP whitelisting When Voucherify sends a webhook, the Voucherify servers make network requests to tenants’ or third parties’ servers. To add an additional layer of security, you can do IP whitelisting. This mechanism verifies if webhook requests come from Voucherify. Voucherify sends webhooks from the IP ranges below. Add all three addresses for your region. | **Region** | **IP** | | ---------- | -------------------------------------------- | | eu1 | 34.247.197.22, 63.32.191.141, 52.215.148.84 | | us1 | 100.25.106.67, 18.209.236.215, 34.192.255.99 | | as1 | 52.76.98.82, 54.169.8.101, 13.214.87.160 | For dedicated regions, contact [Voucherify Support](https://www.voucherify.io/contact-support) or your Technical Account Manager to get the IP ranges for your whitelist. ## Webhook tracking and monitoring You can track and monitor webhook send outs and other details in a couple of ways. ### Audit log You can check details about a webhook sendout. In Voucherify dashboard, go to Audit log and Webhook send outs tab. The Audit Log includes the following details: * Webhook status * Webhook type * Webhook send out ID * Source * Target URL * Request ID * Event created at * Executed at * Complete webhook data (three dot menu on the right > Show data) You can also send a failed webhook again. Go to the three dot menu on the right > Retry. ### Get notified about failed sendouts You can set up notifications to inform you via email or in the app that a webhook did not reach the destination. Go to the Notification Center > Account Settings and scroll down to Webhook callout notifications to configure notifications. ### Responding to webhooks Voucherify expects your webhook to return a response with a `2XX` HTTP status code, indicating that the webhook has been received successfully. If a webhook is not successfully received for any reason, Voucherify will continue trying to send the webhook in the following intervals: | **Re-try No.** | **Time since the initial attempt** | **Interval to next re-try** | | -------------- | ---------------------------------- | --------------------------- | | 1 | 1 min | 1 min | | 2 | 2 min | 2 min | | 3 | 4 min | 4 min | | 4 | 8 min | 8 min | | 5 | 16 min | 16 min | | 6 | 32 min | 32 min | | 7 | 1 h 4 min | 1 h 4 min | | 8 | 2 h 8 min | 2 h 8 min | | 9 | 4 h 16 min | 4 h 16 min | | 10 | 8 h 32 min | 8 h 32 min | | 11 | 17 h 4 min | 17 h 4 min | | 12 | 24 h | Final re-try | Your endpoint must return a response in under 10 seconds; otherwise, it will be considered an error. * Project-level webhooks that are set in Project Settings are disabled after 12 unsuccessful tries. * Distribution-based webhooks that are set up as channels in the Distributions manager are paused after 12 unsuccessful tries. # Fetching Data Source: https://docs.voucherify.io/api-reference/listing Learn how to specify the data you would like to fetch All top-level API resources have support for fetches via **list** API methods. For instance, you can list redemptions, list publications, list customers, list products, and more. These list API methods share a common structure, using at least these *query parameters*: `limit` and `created_at`. | **Parameter name** | **Description** | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `limit` | A limit on the number of objects to be returned; between 1 and 100. | | `created_at` | A filter on the list based on the object `created_at` field. The value is a dictionary with the following options: `before`, `after`. A date value must be presented in ISO 8601 format (`2016-11-16T14:14:31Z` or `2016-11-16`). *Examples:* - `[created_at][before]=2017-09-08T13:52:18.227Z`- `[created_at][after]=2017-09-08` | ## Paging the results Some of the list API methods use the `page` query parameter to display another page of results. However, the following list API methods use the `starting_after_id` query parameter: * [List customer activity](/api-reference/customers/list-customer-activity) * [List member activity](/api-reference/loyalties/list-member-activity) * [List member activity (with campaign ID)](/api-reference/loyalties/list-member-activity-with-campaign-id) * [List campaign transactions](/api-reference/campaigns/list-campaign-transactions) * [List voucher transactions](/api-reference/vouchers/list-voucher-transactions) * [List loyalty campaign transactions](/api-reference/loyalties/list-loyalty-campaign-transactions) * [List loyalty card transactions](/api-reference/loyalties/list-loyalty-card-transactions) * [List loyalty card transactions (with campaign ID)](/api-reference/loyalties/list-loyalty-card-transactions-with-campaign-id) * [List customer redeemables](/api-reference/customers/list-customers-redeemables) * [List referral code holders](/api-reference/referrals/list-referral-code-holders) * [List referral code holders (with campaign ID)](/api-reference/referrals/list-referral-code-holders-with-campaign-id) * [List bin entries](/api-reference/bin/list-bin-entries) * [List campaign templates](/api-reference/templates/list-campaign-templates) * [Management – List campaign templates](/api-reference/management/list-campaign-templates) The response to these methods may include a `more_starting_after` key that takes a string value with an ID. Use this ID with the `starting_after_id` query parameter to display another page of results. ## Cursor pagination (Loyalty v2) Loyalty v2 list endpoints use cursor pagination instead of `page` or `starting_after_id`. Typical response shape: ```json theme={null} { "data": [], "cursor": { "next": "lcrsctx_12989e71c62b6d5baf", "expires_at": "2026-06-18T16:32:07.896Z" }, "object": "list" } ``` How to page results: 1. Call the list endpoint without `cursor` to get the first page. 2. If `cursor.next` is present, call the same endpoint again with `?cursor={cursor.next}`. 3. Stop when `cursor` is `null` or `cursor.next` is missing. 4. Treat `cursor.expires_at` as the validity window for that cursor value. Request a new first page if the cursor expires. Cursor prefixes differ by resource (for example `lcrsctx_` for card transactions and `lcrsmbr_` for members). Always pass the exact `cursor.next` value returned by the previous response. See the Loyalty v2 endpoint pages under API reference for resource-specific cursor patterns. ## Response format The listing method returns a dictionary with a data property that contains an array of resources. The maximum number of resources returned is determined by the `limit` query parameter. If no more resources are available, the resulting array on a given page will be empty. The result can be narrowed down according to the specified (or default) filters. | **Property name** | **Description** | | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `object` | A string describing the object type returned. | | `data_ref` | The value for this property indicates the property name containing the results array. | | `data` | An array that contains objects for a given list endpoint. In older methods, this is replaced by the name of the respective resource, e.g. `publications`. | | `total` | Total number of records for given filtering query. In some methods, this field is absent. | | `has_more` | It indicates that there are more results to be returned for given filter parameters. | | `more_starting_after` | Present in some of the newer endpoints; it provides an ID that can be used with a `starting_after_id` query parameter to return another page of results. | ```json Old method example response theme={null} { "object": "list", "total": 1, "data_ref": "vouchers", "vouchers": [ { "id": "v_yY3smFaWii1iy3EvtaiJJpZqQxoS9rJn", "code": "2018-Heq-mK-2w1", "campaign": "Benefit", "campaign_id": "camp_FzQCVyac6jAAEephT0i2L14F", "type": "DISCOUNT_VOUCHER", "discount": { "type": "AMOUNT", "amount_off": 1000 }, "start_date": "2018-09-03T22:00:00.000Z", "validity_timeframe": { "interval": "P1D", "duration": "PT1H" }, "validity_day_of_week": [ 2, 3 ], "publish": { "object": "list", "count": 1, "url": "/v1/vouchers/2018-Heq-mK-2w1/publications?page=1&limit=10" }, "redemption": { "object": "list", "quantity": 5, "redeemed_quantity": 0, "url": "/v1/vouchers/2018-Heq-mK-2w1/redemptions?page=1&limit=10" }, "active": false, "assets": { "qr": { "id": "U2FsdGVkX1+oNqKQ08m2y1IWJemXXWI7RpgBrrNvmBiQbxe/4XBlAudagPJWbdtDI3S5biYSdslhXIwPyRCx0eUhUqnQmngmBadWq8xX3HeGSjUxMu2/yF9PAc3izKU0MUJ2oXJpjZ/oieEHtIElEA==", "url": "{{voucherify_internal_URL}}" }, "barcode": { "id": "U2FsdGVkX1+anixbnFov/mzPXUmqQp6YDR++HLW2m0WxQBc4t1wbBSKHqP8cAa63CUQE8IdyZEIZIku0RwAQiYflEAq6upaJ5CHiB3LUOh0EsdtnzUCB21EBkaNCs3PKNvFdDwG5UQzqIjN0u5MOGA==", "url": "{{voucherify_internal_URL}}" } }, "is_referral_code": false, "created_at": "2018-09-04T14:58:25.000Z", "updated_at": "2018-09-20T08:03:55Z", "object": "voucher" } ] } ``` ```json New method example response theme={null} { "object": "list", "data_ref": "data", "data": [ { "id": "rh_0f35d7ba9300a8e8e4", "created_at": "2024-08-14T10:29:19.542Z", "redeemable_id": "v_YdDGS5yBnLCp79vfPbHhkoRrqPwkgyiy", "redeemable_object": "voucher", "campaign_id": "camp_vVk4unz3k4gA023fk9XoSiTh", "campaign_type": "REFERRAL_PROGRAM", "voucher_type": "DISCOUNT_VOUCHER", "customer_id": "cust_K11DXLfeJIZz7LZpxgiLhZpX", "holder_role": "REFEREE", "object": "redeemable_holder", "metadata": { "influencer_code": true } }, { "id": "rh_0f35d7ba9300a8e8e3", "created_at": "2024-08-14T10:29:19.542Z", "redeemable_id": "v_YdDGS5yBnLCp79vfPbHhkoRrqPwkgyiy", "redeemable_object": "voucher", "campaign_id": "camp_vVk4unz3k4gA023fk9XoSiTh", "campaign_type": "REFERRAL_PROGRAM", "voucher_type": "DISCOUNT_VOUCHER", "customer_id": "cust_6P4K6p7PxEuK37sDtiLOii0A", "holder_role": "REFEREE", "object": "redeemable_holder", "metadata": { "influencer_code": false } } ], "total": 2, "has_more": true, "more_starting_after": "rh_0f35d7ba9300a8e8e3" } ``` ## Shortcuts List API methods offer a list of query parameters. These parameters allow you to filter the results. Each API resource enables a specific set of options which can be used for simplifying a query. If you need advanced options, read the [next section](#advanced-filters-for-fetching-resources). | Resource | **Shortcuts** | **Example** | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- | | **Vouchers** | `customer` `campaign` `category` | `{api-url}/vouchers?customer=source_id` | | **Redemptions** | `campaign_name` `customer` `voucher_code` `related_object_id` `related_object_parent_id` | `{api-url}/redemptions?customer=customer_id` `{api-url}/redemptions?customer=source_id` | | **Customers** | `email` `name` | `{api-url}/[email protected]` | | **Publications** | `campaign_name` `customer_id` `voucher_code` `result` `voucher_type` `is_referral_code` `parent_object_id` `related_object_id` | `{api-url}/publications?campaign_name=TEST` | | **Validation Rule Assignments** | `related_object_id` `rule` | `{api-url}/validation-rules-assignments?related_object_id=promo_id` | ## Advanced filters for fetching resources Moreover, API methods for fetching resources offer extended capabilities for filtering data. A user can build advanced queries by passing parameters that define search criteria. | **Resource** | **Examples** | | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Vouchers** | `[filters][active][conditions][$active]=true` `[filters][active][conditions][$expired]=true` `[filters][active][conditions][$enabled]=true` `[filters][active][conditions][$disabled]=true` `[filters][redemption.redeemed_quantity][conditions][$is]=0` `[filters][is_referral_code][conditions][$is]=true` `[filters][expiration_date][conditions][$before]=2024-04-29T00:00:00.000Z` `[filters][metadata.seq_number][conditions][$is]=1` | | **Campaigns** | `[filters][metadata.seq_number][conditions][$is]=1` `[filters][metadata.test][conditions][$is]=true` | | **Products and Skus** | `[filters][updated_at][conditions][$after][0]=2020-08-20T14:17:09Z` `[filters][updated_at][conditions][$before][0]=2020-08-20T14:17:09Z` `[filters][created_at][conditions][$after][0]=2020-08-20T14:17:09Z` `[filters][created_at][conditions][$before][0]=2020-08-20T14:17:09Z` | | **List all promotion stacks** | `[created_at][before]=2021-12-30T13:52:18.227Z` `[created_at][after]=2021-12-30T13:52:18.227Z` `[filters][created_at][conditions][$before][0]=2021-12-30T13:52:18.227Z` `[filters][created_at][conditions][$after][0]=2021-12-30T13:52:18.227Z` `[updated_at][before]=2021-12-30T13:52:18.227Z` `[updated_at][after]=2021-12-30T13:52:18.227Z` `[filters][updated_at][conditions][$before][0]=2021-12-30T13:52:18.227Z` `[filters][updated_at][conditions][$after][0]=2021-12-30T13:52:18.227Z` | # Get Location Source: https://docs.voucherify.io/api-reference/locations/get-location /openapi/locations.json get /v1/locations/{locationId} Returns a location object. # List Locations Source: https://docs.voucherify.io/api-reference/locations/list-locations /openapi/locations.json get /v1/locations Returns a list of your locations. # Location Object Source: https://docs.voucherify.io/api-reference/locations/location-object

Location object

Attributes	Description
id `string`	Unique location ID, assigned by the Voucherify API. Example: loc\_NoMGXmHO9OUs7iz9mGWpamma
object `string`	The type of the object represented by JSON. This object stores information about a `location`. Available values: `location`
name `string`	Location name.
shape `object`	Defines the shape and boundaries of the location. One of: Circle Polygon
created\_at `string`	Timestamp representing the date and time when the location was created. The value is shown in the ISO 8601 format. Example: 2022-02-14T15:12:06.817Z
updated\_at `string`, `null`	Timestamp representing the date and time when the location was updated. The value is shown in the ISO 8601 format. Example: 2022-03-14T15:12:06.817Z

Circle

Attributes Description

type
string

The type of shape being defined is a circle.

Available values: circle

format
string

The location is defined in terms of a distance object.

Available values: distance

distance
object

Defines the parameters for the circle.

Distance

Attributes Description

center
string

Center of the circle identified by GPS coordinates in decimal degrees.

Example: geo:40.79372699823857,-74.15092132694554

radius
string

Defines the radius of the circle.

Polygon

Attributes Description

type
string

The type of shape being defined is a polygon.

Available values: polygon

format
string

The location is defined in terms of a geojson object.

Available values: geojson

geojson

One of:

Geojson Polygon
Geojson Multi Polygon

Geojson Polygon

Attributes Description

type
string

Type of geojson coordinates, i.e. Polygon.

Available values: Polygon

coordinates

See: PolygonCoordinates

Geojson Multi Polygon

Attributes Description

type
string

Type of geojson coordinates, i.e. MultiPolygon.

Available values: MultiPolygon

coordinates
array

Array of PolygonCoordinates

PolygonCoordinates

# Activate Member Pending Points Source: https://docs.voucherify.io/api-reference/loyalties/activate-member-pending-points /openapi/loyalties.json post /v1/loyalties/members/{memberId}/pending-points/{pendingPointsId}/activate Legacy loyalty API This endpoint belongs to the legacy loyalty API (`/v1/loyalties`). Voucherify will not develop new features for this API. However, critical issues may still receive fixes. For new integrations, use [Loyalty v2](/build/loyalty-overview). If you have questions, contact [Voucherify support](https://www.voucherify.io/contact-support "Contact Voucherify support"). Activate manually the pending points and add them to the loyalty card. The pending points are determined by the pending point ID. Once activated, the pending point entry with that ID is not listed by the endpoints: List member ([with campaign ID](/api-reference/loyalties/list-member-pending-points-with-campaign-id), [without campaign ID](/api-reference/loyalties/list-member-pending-points)), [List campaign pending points](/api-reference/loyalties/list-campaign-pending-points). This **POST** method does not require a request body. Configuring pending points Pending points are configured as part of an earning rule with [POST Create earning rule](/api-reference/loyalties/create-earning-rule) or [PUT Update earning rule](/api-reference/loyalties/update-earning-rule). # Add Member Source: https://docs.voucherify.io/api-reference/loyalties/add-member /openapi/loyalties.json post /v1/loyalties/{campaignId}/members Legacy loyalty API This endpoint belongs to the legacy loyalty API (`/v1/loyalties`). Voucherify will not develop new features for this API. However, critical issues may still receive fixes. For new integrations, use [Loyalty v2](/build/loyalty-overview). If you have questions, contact [Voucherify support](https://www.voucherify.io/contact-support "Contact Voucherify support"). This method assigns a loyalty card to a customer. It selects a [loyalty card](/api-reference/vouchers/get-voucher) suitable for publication, adds a publish entry, and returns the published voucher. A voucher is suitable for publication when it's active and hasn't been published yet. Auto-update campaign In case you want to ensure the number of publishable codes increases automatically with the number of customers, you should use **auto-update** campaign. # Adjust Loyalty Card Balance Source: https://docs.voucherify.io/api-reference/loyalties/adjust-loyalty-card-balance /openapi/loyalties.json post /v1/loyalties/members/{memberId}/balance Legacy loyalty API This endpoint belongs to the legacy loyalty API (`/v1/loyalties`). Voucherify will not develop new features for this API. However, critical issues may still receive fixes. For new integrations, use [Loyalty v2](/build/loyalty-overview). If you have questions, contact [Voucherify support](https://www.voucherify.io/contact-support "Contact Voucherify support"). This method gives adds or removes balance to an existing loyalty card that is assigned to a holder. The removal of points will consume the points that expire the soonest. Async Action This is an async action. If you want to perform several add or remove loyalty card balance actions in a short time and their order matters, set up sufficient time-out between the calls. Alternative endpoint This endpoint is an alternative to this [endpoint](/api-reference/loyalties/adjust-loyalty-card-balance-with-campaign-id). The URL was re-designed to allow you to add or remove loyalty card balance without having to provide the `campaignId` as a path parameter. # Adjust Loyalty Card Balance with campaign ID Source: https://docs.voucherify.io/api-reference/loyalties/adjust-loyalty-card-balance-with-campaign-id /openapi/loyalties.json post /v1/loyalties/{campaignId}/members/{memberId}/balance Legacy loyalty API This endpoint belongs to the legacy loyalty API (`/v1/loyalties`). Voucherify will not develop new features for this API. However, critical issues may still receive fixes. For new integrations, use [Loyalty v2](/build/loyalty-overview). If you have questions, contact [Voucherify support](https://www.voucherify.io/contact-support "Contact Voucherify support"). This method adds or removes balance to an existing loyalty card that is assigned to a holder. The removal of points will consume the points that expire the soonest. Async Action This is an async action. If you want to perform several add or remove loyalty card balance actions in a short time and their order matters, set up sufficient time-out between the calls. # Adjust Member Pending Points Source: https://docs.voucherify.io/api-reference/loyalties/adjust-member-pending-points /openapi/loyalties.json post /v1/loyalties/members/{memberId}/pending-points/{pendingPointsId}/balance Legacy loyalty API This endpoint belongs to the legacy loyalty API (`/v1/loyalties`). Voucherify will not develop new features for this API. However, critical issues may still receive fixes. For new integrations, use [Loyalty v2](/build/loyalty-overview). If you have questions, contact [Voucherify support](https://www.voucherify.io/contact-support "Contact Voucherify support"). Adjusts the pending points with a given ID. You can add or subtract the number of points. Configuring pending points Pending points are configured as part of an earning rule with [POST Create earning rule](/api-reference/loyalties/create-earning-rule) or [PUT Update earning rule](/api-reference/loyalties/update-earning-rule). # Cancel Member Pending Points Source: https://docs.voucherify.io/api-reference/loyalties/cancel-member-pending-points /openapi/loyalties.json post /v1/loyalties/members/{memberId}/pending-points/{pendingPointsId}/cancel Legacy loyalty API This endpoint belongs to the legacy loyalty API (`/v1/loyalties`). Voucherify will not develop new features for this API. However, critical issues may still receive fixes. For new integrations, use [Loyalty v2](/build/loyalty-overview). If you have questions, contact [Voucherify support](https://www.voucherify.io/contact-support "Contact Voucherify support"). Cancel manually the pending points for the loyalty card. The pending points are determined by the pending point ID. Once canceled, the pending point entry with that ID is not listed by the endpoints: List member ([with campaign ID](/api-reference/loyalties/list-member-pending-points-with-campaign-id), [without campaign ID](/api-reference/loyalties/list-member-pending-points)), [List campaign pending points](/api-reference/loyalties/list-campaign-pending-points). This **POST** method does not require a request body and it returns an empty, 204, response. Configuring pending points Pending points are configured as part of an earning rule with [POST Create earning rule](/api-reference/loyalties/create-earning-rule) or [PUT Update earning rule](/api-reference/loyalties/update-earning-rule). # Create Earning Rule Source: https://docs.voucherify.io/api-reference/loyalties/create-earning-rule /openapi/loyalties.json post /v1/loyalties/{campaignId}/earning-rules Legacy loyalty API This endpoint belongs to the legacy loyalty API (`/v1/loyalties`). Voucherify will not develop new features for this API. However, critical issues may still receive fixes. For new integrations, use [Loyalty v2](/build/loyalty-overview). If you have questions, contact [Voucherify support](https://www.voucherify.io/contact-support "Contact Voucherify support"). Create earning rules for a loyalty campaign. Maximum number of earning rules You can create up to 100 earning rules per project. The limit can be customized for clients with a single-tenant setup. # Create Loyalty Campaign Source: https://docs.voucherify.io/api-reference/loyalties/create-loyalty-campaign /openapi/loyalties.json post /v1/loyalties Legacy loyalty API This endpoint belongs to the legacy loyalty API (`/v1/loyalties`). Voucherify will not develop new features for this API. However, critical issues may still receive fixes. For new integrations, use [Loyalty v2](/build/loyalty-overview). If you have questions, contact [Voucherify support](https://www.voucherify.io/contact-support "Contact Voucherify support"). Creates a batch of [loyalty cards](/api-reference/loyalties/get-member) aggregated in a single loyalty campaign. It also allows you to define a custom codes pattern. Global uniqueness All codes are unique across the whole project. Voucherify won't allow to generate the same codes in any of your campaigns. Asynchronous action! This is an asynchronous action, you can't read or modify a newly created campaign until the code generation is completed. See `creation_status` field in the [loyalty campaign object](/api-reference/loyalties/loyalty-campaign-object) description. # Create Loyalty Campaign Reward Assignment Source: https://docs.voucherify.io/api-reference/loyalties/create-loyalty-campaign-reward-assignment /openapi/loyalties.json post /v1/loyalties/{campaignId}/rewards Legacy loyalty API This endpoint belongs to the legacy loyalty API (`/v1/loyalties`). Voucherify will not develop new features for this API. However, critical issues may still receive fixes. For new integrations, use [Loyalty v2](/build/loyalty-overview). If you have questions, contact [Voucherify support](https://www.voucherify.io/contact-support "Contact Voucherify support"). Add rewards to a loyalty campaign. # Create loyalty tiers Source: https://docs.voucherify.io/api-reference/loyalties/create-loyalty-tiers /openapi/loyalties.json post /v1/loyalties/{campaignId}/tiers Legacy loyalty API This endpoint belongs to the legacy loyalty API (`/v1/loyalties`). Voucherify will not develop new features for this API. However, critical issues may still receive fixes. For new integrations, use [Loyalty v2](/build/loyalty-overview). If you have questions, contact [Voucherify support](https://www.voucherify.io/contact-support "Contact Voucherify support"). Creates loyalty tiers for desired campaign. # Delete Campaign Reward Assignment Source: https://docs.voucherify.io/api-reference/loyalties/delete-campaign-reward-assignment /openapi/loyalties.json delete /v1/loyalties/{campaignId}/rewards/{assignmentId} Legacy loyalty API This endpoint belongs to the legacy loyalty API (`/v1/loyalties`). Voucherify will not develop new features for this API. However, critical issues may still receive fixes. For new integrations, use [Loyalty v2](/build/loyalty-overview). If you have questions, contact [Voucherify support](https://www.voucherify.io/contact-support "Contact Voucherify support"). This method deletes a reward assignment for a particular loyalty campaign. # Delete Earning Rule Source: https://docs.voucherify.io/api-reference/loyalties/delete-earning-rule /openapi/loyalties.json delete /v1/loyalties/{campaignId}/earning-rules/{earningRuleId} Legacy loyalty API This endpoint belongs to the legacy loyalty API (`/v1/loyalties`). Voucherify will not develop new features for this API. However, critical issues may still receive fixes. For new integrations, use [Loyalty v2](/build/loyalty-overview). If you have questions, contact [Voucherify support](https://www.voucherify.io/contact-support "Contact Voucherify support"). This method deletes an earning rule for a specific loyalty campaign. # Delete Loyalty Campaign Source: https://docs.voucherify.io/api-reference/loyalties/delete-loyalty-campaign /openapi/loyalties.json delete /v1/loyalties/{campaignId} Legacy loyalty API This endpoint belongs to the legacy loyalty API (`/v1/loyalties`). Voucherify will not develop new features for this API. However, critical issues may still receive fixes. For new integrations, use [Loyalty v2](/build/loyalty-overview). If you have questions, contact [Voucherify support](https://www.voucherify.io/contact-support "Contact Voucherify support"). Deletes a loyalty campaign and all related loyalty cards. This action cannot be undone. Also, it immediately removes any redemptions on loyalty cards. If the `force` parameter is set to `false` or not set at all, the loyalty campaign and all related loyalty cards will be moved to [the bin](/api-reference/bin/list-bin-entries). # Disable Earning Rule Source: https://docs.voucherify.io/api-reference/loyalties/disable-earning-rule /openapi/loyalties.json post /v1/loyalties/{campaignId}/earning-rules/{earningRuleId}/disable Legacy loyalty API This endpoint belongs to the legacy loyalty API (`/v1/loyalties`). Voucherify will not develop new features for this API. However, critical issues may still receive fixes. For new integrations, use [Loyalty v2](/build/loyalty-overview). If you have questions, contact [Voucherify support](https://www.voucherify.io/contact-support "Contact Voucherify support"). Disable an earning rule. # Earning Rule Object Source: https://docs.voucherify.io/api-reference/loyalties/earning-rule-object

Earning Rule

All of:

EarningRuleBase

Attributes Description

validation\_rule\_id
string, null

A unique validation rule identifier assigned by the Voucherify API. The validation rule is verified before points are added to the balance.

updated\_at
string, null

Timestamp representing the date and time when the earning rule was last updated in ISO 8601 format.

active
boolean

true indicates an active earning rule
false indicates an inactive earning rule

EarningRuleBase

Attributes Description

id
string

Assigned by the Voucherify API, identifies the earning rule object.

created\_at
string

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

loyalty

One of:

Define fixed amount of points
Calculate points proportionally

event

Defines the event which triggers the earning rule to add points to a loyalty card.

Earning Rule Event

custom\_event
object

Contains details about the custom event.

Attributes	Description
schema\_id `string`	Unique identifier of the custom event schema

segment
object

Contains the ID of a customer segment. Required for the customer.segment.entered option in the event.

Attributes	Description
id `string`	Contains a unique identifier of a customer segment. Assigned by the Voucherify API.

loyalty\_tier
object

Defines the tier associated with the earning rule definition.

Attributes Description

id
string

Unique loyalty tier ID associated with the earning rule.

**ANY** : any loyalty tier within the campaign

Example: ltr\_pudTGWasuIqxdiDM0go31OV1

pending\_points
object

Defines the configuration for pending points. Pending points can be used only with the order.paid event.

Attributes Description

period\_type
string

Defines the type of the period during which the points are in the pending state. Currently, only DAY value is accepted.

Available values: DAY

period\_value
integer

Defines for how long the points are in the pending state. The minimum value is 1, maximum is 90.

source
object

Contains the custom earning rule name and parent campaign.

Attributes Description

banner
string

Name of the earning rule. This is displayed as a header for the earning rule in the Dashboard.

object\_id
string

A unique campaign identifier assigned by the Voucherify API.

object\_type
string

Defines the object associated with the earning rule. Defaults to campaign.

Available values: campaign

object
string

The type of the object represented by JSON. Default is earning\_rule.

Available values: earning\_rule

automation\_id
string

For internal use by Voucherify.

start\_date
string

expiration\_date
string

validity\_timeframe

See: Validity Timeframe

validity\_day\_of\_week

See: Validity Day Of Week

validity\_hours

See: Validity Hours

metadata
object

expiration\_rules

See: Earning Rule Expiration Rules

Define fixed amount of points

Attributes Description

type
string

The number of points to be added to the loyalty card.

Available values: FIXED

points
integer

Defines how the points will be added to the loyalty card. FIXED adds a fixed number of points.

points\_formula
string

Formula used to dynamically calculate the rewarded points.

Calculate points proportionally

One of:

Define amount of points proportional to the order
Define amount of points proportional to order items
Define amount of points proportional to customer metadata
Earning Rule Proportional Custom Event

Earning Rule Event

Validity Timeframe

Attributes Description

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

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

Validity Day Of Week

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

Validity Hours

Attributes Description

daily
array

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

Array of:

Attributes Description

start\_time
string

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

Example: 12:00

days\_of\_week
array

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

expiration\_time
string

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

Example: 14:00

Earning Rule Expiration Rules

Attributes	Description
period\_type `string`	Type of period. Can be set for `MONTH` or `FIXED\_DAY\_OF\_YEAR`. `MONTH` requires the `period\_value` field. `FIXED\_DAY\_OF\_YEAR` requires the `fixed\_month` and `fixed\_day` fields. Available values: `FIXED\_DAY\_OF\_YEAR`, `MONTH`
period\_value `integer`	Value of the period. Required for the `period\_type: MONTH`.
rounding\_type `string`	Type of rounding of the expiration period. Optional for the `period\_type: MONTH`. Available values: `END\_OF\_MONTH`, `END\_OF\_QUARTER`, `END\_OF\_HALF\_YEAR`, `END\_OF\_YEAR`, `PARTICULAR\_MONTH`
rounding\_value `integer`	Value of rounding of the expiration period. Required for the `rounding\_type`.
fixed\_month `integer`	Determines the month when the points expire; `1` is January, `2` is February, and so on. Required for the `period\_type: FIXED\_DAY\_OF\_YEAR`.
fixed\_day `integer`	Determines the day of the month when the points expire. Required for the `period\_type: FIXED\_DAY\_OF\_YEAR`.

Define amount of points proportional to the order

One of:

Order Amount
Order Total Amount
Order Metadata

Define amount of points proportional to order items

One of:

Order Items Quantity
Order Items Amount
Order Items Subtotal Amount

Define amount of points proportional to customer metadata

Attributes Description

type
string

Defines how the points will be added to the loyalty card.PROPORTIONAL adds points based on a pre-defined ratio.

Available values: PROPORTIONAL

calculation\_type
string

CUSTOMER\_METADATA: Customer Metadata (X points for every Y in metadata attribute, defined in the property key under the customer.metadata object)

Available values: CUSTOMER\_METADATA

customer
object

Attributes Description

metadata
object

Attributes	Description
every `integer`	For how many increments of the customer metadata property to grant points for.
points `integer`	Number of points to be awarded, i.e. how many points to be added to the loyalty card.
points\_formula `string`	Formula used to dynamically calculate the rewarded points.
property `string`	Customer metadata property.

Earning Rule Proportional Custom Event

Attributes Description

type
string

Defines how the points will be added to the loyalty card.PROPORTIONAL adds points based on a pre-defined ratio.

Available values: PROPORTIONAL

calculation\_type
string

CUSTOM\_EVENT\_METADATA: Custom event metadata (X points for every Y in metadata attribute).

Available values: CUSTOM\_EVENT\_METADATA

custom\_event
object

Attributes Description

metadata
object

Attributes	Description
every `integer`	For how many increments of the customer metadata property to grant points for.
points `integer`	Number of points to be awarded, i.e. how many points to be added to the loyalty card.
points\_formula `string`	Formula used to dynamically calculate the rewarded points.
property `string`	Custom event metadata property.

Order Amount

Attributes Description

type
string

Defines how the points will be added to the loyalty card.PROPORTIONAL adds points based on a pre-defined ratio.

Available values: PROPORTIONAL

calculation\_type
string

ORDER\_AMOUNT : Pre-discount order amount (X points for every Y spent excluding discounts)

Available values: ORDER\_AMOUNT

order
object

Attributes Description

amount
object

Attributes	Description
every `integer`	Value is multiplied by 100 to precisely represent 2 decimal places. For example, a \$10 order amount is written as 1000.
points `integer`	Number of points to be awarded, i.e. how many points to be added to the loyalty card.
points\_formula `string`	Formula used to dynamically calculate the rewarded points.

Order Total Amount

Attributes Description

type
string

Defines how the points will be added to the loyalty card.PROPORTIONAL adds points based on a pre-defined ratio.

Available values: PROPORTIONAL

calculation\_type
string

ORDER\_TOTAL\_AMOUNT : Total order amount (X points for every Y spent including discount)

Available values: ORDER\_TOTAL\_AMOUNT

order
object

Attributes Description

total\_amount
object

Attributes	Description
every `integer`	Value is multiplied by 100 to precisely represent 2 decimal places. For example, a \$10 order amount is written as 1000.
points `integer`	Number of points to be awarded, i.e. how many points to be added to the loyalty card.
points\_formula `string`	Formula used to dynamically calculate the rewarded points.

Order Metadata

Attributes Description

type
string

Defines how the points will be added to the loyalty card.PROPORTIONAL adds points based on a pre-defined ratio.

Available values: PROPORTIONAL

calculation\_type
string

ORDER\_METADATA : Order Metadata (X points for every Y in metadata attribute, defined in the property key under the order.metadata object)

Available values: ORDER\_METADATA

order
object

Defines the formula for calculating points proportionally.

Attributes Description

metadata
object

Attributes	Description
every `integer`	For how many increments of the order metadata property to grant points for.
points `integer`	Number of points to be awarded, i.e. how many points to be added to the loyalty card.
points\_formula `string`	Formula used to dynamically calculate the rewarded points.
property `string`	Order metadata property.

Order Items Quantity

Attributes Description

type
string

Defines how the points will be added to the loyalty card.PROPORTIONAL adds points based on a pre-defined ratio.

Available values: PROPORTIONAL

calculation\_type
string

ORDER\_ITEMS\_QUANTITY : Quantity of items defined in the order\_items.quantity.applicable\_to array or order\_items.quantity.object & .id (X points for every Y items excluding free items).

Available values: ORDER\_ITEMS\_QUANTITY

order\_items
object

Attributes Description

quantity
object

Attributes Description

every
integer

Value is multiplied by 100 to precisely represent 2 decimal places. For example, a \$10 order amount is written as 1000.

points
integer

Number of points to be awarded, i.e. how many points to be added to the loyalty card.

points\_formula
string

Formula used to dynamically calculate the rewarded points.

object
string

Available values: products\_collection, product, sku

id
string

applicable\_to
array

Defines products, SKUs, or product collections covered by the earning rule. Can be replaced by object and id to define only one object.

Array of:

Attributes Description

object
string

Type of object which will be covered by the earning rule.

Available values: products\_collection, product, sku

id
string

Order Items Amount

Attributes Description

type
string

Defines how the points will be added to the loyalty card.PROPORTIONAL adds points based on a pre-defined ratio.

Available values: PROPORTIONAL

calculation\_type
string

Available values: ORDER\_ITEMS\_AMOUNT

order\_items
object

Attributes Description

amount
object

Attributes Description

every
integer

Value is multiplied by 100 to precisely represent 2 decimal places. For example, a \$10 order amount is written as 1000.

points
integer

Number of points to be awarded, i.e. how many points to be added to the loyalty card.

points\_formula
string

Formula used to dynamically calculate the rewarded points.

object
string

Available values: products\_collection, product, sku

id
string

applicable\_to
array

Defines products, SKUs, or product collections covered by the earning rule. Can be replaced by object and id to define only one object.

Array of:

Attributes Description

object
string

Type of object which will be covered by the earning rule.

Available values: products\_collection, product, sku

id
string

Order Items Subtotal Amount

Attributes Description

type
string

Defines how the points will be added to the loyalty card.PROPORTIONAL adds points based on a pre-defined ratio.

Available values: PROPORTIONAL

calculation\_type
string

ORDER\_ITEMS\_SUBTOTAL\_AMOUNT; Amount spent on items defined in the order\_items.subtotal\_amount.object & .id (X points for every Y spent on items including discounts)

Available values: ORDER\_ITEMS\_SUBTOTAL\_AMOUNT

order\_items
object

Attributes Description

subtotal\_amount
object

Attributes Description

every
integer

Value is multiplied by 100 to precisely represent 2 decimal places. For example, a \$10 order amount is written as 1000.

points
integer

Number of points to be awarded, i.e. how many points to be added to the loyalty card.

points\_formula
string

Formula used to dynamically calculate the rewarded points.

object
string

Available values: products\_collection, product, sku

id
string

applicable\_to
array

Defines products, SKUs, or product collections covered by the earning rule. Can be replaced by object and id to define only one object.

Array of:

Attributes Description

object
string

Type of object which will be covered by the earning rule.

Available values: products\_collection, product, sku

id
string

# Enable Earning Rule Source: https://docs.voucherify.io/api-reference/loyalties/enable-earning-rule /openapi/loyalties.json post /v1/loyalties/{campaignId}/earning-rules/{earningRuleId}/enable Legacy loyalty API This endpoint belongs to the legacy loyalty API (`/v1/loyalties`). Voucherify will not develop new features for this API. However, critical issues may still receive fixes. For new integrations, use [Loyalty v2](/build/loyalty-overview). If you have questions, contact [Voucherify support](https://www.voucherify.io/contact-support "Contact Voucherify support"). Enable an earning rule. # Estimate loyalty points Source: https://docs.voucherify.io/api-reference/loyalties/estimate-loyalty-points /openapi/loyalties.json post /v1/loyalties/{campaignId}/qualifications Legacy loyalty API This endpoint belongs to the legacy loyalty API (`/v1/loyalties`). Voucherify will not develop new features for this API. However, critical issues may still receive fixes. For new integrations, use [Loyalty v2](/build/loyalty-overview). If you have questions, contact [Voucherify support](https://www.voucherify.io/contact-support "Contact Voucherify support"). Estimates the number of points a customer will receive for a given order in the loyalty campaign under its earning rules. This endpoint also returns point estimation for created transactions (orders with status `PAID`) This endpoint returns only an estimation, not a precise point value. Also, this estimation works only for the Order paid earning rules. If a campaign includes tiers, mappings, and multiple earning rules, the calculation becomes more complex. During final calculation, a customer may change tiers and earn more or fewer points depending on other factors. # Export Loyalty Campaign Point Expiration Source: https://docs.voucherify.io/api-reference/loyalties/export-loyalty-campaign-point-expiration /openapi/loyalties.json post /v1/loyalties/{campaignId}/points-expiration/export Legacy loyalty API This endpoint belongs to the legacy loyalty API (`/v1/loyalties`). Voucherify will not develop new features for this API. However, critical issues may still receive fixes. For new integrations, use [Loyalty v2](/build/loyalty-overview). If you have questions, contact [Voucherify support](https://www.voucherify.io/contact-support "Contact Voucherify support"). Schedule the generation of a point expiration CSV file for a particular campaign. It can list point buckets, which can have an `ACTIVE` or `EXPIRED` status. # Export Loyalty Campaign Transactions Source: https://docs.voucherify.io/api-reference/loyalties/export-loyalty-campaign-transactions /openapi/loyalties.json post /v1/loyalties/{campaignId}/transactions/export Legacy loyalty API This endpoint belongs to the legacy loyalty API (`/v1/loyalties`). Voucherify will not develop new features for this API. However, critical issues may still receive fixes. For new integrations, use [Loyalty v2](/build/loyalty-overview). If you have questions, contact [Voucherify support](https://www.voucherify.io/contact-support "Contact Voucherify support"). Export transactions is an asynchronous process that generates a CSV file with the data about or point movements on all loyalty cards in a given campaign. To export transactions: 1. In the export request, use parameters to select which fields will be exported, in what order, and which data will be filtered. 2. Use the returned `id` to track the export status with the [GET Export](/api-reference/exports/get-export) method. 3. In the GET Export method, when the returned `status` field has the `DONE` value, the export file has been generated. 4. Use the URL in the `result` property to download the file. You must be logged to your Voucherify account on a given cluster in the browser to be able to download the file. An export request will almost always result in a single file being generated by the system. However, when the data volume is large, the system may split the results into multiple files. An example export file can look as follows: | **Field** | **Definition** | **Example Export** | |:---|:---|:---| | `id` | Unique transaction ID. | `vtx_0cb7811f1c07765800` | | `type` | Transaction type. | - `POINTS_ACCRUAL`
- `POINTS_REDEMPTION`
- `POINTS_REFUND`
- `POINTS_ADDITION`
- `POINTS_REMOVAL`
- `POINTS_EXPIRATION`
- `POINTS_TRANSFER_IN`
- `POINTS_TRANSFER_OUT` | | `source_id` | Unique transaction source ID. Optional and only in manual operations: `POINTS_ADDITION`, `POINTS_REMOVAL`, `POINTS_TRANSFER_OUT`. | 8638 | | `reason` | Contains the reason for the transaction if one was included originally. Optional and only in the following manual operations: `POINTS_ADDITION`, `POINTS_REMOVAL`, `POINTS_TRANSFER_OUT`, `POINTS_TRANSFER_IN`. | `Apology for sending a broken item` | | `balance` | The gift card or loyalty card balance after the transaction. | | | `amount` | The amount of gift card or loyalty card credits being allocated during the transaction. This value can either be negative or positive depending on the nature of the transaction. | | | `created_at` | Timestamp in ISO 8601 format representing the date and time when the transaction was created. | `2024-10-09T09:16:32.521Z` | | `voucher_id` | Unique voucher ID. | `v_dky7ksKfPX50Wb2Bxvcoeb1xT20b6tcp` | | `source`| Channel through which the transaction was initiated. | `API` | | `details` | More detailed information stored in the form of JSON. | Provides more details related to the transaction in the form of an object. | | `related_transaction_id` | Unique transaction ID related to a receiver/donor card in the case of a points transfer from/to another card. | `vtx_0c9afe802593b34b80` | Export Campaign Transactions This method works in the same way the [POST Export Campaign Transactions](/api-reference/campaigns/export-campaign-transactions) does, but it is limited to loyalty campaigns only. The POST Export Campaign Transactions method can also export gift card campaign transactions. # Export Loyalty Card Transactions Source: https://docs.voucherify.io/api-reference/loyalties/export-loyalty-card-transactions /openapi/loyalties.json post /v1/loyalties/members/{memberId}/transactions/export Legacy loyalty API This endpoint belongs to the legacy loyalty API (`/v1/loyalties`). Voucherify will not develop new features for this API. However, critical issues may still receive fixes. For new integrations, use [Loyalty v2](/build/loyalty-overview). If you have questions, contact [Voucherify support](https://www.voucherify.io/contact-support "Contact Voucherify support"). Export transactions that are associated with point movements on a loyalty card. | **Field** | **Definition** | **Example Export** | |:---|:---|:---| | id | Unique transaction ID assigned by Voucherify. | vtx_0cb7811f1c07765800 | | type | Transaction type. | - `POINTS_EXPIRATION`
- `POINTS_ADDITION`
- `POINTS_REMOVAL`
- `POINTS_TRANSFER_OUT`
- `POINTS_ACCRUAL`
- `POINTS_REFUND`
- `POINTS_REDEMPTION` | | source_id | Custom source ID of the transaction if one was included originally. | source_id_custom | | reason | Contains the reason for the transaction if one was included originally. | | | balance | The loyalty card balance after the transaction. | | | amount | The amount of loyalty points being allocated during the transaction. This value can either be negative or positive depending on the nature of the transaction. | | | created_at | Timestamp in ISO 8601 format representing the date and time when the transaction was created. | 2022-03-09T09:16:32.521Z | | voucher_id | Unique Voucher ID. | v_dky7ksKfPX50Wb2Bxvcoeb1xT20b6tcp | | campaign_id | Parent campaign ID. | camp_FNYR4jhqZBM9xTptxDGgeNBV | | source| Channel through which the transaction was initiated. | - `API`
- `voucherify-web-ui`
- `Automation` | | details | More detailed information stored in the form of a JSON. | Provides more details related to the transaction in the form of an object. | | related_transaction_id | Unique transaction ID related to a receiver/donor card in the case of a points transfer from/to another card. | vtx_0c9afe802593b34b80 | # Export Loyalty Card Transactions with campaign ID Source: https://docs.voucherify.io/api-reference/loyalties/export-loyalty-card-transactions-with-campaign-id /openapi/loyalties.json post /v1/loyalties/{campaignId}/members/{memberId}/transactions/export Legacy loyalty API This endpoint belongs to the legacy loyalty API (`/v1/loyalties`). Voucherify will not develop new features for this API. However, critical issues may still receive fixes. For new integrations, use [Loyalty v2](/build/loyalty-overview). If you have questions, contact [Voucherify support](https://www.voucherify.io/contact-support "Contact Voucherify support"). Export transactions that are associated with point movements on a loyalty card. | **Field** | **Definition** | **Example Export** | |:---|:---|:---| | id | Unique transaction ID assigned by Voucherify. | vtx_0cb7811f1c07765800 | | type | Transaction type. | - `POINTS_EXPIRATION`
- `POINTS_ADDITION`
- `POINTS_REMOVAL`
- `POINTS_TRANSFER_OUT`
- `POINTS_ACCRUAL`
- `POINTS_REFUND`
- `POINTS_REDEMPTION` | | source_id | Custom source ID of the transaction if one was included originally. | source_id_custom | | reason | Contains the reason for the transaction if one was included originally. | | | balance | The loyalty card balance after the transaction. | | | amount | The amount of loyalty points being allocated during the transaction. This value can either be negative or positive depending on the nature of the transaction. | | | created_at | Timestamp in ISO 8601 format representing the date and time when the transaction was created. | 2022-03-09T09:16:32.521Z | | voucher_id | Unique Voucher ID. | v_dky7ksKfPX50Wb2Bxvcoeb1xT20b6tcp | | campaign_id | Parent campaign ID. | camp_FNYR4jhqZBM9xTptxDGgeNBV | | source| Channel through which the transaction was initiated. | - `API`
- `voucherify-web-ui`
- `Automation` | | details | More detailed information stored in the form of a JSON. | Provides more details related to the transaction in the form of an object. | | related_transaction_id | Unique transaction ID related to a receiver/donor card in the case of a points transfer from/to another card. | vtx_0c9afe802593b34b80 | # Get Campaign Reward Assignment Source: https://docs.voucherify.io/api-reference/loyalties/get-campaign-reward-assignment /openapi/loyalties.json get /v1/loyalties/{campaignId}/rewards/{assignmentId} Legacy loyalty API This endpoint belongs to the legacy loyalty API (`/v1/loyalties`). Voucherify will not develop new features for this API. However, critical issues may still receive fixes. For new integrations, use [Loyalty v2](/build/loyalty-overview). If you have questions, contact [Voucherify support](https://www.voucherify.io/contact-support "Contact Voucherify support"). Retrieve specific reward assignment. Alternative endpoint This endpoint is an alternative to this [endpoint](/api-reference/loyalties/get-campaign-reward-assignments). # Get Campaign Reward Assignments Source: https://docs.voucherify.io/api-reference/loyalties/get-campaign-reward-assignments /openapi/loyalties.json get /v1/loyalties/{campaignId}/reward-assignments/{assignmentId} Legacy loyalty API This endpoint belongs to the legacy loyalty API (`/v1/loyalties`). Voucherify will not develop new features for this API. However, critical issues may still receive fixes. For new integrations, use [Loyalty v2](/build/loyalty-overview). If you have questions, contact [Voucherify support](https://www.voucherify.io/contact-support "Contact Voucherify support"). Retrieve specific reward assignment. # Get Earning Rule Source: https://docs.voucherify.io/api-reference/loyalties/get-earning-rule /openapi/loyalties.json get /v1/loyalties/{campaignId}/earning-rules/{earningRuleId} Legacy loyalty API This endpoint belongs to the legacy loyalty API (`/v1/loyalties`). Voucherify will not develop new features for this API. However, critical issues may still receive fixes. For new integrations, use [Loyalty v2](/build/loyalty-overview). If you have questions, contact [Voucherify support](https://www.voucherify.io/contact-support "Contact Voucherify support"). Retrieves an earning rule assigned to a campaign. # Get Loyalty Campaign Source: https://docs.voucherify.io/api-reference/loyalties/get-loyalty-campaign /openapi/loyalties.json get /v1/loyalties/{campaignId} Legacy loyalty API This endpoint belongs to the legacy loyalty API (`/v1/loyalties`). Voucherify will not develop new features for this API. However, critical issues may still receive fixes. For new integrations, use [Loyalty v2](/build/loyalty-overview). If you have questions, contact [Voucherify support](https://www.voucherify.io/contact-support "Contact Voucherify support"). Retrieve a specific loyalty campaign. # Get Loyalty Tier Source: https://docs.voucherify.io/api-reference/loyalties/get-loyalty-tier /openapi/loyalties.json get /v1/loyalties/{campaignId}/tiers/{loyaltyTierId} Legacy loyalty API This endpoint belongs to the legacy loyalty API (`/v1/loyalties`). Voucherify will not develop new features for this API. However, critical issues may still receive fixes. For new integrations, use [Loyalty v2](/build/loyalty-overview). If you have questions, contact [Voucherify support](https://www.voucherify.io/contact-support "Contact Voucherify support"). Retrieve a loyalty tier from a loyalty campaign by the loyalty tier ID. # Get Member Source: https://docs.voucherify.io/api-reference/loyalties/get-member /openapi/loyalties.json get /v1/loyalties/members/{memberId} Legacy loyalty API This endpoint belongs to the legacy loyalty API (`/v1/loyalties`). Voucherify will not develop new features for this API. However, critical issues may still receive fixes. For new integrations, use [Loyalty v2](/build/loyalty-overview). If you have questions, contact [Voucherify support](https://www.voucherify.io/contact-support "Contact Voucherify support"). Retrieve loyalty card with the given member ID (i.e. voucher code). Alternative endpoint This endpoint is an alternative to this [endpoint](/api-reference/loyalties/get-member-with-campaign-id). The URL was re-designed to allow you to retrieve loyalty card details without having to provide the `campaignId` as a path parameter. # Get Member with campaign ID Source: https://docs.voucherify.io/api-reference/loyalties/get-member-with-campaign-id /openapi/loyalties.json get /v1/loyalties/{campaignId}/members/{memberId} Legacy loyalty API This endpoint belongs to the legacy loyalty API (`/v1/loyalties`). Voucherify will not develop new features for this API. However, critical issues may still receive fixes. For new integrations, use [Loyalty v2](/build/loyalty-overview). If you have questions, contact [Voucherify support](https://www.voucherify.io/contact-support "Contact Voucherify support"). Retrieves the loyalty card with the given member ID (i.e. voucher code). # Get Reward Details Source: https://docs.voucherify.io/api-reference/loyalties/get-reward-details /openapi/loyalties.json get /v1/loyalties/{campaignId}/reward-assignments/{assignmentId}/reward Legacy loyalty API This endpoint belongs to the legacy loyalty API (`/v1/loyalties`). Voucherify will not develop new features for this API. However, critical issues may still receive fixes. For new integrations, use [Loyalty v2](/build/loyalty-overview). If you have questions, contact [Voucherify support](https://www.voucherify.io/contact-support "Contact Voucherify support"). Get reward details in the context of a loyalty campaign and reward assignment ID. # Legacy loyalty API Source: https://docs.voucherify.io/api-reference/loyalties/introduction-to-legacy-loyalty Legacy loyalty API endpoints for managing loyalty campaigns, members, points, tiers, and rewards. Legacy loyalty API These endpoints belong to the legacy loyalty API (`/v1/loyalties`). Voucherify will not develop new features for this API. Critical issues may still receive fixes. For new integrations, use [Loyalty v2](/guides/loyalty-v2-overview). If you have questions, contact [Voucherify support](https://www.voucherify.io/contact-support "Contact Voucherify support"). The Loyalties API lets you manage legacy loyalty campaigns and their members, points, earning rules, tiers, and rewards through the `/v1/loyalties` endpoints. For the current loyalty solution, see: * [Loyalty v2 API: Overview](/api-reference/loyalty-v2-api-overview) * [Loyalty v2 developer overview](/guides/loyalty-v2-overview) * [Integrate loyalty v2](/guides/loyalty-v2-integrate) * [Loyalty hub overview](/build/loyalty-overview) # List Campaign Pending Points Source: https://docs.voucherify.io/api-reference/loyalties/list-campaign-pending-points /openapi/loyalties.json get /v1/loyalties/{campaignId}/pending-points Legacy loyalty API This endpoint belongs to the legacy loyalty API (`/v1/loyalties`). Voucherify will not develop new features for this API. However, critical issues may still receive fixes. For new integrations, use [Loyalty v2](/build/loyalty-overview). If you have questions, contact [Voucherify support](https://www.voucherify.io/contact-support "Contact Voucherify support"). Lists all pending points that are currently assigned to all loyalty cards in a campaign. Once the points are added to the card, the entry is no longer returned. Configuring pending points Pending points are configured as part of an earning rule with [POST Create earning rule](/api-reference/loyalties/create-earning-rule) or [PUT Update earning rule](/api-reference/loyalties/update-earning-rule). # List Campaign Rewards Source: https://docs.voucherify.io/api-reference/loyalties/list-campaign-rewards /openapi/loyalties.json get /v1/loyalties/{campaignId}/rewards Legacy loyalty API This endpoint belongs to the legacy loyalty API (`/v1/loyalties`). Voucherify will not develop new features for this API. However, critical issues may still receive fixes. For new integrations, use [Loyalty v2](/build/loyalty-overview). If you have questions, contact [Voucherify support](https://www.voucherify.io/contact-support "Contact Voucherify support"). Returns active rewards from a given loyalty campaign. # List Earning Rules Source: https://docs.voucherify.io/api-reference/loyalties/list-earning-rules /openapi/loyalties.json get /v1/loyalties/{campaignId}/earning-rules Legacy loyalty API This endpoint belongs to the legacy loyalty API (`/v1/loyalties`). Voucherify will not develop new features for this API. However, critical issues may still receive fixes. For new integrations, use [Loyalty v2](/build/loyalty-overview). If you have questions, contact [Voucherify support](https://www.voucherify.io/contact-support "Contact Voucherify support"). Returns a list of all earning rules within a given campaign. # List Loyalty Campaign Transactions Source: https://docs.voucherify.io/api-reference/loyalties/list-loyalty-campaign-transactions /openapi/loyalties.json get /v1/loyalties/{campaignId}/transactions Legacy loyalty API This endpoint belongs to the legacy loyalty API (`/v1/loyalties`). Voucherify will not develop new features for this API. However, critical issues may still receive fixes. For new integrations, use [Loyalty v2](/build/loyalty-overview). If you have questions, contact [Voucherify support](https://www.voucherify.io/contact-support "Contact Voucherify support"). Retrieves all transactions for the campaign with the given campaign ID or campaign name. # List Loyalty Campaigns Source: https://docs.voucherify.io/api-reference/loyalties/list-loyalty-campaigns /openapi/loyalties.json get /v1/loyalties Legacy loyalty API This endpoint belongs to the legacy loyalty API (`/v1/loyalties`). Voucherify will not develop new features for this API. However, critical issues may still receive fixes. For new integrations, use [Loyalty v2](/build/loyalty-overview). If you have questions, contact [Voucherify support](https://www.voucherify.io/contact-support "Contact Voucherify support"). Returns a list of your loyalty campaigns. # List Loyalty Card Point Expiration Source: https://docs.voucherify.io/api-reference/loyalties/list-loyalty-card-point-expiration /openapi/loyalties.json get /v1/loyalties/{campaignId}/members/{memberId}/points-expiration Legacy loyalty API This endpoint belongs to the legacy loyalty API (`/v1/loyalties`). Voucherify will not develop new features for this API. However, critical issues may still receive fixes. For new integrations, use [Loyalty v2](/build/loyalty-overview). If you have questions, contact [Voucherify support](https://www.voucherify.io/contact-support "Contact Voucherify support"). Retrieve loyalty point expiration buckets for a given loyalty card. Expired point buckets are not returned in this endpoint. You can use the [Exports API](/api-reference/exports/create-export) to retrieve a list of both `ACTIVE` and `EXPIRED` point buckets. # List Loyalty Card Transactions Source: https://docs.voucherify.io/api-reference/loyalties/list-loyalty-card-transactions /openapi/loyalties.json get /v1/loyalties/members/{memberId}/transactions Legacy loyalty API This endpoint belongs to the legacy loyalty API (`/v1/loyalties`). Voucherify will not develop new features for this API. However, critical issues may still receive fixes. For new integrations, use [Loyalty v2](/build/loyalty-overview). If you have questions, contact [Voucherify support](https://www.voucherify.io/contact-support "Contact Voucherify support"). Retrieve transaction data related to point movements for a specific loyalty card. # List Loyalty Card Transactions with campaign ID Source: https://docs.voucherify.io/api-reference/loyalties/list-loyalty-card-transactions-with-campaign-id /openapi/loyalties.json get /v1/loyalties/{campaignId}/members/{memberId}/transactions Legacy loyalty API This endpoint belongs to the legacy loyalty API (`/v1/loyalties`). Voucherify will not develop new features for this API. However, critical issues may still receive fixes. For new integrations, use [Loyalty v2](/build/loyalty-overview). If you have questions, contact [Voucherify support](https://www.voucherify.io/contact-support "Contact Voucherify support"). Retrieve transaction data related to point movements for a specific loyalty card. # List Loyalty Tier Earning Rules Source: https://docs.voucherify.io/api-reference/loyalties/list-loyalty-tier-earning-rules /openapi/loyalties.json get /v1/loyalties/{campaignId}/tiers/{loyaltyTierId}/earning-rules Legacy loyalty API This endpoint belongs to the legacy loyalty API (`/v1/loyalties`). Voucherify will not develop new features for this API. However, critical issues may still receive fixes. For new integrations, use [Loyalty v2](/build/loyalty-overview). If you have questions, contact [Voucherify support](https://www.voucherify.io/contact-support "Contact Voucherify support"). Retrieve available earning rules for a given tier and the calculation method for earning points. # List Loyalty Tier Rewards Source: https://docs.voucherify.io/api-reference/loyalties/list-loyalty-tier-rewards /openapi/loyalties.json get /v1/loyalties/{campaignId}/tiers/{loyaltyTierId}/rewards Legacy loyalty API This endpoint belongs to the legacy loyalty API (`/v1/loyalties`). Voucherify will not develop new features for this API. However, critical issues may still receive fixes. For new integrations, use [Loyalty v2](/build/loyalty-overview). If you have questions, contact [Voucherify support](https://www.voucherify.io/contact-support "Contact Voucherify support"). Get available rewards for a given tier. # List Loyalty Tiers Source: https://docs.voucherify.io/api-reference/loyalties/list-loyalty-tiers /openapi/loyalties.json get /v1/loyalties/{campaignId}/tiers Legacy loyalty API This endpoint belongs to the legacy loyalty API (`/v1/loyalties`). Voucherify will not develop new features for this API. However, critical issues may still receive fixes. For new integrations, use [Loyalty v2](/build/loyalty-overview). If you have questions, contact [Voucherify support](https://www.voucherify.io/contact-support "Contact Voucherify support"). Retrieve a list of loyalty tiers which were added to the loyalty program. # List Member Activity Source: https://docs.voucherify.io/api-reference/loyalties/list-member-activity /openapi/loyalties.json get /v1/loyalties/members/{memberId}/activity Legacy loyalty API This endpoint belongs to the legacy loyalty API (`/v1/loyalties`). Voucherify will not develop new features for this API. However, critical issues may still receive fixes. For new integrations, use [Loyalty v2](/build/loyalty-overview). If you have questions, contact [Voucherify support](https://www.voucherify.io/contact-support "Contact Voucherify support"). Alternative endpoint This endpoint is an alternative to this [endpoint](/api-reference/loyalties/list-member-activity-with-campaign-id). The URL was re-designed to allow you to get member activities without having to provide the `campaignId` as a path parameter. Retrieves the list of activities for the given member ID related to a voucher and customer who is the holder of the voucher. # List Member Activity with campaign ID Source: https://docs.voucherify.io/api-reference/loyalties/list-member-activity-with-campaign-id /openapi/loyalties.json get /v1/loyalties/{campaignId}/members/{memberId}/activity Legacy loyalty API This endpoint belongs to the legacy loyalty API (`/v1/loyalties`). Voucherify will not develop new features for this API. However, critical issues may still receive fixes. For new integrations, use [Loyalty v2](/build/loyalty-overview). If you have questions, contact [Voucherify support](https://www.voucherify.io/contact-support "Contact Voucherify support"). Retrieves the list of activities for the given member ID related to a voucher and customer who is the holder of the voucher. # List Member Pending Points Source: https://docs.voucherify.io/api-reference/loyalties/list-member-pending-points /openapi/loyalties.json get /v1/loyalties/members/{memberId}/pending-points Legacy loyalty API This endpoint belongs to the legacy loyalty API (`/v1/loyalties`). Voucherify will not develop new features for this API. However, critical issues may still receive fixes. For new integrations, use [Loyalty v2](/build/loyalty-overview). If you have questions, contact [Voucherify support](https://www.voucherify.io/contact-support "Contact Voucherify support"). Alternative endpoint This endpoint is an alternative to this [endpoint](/api-reference/loyalties/list-member-pending-points-with-campaign-id). The URL was re-designed to list member pending points without having to provide the `campaignId` as a path parameter. Lists all pending points that are currently assigned to the loyalty card. Once the points are added to the card, the entry is no longer returned. Configuring pending points Pending points are configured as part of an earning rule with [POST Create earning rule](/api-reference/loyalties/create-earning-rule) or [PUT Update earning rule](/api-reference/loyalties/update-earning-rule). # List Member Pending Points with campaign ID Source: https://docs.voucherify.io/api-reference/loyalties/list-member-pending-points-with-campaign-id /openapi/loyalties.json get /v1/loyalties/{campaignId}/members/{memberId}/pending-points Legacy loyalty API This endpoint belongs to the legacy loyalty API (`/v1/loyalties`). Voucherify will not develop new features for this API. However, critical issues may still receive fixes. For new integrations, use [Loyalty v2](/build/loyalty-overview). If you have questions, contact [Voucherify support](https://www.voucherify.io/contact-support "Contact Voucherify support"). Lists all pending points that are currently assigned to the loyalty card. Once the points are added to the card, the entry is no longer returned. Configuring pending points Pending points are configured as part of an earning rule with [POST Create earning rule](/api-reference/loyalties/create-earning-rule) or [PUT Update earning rule](/api-reference/loyalties/update-earning-rule). # List Member Rewards Source: https://docs.voucherify.io/api-reference/loyalties/list-member-rewards /openapi/loyalties.json get /v1/loyalties/members/{memberId}/rewards Legacy loyalty API This endpoint belongs to the legacy loyalty API (`/v1/loyalties`). Voucherify will not develop new features for this API. However, critical issues may still receive fixes. For new integrations, use [Loyalty v2](/build/loyalty-overview). If you have questions, contact [Voucherify support](https://www.voucherify.io/contact-support "Contact Voucherify support"). Retrieves the list of rewards that the given customer (identified by `member_id`, which is a loyalty card assigned to a particular customer) **can get in exchange for loyalty points**. You can use the `affordable_only` parameter to limit the results to rewards that the customer can actually afford (only rewards whose price in points is not higher than the loyalty points balance on a loyalty card). Please note that rewards that are disabled (i.e. set to `Not Available` in the Dashboard) for a given loyalty tier reward mapping will not be returned in this endpoint. # List Members Source: https://docs.voucherify.io/api-reference/loyalties/list-members /openapi/loyalties.json get /v1/loyalties/{campaignId}/members Legacy loyalty API This endpoint belongs to the legacy loyalty API (`/v1/loyalties`). Voucherify will not develop new features for this API. However, critical issues may still receive fixes. For new integrations, use [Loyalty v2](/build/loyalty-overview). If you have questions, contact [Voucherify support](https://www.voucherify.io/contact-support "Contact Voucherify support"). Returns a list of your loyalty cards. The loyalty cards are sorted by creation date, with the most recent loyalty cards appearing first. # List Member's Loyalty Tiers Source: https://docs.voucherify.io/api-reference/loyalties/list-members-loyalty-tiers /openapi/loyalties.json get /v1/loyalties/members/{memberId}/tiers Legacy loyalty API This endpoint belongs to the legacy loyalty API (`/v1/loyalties`). Voucherify will not develop new features for this API. However, critical issues may still receive fixes. For new integrations, use [Loyalty v2](/build/loyalty-overview). If you have questions, contact [Voucherify support](https://www.voucherify.io/contact-support "Contact Voucherify support"). Retrieve member tiers using the loyalty card ID. # List Reward Assignments with campaign ID Source: https://docs.voucherify.io/api-reference/loyalties/list-reward-assignments-with-campaign-id /openapi/loyalties.json get /v1/loyalties/{campaignId}/reward-assignments Legacy loyalty API This endpoint belongs to the legacy loyalty API (`/v1/loyalties`). Voucherify will not develop new features for this API. However, critical issues may still receive fixes. For new integrations, use [Loyalty v2](/build/loyalty-overview). If you have questions, contact [Voucherify support](https://www.voucherify.io/contact-support "Contact Voucherify support"). Returns reward assignments from a given loyalty campaign. Alternative endpoint This endpoint is an alternative to this [endpoint](/api-reference/loyalties/list-campaign-rewards). The URL was re-designed to be more contextual to the type of data returned in the response. # Loyalty Campaign Object Source: https://docs.voucherify.io/api-reference/loyalties/loyalty-campaign-object

Loyalty Campaign Object

Attributes	Description
id `string`	Unique campaign ID, assigned by Voucherify. Example: camp\_f7fBbQxUuTN7dI7tGOo5XMDA
name `string`	Loyalty campaign name.
campaign\_type `string`	Type of campaign. Available values: `LOYALTY\_PROGRAM`
type `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 values: `AUTO\_UPDATE`, `STATIC`
voucher	See: Loyalty Card
auto\_join `boolean`	Indicates whether customers will be able to auto-join a loyalty campaign if any earning rule is fulfilled.
join\_once `boolean`	If this value is set to `true`, customers will be able to join the campaign only once.
use\_voucher\_metadata\_schema `boolean`	Flag indicating whether the campaign is to use the voucher's metadata schema instead of the campaign metadata schema.
start\_date `string`	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 `string`	Expiration timestamp defines when the campaign expires in ISO 8601 format. Campaign is inactive after this date. Example: 2022-09-30T00:00:00.000Z
validity\_timeframe	See: Validity Timeframe
validity\_day\_of\_week	See: Validity Day Of Week
validity\_hours	See: Validity Hours
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.
description `string`	An optional field to keep any extra textual information about the campaign such as a campaign description and details.
vouchers\_count `integer`	Total number of unique vouchers in campaign.
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
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.
created\_at `string`	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
updated\_at `string`	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
creation\_status `string`	Indicates the status of the campaign creation. Available values: `DONE`, `IN\_PROGRESS`, `FAILED`, `DRAFT`, `MODIFYING`
vouchers\_generation\_status `string`	Indicates the status of the campaign's vouchers. Available values: `DONE`, `IN\_PROGRESS`, `FAILED`, `DRAFT`
protected `boolean`	Indicates whether the resource can be deleted.
access\_settings\_assignments	See: Access Settings Campaign Assignments List
category\_id `string`	Unique category ID that this campaign belongs to. Example: cat\_0b688929a2476386a7
categories	See: Category
loyalty\_tiers\_expiration `object`	Defines the expiration mechanism for loyalty tiers. One of: Balance Points in Period
object `string`	The type of the object represented by JSON. This object stores information about the campaign.

Loyalty Card

Attributes Description

type
string

Type of voucher.

loyalty\_card
object

Defines the loyalty card details.

Attributes Description

points
integer

Initial loyalty card income in points to be applied to the loyalty card at voucher generation.

expiration\_rules
object

Defines point expiration rules.

Attributes Description

period\_type
string

The expiration period.

Available values: MONTH

period\_value
integer

How many periods should pass before the expiration occurs.

rounding\_type
string

Round up expiration till the end of the given period type.

Available values: END\_OF\_MONTH, END\_OF\_QUARTER, END\_OF\_HALF\_YEAR, END\_OF\_YEAR, PARTICULAR\_MONTH

redemption
object

Defines the redemption limits on vouchers.

Attributes	Description
quantity `integer`	How many times a voucher can be redeemed. A `null` value means unlimited.

code\_config
object

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

Attributes	Description
length `string`	Number of characters in a generated code (excluding prefix and postfix).
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
prefix `string`	A text appended before the code.
postfix `string`	A text appended after the code.
pattern `string`	A pattern for codes where hashes (#) will be replaced with random characters. Overrides `length`.

is\_referral\_code
boolean

Flag indicating whether this voucher is a referral code; true for campaign type REFERRAL\_PROGRAM.

Validity Timeframe

Attributes Description

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

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

Validity Day Of Week

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

Validity Hours

Attributes Description

daily
array

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

Array of:

Attributes Description

start\_time
string

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

Example: 12:00

days\_of\_week
array

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

expiration\_time
string

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

Example: 14:00

Access Settings Campaign Assignments List

Attributes	Description
object `string`	The type of the object represented by JSON. Default is `list`. This object stores information about campaign assignments to areas and stores Available values: `list`
data\_ref `string`	Identifies the name of the attribute that contains the array of campaign assignments. Available values: `data`
data `array`	Contains an array of campaign assignments. Array of Areas and Stores Campain Assignment
total `integer`	Total number of areas and stores to which the campaign is assigned.

Category

Attributes	Description
id `string`	Unique category ID assigned by Voucherify.
name `string`	Category name.
hierarchy `integer`	Category hierarchy. Categories with lower hierarchy are processed before categories with higher hierarchy value.
object `string`	The type of the object represented by the JSON. This object stores information about the category. Available values: `category`
created\_at `string`	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
updated\_at `string`	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

Balance

Attributes Description

qualification\_type
string

Tier qualification.

BALANCE : Points balance is based on the customer's current points balance. Customers qualify for the tier if their points balance is in the points range of the tier.

Available values: BALANCE

start\_date
object

Defines the conditions for the start date of the tier.

Attributes Description

type
string

What triggers the tier to be valid for a customer.
IMMEDIATE : After reaching the minimum required points.

Available values: IMMEDIATE

expiration\_date

Defines the conditions for the expiration date of a tier.

One of:

Balance Drop
Custom

Points in Period

Attributes Description

qualification\_type
string

Tier qualification.

POINTS\_IN\_PERIOD : A customer qualifies for the tier only if the sum of the accumulated points in a defined time interval reaches the tier threshold.

Available values: POINTS\_IN\_PERIOD

qualification\_period
string

Period	Definition
Calendar Month	Points collected in one calendar month January, February, March, etc.
Calendar Quarter	Points collected in the quarter \- January - March \- April - June \- July - September \- October - December
Calendar Half-year	Points collected in the half-year \- January - June \- July - December
Calendar Year	Points collected in one calendar year January - December

Available values: MONTH, QUARTER, HALF\_YEAR, YEAR

start\_date
object

Defines the conditions for the start date of the tier.

Attributes Description

type
string

What triggers the tier to be valid for a customer.
IMMEDIATE : After reaching the minimum required points.
NEXT\_PERIOD : When the next qualification period starts.

Available values: IMMEDIATE, NEXT\_PERIOD

expiration\_date
object

Defines the conditions for the expiration date of a tier.

Attributes Description

type
string

What triggers the tier to expire for a customer.
END\_OF\_PERIOD : Expire tier at the end of the period.
END\_OF\_NEXT\_PERIOD : Expire tier at the end of the next period.

Available values: END\_OF\_PERIOD, END\_OF\_NEXT\_PERIOD

extend
string

Areas and Stores Campain Assignment

Attributes	Description
id `string`	Unique identifier of the campaign assignment. Example: arsca\_0ef5ee192117ae2416
area\_id `string`	Unique identifier of the area to which the campaign is assigned. Example: ar\_0ea6cd7b781b8f857f
all\_stores `boolean`	Determines if the campaign is assigned to all of the stores in the area, i.e. if an area ID is passed in the `access\_settings.assign.area\_all\_stores\_ids` in the request.
area\_store\_id `string`	Unique identifier of the store to which the campaign is assigned. Example: ars\_0ec347e2016bed85f4
created\_at `string`	Date and time when the assignment was made. The value is shown in the ISO 8601 format. Example: 2024-06-25T19:04:16.260Z
object `string`	The type of the object represented by JSON. This object stores information about the campaign assignment to areas or stores. Available values: `area\_store\_campaign\_assignment`

Balance Drop

Attributes Description

type
string

What triggers the tier to expire for a customer.
BALANCE\_DROP : Tier expires when the points balance drops below the required range of the tier.

Available values: BALANCE\_DROP

Custom

Attributes Description

type
string

What triggers the tier to expire for a customer.
CUSTOM : Tier expires after a certain time period passes following the instance the points balance drops below the required range of the tier.

Available values: CUSTOM

extend
string

Defines the amount of time the tier will remain active in ISO 8601 format. The expiration date counter starts at the moment when the customer reaches the minimum required points that are required to be in the tier. For example, a tier with a duration of P3M will be valid for a duration of 3 months.

rounding

Defines the rounding mechanism for tier expiration.

One of:

Calendar Periods
Specific Month

Calendar Periods

Attributes Description

type
string

Period to which the expiration will be rounded to.

MONTH : The expiration date will be rounded to the end of the month.
QUARTER : The expiration date will be rounded to the end of the quarter.
HALF\_YEAR : The expiration date will be rounded to the half year.
YEAR : The expiration date will be rounded to the end of the year.

Available values: MONTH, QUARTER, HALF\_YEAR, YEAR

strategy
string

Which portion of the given period should the rounding be applied to.

Available values: END

Specific Month

Attributes	Description
type `string`	This mechanism describes a custom rounding for the expiration date. Available values: `CUSTOM`
strategy `string`	Which portion of the given period should the rounding be applied to. Available values: `END`
unit `string`	Defines the type of unit of time in which the rounding period is counted. Available values: `MONTH`
value `integer`	Value for the unit of time that the rounding applies to. Units for this parameter are defined by the `rounding.unit` parameter. `0` : January `1` : February `2` : March `3` : April `4` : May `5` : June `6` : July `7` : August `8` : September `9` : October `10` : November `11` : December

# Loyalty Card Object Source: https://docs.voucherify.io/api-reference/loyalties/loyalty-card-object

Loyalty Card Object

Attributes Description

id
string

Assigned by the Voucherify API, identifies the voucher.

Example: v\_mkZN9v7vjYUadXnHrMza8W5c34fE5KiV

code
string

A code that identifies a voucher. Pattern can use all letters of the English alphabet, Arabic numerals, and special characters.

Example: WVPblOYX

campaign
string

A unique campaign name, identifies the voucher's parent campaign.

Example: Loyalty Card Campaign

campaign\_id
string

Assigned by the Voucherify API, identifies the voucher's parent campaign.

Example: camp\_FNYR4jhqZBM9xTptxDGgeNBV

category
string

Tag defining the category that this voucher belongs to.

category\_id
string

Unique category ID assigned by Voucherify.

Example: cat\_0bb343dee3cdb5ec0c

categories
array

Contains details about the category.

Array of Category

type
string

Defines the type of the voucher.

Available values: LOYALTY\_CARD

discount
object, null

Object representing discount parameters. Child attributes are present only if type is DISCOUNT\_VOUCHER. Defaults to null.

gift
object, null

Object representing gift parameters. Child attributes are present only if type is GIFT\_VOUCHER. Defaults to null.

loyalty\_card
object

Object representing loyalty card parameters. Child attributes are present only if type is LOYALTY\_CARD.

Attributes	Description
points `integer`	Total number of points added to the loyalty card over its lifespan. Example: 7000
balance `integer`	Points available for reward redemption. This is calculated as follows: `balance` \= `points` \- `expired\_points` \- `subtracted\_points` \- `redemption.redeemed\_points`. Example: 6970
next\_expiration\_date `string`	The next closest date when the next set of points are due to expire. Example: 2023-05-30
next\_expiration\_points `integer`	The amount of points that are set to expire next.

start\_date
string

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

Example: 2021-12-01T00:00:00.000Z

expiration\_date
string

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

Example: 2021-12-31T00:00:00.000Z

validity\_timeframe

See: Validity Timeframe

validity\_day\_of\_week

See: Validity Day Of Week

validity\_hours

See: Validity Hours

active
boolean

A flag to toggle the voucher on or off. You can disable a voucher even though it's within the active period defined by the start\_date and expiration\_date.

true indicates an active voucher
false indicates an inactive voucher

additional\_info
string

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

metadata
object

assets
object

Stores links to images of QR and barcode that correspond to an encrypted voucher code.

Attributes Description

qr
object

Stores Quick Response (QR) representation of encrypted code.

Attributes Description

id
string

Encrypted voucher code ID.

Example: U2FsdGVkX19ucFhvVmBVpVYG5KoswTsjSIaqoKg5L9ie4BK+t4pp7U7oFzjGJzj9q/bmuMOj9mEFiVKDMIkSaruKedMvHbKoPX5Sg+BaZk5QwXMf8k/OzSlOEVybpwSq+AiqPoNtjeuqtIgkDyvT6Q==

url
string

URL to QR code

Optional: Attach query parameters to base URL to customize the image of the encrypted voucher code.

size : integer value from 1 to 100
format : string, either png (default) or svg

barcode
object

Stores barcode representation of encrypted code.

Attributes Description

id
string

Encrypted voucher code ID.

Example: U2FsdGVkX19eJhGfWwUrH9+tulBkON+AnMktic+N6CVWzZ9+fHVxuVx22WakrzxiWXy0skuvvEHSeZIw9HlgyIJ+kJ1iPdUKpyENuNYJKzoZlO0mmTf6WQM6/pFs61apEn9SJx32ttCF6d3oxKISQQ==

url
string

URL to barcode

Optional: Attach query parameters to base URL to customize the image of the encrypted voucher code.

size : integer value from 1 to 100
format : string, either png (default) or svg

is\_referral\_code
boolean

Flag indicating whether this voucher is a referral code; true for campaign type REFERRAL\_PROGRAM.

created\_at
string

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

Example: 2021-12-22T10:13:06.487Z

updated\_at
string

Timestamp representing the date and time when the voucher was last updated in ISO 8601 format.

Example: 2021-12-22T10:14:45.316Z

holder\_id
string

Unique customer identifier of the redeemable holder. It equals to the customer ID assigned by Voucherify.

Example: cust\_eWgXlBBiY6THFRJwX45Iakv4

redemption
object

Stores a summary of redemptions that have been applied to the voucher.

Attributes	Description
quantity `integer`	How many times a voucher can be redeemed. A `null` value means unlimited.
redeemed\_quantity `integer`	How many times a voucher has already been redeemed. Example: 1
redeemed\_points `integer`	Total loyalty points redeemed. Example: 100000
object `string`	The type of the object represented is by default `list`. To get this list, you need to make a call to the endpoint returned in the url attribute.
url `string`	The endpoint where this list of redemptions can be accessed using a GET method. `/v1/vouchers//redemptions` Example: /v1/vouchers/WVPblOYX/redemptions?page=1\&limit=10

publish
object

This object stores a summary of publish events: an events counter and an endpoint which can be called to return details of each event. A publication is required for loyalty cards and referral codes. This object gets updated whenever a voucher has been published. Publication means assigning a code to a particular customer. Typically, a publication is made by distributing your codes to your customers, e.g. through Export to MailChimp or publish voucher API method.

Required	Optional
`type` : `LOYALTY\_CARD`	`type` : `DISCOUNT\_VOUCHER`
`is\_referral\_code` : `true`	`type` : `GIFT\_VOUCHER`

Attributes Description

object
string

The type of the object represented is by default list. To get this list, you need to make a call to the endpoint returned in the url attribute.

count
integer

Publication events counter.

Example: 0

url
string

The endpoint where this list of publications can be accessed using a GET method. /v1/vouchers//publications

Example: /v1/vouchers/WVPblOYX/publications?page=1\&limit=10

object
string

The type of the object represented by JSON. Default is voucher.

Category

Attributes	Description
id `string`	Unique category ID assigned by Voucherify.
name `string`	Category name.
hierarchy `integer`	Category hierarchy. Categories with lower hierarchy are processed before categories with higher hierarchy value.
object `string`	The type of the object represented by the JSON. This object stores information about the category. Available values: `category`
created\_at `string`	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
updated\_at `string`	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

Validity Timeframe

Attributes Description

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

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

Validity Day Of Week

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

Validity Hours

Attributes Description

daily
array

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

Array of:

Attributes Description

start\_time
string

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

Example: 12:00

days\_of\_week
array

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

expiration\_time
string

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

Example: 14:00

# Loyalty Tier Object Source: https://docs.voucherify.io/api-reference/loyalties/loyalty-tier-object

Loyalty Tier

All of:

Loyalty Tier Base

Attributes Description

id
string

Unique loyalty tier ID.

campaign\_id
string

Unique parent campaign ID.

metadata
object, null

created\_at
string

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

updated\_at
string, null

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

config
object

Defines loyalty tier range in points.

Attributes Description

points
object

Defines range of loyalty tier in points.

Attributes	Description
from `integer`	Bottom points threshold value.
to `integer`	Top points threshold value.

expiration

See: Loyalty Tier Expiration

object
string

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

Available values: loyalty\_tier

Loyalty Tier Base

Attributes Description

name
string

Loyalty Tier name.

earning\_rules
object

Contains a list of earning rule IDs and their points mapping for the given earning rule.

Attributes	Description
\[propertyName]	See: MappingPoints

rewards
object

Contains a list of reward IDs and their points mapping for the given reward.

Attributes	Description
\[propertyName]	See: MappingPoints

points
object

Defines range of loyalty tier in points.

Attributes	Description
from `integer`	Bottom points threshold value.
to `integer`	Top points threshold value.

Loyalty Tier Expiration

Attributes	Description
customer\_id `string`	Unique customer identifier of the customer making the purchase. The ID is assigned by Voucherify. Example: cust\_7iUa6ICKyU6gH40dBU25kQU1
campaign\_id `string`	Unique campaign ID, assigned by Voucherify. Example: camp\_rRsfatlwN7unSeUIJDCYedal
tier\_id `string`	Unique tier ID, assigned by Voucherify.
start\_date `string`	Activation timestamp defines when the loyalty tier starts to be active in ISO 8601 format. Loyalty tier is inactive before this date.
expiration\_date `string`	Expiration timestamp defines when the loyalty tier expires in ISO 8601 format. Loyalty tier is inactive after this date.
created\_at `string`	Timestamp representing the date and time when the loyalty tier was created. The value is shown in the ISO 8601 format. Example: 2021-12-22T10:13:06.487Z
updated\_at `string`	Timestamp representing the date and time when the loyalty tier was updated. The value is shown in the ISO 8601 format. Example: 2021-12-22T10:13:06.487Z

MappingPoints

One of:

MappingMultiply
MappingFixed

MappingMultiply

Attributes Description

type
string

Type of calculation.

Available values: MULTIPLY

multiplier
number

Multiplication factor used to multiply the points to obtain the mapped points.

MappingFixed

Attributes Description

type
string

Type of calculation.

Available values: CUSTOM

points
integer

Fixed number of points to be applied.

# Redeem Reward Source: https://docs.voucherify.io/api-reference/loyalties/redeem-reward /openapi/loyalties.json post /v1/loyalties/members/{memberId}/redemption Legacy loyalty API This endpoint belongs to the legacy loyalty API (`/v1/loyalties`). Voucherify will not develop new features for this API. However, critical issues may still receive fixes. For new integrations, use [Loyalty v2](/build/loyalty-overview). If you have questions, contact [Voucherify support](https://www.voucherify.io/contact-support "Contact Voucherify support"). Alternative endpoint This endpoint is an alternative to this [endpoint](/api-reference/loyalties/redeem-reward-with-campaign-id). The URL was re-designed to allow you to redeem a reward without having to provide the `campaignId` as a path parameter. # Redeem Reward with campaign ID Source: https://docs.voucherify.io/api-reference/loyalties/redeem-reward-with-campaign-id /openapi/loyalties.json post /v1/loyalties/{campaignId}/members/{memberId}/redemption Legacy loyalty API This endpoint belongs to the legacy loyalty API (`/v1/loyalties`). Voucherify will not develop new features for this API. However, critical issues may still receive fixes. For new integrations, use [Loyalty v2](/build/loyalty-overview). If you have questions, contact [Voucherify support](https://www.voucherify.io/contact-support "Contact Voucherify support"). Exchange points from a loyalty card for a specified reward. This API method returns an assigned award in the response. It means that if a requesting customer gets a coupon code with a discount for the next order, that discount code will be visible in response as part of the reward object definition. # Transfer Loyalty Points Source: https://docs.voucherify.io/api-reference/loyalties/transfer-loyalty-points /openapi/loyalties.json post /v1/loyalties/{campaignId}/members/{memberId}/transfers Legacy loyalty API This endpoint belongs to the legacy loyalty API (`/v1/loyalties`). Voucherify will not develop new features for this API. However, critical issues may still receive fixes. For new integrations, use [Loyalty v2](/build/loyalty-overview). If you have questions, contact [Voucherify support](https://www.voucherify.io/contact-support "Contact Voucherify support"). Transfer points between different loyalty cards which have holders. Provide the campaign ID and the loyalty card ID you want the points to be transferred to as path parameters. In the request body, provide the loyalty cards you want the points to be transferred from and the number of points to transfer from each card. Transfer works only for loyalty cards that have holders, meaning the cards were published to customers. The transferred points expire according to the target program expiration rules. # Update Campaign Reward Assignment Source: https://docs.voucherify.io/api-reference/loyalties/update-campaign-reward-assignment /openapi/loyalties.json put /v1/loyalties/{campaignId}/rewards/{assignmentId} Legacy loyalty API This endpoint belongs to the legacy loyalty API (`/v1/loyalties`). Voucherify will not develop new features for this API. However, critical issues may still receive fixes. For new integrations, use [Loyalty v2](/build/loyalty-overview). If you have questions, contact [Voucherify support](https://www.voucherify.io/contact-support "Contact Voucherify support"). Updates rewards parameters, i.e. the points cost for the specific reward. # Update Earning Rule Source: https://docs.voucherify.io/api-reference/loyalties/update-earning-rule /openapi/loyalties.json put /v1/loyalties/{campaignId}/earning-rules/{earningRuleId} Legacy loyalty API This endpoint belongs to the legacy loyalty API (`/v1/loyalties`). Voucherify will not develop new features for this API. However, critical issues may still receive fixes. For new integrations, use [Loyalty v2](/build/loyalty-overview). If you have questions, contact [Voucherify support](https://www.voucherify.io/contact-support "Contact Voucherify support"). Update an earning rule definition. # Update Loyalty Campaign Source: https://docs.voucherify.io/api-reference/loyalties/update-loyalty-campaign /openapi/loyalties.json put /v1/loyalties/{campaignId} Legacy loyalty API This endpoint belongs to the legacy loyalty API (`/v1/loyalties`). Voucherify will not develop new features for this API. However, critical issues may still receive fixes. For new integrations, use [Loyalty v2](/build/loyalty-overview). If you have questions, contact [Voucherify support](https://www.voucherify.io/contact-support "Contact Voucherify support"). Updates a loyalty program. Fields other than those specified in the allowed request body payload won't be modified (even if provided they are silently skipped). Any parameters not provided will be left unchanged. This method will update the [loyalty cards](/api-reference/loyalties/get-member) which have not been published or redeemed yet. # Loyalty v2 API: Overview Source: https://docs.voucherify.io/api-reference/loyalty-v2-api-overview Map the Loyalty v2 API under /v2/loyalties: Programs, reusable components, members, examine, and reports The Loyalty v2 API lives under `/v2/loyalties`. It manages modular loyalty programs: Reusable components (card definitions, earning rules, rewards, benefits, and tier structures), program assignments, members and their cards, dry-run examine calls, and aggregated reports. This is the entry point into the API reference. For product concepts and the **Loyalty hub**, see [Loyalty program overview](/build/loyalty-overview). For an integration-oriented map of the member journey, see [Loyalty v2 developer overview](/guides/loyalty-v2-overview). Legacy `/v1/loyalties` remains in maintenance mode. For new integrations, use Loyalty v2. See [Legacy loyalty API](/api-reference/loyalties/introduction-to-legacy-loyalty). ## How resources connect Loyalty v2 separates configuration from runtime membership: * **Components** are created independently under their own paths (`/card-definitions`, `/earning-rules`, `/rewards`, `/benefits`, `/tier-structures`). * A **program** (`/programs`) is the container that assigns those components into one customer-facing setup. Activation requires at least one active card definition (point wallet in the dashboard) and one active earning rule. * **Members** enroll under a program. Voucherify issues one loyalty card per active card definition assigned to that program. * **Examine** endpoints estimate earnings and reward availability without writing balances. * **Reports** return aggregated program and member statistics for dashboards and analytics. Many integrations configure the program in the dashboard (**Loyalty hub**), then automate only the runtime member journey through the API. ## API groups Create and manage programs, and assign wallets, earning rules, tiers, and rewards. Enroll members, read memberships, adjust points, list transactions, pay with points, and purchase rewards. Dry-run earning and reward evaluation for member portals and checkout previews. Configure point wallets: pending points, expiration, limits, and pay-with-points exchange. Define triggers and earnings for orders, custom events, and segment entry. Build the reward catalog members can purchase with points. Define automatic material or digital grants from earning rules. Configure tier levels and read tier progress on memberships. Read aggregated spending, earnings, tier movements, and earning-rule statistics. ## Core objects and identifiers Loyalty v2 uses program-scoped resources. Store these IDs in your system and pass the correct type on each call. | Object | ID prefix | Role in the integration | | ------------------------------ | -------------- | ---------------------------------------------------------- | | Program | `lprg_` | Parent container for wallets, rules, rewards, and members | | Card definition (point wallet) | `lcdef_` | Defines how points behave on cards issued from that wallet | | Member | `lmbr_` | Program-specific enrollment of a Voucherify customer | | Loyalty card | `lcrd_` | Point balance for one wallet on one member | | Earning rule | `lern_` | Trigger and effects that grant points or benefits | | Reward | `lrew_` | Catalog item members can purchase with points | | Benefit | `lben_` | Automatic grant (material or digital) from an earning rule | | Tier structure / tier | `lts_` / `lt_` | Levels and progress tied to a point wallet | | Customer (shared) | `cust_` | Must exist before enrollment; not loyalty-specific | Do not interchange `cust_…` and `lmbr_…`. Member endpoints expect a member ID. Membership lookup can use a customer ID with the correct identification type. Mixing IDs is a common cause of `404` responses. See [Take loyalty v2 to production](/guides/loyalty-v2-take-to-production#troubleshooting). ## Shared platform APIs Loyalty v2 does not replace the rest of the Voucherify API. Runtime flows still use: * [Authentication](/guides/authentication) and regional base URLs from [API overview](/guides/api-overview#choose-the-right-api-endpoint) * [Customers](/api-reference/customers/create-customer) before membership * [Orders](/api-reference/orders/create-order) with `status: PAID` for order-paid earning rules and pay with points * [Custom events](/api-reference/events/track-custom-event) for event-based earning rules * Discount or gift [campaigns](/build/campaign-overview) when rewards or benefits issue vouchers or credits * [Async actions](/api-reference/async-actions/get-async-action) for background enrollment ## Related resources * [Loyalty v2 developer overview](/guides/loyalty-v2-overview) for the member journey, constraints, and documentation map. * [Integrate loyalty v2](/guides/loyalty-v2-integrate) for step-by-step API flows with example payloads. * [Take loyalty v2 to production](/guides/loyalty-v2-take-to-production) for go-live and troubleshooting. * [Loyalty program overview](/build/loyalty-overview) for the product model and rollout context. * [Loyalty key concepts](/build/loyalty-key-concepts) for point wallets, earning rules, rewards, tiers, and benefits. * [Legacy loyalty API](/api-reference/loyalties/introduction-to-legacy-loyalty) for the maintenance-mode `/v1/loyalties` endpoints. # Benefits overview Source: https://docs.voucherify.io/api-reference/loyalty-v2-benefits-overview Understand how benefits let Loyalty v2 earning rules grant points, material items, or digital incentives automatically A benefit is a value granted automatically to a member when an earning rule's conditions are met. It can serve as an alternative to earning points on a loyalty card or it can be used alongside points. Members don't redeem benefits themselves; they simply receive one once they fulfill the conditions of the earning rule that references it. Benefits are optional and are only useful once connected to at least one earning rule. ## Benefit types A benefit must define exactly one type-specific configuration object that matches its `type`: * `points`: A fixed number of points added to a card. * `points_proportional`: Points calculated proportionally to a triggering value, such as order amount. * `material`: A physical product or SKU. * `digital`: A discount coupon or gift card. ## Stock Like rewards, benefits can be limited in quantity through a `stock` configuration. When omitted, a benefit defaults to `UNLIMITED` stock, meaning it can be granted as many times as its earning rule is triggered. ## Referenced resources Depending on its type, a benefit references other resources: A card definition for points-based benefits, or a product/SKU/campaign for material and digital benefits. These references are validated on create and update; for example, a points-based benefit can only be activated if its connected card definition is itself `ACTIVE`. ## Lifecycle A benefit is created in `DRAFT` status by default, and only moves between `DRAFT` and `ACTIVE` through the activate and draft endpoints. There is no `INACTIVE` state. While in `DRAFT`, every property can be updated; once `ACTIVE`, only `name` and `stock` can still be changed. Two safeguards protect benefits that are already wired into your program: * A benefit that's referenced by any earning rule can't be deleted until that reference is removed. * A benefit connected to an active earning rule can't be moved back to `DRAFT`. ## Related resources * [Loyalty v2 API: Overview](/api-reference/loyalty-v2-api-overview) for the full Loyalty v2 API map. * [Earning Rules overview](/api-reference/loyalty-v2-earning-rules-overview) for how benefits are triggered. * [Rewards overview](/api-reference/loyalty-v2-rewards-overview) for the point-redeemable counterpart to benefits. * [Create benefits](/build/create-benefits) for the dashboard perspective on configuring benefits. # Card definitions: Overview Source: https://docs.voucherify.io/api-reference/loyalty-v2-card-definitions-overview Understand how card definitions configure the loyalty cards (point wallets) that store and govern a member's points in Loyalty v2 A card definition is the configuration blueprint for a loyalty card. In the **Loyalty hub** dashboard, this resource is called a **point wallet**. Every loyalty card a member holds is generated from a card definition, which controls how points on that card are held, spent, returned, and eventually expired. A loyalty program can reference multiple card definitions. When a customer becomes a member of a program, Voucherify automatically creates one loyalty card for each active card definition assigned to that program, so a member can hold several point balances at once (for example, a standard points wallet and a separate seasonal-promotion wallet). ## What a card definition controls Besides `name` and `type`, a card definition groups several independent configuration sections. Any section left out on creation falls back to a permissive default: * `code_config`: The pattern used to generate loyalty card codes (defaults to a 10-character alphanumeric pattern). * `points_expiration`: Whether and how points expire (defaults to `NO_EXPIRATION`). * `pending_points`: Whether newly earned points are available immediately or held back for a period, until a fixed date, or until an activation event (defaults to `IMMEDIATE`). * `earning_limits` and `spending_limits`: Global and per-transaction caps on how many points a member can earn or spend (default to `NO_LIMIT`). * `refunds`: What happens to earned or spent points when a related order is refunded (default to `NONE`). * `balance_settings`: Whether the card balance is allowed to go negative (defaults to disallowed). * `pay_with_points`: The exchange ratio formula used when members pay for orders with points. ## Lifecycle A card definition is created in `DRAFT` status by default. Use the activate and draft endpoints to move it between `DRAFT` and `ACTIVE`: * `DRAFT` > `ACTIVE`: Makes the card definition eligible to be assigned to a program and used for new loyalty cards. * `ACTIVE` > `DRAFT`: Makes the card definition editable again. However, you can't change the statue to `DRAFT` once it has been assigned to a program. Once a card definition is `ACTIVE` and in use – for example assigned to a program that already issued cards from it – most configuration sections become locked to protect existing point balances. Only `name`, `metadata`, and `pay_with_points` can always be updated regardless of usage; other sections may be rejected with a resource-locked error until the card definition is no longer referenced. ## How card definitions fit into a program Card definitions are standalone resources, created and managed independently of any single program, then connected through the [Programs](/api-reference/loyalty-v2-programs-overview) assignment endpoints. A program needs at least one active card definition before it can itself become `ACTIVE`. An active card definition can be deleted or removed from a program only when the program itself is deleted first. Every activity performed on a card definition, like creation, updates, status transitions, and program assignments, is recorded and available through its [activity history endpoint](/api-reference/card-definitions/list-card-definition-activities). The `activities` endpoint is useful for auditing configuration changes over time. ## Related resources * [Loyalty v2 API: Overview](/api-reference/loyalty-v2-api-overview) for the full Loyalty v2 API map. * [Create point wallets](/build/create-point-wallets) for the point wallet concept as presented in the dashboard. * [Programs overview](/api-reference/loyalty-v2-programs-overview) to see how card definitions are assigned to a program. * [Members overview](/api-reference/loyalty-v2-members-overview) to see how loyalty cards are issued to members from active card definitions. * [Integrate loyalty v2](/guides/loyalty-v2-integrate) for an end-to-end integration walkthrough. # Earning rules: Overview Source: https://docs.voucherify.io/api-reference/loyalty-v2-earning-rules-overview Understand how earning rules define when and how Loyalty v2 members earn points or receive benefits An earning rule defines when a member earns points or receives another configured result for something they did. Each earning rule combines a trigger, optional conditions, and one or more earnings. Voucherify evaluates a member's earning rules and applies the first matching earning configuration for the triggering event. ## Triggers An earning rule reacts to one of three triggers: * **Order paid**: Triggered after an order is successfully paid and can calculate points proportionally to the order or item amounts. * **Custom event**: Triggered when a selected custom event is sent to Voucherify. * **Segment entered**: Triggered when a member enters a selected customer segment. ## Conditions and earnings Beyond the trigger itself, a rule can require that the member belongs to a specific loyalty tier, or that the triggering event meets additional criteria (for example, a minimum order amount). Each earning inside the rule then defines its effect, typically adding points to a point wallet, but an earning can also grant a benefit instead of points. A single rule can hold multiple earnings, evaluated in order, with the first matching one applied. Additionally, you can override the general point expiration settings set for a card definition by setting a custom expiration rules for the points earned by an earning rule. ## Trigger limits Trigger limits control how often a rule is allowed to fire for the same member: A cooldown period between triggers, and/or a frequency cap over a time window. When omitted, a rule defaults to no cooldown and no frequency limit, meaning it can fire every time its trigger occurs. ## Lifecycle An earning rule is created in `DRAFT` status unless `status` is specified explicitly. From there: * `DRAFT` or `INACTIVE` > `ACTIVE` with the [activate endpoint](/api-reference/earning-rules/activate-earning-rule). * `ACTIVE` > `INACTIVE` with the [deactivate endpoint](/api-reference/earning-rules/deactivate-earning-rule). * `ACTIVE` > `DRAFT` with the [draft endpoint](/api-reference/earning-rules/move-earning-rule-to-draft). Once a rule leaves `DRAFT`, only a some of its properties can still be changed, like name, earnings, error handling, validity hours, start/end dates, trigger limits, and metadata. However, trigger and condition definitions can't be edited. Deleting a rule performs a soft delete and keeps its last state for reference. You can delete only an earning rule that's not currently assigned to a program. ## Assigning earning rules to a program Earning rules are created independently of any program and connected through the [Programs](/api-reference/loyalty-v2-programs-overview) batch assignment endpoint. Unlike card definitions, earning rules can be assigned or unassigned while the program is `ACTIVE`, as long as the program keeps at least one active earning rule. ## Related resources * [Loyalty v2 API: Overview](/api-reference/loyalty-v2-api-overview) for the full Loyalty v2 API map. * [Programs overview](/api-reference/loyalty-v2-programs-overview) for overall program management. * [Benefits overview](/api-reference/loyalty-v2-benefits-overview) for the benefit effect an earning can grant. * [Examine overview](/api-reference/loyalty-v2-examine-overview) to simulate what an earning rule would grant before it fires. * [Reports overview](/api-reference/loyalty-v2-reports-overview) for program and member earning-rule usage statistics. * [Create earning rules](/build/create-earning-rules) for the dashboard perspective on earning rules. # Examine: Overview Source: https://docs.voucherify.io/api-reference/loyalty-v2-examine-overview Understand how the examine endpoints estimate earning opportunities and reward availability for a Loyalty v2 member without any side effects The examine endpoints let you evaluate what a member could earn or redeem across their loyalty program memberships, without creating any transactions or otherwise changing stored data. Because they are pure dry-run operations, you can call them as often as needed to power member-facing UI, such as "ways to earn" screens or reward catalogs. ## Examine earning rules The examine earning rule endpoint estimates the points and benefits a member would receive for a given scenario. You choose a trigger mode: * `ALL`: Evaluates every active earning rule across the member's programs at once, useful for showing all the available ways a member can earn points in a single call. * `SPECIFIC`: Evaluates only the earning rules tied to one event – an order being paid, a customer entering a segment, or a custom event. This mode requires the matching context object for that event (for example, order line items for `customer.order.paid`). The response lists the estimated points per card and per earning rule, plus any material or digital benefits that would be granted. Because the estimation is a single dry-run pass, it does not chain further consequences of the earned points; for example, it won't simulate a tier upgrade that itself unlocks additional points. ## Examine rewards This endpoint evaluates every reward assigned to a member's active program memberships and reports whether each one is currently redeemable on each of the member's cards. You can scope the evaluation to a single membership with `member_id`. Each reward on each card is classified as: * `AVAILABLE`: The member has an active card for the reward's card definition, the card balance covers the resolved point cost, and the reward assignment has stock. * `UNAVAILABLE`: Accompanied by one or more structured reasons, such as `insufficient_balance` (with the exact points still missing), `out_of_stock`, `no_matching_cost`, `no_card_for_cost`, or `reward_inactive`. The structured unavailability reasons are designed so your frontend doesn't need to guess why a reward is greyed out. You can use the same response to render progress bars or "points needed" messaging. ## Related resources * [Loyalty v2 API: Overview](/api-reference/loyalty-v2-api-overview) for the full Loyalty v2 API map. * [Earning rules: Overview](/api-reference/loyalty-v2-earning-rules-overview) for how to configure rules for gaining points and benefits. * [Rewards: Overview](/api-reference/loyalty-v2-rewards-overview) for how to manage rewards. * [Members: Overview](/api-reference/loyalty-v2-members-overview) for overall member management. * [Integrate loyalty v2](/guides/loyalty-v2-integrate) for worked examples of both examine endpoints. # Members: Overview Source: https://docs.voucherify.io/api-reference/loyalty-v2-members-overview Understand how customers are enrolled as members of a Loyalty v2 program, and how their loyalty cards, points, rewards, and payments are managed A member is a Voucherify customer enrolled in a specific loyalty program. Membership is program-scoped. The same customer can be a member of several programs at once, but only once per program; a second enrollment attempt for the same customer is rejected. The customer must already exist in Voucherify, and the target program must be `ACTIVE` before it can accept new members. ## Enrollment Members can be [created one at a time](/api-reference/programs/create-program-member), or in bulk through a [batch endpoint](/api-reference/programs/batch-create-program-members) that processes up to 10 MB of entries asynchronously in batches of 100, tracked as an [async action](/api-reference/async-actions/async-action-object). When a member is created, Voucherify automatically issues one loyalty card for every active card definition assigned to the program, so a member can start with several point wallets at once. Card `code` generation happens asynchronously, so a newly created card's `code` may briefly be `null`. ## Member lifecycle A member is typically `ACTIVE` on creation, but can also be created as `INACTIVE`. Use the [activate](/api-reference/programs/activate-program-member) and [deactivate](/api-reference/programs/deactivate-program-member) endpoints to move a member between these two states. An inactive member can't earn or spend points. Updating a member merges metadata into the existing object and cannot change `status`; use activate or deactivate for status transitions. Deleting a member soft-deletes the member and its cards. ## Loyalty cards and points Each of a member's loyalty cards tracks its own balance, lifetime point counters, and upcoming activation or expiration events. Beyond the automatic earning and spending flows, several endpoints let you manage points on a specific card directly: * Manually [adjust points](/api-reference/programs/adjust-card-points) (positive values create an admin credit, negative values an admin debit). * [List](/api-reference/programs/list-card-pending-points-buckets), and optionally manually [activate](/api-reference/programs/activate-a-pending-points-bucket) or [cancel](/api-reference/programs/cancel-a-pending-points-bucket), pending points buckets before their scheduled activation date. * [List](/api-reference/programs/list-card-expiring-points-buckets), and optionally manually [expire](/api-reference/programs/expire-points-bucket), expiring points buckets before their scheduled expiration date. * List [the full transaction history](/api-reference/programs/list-card-transactions) of a card. Aggregated daily points and earning-rule usage for a member are covered in the [Reports overview](/api-reference/loyalty-v2-reports-overview). ## Rewards and payments Members spend points in two ways, both scoped to a member's card: * [Purchasing a reward](/api-reference/programs/purchase-reward-with-points): Spends points from the card tied to the reward's cost configuration, and can later be refunded, which returns the points to the card. * [Paying for an order with points](/api-reference/programs/pay-for-order-with-points): Spends points based on the card definition's pay-with-points exchange ratio, capped by the card balance or an optional payment limit, and can be run as a dry run before committing to a real transaction. Members also expose read-only history for benefit fulfillments and tier transitions (joins, upgrades, downgrades, prolongations, and exits), so you can build a complete activity feed for a member without combining several other endpoints. ## Member vs. membership Related endpoints return a member's data from different angles: * [Get member](/api-reference/programs/get-program-member) returns the member together with its cards within one program. * [Get program membership](/api-reference/programs/get-program-membership) additionally enriches each card with tier progress. Use it whenever your integration needs to show progress toward the next loyalty tier. * [Get customer memberships](/api-reference/programs/get-customer-memberships) returns every membership for a customer across programs, including member, program, and cards. Membership lookups accept a path identifier interpreted through `identification_type` (for example customer ID or member ID). ## Related resources * [Loyalty v2 API: Overview](/api-reference/loyalty-v2-api-overview) for the full Loyalty v2 API map. * [Programs: Overview](/api-reference/loyalty-v2-programs-overview) for overall program management. * [Card definitions: Overview](/api-reference/loyalty-v2-card-definitions-overview) for how to manage card definitions. * [Rewards: Overview](/api-reference/loyalty-v2-rewards-overview) for how to manage rewards. * [Tier structures: Overview](/api-reference/loyalty-v2-tier-structures-overview) for how to manage tier structures. * [Reports: Overview](/api-reference/loyalty-v2-reports-overview) for member card and earning-rule daily reports. * [Integrate loyalty v2](/guides/loyalty-v2-integrate) for a step-by-step member integration walkthrough. # Programs: Overview Source: https://docs.voucherify.io/api-reference/loyalty-v2-programs-overview Understand how a Loyalty v2 program connects card definitions, earning rules, tier structures, and rewards into one customer-facing loyalty setup A loyalty program is the container that ties the individual Loyalty v2 building blocks, like card definitions (point wallets), earning rules, tier structures, and rewards, into a single, customer-facing loyalty setup. Members join a program, not an individual card definition or earning rule, which is what lets a program combine several of these components into one experience. ## Program status A program is created in `DRAFT` status by default, and can be created directly as `ACTIVE` if it already has the required assignments. To become or remain `ACTIVE`, a program must have at least one active card definition and at least one active earning rule assigned; otherwise activation is rejected. Deleting a program soft-deletes it and removes all of its card definition, earning rule, reward, and tier structure assignments. ## Assigning components to a program Card definitions, earning rules, tier structures, and rewards are all created independently (see their respective overview pages) and then connected to a program through dedicated assignment endpoints. Most component types use a batch endpoint that can assign and unassign multiple items in a single request; unassign operations are always processed before assign operations, and, in the default strict mode, any missing resource or missing assignment fails the whole batch. A few rules are specific to each component: * Card definitions: They can be assigned or unassigned one at a time or in a batch, but only while the program is in `DRAFT` status. Unassigning fails if the card definition is still referenced by an earning rule, reward, or tier structure assigned to the same program. * Earning rules: They can be assigned or unassigned at any time, but if the program is `ACTIVE`, the batch is validated to leave at least one active earning rule assigned. * Tier structures: A program can have at most one tier structure assigned, and it can't be unassigned once the program's \`ACTIVE. * Rewards: Each reward being assigned must include its stock configuration, which can later be updated through a dedicated endpoint without going through the batch flow. Reward purchases can also be refunded through a program-scoped refund endpoint. ## Reporting Aggregated program and member reports, like spending, points earnings, tier movements, and earning-rule evaluations, live in the [Reports](/api-reference/loyalty-v2-reports-overview) group. Use those endpoints for dashboards and analytics rather than reconstructing metrics from activity or transaction lists. ## Activity history Every change to a program, like creation, updates, deletion, activation, deactivation, and assignment changes, is recorded and available through its [activity history endpoint](/api-reference/programs/list-program-activities). The program activity endpoint gives you an audit trail independent of your own event logging. ## Related resources * [Loyalty v2 API: Overview](/api-reference/loyalty-v2-api-overview) for the full Loyalty v2 API map. * [Card definitions: Overview](/api-reference/loyalty-v2-card-definitions-overview) for how to manage card definitions. * [Earning rules: Overview](/api-reference/loyalty-v2-earning-rules-overview) for how to manage earning rules. * [Tier structures: Overview](/api-reference/loyalty-v2-tier-structures-overview) for how to manage tier structures. * [Rewards: Overview](/api-reference/loyalty-v2-rewards-overview) for how to manage rewards. * [Members: Overview](/api-reference/loyalty-v2-members-overview) for enrolling customers into a program. * [Reports: Overview](/api-reference/loyalty-v2-reports-overview) for program-level analytics. * [Loyalty program overview](/build/loyalty-overview) for the dashboard perspective on programs. # Reports: Overview Source: https://docs.voucherify.io/api-reference/loyalty-v2-reports-overview Understand how Loyalty v2 report endpoints return aggregated spending, earnings, tier movements, and earning-rule statistics for programs and members Reports return read-only, aggregated statistics for a loyalty program or for a specific member within that program. Use them for dashboards, operational monitoring, and analytics – not for reconstructing individual transactions. Transaction and activity list endpoints are for per-event details. Every report endpoint is scoped under a program (`programId`). Member-scoped reports additionally require `memberId` and either a card or an earning rule identifier. ## Program reports Program reports cover four metric families. Each family exposes a daily breakdown over a date range and an all-time summary. | Metric family | What it measures | Optional filters | | --------------- | ------------------------------------------------------------------------------------------------ | ----------------------------- | | Spending | Points spent across the program | Card definition | | Points earnings | Points earned across the program | Earning rule, card definition | | Tiers | Tier movements (joins, upgrades, downgrades, and related events) | Tier structure, tier | | Earning rules | Earning-rule evaluation outcomes, including success and failure counts with a failures breakdown | Earning rule | Daily endpoints require `start_date`, `end_date`, and `resolution`. Summary endpoints return totals for the lifetime of the program (subject to any filters you pass). ## Member reports There are two member-scoped daily reports: * [Card daily points](/api-reference/programs/get-card-daily-points-report): Aggregated points statistics for one of the member's loyalty cards over a date range and resolution. * [Earning-rule daily](/api-reference/programs/get-member-earning-rule-daily-report): Aggregated usage statistics for one earning rule and one member over a date range and resolution. These endpoints do not have summary counterparts in the Reports group. For per-transaction detail on a card, use the card transactions list under [Members](/api-reference/loyalty-v2-members-overview). ## Date range and resolution Daily reports share the same resolution options and range caps. | `resolution` | Maximum date range | | ------------ | ------------------ | | `day` | 90 days | | `week` | 12 weeks | | `month` | 12 months | | `quarter` | 4 quarters | `start_date` and `end_date` use `YYYY-MM-DD`. `end_date` must be after `start_date`. Requests that exceed the resolution's range limit are rejected. ## Filters Program reports accept optional `filters` query parameters that narrow results by resource ID. For example, `filters[card_definition_id][conditions][$is]=lcdef_…` can be used with spending reports, or `filters[tier_id][conditions][$is]=lt_…` with tier reports. Filters use the same condition-operator shape as other Loyalty v2 and general Voucherify API list endpoints. The tiers summary report also accepts `limit` and `order` to page and sort its result set (defaults: `limit=100`, `order=-id`). ## Related resources * [Loyalty v2 API: Overview](/api-reference/loyalty-v2-api-overview) for the full Loyalty v2 API map. * [Programs overview](/api-reference/loyalty-v2-programs-overview) for the program container these reports aggregate. * [Members overview](/api-reference/loyalty-v2-members-overview) for card transactions and member activity. * [Earning Rules overview](/api-reference/loyalty-v2-earning-rules-overview) for the rules measured by earning-rule reports. * [Tier Structures overview](/api-reference/loyalty-v2-tier-structures-overview) for the tiers measured by tier reports. * [Loyalty v2 developer overview](/guides/loyalty-v2-overview) for integration orientation. # Rewards overview Source: https://docs.voucherify.io/api-reference/loyalty-v2-rewards-overview Understand how rewards let Loyalty v2 members redeem their points for material products or digital incentives A reward is what a member actively redeems by spending points, unlike a [benefit](/api-reference/loyalty-v2-benefits-overview), which is granted automatically by an earning rule. Rewards are optional and only become redeemable once assigned to a program with a stock configuration. ## Reward types A reward requires `name`, `type`, and `costs`, plus exactly one type-specific object matching its `type`: * `MATERIAL`: A physical product or SKU, defined in the `material` object. * `DIGITAL`: A discount coupon or gift card, defined in the `digital` object. ## Costs and program assignment A reward's `costs` array can define a different point price per card definition, so the same reward can be connected to multiple point wallets – even across different programs – each with its own price. The reward itself doesn't carry stock; stock is set per program when the reward is assigned through the [Programs](/api-reference/loyalty-v2-programs-overview) batch assignment endpoint, and can be updated afterwards without going through the batch flow again. ## Validity and refunds A reward can define `validity_hours` to restrict when it's redeemable (defaulting to any time), and `refunds` behavior for what happens to spent points when a reward purchase is refunded. ## Lifecycle A reward can be created directly in `DRAFT` or `ACTIVE` status. From there, it follows the same three-state pattern as earning rules and tier structures: `DRAFT`/`INACTIVE` > `ACTIVE` with the [reward activate endpoint](/api-reference/rewards/activate-reward), `ACTIVE` > `INACTIVE` with the [reward deactivate endpoint](/api-reference/rewards/deactivate-reward), and `ACTIVE` > `DRAFT` with the [reward draft endpoint](/api-reference/rewards/move-reward-back-to-draft) for unassigned rewards. While in `DRAFT`, every property can be updated; once active or inactive, only `name`, `metadata`, `refunds`, `validity_hours`, `start_date`, `end_date`, and `costs` can still change. Deleting a reward moves it to a `DELETED` status. ## Redeeming and checking availability Members redeem rewards through the [member reward-purchase endpoint](/api-reference/programs/purchase-reward-with-points), which spend points from the card tied to the reward's cost configuration and can later be [refunded](/api-reference/programs/refund-a-reward-purchase). Before building a redemption flow, use the [Examine overview](/api-reference/loyalty-v2-examine-overview) endpoint to check which rewards a member can currently afford and why any others are unavailable. ## Related resources * [Loyalty v2 API: Overview](/api-reference/loyalty-v2-api-overview) for the full Loyalty v2 API map. * [Programs overview](/api-reference/loyalty-v2-programs-overview) for assigning rewards and their stock to a program. * [Members overview](/api-reference/loyalty-v2-members-overview) for purchasing and refunding rewards. * [Benefits overview](/api-reference/loyalty-v2-benefits-overview) for the automatically granted counterpart to rewards. * [Create loyalty rewards](/build/create-loyalty-rewards) for the dashboard perspective on configuring rewards. # Tier structures: Overview Source: https://docs.voucherify.io/api-reference/loyalty-v2-tier-structures-overview Understand how tier structures define the tiering model that determines how Loyalty v2 members qualify for and move between tiers A tier structure defines the tiering model for a loyalty program: the levels members can reach, and the rule that decides which level a member currently qualifies for. Tier structures are optional. A program can run entirely on points and rewards without any tiers. ## Tier structure types A tier structure qualifies members based on exactly one of two measures, set through its `type`: * `POINT_BALANCE`: The member's current point balance on the associated card. * `POINT_EARNED`: The total points the member has earned over a given period, regardless of how many have since been spent or expired. Only the configuration object matching the chosen type (`point_balance` or `point_earned`) can be set; the other must be left empty. If not specified, a tier structure defaults to no tier expiration (`NO_RETENTION`) and no automatic downgrade (`NO_DOWNGRADE`). ## Tiers Each tier structure contains its own nested tiers (like Bronze, Silver, and Gold) managed through dedicated create, list, update, and delete endpoints scoped to the parent structure. A tier structure can hold a maximum of 100 tiers. Each tier can define its own downgrade behavior, or inherit the parent structure's setting, which is the default when not specified. It can also set tier point expiration which will govern how points are retained when the member is in the tier. ## Lifecycle A tier structure is created in `DRAFT` status by default, and moves between `DRAFT`, `ACTIVE`, and `INACTIVE` through the [activate](/api-reference/tier-structures/activate-tier-structure), [deactivate](/api-reference/tier-structures/deactivate-tier-structure), and [move tier structure back to draft](/api-reference/tier-structures/move-tier-structure-to-draft) endpoints – the same three-state pattern used by earning rules and rewards. Once a tier structure (or one of its tiers) leaves `DRAFT`, only `name` and `metadata` can still be updated. The qualification logic itself stays fixed to protect members already progressing through the tiers. ## Assigning a tier structure to a program A program can have at most one tier structure assigned at a time, connected through the [program batch assignment endpoint](/api-reference/programs/batch-assignunassign-tier-structures). Unassigning a tier structure is only allowed while the program is in `DRAFT` status. Once the program is active, you can't unassign a tier structure. This prevents members from losing their tier context on a live program. ## Related resources * [Loyalty v2 API: Overview](/api-reference/loyalty-v2-api-overview) for the full Loyalty v2 API map. * [Programs overview](/api-reference/loyalty-v2-programs-overview) for assigning a tier structure to a program. * [Members overview](/api-reference/loyalty-v2-members-overview) to see a member's tier progress. * [Reports overview](/api-reference/loyalty-v2-reports-overview) for program-level tier movement statistics. * [Create tier structures](/build/create-tier-structures) for the dashboard perspective on configuring tiers. * [Loyalty key concepts](/build/loyalty-key-concepts#tier-structure) for the underlying tier concepts. # Assign User Source: https://docs.voucherify.io/api-reference/management/assign-user /openapi/management.json post /management/v1/projects/{projectId}/users Assigns a user to a given project. The user must be an existing user in Voucherify. Correct Use of Data To avoid errors, use the `"role"` key with either `"id"` or `"login"` keys. # Copy Campaign Template to a Project Source: https://docs.voucherify.io/api-reference/management/copy-campaign-template-to-a-project /openapi/management.json post /management/v1/projects/{projectId}/templates/campaigns/{campaignTemplateId}/copy Copies a campaign template to another project. The resources, like validation rules or products, will not be copied to the destination project yet. When the template is used to create a new campaign or add a new promotion tier, the resources will be created in the destination project. Campaign Templates – Documentation Read the [Campaign Templates documentation](/build/campaign-templates) to learn more about this feature. # Create Brand Source: https://docs.voucherify.io/api-reference/management/create-brand /openapi/management.json post /management/v1/projects/{projectId}/branding Creates a new brand configuration. You can have only one brand configured for a project. White Labelling The white labelling settings which can be found in Project Settings > Brand Details and which are available only for Enterprise clients as a separate service can be configured only in the user interface. # Create Custom Event Schema Source: https://docs.voucherify.io/api-reference/management/create-custom-event-schema /openapi/management.json post /management/v1/projects/{projectId}/custom-event-schemas Creates a custom event schema. The `"properties"` object is required, but it can be empty, however. This object is for optional custom properties (metadata). Custom Event Documentation Read [Custom Events](/prepare/custom-events) article to learn how custom events work in Voucherify. Read also the details about the [Track Custom Event](/api-reference/events/track-custom-event) endpoint and the [Custom Event Object](/api-reference/events/event-object). # Create Metadata Schema Source: https://docs.voucherify.io/api-reference/management/create-metadata-schema /openapi/management.json post /management/v1/projects/{projectId}/metadata-schemas Creates a new metadata (custom attribute) schema for a given resource. The schema consists of a set of key-value pairs to customize Voucherify resources. You can nest your object within a standard metadata schema, e.g. within a campaign or customer schema. However, your nested object can't include another nested object. The standard metadata schemas are: - Campaign - Voucher - Publication - Redemption - Product - Customer - Order - Order line item - Loyalty Tier - Promotion Tier - Earning rule - Reward Use this endpoint to define a metadata schema of a given resource for the first time. Once you configure a metadata schema for a given `related_object`, use the PUT [Update metadata schema](/api-reference/management/update-metadata-schema) endpoint to either update or add new metadata key-value pairs. For example, use this endpoint to define a metadata schema for `related_object: campaign` for the first time. If you want define a new metadata property for `campaign`, use the [PUT Update metadata schema](/api-reference/management/update-metadata-schema) endpoint. Metadata Documentation Read [the Getting Started with Metadata](/prepare/metadata) and [Metadata Mapping](/guides/metadata-mapping) articles to learn how metadata work in Voucherify. # Create Project Source: https://docs.voucherify.io/api-reference/management/create-project /openapi/management.json post /management/v1/projects Creates a new project. You can add users, specify the cluster, timezone, currency, and other details. All owners are added to the project by default. # Create Stacking Rules Source: https://docs.voucherify.io/api-reference/management/create-stacking-rules /openapi/management.json post /management/v1/projects/{projectId}/stacking-rules Overwrites the default stacking rules. If new stacking rules have been created for the project earlier (e.g. in the user interface), it returns an error. Use [Update stacking rules](/api-reference/management/update-stacking-rules) endpoint to change the rules. Stacking rules documentation Read [the Stacking rules article](/orchestrate/stacking-rules) to learn how they work. # Create Webhook Source: https://docs.voucherify.io/api-reference/management/create-webhook /openapi/management.json post /management/v1/projects/{projectId}/webhooks Creates a new webhook configuration. Webhook Documentation Read [Introduction to webhooks](/api-reference/introduction-to-webhooks) article to learn how webhooks work in Voucherify. # Delete Brand Source: https://docs.voucherify.io/api-reference/management/delete-brand /openapi/management.json delete /management/v1/projects/{projectId}/branding/{brandingId} Deletes permanently a brand configuration. # Delete Custom Event Schema Source: https://docs.voucherify.io/api-reference/management/delete-custom-event-schema /openapi/management.json delete /management/v1/projects/{projectId}/custom-event-schemas/{customEventSchemaId} Deletes permanently the custom event schema with its custom properties (metadata). Custom Event Documentation Read [Custom Events](/prepare/custom-events) article to learn how custom events work in Voucherify. Read also the details about the [Track Custom Event](/api-reference/events/track-custom-event) endpoint and the [Custom Event Object](/api-reference/events/event-object). # Delete Metadata Schema Source: https://docs.voucherify.io/api-reference/management/delete-metadata-schema /openapi/management.json delete /management/v1/projects/{projectId}/metadata-schemas/{metadataSchemaId} Deletes permanently the metadata schema. In standard metadata schemas, this endpoint removes permanently all definitions. The standard metadata schemas are: - Campaign - Voucher - Publication - Redemption - Product - Customer - Order - Order line item - Loyalty Tier - Promotion Tier - Earning rule - Reward If you want to delete only one definition, use the [Update Metadata Schema](/api-reference/management/update-metadata-schema) endpoint. In the request, provide the `"deleted": true` pair in the definition object. This definition will be moved to Removed definitions. If you want to create a new standard metadata schema, use the [Create Metadata Schema](/api-reference/management/create-metadata-schema) endpoint. Metadata Purging This endpoint deletes permanently the metadata schemas only. However, it does not purge the metadata from associated entities, so the metadata added to those entities will remain. If you want to purge metadata from the entities: 1. Remove all the definitions you want to purge. You can do this either in Voucherify Project Settings > Metadata Schema tab or with the [Update Metadata Schema](/api-reference/management/update-metadata-schema) endpoint. 2. In Voucherify Project Settings > Metadata Schema tab, go to the relevant metadata schema. 3. In Removed definitions, click the bin button next to the definitions whose metadata you want to purge from entities. Note: - This is an asynchronous action. You will be notified when it has been completed. - You cannot purge metadata for the Redemption and Publication schemas. 4. Use the Delete Metadata Schema request to delete the metadata schema from Voucherify. Metadata Documentation Read [the Getting Started with Metadata](/prepare/metadata) and [Metadata Mapping](/guides/metadata-mapping) articles to learn how metadata work in Voucherify. # Delete Project Source: https://docs.voucherify.io/api-reference/management/delete-project /openapi/management.json delete /management/v1/projects/{projectId} Deletes an existing project. The users currently using the deleted project will be automatically logged out. Sandbox Project The sandbox project cannot be deleted. # Delete Stacking Rules Source: https://docs.voucherify.io/api-reference/management/delete-stacking-rules /openapi/management.json delete /management/v1/projects/{projectId}/stacking-rules/{stackingRulesId} Deletes permanently the current settings for the stacking rules. The stacking rules are restored to default values. Stacking Rules Documentation Read [the Stacking rules article](/orchestrate/stacking-rules) to learn how they work. # Delete Webhook Source: https://docs.voucherify.io/api-reference/management/delete-webhook /openapi/management.json delete /management/v1/projects/{projectId}/webhooks/{webhookId} Deletes a webhook configuration. Webhook Documentation Read [Introduction to webhooks](/api-reference/introduction-to-webhooks) article to learn how webhooks work in Voucherify. # Get Brand Source: https://docs.voucherify.io/api-reference/management/get-brand /openapi/management.json get /management/v1/projects/{projectId}/branding/{brandingId} Retrieves a brand configuration. # Get Custom Event Schema Source: https://docs.voucherify.io/api-reference/management/get-custom-event-schema /openapi/management.json get /management/v1/projects/{projectId}/custom-event-schemas/{customEventSchemaId} Retrieves a custom event schema. Custom Event Documentation Read [Custom Events](/prepare/custom-events) article to learn how custom events work in Voucherify. Read also the details about the [Track Custom Event](/api-reference/events/track-custom-event) endpoint and the [Custom Event Object](/api-reference/events/event-object). # Get Metadata Schema Source: https://docs.voucherify.io/api-reference/management/get-metadata-schema /openapi/management.json get /management/v1/projects/{projectId}/metadata-schemas/{metadataSchemaId} Retrieves a metadata schema. Metadata Documentation Read [the Getting Started with Metadata](/prepare/metadata) and [Metadata Mapping](/guides/metadata-mapping) articles to learn how metadata work in Voucherify. # Get Project Source: https://docs.voucherify.io/api-reference/management/get-project /openapi/management.json get /management/v1/projects/{projectId} Retrieves an existing project. # Get Stacking Rules Source: https://docs.voucherify.io/api-reference/management/get-stacking-rules /openapi/management.json get /management/v1/projects/{projectId}/stacking-rules/{stackingRulesId} Retrieves the stacking rules for the project. Stacking Rules Documentation Read [the Stacking rules article](/orchestrate/stacking-rules) to learn how they work. # Get User Source: https://docs.voucherify.io/api-reference/management/get-user /openapi/management.json get /management/v1/projects/{projectId}/users/{userId} Retrieves the project user's details. # Get Webhook Source: https://docs.voucherify.io/api-reference/management/get-webhook /openapi/management.json get /management/v1/projects/{projectId}/webhooks/{webhookId} Retrieves a webhook configuration. Webhook Documentation Read [Introduction to webhooks](/api-reference/introduction-to-webhooks) article to learn how webhooks work in Voucherify. # Invite a New User Source: https://docs.voucherify.io/api-reference/management/invite-a-new-user /openapi/management.json post /management/v1/projects/users/invite Sends an invitation to an email address that has not been used yet as a Voucherify user login. You can specify the projects to which the invited user will be assigned and define their roles. # List Brands Source: https://docs.voucherify.io/api-reference/management/list-brands /openapi/management.json get /management/v1/projects/{projectId}/branding Lists all brand configurations. Because a project can have only one brand, it always returns a list with one item. This endpoint can be used to retrieve the brand configuration created with the Voucherify Dashboard and the ID. # List Campaign Templates Source: https://docs.voucherify.io/api-reference/management/list-campaign-templates /openapi/management.json get /management/v1/projects/{projectId}/templates/campaigns Lists all campaign templates available in the project. List Campaign Templates This endpoint works in the same way as the [List Campaign Templates endpoint](/api-reference/templates/list-campaign-templates). Campaign Templates – Documentation Read the [Campaign Templates documentation](/build/campaign-templates) to learn more about this feature. # List Custom Event Schemas Source: https://docs.voucherify.io/api-reference/management/list-custom-event-schemas /openapi/management.json get /management/v1/projects/{projectId}/custom-event-schemas Lists all custom event schemas available in the project. Custom Event Documentation Read [Custom Events](/prepare/custom-events) article to learn how custom events work in Voucherify. Read also the details about the [Track Custom Event](/api-reference/events/track-custom-event) endpoint and the [Custom Event Object](/api-reference/events/event-object). # List Metadata Schemas Source: https://docs.voucherify.io/api-reference/management/list-metadata-schemas /openapi/management.json get /management/v1/projects/{projectId}/metadata-schemas Lists all metadata schemas available in the project. Metadata Documentation Read [the Getting Started with Metadata](/prepare/metadata) and [Metadata Mapping](/guides/metadata-mapping) articles to learn how metadata work in Voucherify. # List Projects Source: https://docs.voucherify.io/api-reference/management/list-projects /openapi/management.json get /management/v1/projects Lists all projects for the organization. The endpoint does not require any query parameters. # List Stacking Rules Source: https://docs.voucherify.io/api-reference/management/list-stacking-rules /openapi/management.json get /management/v1/projects/{projectId}/stacking-rules Lists all stacking rules. Returns always a list with one item. This endpoint can be used to retrieve the default stacking rules. The default stacking rules do not have an ID that could be used with the [Get Stacking Rules](/api-reference/management/get-stacking-rules) or [Update Stacking Rules](/api-reference/management/update-stacking-rules) endpoints. Stacking Rules Documentation Read [the Stacking rules article](/orchestrate/stacking-rules) to learn how they work. # List Users Source: https://docs.voucherify.io/api-reference/management/list-users /openapi/management.json get /management/v1/projects/{projectId}/users Lists all users assigned to the project. # List Webhooks Source: https://docs.voucherify.io/api-reference/management/list-webhooks /openapi/management.json get /management/v1/projects/{projectId}/webhooks Lists all webhook configurations for the project. Webhook Documentation Read [Introduction to webhooks](/api-reference/introduction-to-webhooks) article to learn how webhooks work in Voucherify. # Unassign User Source: https://docs.voucherify.io/api-reference/management/unassign-user /openapi/management.json delete /management/v1/projects/{projectId}/users/{userId} Unassigns the user from the project. If the user is currently logged in, they are automatically logged out. If the user is assigned to only one project, they cannot be unassigned from that project. # Update Brand Source: https://docs.voucherify.io/api-reference/management/update-brand /openapi/management.json put /management/v1/projects/{projectId}/branding/{brandingId} Updates a brand configuration. Only the fields sent in the request will be updated. The fields omitted in the request will remain unchanged. White Labelling The white labelling settings which can be found in Project Settings > Brand Details and which are available only for Enterprise clients as a separate service can be configured only in the user interface. # Update Custom Event Schema Source: https://docs.voucherify.io/api-reference/management/update-custom-event-schema /openapi/management.json put /management/v1/projects/{projectId}/custom-event-schemas/{customEventSchemaId} Updates a custom event schema. With this request, you can: - Add a nonexistent property to a custom event schema. - Update an existing property. In the request, you can provide only those properties you want to add or update. Definitions omitted in the request remain unchanged. Additional Notes - You can change the type of an existing property, e.g. from `"string"` to `"number"`. - You can remove a custom property with this endpoint by providing `"deleted": true` in the request. However, you cannot permanently remove an event definition or its property with this endpoint. Custom Event Documentation Read [Custom Events](/prepare/custom-events) article to learn how custom events work in Voucherify. Read also the details about the [Track Custom Event](/api-reference/events/track-custom-event) endpoint and the [Custom Event Object](/api-reference/events/event-object). # Update Metadata Schema Source: https://docs.voucherify.io/api-reference/management/update-metadata-schema /openapi/management.json put /management/v1/projects/{projectId}/metadata-schemas/{metadataSchemaId} Updates a metadata schema. With this request, you can: - Add a nonexistent attribute definition to the metadata schema. - Update an existing attribute definition by overwriting its current values. In the request, you can provide only those definitions you want to add or update. Definitions omitted in the request remain unchanged. However, if you want to update a definition, you will have to add all its current key-value pairs as well. Only the pairs sent in the request are saved for this definition. This means that the key-value pairs that are not sent in a request are restored to default values. For example, if your definition has an array with values and it is not sent in an update request, the array values will be deleted. Additional Notes - You cannot change the type of an existing schema, e.g. from `"string"` to `"number"`. - You can remove a definition with this endpoint by providing `"deleted": true` in the request. It will be moved to the Removed definitions section in the user interface. However, you cannot permanently remove a definition with this endpoint. Metadata Documentation Read [the Getting Started with Metadata](/prepare/metadata) and [Metadata Mapping](/guides/metadata-mapping) articles to learn how metadata work in Voucherify. # Update Project Source: https://docs.voucherify.io/api-reference/management/update-project /openapi/management.json put /management/v1/projects/{projectId} Updates an existing project. You can add or modify settings for timezone, currency, notifications, and other details. Only the fields sent in the request will be updated. # Update Stacking Rules Source: https://docs.voucherify.io/api-reference/management/update-stacking-rules /openapi/management.json put /management/v1/projects/{projectId}/stacking-rules/{stackingRulesId} Updates the stacking rules. Only the provided fields will be updated. However, if you update an array, the content of the array is overwritten. This means that if you want to add new values to an array and retain existing ones, you need to provide both the existing and new values in the request. Stacking Rules Documentation Read [the Stacking rules article](/orchestrate/stacking-rules) to learn how they work. # Update User Source: https://docs.voucherify.io/api-reference/management/update-user /openapi/management.json put /management/v1/projects/{projectId}/users/{userId} Updates the user's role. # Update Webhook Source: https://docs.voucherify.io/api-reference/management/update-webhook /openapi/management.json put /management/v1/projects/{projectId}/webhooks/{webhookId} Updates a webhook configuration. The `"events"` listed in the request are overwritten. If you want to add more events, provide also the events that are already in the webhook configuration. Webhook Documentation Read [Introduction to webhooks](/api-reference/introduction-to-webhooks) article to learn how webhooks work in Voucherify. # Get Metadata Schema Source: https://docs.voucherify.io/api-reference/metadata-schemas/get-metadata-schema /openapi/metadata-schemas.json get /v1/metadata-schemas/{resource} Retrieves a metadata schema per resource type. ## Resource types ### Standard You can retrieve metadata schemas for the standard metadata schema definitions listed below. Add one of these types as the resource path parameter. - `campaign` - `customer` - `earning_rule` - `loyalty_tier` - `order` - `order_item` - `product` - `promotion_tier` - `publication` - `redemption` - `reward` - `voucher` ### Custom If you have defined a [custom metadata schema](/prepare/metadata#add-metadata), provide its name in the `"resource"` field to retrieve its details. Management API If you have Management API enabled, you can also use the [Get Metadata Schemas](/api-reference/management/get-metadata-schema) endpoint to retrieve a metadata schema using its ID. # List Metadata Schema Definitions Source: https://docs.voucherify.io/api-reference/metadata-schemas/list-metadata-schema-definitions /openapi/metadata-schemas.json get /v1/metadata-schemas Retrieve metadata schema definitions. Management API If you have Management API enabled, you can also use the [List Metadata Schemas](/api-reference/management/list-metadata-schemas) endpoint to list all metadata schemas. # Metadata Schema Object Source: https://docs.voucherify.io/api-reference/metadata-schemas/metadata-schema-object

Metadata Schema Object

Attributes Description

id
string

Unique metadata schema ID.

Example: ms\_OF36L2rk4EqhdxvZs56IW9iE

related\_object
string

The resource type. There is an infinite number of possibilities for the resource type because you can define custom metadata schemas. Some examples are included here to show you the standard metadata schema resource types.

Available values: campaign, customer, earning\_rule, loyalty\_tier, order, order\_item, product, promotion\_tier, publication, redemption, reward, voucher

properties
object

Contains the metadata definitions. There can be many properties within this object.

Attributes Description

custom\_property\_name
object

Custom property name. This is defined in Project Settings > Metadata Schema in the Dashboard.

Attributes	Description
type `string`	Available values: `string`, `number`, `object`, `date`, `datetime`, `geopoint`, `boolean`, `image\_url`
array `boolean`	Indicates whether the definition is an array.
optional `boolean`	Indicates whether this definition is optional or not optional for the resource.
objectType `string`, `null`	Returns the name of the custom resource if the resource was previously defined in the Dashboard as a custom (non-standard) Nested object.
eq `array`	Array of possible values when the setting for `is equal to any of` in the Dashboard is defined explicitly.
ne `array`	Array of values that are not allowed when the setting for `is not equal to any of` in the Dashboard is defined explicitly.
lt `integer`	A property of `number` type must have `less than` this value.
lte `integer`	A property of `number` type must be `less than or equal` to this value.
gt `integer`	A property of `number` type must be `greater than` this value.
gte `integer`	A property of `number` type must be `greater than or equal` to this value.
deleted `boolean`	Indicates whether the definition was deleted from the schema.
maxLength `integer`	Value for maximum length when the setting for `has maximum length of` in the Dashboard is defined explicitly.
minLength `integer`	Value indicating minimum length when the setting for `has minimum length of` in the Dashboard is defined explicitly.
exactLength `integer`	Value indicating exact length when the setting for `has exact length of` in the Dashboard is defined explicitly.

allow\_defined\_only
boolean

Restricts the creation of metadata fields when set to true. In other words, it indicates whether or not you are allowed to create new metadata definitions; for example, in the campaign manager or publication manager. If it is set to true, then only the defined fields will be available for assigning values.

created\_at
string

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

Example: 2021-12-03T13:33:44.556Z

updated\_at
string

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

Example: 2022-08-11T08:05:30.695Z

object
string

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

# Generate OAuth 2.0 Token Source: https://docs.voucherify.io/api-reference/oauth/generate-oauth-20-token /openapi/oauth.json post /v1/oauth/token Generate an OAuth 2.0 token for an API client. The token can be used to authorize access to the Voucherify API. The token inherits the permissions and IP whitelists of the API key that is used to generate the OAuth token. You can define the scope that limits its usage. You can generate up to 1000 OAuth tokens per project. The token expires in 900 seconds (15 minutes). If the API key that is used to generate the OAuth token is deleted or blocked, you cannot generate new OAuth tokens and the existing ones will stop working within one minute. If the API key used to generate an OAuth token is regenerated, the OAuth token can still be used. Format of scope values Separate the values of the `scope` property with spaces. # Introspect OAuth 2.0 Token Source: https://docs.voucherify.io/api-reference/oauth/introspect-oauth-20-token /openapi/oauth.json post /v1/oauth/introspect Introspect an OAuth 2.0 token for an API client. # Revoke OAuth 2.0 Token Source: https://docs.voucherify.io/api-reference/oauth/revoke-oauth-20-token /openapi/oauth.json post /v1/oauth/token/revoke Revoke an OAuth 2.0 token for an API client. Once revoked, the token cannot be used anymore. # Object Schemas Source: https://docs.voucherify.io/api-reference/object-schemas Schema model definitions You can find the object definitions for the given schemas by navigating to the respective endpoint and viewing the response schema definition and examples. | **API** | **Object** | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Vouchers | [Voucher object](/api-reference/vouchers/voucher-object) | | Campaigns | [Campaign object](/api-reference/campaigns/campaign-object) | | Promotions | [Promotion tier object](/api-reference/promotions/promotion-tier-object) | | Rewards | [Reward object](/api-reference/rewards/reward-object)[Reward assignment object](/api-reference/rewards/reward-assignment-object) | | Publications | [Publication object](/api-reference/publications/publication-object) | | Validations | [Validation object](/api-reference/validations/validation-object) | | Redemptions | [Redemption object](/api-reference/redemptions/redemption-object)[Redemption rollback object](/api-reference/redemptions/redemption-rollback-object) | | Stackable Discounts | [Stackable Redemptions object](/api-reference/redemptions/stackable-redemptions-object) | | Loyalties | [Loyalty campaign object](/api-reference/loyalties/loyalty-campaign-object)[Loyalty card object](/api-reference/loyalties/loyalty-card-object)[Earning rule object](/api-reference/loyalties/earning-rule-object)[Loyalty tier object](/api-reference/loyalties/loyalty-tier-object) | | Customers | [Customer object](/api-reference/customers/customer-object)[Customer activity object](/api-reference/customers/customer-activity-object) | | Orders | [Order object](/api-reference/orders/order-calculated-object) | | Products | [Product object](/api-reference/products/product-object)[SKU object](/api-reference/products/sku-object) | | Product Collections | [Product collection object](/api-reference/product-collections/product-collection-object) | | Validation Rules | [Validation rule object](/api-reference/validation-rules/validation-rule-object)[Validation rule assignment object](/api-reference/validation-rules/validation-rule-assignment-object) | | Segments | [Segment object](/api-reference/segments/segment-object) | | Events | [Event object](/api-reference/events/event-object) | | Async Actions | [Async action object](/api-reference/async-actions/async-action-object) | | Exports | [Export object](/api-reference/exports/export-object) | | Categories | [Category object](/api-reference/categories/category-object) | | Metadata Schemas | [Metadata schema object](/api-reference/metadata-schemas/metadata-schema-object) | # Create Order Source: https://docs.voucherify.io/api-reference/orders/create-order /openapi/orders.json post /v1/orders Creates an order object and triggers an order creation event. Upsert Mode If you pass an `id` or a `source_id` that already exists in the order database, Voucherify will return a related order object with updated fields. # Create Orders Export Source: https://docs.voucherify.io/api-reference/orders/create-orders-export /openapi/orders.json post /v1/orders/export Creates a downloadable CSV file containing a list of orders. The parameters listed in the payload resembles headers in the CSV file. To include a parameter to the file, add it to the `parameters.fields` object in the request body. The available filters are all [order object](/api-reference/orders/order-calculated-object) attributes. Additionally, any metadata defined in the metadata schema can be exported. Passing an empty JSON will generate a file containing three default fields: `id`, `source_id`, and `status`. The fields array is an array of strings containing the data in the export. These fields define the headers in the CSV file. The array can be a combination of any of the following available fields: | **Field** | **Definition** | **Example Export** | |:---|:---|:---| | `id` | Unique order ID. | ord_A69RIxEdRsPuC6i8gFGVHUft | | `source_id` | Unique order source ID. | 8638 | | `created_at` | Timestamp in ISO 8601 format representing the date and time when the order was created. | 2022-03-09T09:16:32.521Z | | `updated_at` | Timestamp in ISO 8601 format representing the date and time when the order was last updated. | 2022-03-09T09:16:33.331Z | | `status` | Order status. | `PAID`, `CREATED`, `FULFILLED`, `CANCELED` | | `amount` | Total amount of order items. | 7700 | | `discount_amount` | Represents total amount of the discount applied to whole cart. | 500 | | `items_discount_amount` | Represents total amount of the discount applied to order line items. | 100 | | `total_discount_amount` | All discounts applied to the order including discounts applied to particular order line items and discounts applied to the whole cart. | 600 | | `total_amount` | Total order amount after applying all discounts. | 7100 | | `customer_id` | Customer unique ID. | cust_2G4fUQdCXUqp35nXNleav7bO | | `referrer_id` | Referrer unique ID. | cust_IkrTR674vvQvr9a4rDMiqglY | | `metadata` | Returns all order metadata. | Response will include all order metadata. | | `metadata.X` | Where X is the name of a particular order metadata property. | The returned value will depend on the type of data defined in the Dashboard > Project Settings > Metdata Schemas > Order. | # Get Order Source: https://docs.voucherify.io/api-reference/orders/get-order /openapi/orders.json get /v1/orders/{orderId} Retrieve a specific order by passing its ID. # Import Orders Source: https://docs.voucherify.io/api-reference/orders/import-orders /openapi/orders.json post /v1/orders/import Historical orders This endpoint should only be used to import historical orders into Voucherify. For on-going synchronization, the [update order](/api-reference/orders/update-order) endpoint should be used. This is critical because this endpoint does not store events or launch distributions. The orders will also have a `created_at` date that's assigned when they've been imported to Voucherify. To keep track of the actual order creation date, add an order metadata in ISO 8601 date or date time format to each imported order. ## Limitations ### Import volume There can be only a single on-going order import per tenant per project at a given time. The user can schedule more imports but those extra imports will be scheduled to run in sequence one by one. ### Maximum count of orders in single import There is a `2000` limit of orders per one request. ## Notifications There are no notifications on the Dashboard because this import is launched via the API. ## Triggered actions If you import orders with customers, then a logic will be scheduled responsible for placing these customers into segments and refreshing the segment's summary. Consequently, this update will trigger - Customers entering into segments - Distributions based on any rules tied to customer entering segment(s) - Earning rules based on the customer entering segment(s) ## What is not triggered 1. No webhooks are triggered during the import of orders - for both orders and upserted products / SKUs. 2. Distributions based on Order Update, Order Paid, Order Created and Order Cancelled. In other words if you have a distribution based on Order Paid and you import an order with a `PAID` status, the distribution is not going to be triggered. 3. No events are created during the import of orders - for both orders and upserted products / SKUs. In other words you won't see any events in the Activity tab in the Dashboard such as Order created or Order paid. If you are additionally upserting products / SKUs, then you won't see the Product created events listed, etc. 4. Earning rules based on Order Paid won't be triggered. This API request starts a process that affects Voucherify data in bulk. In case of small jobs (like bulk update) the request is put into a queue and processed once every other bulk request placed in the queue prior to this request is finished. However, when the job takes a longer time (like vouchers generation) then it is processed in small portions in a round-robin fashion. When there is a list of vouchers generation scheduled, then they will all have the `IN_PROGRESS` status shortly. This way, small jobs added just after scheduling big jobs of the same type will be processed in a short time window. The result will return the async ID. You can verify the status of your request with [GET Async Action](/api-reference/async-actions/get-async-action) endpoint. # List Orders Source: https://docs.voucherify.io/api-reference/orders/list-orders /openapi/orders.json get /v1/orders Returns a list of orders. # Order Calculated Object Source: https://docs.voucherify.io/api-reference/orders/order-calculated-object

Order Calculated No Customer Data

Attributes Description

id
string

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

source\_id
string, null

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

status
string

The order status.

Available values: CREATED, PAID, CANCELED, FULFILLED

amount
integer

This is the sum of the order items' amounts. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for \$1.00).

initial\_amount
integer

discount\_amount
integer

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\_discount\_amount
integer

Sum of all product-specific discounts applied to the order. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for \$1.00).

total\_discount\_amount
integer

Sum of all order-level AND all product-specific discounts applied to the order. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for \$1.00).

total\_amount
integer

Order amount after undoing all the discounts through the rollback redemption. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for \$1.00).

applied\_discount\_amount
integer

This field shows the order-level discount applied. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for \$1.00).

items\_applied\_discount\_amount
integer

total\_applied\_discount\_amount
integer

metadata
object

object
string

The type of the object represented by JSON.

Available values: order

created\_at
string

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

Example: 2021-12-22T10:13:06.487Z

updated\_at
string, null

Timestamp representing the date and time when the order was last updated in ISO 8601 format.

Example: 2021-12-22T10:14:45.316Z

customer\_id
string, null

Unique customer identifier of the customer making the purchase. The ID is assigned by Voucherify.

Example: cust\_7iUa6ICKyU6gH40dBU25kQU1

referrer\_id
string, null

Unique referrer ID.

Example: cust\_nM4jqPiaXUvQdVSA6vTRUnix

customer

Customer Id

referrer

Referrer Id

redemptions
object

Attributes	Description
\[propertyName]	See: Order Redemptions

Customer Id

Attributes Description

id
string

A unique identifier of an existing customer.

object
string

The type of the object represented by JSON.

Available values: customer

Referrer Id

Customer Id

Order Redemptions

Attributes	Description
date `string`	Timestamp representing the date and time when the redemption was created. The value is shown in the ISO 8601 format. Example: 2022-09-02T17:06:56.649Z
rollback\_id `string`	Unique ID of the redemption rollback. Example: rr\_0c63c84eb78ee0a6c0
rollback\_date `string`	Timestamp representing the date and time when the redemption rollback was created. The value is shown in the ISO 8601 format. Example: 2023-01-31T14:18:37.150Z
related\_object\_type `string`	The source of the incentive.
related\_object\_id `string`	Unique ID of the parent redemption. Example: r\_0ba186c4824e4881e1
related\_object\_parent\_id `string`	Represent's the campaign ID of the voucher if the redemption was based on a voucher that was part of bulk codes generated within a campaign. In case of a promotion tier, this represents the campaign ID of the promotion tier's parent campaign.
stacked `array`	Contains a list of unique IDs of child redemptions, which belong to the stacked incentives.
rollback\_stacked `array`	Lists the rollback redemption IDs of the particular child redemptions.

# Update Order Source: https://docs.voucherify.io/api-reference/orders/update-order /openapi/orders.json put /v1/orders/{orderId} Updates the specified order by setting the values of the parameters passed in the request body. Any parameters not provided will be left unchanged. # Create Product Collection Source: https://docs.voucherify.io/api-reference/product-collections/create-product-collection /openapi/product-collections.json post /v1/product-collections This method creates a new product collection. # Delete Product Collection Source: https://docs.voucherify.io/api-reference/product-collections/delete-product-collection /openapi/product-collections.json delete /v1/product-collections/{productCollectionId} This method deletes a product collection. # Get Product Collection Source: https://docs.voucherify.io/api-reference/product-collections/get-product-collection /openapi/product-collections.json get /v1/product-collections/{productCollectionId} Retrieves the product collection. # List Product Collections Source: https://docs.voucherify.io/api-reference/product-collections/list-product-collections /openapi/product-collections.json get /v1/product-collections This method returns a list of product collections. # List Products in Collection Source: https://docs.voucherify.io/api-reference/product-collections/list-products-in-collection /openapi/product-collections.json get /v1/product-collections/{productCollectionId}/products Retrieves list of products from a product collection; works for both dynamic and static product collections. # Product Collection Object Source: https://docs.voucherify.io/api-reference/product-collections/product-collection-object

Product Collection Base

Attributes Description

id
string

Product collection ID.

name
string

Unique user-defined product collection name.

Example: All Products

type
string

Describes whether the product collection is dynamic (products come in and leave based on set criteria) or static (manually selected products).

Available values: STATIC, AUTO\_UPDATE

filter
object

Defines a set of criteria and boundary conditions for an AUTO\_UPDATE product collection type.

Attributes	Description
junction	See: Junction
\[propertyName]	Valid keys: `id`, `product\_id`, `source\_id`, `name`, `price`, `object`, `attributes`, `image\_url`, `skus`, `created\_at`, `updated\_at` and `metadata.\*` Field Conditions

products
array

Defines a set of products for a STATIC product collection type.

Array of:

Product Collections Item Products Item

Attributes Description

id
string

The product ID.

Example: prod\_0a41bcf807c5fcaaf6

product\_id
string

Product ID for SKUs.

object
string

Denotes the type of the object represented by the ID.

Available values: sku, product

created\_at
string

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

Example: 2021-12-09T12:51:29.898Z

object
string

The type of the object represented by JSON. This object stores information about the static product collection.

Available values: products\_collection

Junction

Available values: and, or

Field Conditions

Attributes	Description
conditions	Data filters used to narrow down the data records to be returned in the result. Filters Condition

Filters Condition

Attributes	Description
\$in	See: Any
\$not\_in	See: Any
\$is	See: Any
\$is\_days\_ago	See: Any
\$is\_days\_in\_future	See: Any
\$is\_not	See: Any
\$has\_value	See: Any
\$is\_unknown	See: Any
\$contains	See: Any
\$not\_contain	See: Any
\$starts\_with	See: Any
\$ends\_with	See: Any
\$more\_than	See: Any
\$less\_than	See: Any
\$more\_than\_ago	See: Any
\$less\_than\_ago	See: Any
\$more\_than\_future	See: Any
\$less\_than\_future	See: Any
\$more\_than\_equal	See: Any
\$less\_than\_equal	See: Any
\$after	See: Any
\$before	See: Any
\$count	See: Any
\$count\_less	See: Any
\$count\_more	See: Any

Any

Array any of:

string
string
string
number
object

# Update Product Collection Source: https://docs.voucherify.io/api-reference/product-collections/update-product-collection /openapi/product-collections.json put /v1/product-collections/{productCollectionId} Updates the product collection. For `STATIC` collections, you can update only the `name`. For `AUTO_UPDATE` collections, you can update its `name` and `filters`. # Create Product Source: https://docs.voucherify.io/api-reference/products/create-product /openapi/products.json post /v1/products Creates a product object. Upsert Mode If you pass an `id` or a `source_id` that already exists in the product database, Voucherify will return a related product object with updated fields. # Create SKU Source: https://docs.voucherify.io/api-reference/products/create-sku /openapi/products.json post /v1/products/{productId}/skus This method adds product variants to a [created product](/api-reference/products/create-product). Upsert Mode If you pass an `id` or a `source_id` that already exists in the sku database, Voucherify will return a related sku object with updated fields. # Delete Product Source: https://docs.voucherify.io/api-reference/products/delete-product /openapi/products.json delete /v1/products/{productId} Deletes a product and all related SKUs. This operation cannot be undone. If the `force` parameter is set to `false` or not set at all, the product and all related SKUs will be moved to [the bin](/api-reference/bin/list-bin-entries). # Delete SKU Source: https://docs.voucherify.io/api-reference/products/delete-sku /openapi/products.json delete /v1/products/{productId}/skus/{skuId} Deletes a product SKU. This operation cannot be undone. If the `force` parameter is set to `false` or not set at all, the SKU will be moved to [the bin](/api-reference/bin/list-bin-entries). # Get Product Source: https://docs.voucherify.io/api-reference/products/get-product /openapi/products.json get /v1/products/{productId} Retrieve details of a given product and its SKUs, if any. # Get SKU Source: https://docs.voucherify.io/api-reference/products/get-sku /openapi/products.json get /v1/skus/{skuId} Retrieve details of a SKU. # Import Products using CSV Source: https://docs.voucherify.io/api-reference/products/import-products-using-csv /openapi/products.json post /v1/products/importCSV Import products into the repository using a CSV file. The CSV file has to include headers in the first line. Standard product fields mapping - Create a **comma separated value (CSV) file** or download our CSV import template. You can find an example template [here](https://s3.amazonaws.com/helpscout.net/docs/assets/5902f1c12c7d3a057f88a36d/attachments/627b82ed68d51e779443f550/Import_products_template.csv). - Supported CSV file headers: `name,source_id,price,attributes,image_url,Metadata_property_name` - **Name** is a **required** field. The remaining fields in the CSV template are optional. - Override/Update products' **names** in Voucherify using this method. Data will be updated for each product included in the CSV file whose **source_id** matches a source ID in Voucherify. No other data can be updated other than the product name. - Note that dates and date-time attributes need to be provided in compliance with the **ISO 8601 standard**. For example, 2022-03-11T09:00:00.000Z or 2022-03-11 - `YYYY-MM-DD` - `YYYY-MM-DDTHH` - `YYYY-MM-DDTHH:mm` - `YYYY-MM-DDTHH:mm:ss` - `YYYY-MM-DDTHH:mm:ssZ` - `YYYY-MM-DDTHH:mm:ssZ` - `YYYY-MM-DDTHH:mm:ss.SSSZ` - Columns that cannot be mapped to standard fields, will be mapped to **Custom attributes** and added as **products' metadata**. There is no limit on the number of custom attributes that you can import as metadata. - To provide the proper data type, you need to add all custom attributes to the metadata schema **before importing the file**. Read more [here](/prepare/metadata#add-metadata). - **Product attributes** (not custom attributes) need to be separated by a comma and enclosed in double quotes, i.e "attribute1,attribute2". - Headers with metadata names **can't contain white-space characters**. - If you import metadata defined in the schema as **arrays (multiple)**, you need to separate each value using a comma, for example: - array of strings: "subscribed,premium" - array of numbers: "123,234". - array of dates: "2000-01-01,2000-01-02" This API request starts a process that affects Voucherify data in bulk. In case of small jobs (like bulk update) the request is put into a queue and processed once every other bulk request placed in the queue prior to this request is finished. However, when the job takes a longer time (like vouchers generation) then it is processed in small portions in a round-robin fashion. When there is a list of vouchers generation scheduled, then they will all have the `IN_PROGRESS` status shortly. This way, small jobs added just after scheduling big jobs of the same type will be processed in a short time window. The result will return the async ID. You can verify the status of your request via this [API request](/api-reference/async-actions/get-async-action). # Import SKUs using CSV Source: https://docs.voucherify.io/api-reference/products/import-skus-using-csv /openapi/products.json post /v1/skus/importCSV Import SKUs into the repository using a CSV file. The CSV file has to include headers in the first line. All properties which cannot be mapped to standard SKU fields will be added to the metadata object. You can find an example template [here](https://s3.amazonaws.com/helpscout.net/docs/assets/5902f1c12c7d3a057f88a36d/attachments/627b98d08c9b585083488a4c/Import_SKUS_template.csv). Import sequence First import products using the [dedicated endpoint](/api-reference/products/import-products-using-csv), then import SKUs using this endpoint to properly match SKUs to products. Standard SKU fields mapping - **Required** fields are `source_id` and `product_id`. - Supported CSV file headers: `product_id,sku,source_id,price,image_url,attributes` - SKU **source_id** must be unique in the entire product catalog, no duplicates are allowed. - SKU attributes need to be in the form of a stringy-fied json, i.e.`"{'color':'blue'}"`. These attributes must be defined in the **product** beforehand so you can import them to the SKU. - You can use this method to update the following parameters in bulk: **sku** and the sku **price**. - Columns that cannot be mapped to standard fields will be mapped to Custom attributes and added as product metadata. There is no limit on the number of custom attributes that you can import as metadata. This API request starts a process that affects Voucherify data in bulk. In case of small jobs (like bulk update) the request is put into a queue and processed once every other bulk request placed in the queue prior to this request is finished. However, when the job takes a longer time (like vouchers generation) then it is processed in small portions in a round-robin fashion. When there is a list of vouchers generation scheduled, then they will all have the `IN_PROGRESS` status shortly. This way, small jobs added just after scheduling big jobs of the same type will be processed in a short time window. The result will return the async ID. You can verify the status of your request via this [API request](/api-reference/async-actions/get-async-action). # List Products Source: https://docs.voucherify.io/api-reference/products/list-products /openapi/products.json get /v1/products Retrieve a list of products. # List SKUs in Product Source: https://docs.voucherify.io/api-reference/products/list-skus-in-product /openapi/products.json get /v1/products/{productId}/skus Retrieve all SKUs for a given product. # Product Object Source: https://docs.voucherify.io/api-reference/products/product-object

Product

This is an object representing a product.

This entity should be used to map product items from your inventory management system. The aim of products is to build which reflect product-specific campaigns.

All of:

Product without Skus Object

Attributes	Description
skus	See: Skus List For Product

Product without Skus Object

Attributes	Description
id `string`	Unique product ID assigned by Voucherify. Example: prod\_0b1da8105693710357
source\_id `string`, `null`	Unique product source ID. Example: productSourceID16
name `string`, `null`	Unique user-defined product name. Example: T-shirt
price `integer`, `null`	Unit price. It is represented by a value multiplied by 100 to accurately reflect 2 decimal places, such as `\$100.00` being expressed as `10000`.
attributes `array`	A list of product attributes whose values you can customize for given SKUs: `\["color","size","ranking"]`. Each child SKU can have a unique value for a given attribute.
metadata `object`	The metadata object stores all custom attributes assigned to the product. A set of key/value pairs that you can attach to a product object. It can be useful for storing additional information about the product in a structured format. It can be used to create product collections.
image\_url `string`, `null`	The HTTPS URL pointing to the .png or .jpg file that will be used to render the product image. Example: [https://images.com/original.jpg](https://images.com/original.jpg)
created\_at `string`	Timestamp representing the date and time when the product was created. The value is shown in the ISO 8601 format. Example: 2022-05-23T06:52:55.008Z
updated\_at `string`, `null`	Timestamp representing the date and time when the product was updated. The value is shown in the ISO 8601 format. Example: 2022-05-23T09:24:07.405Z
object `string`	The type of the object represented by JSON. This object stores information about the product. Available values: `product`

Skus List For Product

Attributes	Description
object `string`	The type of the object represented by JSON. This object stores information about SKUs.
data\_ref `string`	Identifies the name of the JSON property that contains the array of SKUs.
data `array`	A dictionary that contains an array of SKUs. Array of SKU Object
total `integer`	Total number of SKUs in the product.

SKU Object

Attributes	Description
id `string`	A unique identifier that represents the SKU and is assigned by Voucherify. Example: sku\_0b1621b319d248b79f
source\_id `string`, `null`	A unique SKU identifier from your inventory system. Example: sku\_source\_id\_4
product\_id `string`	The parent product's unique ID. Example: prod\_0b15f6b9f650c16990
sku `string`, `null`	Unique user-defined SKU name. Example: Large Pink Shirt
price `integer`, `null`	Unit price. It is represented by a value multiplied by 100 to accurately reflect 2 decimal places, such as `\$100.00` being expressed as `10000`.
currency `string`, `null`	SKU price currency. Example: USD
attributes `object`	The attributes object stores values for all custom attributes inherited by the SKU from the parent product. A set of key/value pairs that are attached to a SKU object and are unique to each SKU within a product family.
image\_url `string`, `null`	The HTTPS URL pointing to the .png or .jpg file that will be used to render the SKU image.
metadata `object`	The metadata object stores all custom attributes assigned to the SKU. A set of key/value pairs that you can attach to a SKU object. It can be useful for storing additional information about the SKU in a structured format. It can be used to create product collections.
created\_at `string`	Timestamp representing the date and time when the SKU was created. The value is shown in the ISO 8601 format. Example: 2022-05-17T10:36:30.187Z
updated\_at `string`, `null`	Timestamp representing the date and time when the SKU was updated. The value is shown in the ISO 8601 format. Example: 2022-05-17T10:55:09.137Z
object `string`	The type of the object represented by JSON. This object stores information about the `SKU`. Available values: `sku`

# SKU Object Source: https://docs.voucherify.io/api-reference/products/sku-object

SKU Object

Attributes	Description
id `string`	A unique identifier that represents the SKU and is assigned by Voucherify. Example: sku\_0b1621b319d248b79f
source\_id `string`, `null`	A unique SKU identifier from your inventory system. Example: sku\_source\_id\_4
product\_id `string`	The parent product's unique ID. Example: prod\_0b15f6b9f650c16990
sku `string`, `null`	Unique user-defined SKU name. Example: Large Pink Shirt
price `integer`, `null`	Unit price. It is represented by a value multiplied by 100 to accurately reflect 2 decimal places, such as `\$100.00` being expressed as `10000`.
currency `string`, `null`	SKU price currency. Example: USD
attributes `object`	The attributes object stores values for all custom attributes inherited by the SKU from the parent product. A set of key/value pairs that are attached to a SKU object and are unique to each SKU within a product family.
image\_url `string`, `null`	The HTTPS URL pointing to the .png or .jpg file that will be used to render the SKU image.
metadata `object`	The metadata object stores all custom attributes assigned to the SKU. A set of key/value pairs that you can attach to a SKU object. It can be useful for storing additional information about the SKU in a structured format. It can be used to create product collections.
created\_at `string`	Timestamp representing the date and time when the SKU was created. The value is shown in the ISO 8601 format. Example: 2022-05-17T10:36:30.187Z
updated\_at `string`, `null`	Timestamp representing the date and time when the SKU was updated. The value is shown in the ISO 8601 format. Example: 2022-05-17T10:55:09.137Z
object `string`	The type of the object represented by JSON. This object stores information about the `SKU`. Available values: `sku`

# Update Product Source: https://docs.voucherify.io/api-reference/products/update-product /openapi/products.json put /v1/products/{productId} Updates the specified product by setting the values of the parameters passed in the request body. Any parameters not provided in the payload will be left unchanged. # Update Products in Bulk Source: https://docs.voucherify.io/api-reference/products/update-products-in-bulk /openapi/products.json post /v1/products/bulk/async Update products in one asynchronous operation. The request can include up to **10 MB** of data. The response returns a unique asynchronous action ID. Use this ID in the query paramater of the [GET Async Action](/api-reference/async-actions/get-async-action) endpoint to check, e.g.: - The status of your request (in queue, in progress, done, or failed) - Resources that failed to be updated - The report file with details about the update If a product object is not found, it is **upserted**. This is shown in the report file in the **GET** Async Action endpoint. The upserted resources have value `false` in the `found` column and `true` in the `updated` column. This API request starts a process that affects Voucherify data in bulk. In the case of small jobs (like bulk update), the request is put into a queue and processed when every other bulk request placed in the queue prior to this request is finished. # Update Products' Metadata in Bulk Source: https://docs.voucherify.io/api-reference/products/update-products-metadata-in-bulk /openapi/products.json post /v1/products/metadata/async Updates metadata parameters for a list of products. Every resource in the list will receive the metadata defined in the request. The request can include up to **10 MB** of data. The response returns a unique asynchronous action ID. Use this ID in the query paramater of the [GET Async Action](/api-reference/async-actions/get-async-action) endpoint to check, e.g.: - The status of your request (in queue, in progress, done, or failed) - Resources that failed to be updated - The report file with details about the update If a product object is not found, it is **upserted**. This is shown in the report file in the **GET** Async Action endpoint. The upserted resources have value `false` in the `found` column and `true` in the `updated` column. This API request starts a process that affects Voucherify data in bulk. In the case of small jobs (like bulk update), the request is put into a queue and processed when every other bulk request placed in the queue prior to this request is finished. # Update SKU Source: https://docs.voucherify.io/api-reference/products/update-sku /openapi/products.json put /v1/products/{productId}/skus/{skuId} Updates the specified SKU by setting the values of the parameters passed in the request body. Any parameters not provided in the payload will be left unchanged. Fields other than the ones listed in the request body schema won't be modified. Even if provided, they will be silently skipped. # Activate pending point bucket Source: https://docs.voucherify.io/api-reference/programs/activate-pending-point-bucket /openapi/loyalties-v2.json post /v2/loyalties/programs/{programId}/members/{memberId}/cards/{cardId}/pending-points/{bucketId}/activate Manually activates a pending points bucket before its scheduled activation date, creating a `PENDING_POINTS_ACTIVATED` card transaction (status `PENDING`, processed asynchronously). No request body. The program and member must be in `ACTIVE` status now, the card definition must have pending points enabled, the bucket must be in `PENDING` status, and the bucket's activation date must be in the future (`423` otherwise). Returns `404` when the program, member, card or bucket does not exist. # Activate program Source: https://docs.voucherify.io/api-reference/programs/activate-program /openapi/loyalties-v2.json post /v2/loyalties/programs/{programId}/activate Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Transitions the program to `ACTIVE` status. Allowed transitions to `ACTIVE` are from `DRAFT` and `INACTIVE`. Before activation the program's card definition, earning rule and tier structure assignments are validated (at least one active card definition and earning rule is required). An invalid state transition is rejected with `400` (key `invalid_state_transition`). No request body. # Activate program member Source: https://docs.voucherify.io/api-reference/programs/activate-program-member /openapi/loyalties-v2.json post /v2/loyalties/programs/{programId}/members/{memberId}/activate Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Moves the member to `ACTIVE` status and records a `vl.member.activated` activity. No request body. Returns `404` when the program or member does not exist. Returns `400` (`invalid_state_transition`) when the member cannot be activated from its current state. # Adjust card points Source: https://docs.voucherify.io/api-reference/programs/adjust-card-points /openapi/loyalties-v2.json post /v2/loyalties/programs/{programId}/members/{memberId}/cards/{cardId}/points Manually adjusts the points balance of the member's card. A positive `points` value creates an `ADMIN_CREDIT` card transaction (point addition). The added points get an expiration date calculated from the point expiration settings for the card definition or earning rule. A negative `points` value creates an `ADMIN_DEBIT` card transaction (point subtraction). When `points` is `0`, no transaction is created and the result status is `NO_CHANGE`. The transaction is created with status `PENDING` and processed asynchronously. Both the program and the member must be in `ACTIVE` status (`423` otherwise). Returns `404` when the program, member, or card does not exist. # Batch assign/unassign card definitions Source: https://docs.voucherify.io/api-reference/programs/batch-assignunassign-card-definitions /openapi/loyalties-v2.json post /v2/loyalties/programs/{programId}/card-definitions/batch Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Assigns and/or unassigns card definitions to/from a program in a single batch. Unassign operations are processed before assign operations. The program must be in `DRAFT` status - otherwise the request is rejected with `423 Locked` (key `non_draft_program`). In strict mode (default) missing card definitions, inactive card definitions or missing assignments cause the whole batch to fail. # Batch assign/unassign earning rules Source: https://docs.voucherify.io/api-reference/programs/batch-assignunassign-earning-rules /openapi/loyalties-v2.json post /v2/loyalties/programs/{programId}/earning-rules/batch Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Assigns and/or unassigns earning rules to/from a program in a single batch. Unassign operations are processed before assign operations. When the program is `ACTIVE`, the batch is validated to leave at least one active earning rule assigned. In strict mode (default) missing earning rules or missing assignments cause the whole batch to fail. # Batch assign/unassign rewards Source: https://docs.voucherify.io/api-reference/programs/batch-assignunassign-rewards /openapi/loyalties-v2.json post /v2/loyalties/programs/{programId}/rewards/batch Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Assigns and/or unassigns rewards to/from a program in a single batch. Unassign operations are processed before assign operations. Each reward to assign must include its `stock` configuration. In strict mode (default) missing rewards or missing assignments cause the whole batch to fail (`404 Not Found`). # Batch assign/unassign tier structures Source: https://docs.voucherify.io/api-reference/programs/batch-assignunassign-tier-structures /openapi/loyalties-v2.json post /v2/loyalties/programs/{programId}/tier-structures/batch Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Assigns and/or unassigns tier structures to/from a program in a single batch. Unassign operations are processed before assign operations. Unassigning is only allowed while the program is in `DRAFT` status - otherwise the request is rejected with `423 Locked` (key `non_draft_program`). A program can have at most one tier structure assigned. In strict mode (default) missing tier structures, inactive tier structures or missing assignments cause the whole batch to fail. # Batch create program members Source: https://docs.voucherify.io/api-reference/programs/batch-create-program-members /openapi/loyalties-v2.json post /v2/loyalties/programs/{programId}/members/batch Schedules asynchronous batch creation of program members. The request body is a JSON array of member entries (maximum body size is 10 MB). The request is processed asynchronously in batches of 100 entries. The program must exist (otherwise, it returns a `404` error) and be in `ACTIVE` status (otherwise, it returns a `423` error). Supported member fields are validated during background processing using the same domain validation rules as single member creation. Entries that fail validation (missing/invalid `customer_id`, unknown customer, invalid `status`, duplicate `customer_id` within the same batch, member already exists) are reported per-entry individually in the report linked from the async action result. The failed entries do not fail the whole batch (conflicting members are skipped). Returns `202` status with the identifier of the scheduled async action. Use the [GET Async Action](/api-reference/async-actions/get-async-action) endpoint to check the status of the batch creation. You can also check the processing status and the result in the Audit log – [Background tasks](/analyze/audit-logs#background-tasks) in the Voucherify dashboard. # Cancel pending point bucket Source: https://docs.voucherify.io/api-reference/programs/cancel-pending-point-bucket /openapi/loyalties-v2.json post /v2/loyalties/programs/{programId}/members/{memberId}/cards/{cardId}/pending-points/{bucketId}/cancel Cancels a pending point bucket so its points are never activated, creating a `PENDING_POINTS_CANCELED` card transaction (status `PENDING`, processed asynchronously). No request body. The program and member must be in `ACTIVE` status, the card definition must have pending points enabled, the bucket must be in `PENDING` status, and the bucket's activation date must be in the future (`423` otherwise). Returns `404` when the program, member, card, or bucket does not exist. # Create program Source: https://docs.voucherify.io/api-reference/programs/create-program /openapi/loyalties-v2.json post /v2/loyalties/programs Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Creates a new loyalty program. The program can be created with status `DRAFT` (default) or `ACTIVE`. When created as `ACTIVE`, the program must be connected to at least one active card definition and at least one active earning rule (provided via `card_definitions` and `earning_rules` arrays), otherwise the request is rejected with `423 Locked` (keys `missing_active_card_definition` / `missing_active_earning_rule`). Optionally assigns card definitions, earning rules, rewards and tier structures in the same request. # Create program member Source: https://docs.voucherify.io/api-reference/programs/create-program-member /openapi/loyalties-v2.json post /v2/loyalties/programs/{programId}/members Enrolls a customer as a member of the loyalty program. The program must be in `ACTIVE` status (returns a `423` error otherwise) and the customer must exist in Voucherify. A customer can be a member of a given program only once - creating a second member for the same customer ID returns `409` error (`member_already_exists`). Loyalty cards are created automatically for all card definitions assigned to the program and returned in the `cards` array. Card `code` generation is asynchronous: `code` may be `null` immediately after creation. # Deactivate program Source: https://docs.voucherify.io/api-reference/programs/deactivate-program /openapi/loyalties-v2.json post /v2/loyalties/programs/{programId}/deactivate Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Transitions the program to `INACTIVE` status. Only an `ACTIVE` program can be deactivated. An invalid state transition is rejected with `400` (key `invalid_state_transition`). No request body. # Deactivate program member Source: https://docs.voucherify.io/api-reference/programs/deactivate-program-member /openapi/loyalties-v2.json post /v2/loyalties/programs/{programId}/members/{memberId}/deactivate Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Moves the member to `INACTIVE` status and records a `vl.member.deactivated` activity. No request body. Returns `404` when the program or member does not exist. Returns 400 (`invalid_state_transition`) when the member cannot be deactivated from its current state. # Delete program Source: https://docs.voucherify.io/api-reference/programs/delete-program /openapi/loyalties-v2.json delete /v2/loyalties/programs/{programId} Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Soft-deletes a loyalty program and removes all of its card definition, earning rule, reward and tier structure assignments. # Delete program member Source: https://docs.voucherify.io/api-reference/programs/delete-program-member /openapi/loyalties-v2.json delete /v2/loyalties/programs/{programId}/members/{memberId} Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Deletes the member from the program (soft delete - status becomes `DELETED`) and deletes the member's cards. Records a `vl.member.deleted` activity. Returns the deleted member (without cards). Returns `404` when the program or member does not exist. # Expire points bucket Source: https://docs.voucherify.io/api-reference/programs/expire-points-bucket /openapi/loyalties-v2.json post /v2/loyalties/programs/{programId}/members/{memberId}/cards/{cardId}/expiring-points/{bucketId}/expire Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Manually expires a points bucket before its scheduled expiration date, creating an `ADMIN_POINTS_EXPIRATION` card transaction (status `PENDING`, processed asynchronously). No request body. The program and member must be in `ACTIVE` status, the card definition must have points expiration enabled, the bucket must be in `ACTIVE` status, and the bucket's expiration date must not be in the past (423 otherwise). Returns `404` when the program, member, card or bucket does not exist. # Get card daily points report Source: https://docs.voucherify.io/api-reference/programs/get-card-daily-points-report /openapi/loyalties-v2.json get /v2/loyalties/programs/{programId}/members/{memberId}/cards/{cardId}/reports/daily Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Returns aggregated daily points statistics for a member's loyalty card over the given date range and resolution. The date range is limited per resolution: maximum 90 days for `day`, 12 weeks for `week`, 12 months for `month`, 4 quarters for `quarter`. # Get customer memberships Source: https://docs.voucherify.io/api-reference/programs/get-customer-memberships /openapi/loyalties-v2.json get /v2/loyalties/memberships/{customerId} Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Returns all loyalty memberships for a customer across programs, including the resolved customer identity and each membership's member, program, and cards. Use `identification_type` to choose how the `customerId` path value is interpreted. Returns an empty `memberships` array when the customer exists but has no memberships. Returns `404` when the customer or member cannot be resolved. # Get member earning-rule daily report Source: https://docs.voucherify.io/api-reference/programs/get-member-earning-rule-daily-report /openapi/loyalties-v2.json get /v2/loyalties/programs/{programId}/members/{memberId}/earning-rules/{earningRuleId}/reports/daily Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Returns aggregated daily usage statistics for a specific earning rule and member over the given date range and resolution. The date range is limited per resolution: maximum 90 days for `day`, 12 weeks for `week`, 12 months for `month`, 4 quarters for `quarter`. # Get program Source: https://docs.voucherify.io/api-reference/programs/get-program /openapi/loyalties-v2.json get /v2/loyalties/programs/{programId} Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Returns a single loyalty program by its id. # Get program earning-rules daily report Source: https://docs.voucherify.io/api-reference/programs/get-program-earning-rules-daily-report /openapi/loyalties-v2.json get /v2/loyalties/programs/{programId}/reports/earning-rules/daily Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Returns aggregated daily earning-rule evaluation statistics for the program over the given date range and resolution, optionally filtered by earning rule. Includes success and failure counts with a failures breakdown. The date range is limited per resolution: maximum 90 days for `day`, 12 weeks for `week`, 12 months for `month`, 4 quarters for `quarter`. # Get program earning-rules summary report Source: https://docs.voucherify.io/api-reference/programs/get-program-earning-rules-summary-report /openapi/loyalties-v2.json get /v2/loyalties/programs/{programId}/reports/earning-rules/summary Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Returns total earning-rule evaluation statistics for the program (all time), optionally filtered by earning rule. Includes success and failure counts with a failures breakdown. # Get program member Source: https://docs.voucherify.io/api-reference/programs/get-program-member /openapi/loyalties-v2.json get /v2/loyalties/programs/{programId}/members/{memberId} Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Returns a single member of the program together with all its loyalty cards. Each card includes the current balance, lifetime bucket counters, and next expiration/activation info. Card `code` may be `null` shortly after member creation because card code generation is asynchronous. Returns `404` when the program or member does not exist. # Get program membership Source: https://docs.voucherify.io/api-reference/programs/get-program-membership /openapi/loyalties-v2.json get /v2/loyalties/programs/{programId}/memberships/{customerId} Returns a single membership - the member's full loyalty profile within the program, combining the member, the program, and the member's loyalty cards enriched with tier progress. Use `identification_type` to choose how the `customerId` path value is interpreted. Returns `404` when the program does not exist, or when the customer/member has no membership in the program. # Get program points-earnings daily report Source: https://docs.voucherify.io/api-reference/programs/get-program-points-earnings-daily-report /openapi/loyalties-v2.json get /v2/loyalties/programs/{programId}/reports/points-earnings/daily Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Returns aggregated daily points-earnings statistics for the program over the given date range and resolution, optionally filtered by earning rule and card definition. The date range is limited per resolution: maximum 90 days for `day`, 12 weeks for `week`, 12 months for `month`, 4 quarters for `quarter`. # Get program points-earnings summary report Source: https://docs.voucherify.io/api-reference/programs/get-program-points-earnings-summary-report /openapi/loyalties-v2.json get /v2/loyalties/programs/{programId}/reports/points-earnings/summary Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Returns total points-earnings statistics for the program (all time), optionally filtered by earning rule and card definition. # Get program spending daily report Source: https://docs.voucherify.io/api-reference/programs/get-program-spending-daily-report /openapi/loyalties-v2.json get /v2/loyalties/programs/{programId}/reports/spending/daily Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Returns aggregated daily points-spending statistics for the program over the given date range and resolution, optionally filtered by card definition. The date range is limited per resolution: maximum 90 days for `day`, 12 weeks for `week`, 12 months for `month`, 4 quarters for `quarter`. # Get program spending summary report Source: https://docs.voucherify.io/api-reference/programs/get-program-spending-summary-report /openapi/loyalties-v2.json get /v2/loyalties/programs/{programId}/reports/spending/summary Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Returns total points-spending statistics for the program (all time), optionally filtered by card definition. # Get program tiers daily report Source: https://docs.voucherify.io/api-reference/programs/get-program-tiers-daily-report /openapi/loyalties-v2.json get /v2/loyalties/programs/{programId}/reports/tiers/daily Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Returns aggregated daily tier-movement statistics for the program over the given date range and resolution, optionally filtered by tier structure and tier. The date range is limited per resolution: maximum 90 days for `day`, 12 weeks for `week`, 12 months for `month`, 4 quarters for `quarter`. # Get program tiers summary report Source: https://docs.voucherify.io/api-reference/programs/get-program-tiers-summary-report /openapi/loyalties-v2.json get /v2/loyalties/programs/{programId}/reports/tiers/summary Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Returns total tier-movement statistics for the program (all time), optionally filtered by tier structure and tier. Results are capped by `limit` (default `100`) and sorted by `order` (default `-id`). # List card activities Source: https://docs.voucherify.io/api-reference/programs/list-card-activities /openapi/loyalties-v2.json get /v2/loyalties/programs/{programId}/members/{memberId}/cards/{cardId}/activities Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Returns a cursor-paginated list of activities recorded for the member's card (created, assigned, unassigned, code generation succeeded/failed). Results can be filtered by id, type and created_at. Returns `404` when the program, member or card does not exist. # List card expiring points buckets Source: https://docs.voucherify.io/api-reference/programs/list-card-expiring-points-buckets /openapi/loyalties-v2.json get /v2/loyalties/programs/{programId}/members/{memberId}/cards/{cardId}/expiring-points Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Returns a cursor-paginated list of points expiration buckets of the member's card. Each bucket groups active points sharing the same expiration date and expiration type. Results can be ordered by `expiration_date`. Returns `404` when the program, member, or card does not exist. # List card pending point buckets Source: https://docs.voucherify.io/api-reference/programs/list-card-pending-point-buckets /openapi/loyalties-v2.json get /v2/loyalties/programs/{programId}/members/{memberId}/cards/{cardId}/pending-points Returns a cursor-paginated list of pending point buckets (`status` is `PENDING`) of the member's card. Pending points are earned points waiting for activation (period-based, fixed-dates or event-based activation, per the card definition's pending points settings). Results can be ordered by activation `date`. Returns `404` when the program, member, or card does not exist. Use this endpoint to get the list of IDs of pending point bucket to use the [POST Activate pending point bucket](/api-reference/programs/activate-pending-point-bucket) or [POST Cancel pending point bucket](/api-reference/programs/cancel-a-pending-points-bucket). # List card transactions Source: https://docs.voucherify.io/api-reference/programs/list-card-transactions /openapi/loyalties-v2.json get /v2/loyalties/programs/{programId}/members/{memberId}/cards/{cardId}/transactions Returns a cursor-paginated list of transactions of the member's card. Results can be filtered by `id` and `created_at`, and ordered by `created_at` (default `-created_at`, newest first). Returns `404` when the program, member or card does not exist. # List member activities Source: https://docs.voucherify.io/api-reference/programs/list-member-activities /openapi/loyalties-v2.json get /v2/loyalties/programs/{programId}/members/{memberId}/activities Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Returns a cursor-paginated list of activities recorded for the member (created, deleted, activated, deactivated, card assigned, card unassigned). Results can be filtered by id, type and created_at. Returns `404` when the program or member does not exist. # List member benefit transactions Source: https://docs.voucherify.io/api-reference/programs/list-member-benefit-transactions /openapi/loyalties-v2.json get /v2/loyalties/programs/{programId}/members/{memberId}/benefits/transactions Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Lists benefit transactions (benefit fulfillments) for the given program member, with cursor-based pagination. Supports filtering by benefit id and creation date. # List member order payments Source: https://docs.voucherify.io/api-reference/programs/list-member-order-payments /openapi/loyalties-v2.json get /v2/loyalties/programs/{programId}/members/{memberId}/orders/payments Lists persisted order transactions (pay-with-points payments) for the given program member, with cursor-based pagination. Supports filtering by transaction `id` and `created_at` date. Dry-run (`SIMULATED`) results from create are never persisted and do not appear in this list. # List member reward purchases Source: https://docs.voucherify.io/api-reference/programs/list-member-reward-purchases /openapi/loyalties-v2.json get /v2/loyalties/programs/{programId}/members/{memberId}/rewards/purchases Lists reward transactions of type `PURCHASE` for the given program member, with cursor-based pagination. Supports filtering by transaction `id`, `reward_id`, and `created_at` date. It returns all persisted purchase transactions for the member, regardless of status. Purchases rejected synchronously at creation time (for example, insufficient card balance or unavailable stock) are not stored and do not appear in this list. Purchases accepted for processing (202) that later fail asynchronously appear with status: "REJECTED" and `details.rejection`. # List member tier transactions Source: https://docs.voucherify.io/api-reference/programs/list-member-tier-transactions /openapi/loyalties-v2.json get /v2/loyalties/programs/{programId}/members/{memberId}/tiers/transactions Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Lists tier transactions (tier joins, upgrades, downgrades, prolongations and exits) for the given program member, with cursor-based pagination. Supports filtering by card id and creation date. # List program activities Source: https://docs.voucherify.io/api-reference/programs/list-program-activities /openapi/loyalties-v2.json get /v2/loyalties/programs/{programId}/activities Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Returns a cursor-paginated list of activities recorded for a program (created, updated, deleted, activated, deactivated and assignment changes). Supports filtering by activity `id`, `type` and `created_at`. # List program card definition assignments Source: https://docs.voucherify.io/api-reference/programs/list-program-card-definition-assignments /openapi/loyalties-v2.json get /v2/loyalties/programs/{programId}/card-definitions Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Returns a cursor-paginated list of card definitions assigned to the program. # List program earning rule assignments Source: https://docs.voucherify.io/api-reference/programs/list-program-earning-rule-assignments /openapi/loyalties-v2.json get /v2/loyalties/programs/{programId}/earning-rules Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Returns a cursor-paginated list of earning rules assigned to the program. # List program members Source: https://docs.voucherify.io/api-reference/programs/list-program-members /openapi/loyalties-v2.json get /v2/loyalties/programs/{programId}/members Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Returns a cursor-paginated list of members of the program. Results can be filtered by id, status, customer_id and created_at, and ordered by created_at, status or customer_id (ascending or descending). The same field cannot be ordered both ascending and descending at the same time. Returns `404` when the program does not exist. List items do not include the `cards` array - use the get-member endpoint to retrieve a member with cards. # List program reward assignments Source: https://docs.voucherify.io/api-reference/programs/list-program-reward-assignments /openapi/loyalties-v2.json get /v2/loyalties/programs/{programId}/rewards Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Returns a cursor-paginated list of rewards assigned to the program, including their stock configuration and redemption counters. # List program tier structure assignments Source: https://docs.voucherify.io/api-reference/programs/list-program-tier-structure-assignments /openapi/loyalties-v2.json get /v2/loyalties/programs/{programId}/tier-structures Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Returns a cursor-paginated list of tier structures assigned to the program. # List programs Source: https://docs.voucherify.io/api-reference/programs/list-programs /openapi/loyalties-v2.json get /v2/loyalties/programs Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Returns a cursor-paginated list of loyalty programs. Supports filtering by `id`, `name`, `status` and `created_at`. The same field cannot be used in both ascending and descending order at once. # Pay for order with points Source: https://docs.voucherify.io/api-reference/programs/pay-for-order-with-points /openapi/loyalties-v2.json post /v2/loyalties/programs/{programId}/members/{memberId}/orders/payments Pays for an order using points from the specified member loyalty card. The payment amount and points to spend are calculated from the card definition's pay-with-points exchange ratio formula, capped by the card balance and the optional `payment_limit`. Requires: - `ACTIVE` program; - `ACTIVE` member; - Card definition with pay-with-points enabled and a configured exchange ratio formula; - Existing order in Voucherify with order `id` or order `source_id`. Modes: - `TRANSACTION` (default): Creates a `PENDING` order transaction (and an underlying card transaction) processed asynchronously. Returns HTTP `202`. Sending a request for the same order `id` or `source_id` creates a new transaction each time. - `DRY_RUN`: Simulates the payment without creating any transaction. Returns HTTP `200` with a `SIMULATED` transaction payload. # Purchase reward with points Source: https://docs.voucherify.io/api-reference/programs/purchase-reward-with-points /openapi/loyalties-v2.json post /v2/loyalties/programs/{programId}/members/{memberId}/rewards/purchases Purchases a reward on behalf of the program member by spending points from the member's loyalty card (the card is resolved from the reward cost's card definition). Requires an `ACTIVE` program and an `ACTIVE` reward within their configured validity windows, an `ACTIVE` member, the reward to be assigned to the program with available stock, a matching reward cost for the customer's context, and sufficient points within the configured spending limits. Modes: - `TRANSACTION` (default): creates a `PENDING` reward transaction (and an underlying card transaction) processed asynchronously. Returns HTTP `202`. - `DRY_RUN`: simulates the purchase without creating any transaction. Returns HTTP `200` with a `SIMULATED` transaction payload. # Refund a reward purchase Source: https://docs.voucherify.io/api-reference/programs/refund-a-reward-purchase /openapi/loyalties-v2.json post /v2/loyalties/programs/{programId}/rewards/purchases/{rewardTransactionId}/refund Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Refunds a previously approved reward purchase transaction. Creates a REFUND-type reward transaction and schedules the return of the spent points to the member's card ("Reward refund transaction created. Points will be returned to the member's card shortly."). The refunded purchase transaction must be of type `PURCHASE` and in `APPROVED` status, otherwise the request is rejected with a conflict error. The request body is optional (an empty payload is allowed). When omitted, default policies are applied: `refund: DEFAULT`, `stock: DEFAULT`. # Update program Source: https://docs.voucherify.io/api-reference/programs/update-program /openapi/loyalties-v2.json put /v2/loyalties/programs/{programId} Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Updates a loyalty program. When the program is not in `DRAFT` status, only `name` and `metadata` may be changed (other properties are restricted after leaving draft). # Update program member Source: https://docs.voucherify.io/api-reference/programs/update-program-member /openapi/loyalties-v2.json put /v2/loyalties/programs/{programId}/members/{memberId} Updates a program member's metadata. Provided object keys are merged into the existing metadata; omitted keys are preserved. Pass `metadata: null` to clear all metadata (sets it to an empty object). This endpoint cannot change `status`. Use [Activate a program member](/api-reference/programs/activate-a-program-member) or [Deactivate a program member](/api-reference/programs/deactivate-a-program-member) for status transitions. Records a `vl.member.updated` activity. Returns the updated member without the `cards` array. Returns `404` when the program or member does not exist. Returns `400` when the request body fails validation or the project `vl_member` metadata schema rejects the payload. # Update program reward assignment Source: https://docs.voucherify.io/api-reference/programs/update-program-reward-assignment /openapi/loyalties-v2.json put /v2/loyalties/programs/{programId}/rewards/{rewardId} Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Updates the stock configuration of a reward assigned to a program. Returns the updated reward assignment. # Project settings webhooks Source: https://docs.voucherify.io/api-reference/project-settings-webhooks Use webhooks to get notified about project events in Voucherify Project-level webhooks in Voucherify are notifications sent automatically to your application whenever certain actions happen in your project. Examples include when a voucher is redeemed, a customer profile changes, or an order is created. To use these webhooks, provide Voucherify with an endpoint URL where notifications should be sent. ## Configuring webhooks Follow these steps to configure webhooks: 1. In Voucherify dashboard, go to Project settings. 2. Scroll down to the Webhooks section. 3. Click the plus button – Add new webhook. 4. Choose v2024-01-01 webhook version. 5. Provide the following details: 1. Enter the target URL. 2. Tick the Is active? checkbox. 3. Select the [events](#webhooks-available-in-project-settings "Project setting webhooks") you want to receive. If you want to receive all the events, choose Send me all events option. 4. Provide additional custom HTTP header (optional). 5. Click Send test webhook to test your configuration (optional). 6. Click Create endpoint. 6. If necessary for authentication reasons, enter the Secret key in your system to receive webhooks from Voucherify. You can add multiple webhooks to your projects following the steps above. To update webhook details, click the Pencil button – edit. Enter your changes and click Update endpoint. To delete a webhook, click the trash button and click Delete. ## Re-Enabling a Webhook To re-enable a disabled webhook: 1. In the Project settings, go to the General tab. 2. Scroll down to the Webhooks section. 3. Edit the specific Webhook. 4. Click Is active. 5. Click Update endpoint. ## Webhooks available in Project settings These webhooks are triggered by the events listed in the Project settings. Documentation of some of the events is still in progress. The following events can send a webhook: * Redemption events: * [Redemption succeeded](/api-reference/redemption/succeeded "Redemption succeeded event documentation") * [Redemption failed](/api-reference/redemption/failed "Redemption failed event documentation") * [Redemption rollback succeeded](/api-reference/redemption/rollback-succeeded "Redemption rollback succeeded event documentation") * [Redemption rollback failed](/api-reference/redemption/rollback-failed "Redemption rollback failed event documentation") * Publication event: * [Publication succeeded](/api-reference/publication/succeeded "Publication succeeded event documentation") * Customer events: * [Customer created](/api-reference/customer/created "Customer created event documentation") * [Customer updated](/api-reference/customer/updated "Customer updated event documentation") * [Customer deleted](/api-reference/customer/deleted "Customer deleted event documentation") * [Customer rewarded](/api-reference/customer/rewarded "Customer rewarded event documentation") * [Customer rewarded loyalty points](/api-reference/customer/rewarded-loyalty-points "Customer rewarded loyalty points event documentation") * Customer confirmed * Voucher events: * [Voucher created](/api-reference/voucher/created "Voucher created event documentation") * [Voucher disabled](/api-reference/voucher/disabled "Voucher disabled event documentation") * [Voucher enabled](/api-reference/voucher/enabled "Voucher enabled event documentation") * [Voucher updated](/api-reference/voucher/updated "Voucher updated event documentation") * [Voucher published](/api-reference/voucher/published "Voucher published event documentation") * [Voucher loyalty card pending points activated](/api-reference/voucher/loyalty-card-pending-points-activated "Voucher loyalty card pending points activated event documentation") * [Voucher loyalty card pending points added](/api-reference/voucher/loyalty-card-pending-points-added "Voucher loyalty card pending points added event documentation") * [Voucher loyalty card pending points canceled](/api-reference/voucher/loyalty-card-pending-points-canceled "Voucher loyalty card pending points canceled event documentation") * [Voucher loyalty card pending points updated](/api-reference/voucher/loyalty-card-pending-points-updated "Voucher loyalty card pending points update event documentation") * [Voucher loyalty card points added](/api-reference/voucher/loyalty-card-points-added "Voucher loyalty card points added event documentation") * [Voucher loyalty card points expired](/api-reference/voucher/loyalty-card-points-expired "Voucher loyalty card points expired event documentation") * [Voucher loyalty card transaction created](/api-reference/voucher/loyalty-card-transaction-created "Voucher loyalty card transaction created event documentation") * [Voucher gift transaction created](/api-reference/voucher/gift-transaction-created "Voucher gift transaction created event documentation") * [Voucher gift balance added](/api-reference/voucher/gift-balance-added "Voucher gift balance added event documentation") * [Voucher deleted](/api-reference/voucher/deleted "Voucher deleted event documentation") * Campaign events: * [Campaign created](/api-reference/campaign/created "Campaign created event documentation") * [Campaign voucher generation completed](/api-reference/campaign/vouchers-generation-completed "Campaign voucher generation completed event documentation") * [Campaign disabled](/api-reference/campaign/disabled "Campaign disabled event documentation") * [Campaign enabled](/api-reference/campaign/enabled "Campaign enabled event documentation") * [Campaign updated](/api-reference/campaign/updated "Campaign updated event documentation") * [Campaign deleted](/api-reference/campaign/deleted "Campaign deleted event documentation") * Campaign vouchers added * Promotion tier events: * [Promotion tier created](/api-reference/campaign/promotion-tier-created "Promotion tier created event documentation") * [Promotion tier disabled](/api-reference/campaign/promotion-tier-disabled "Promotion tier disabled event documentation") * [Promotion tier enabled](/api-reference/campaign/promotion-tier-enabled "Promotion tier enabled event documentation") * [Promotion tier updated](/api-reference/campaign/promotion-tier-updated "Promotion tier updated event documentation") * [Promotion tier deleted](/api-reference/campaign/promotion-tier-deleted "Promotion tier deleted event documentation") * Business validation rule events: * [Business validation rule created](/api-reference/validation-rules/created "Validation rule created event documentation") * [Business validation rule updated](/api-reference/validation-rules/updated "Validation rule updated event documentation") * [Business validation rule assignment created](/api-reference/validation-rules/assignment-created "Validation rule assignment created event documentation") * [Business validation rule assignment deleted](/api-reference/validation-rules/assignment-deleted "Validation rule assignment deleted event documentation") * [Business validation rule deleted](/api-reference/validation-rules/deleted "Validation rule deleted event documentation") * Earning rule events: * Earning rule assigned * Earning rule deleted * Earning rule disabled * Earning rule enabled * Earning rule updated * Loyalty tier related events: * [Loyalty tier created](/api-reference/campaign/loyalty-tier-created "Campaign loyalty tier created documentation") * [Loyalty tier deleted](/api-reference/campaign/loyalty-tier-deleted "Campaign loyalty tier deleted documentation") * [Loyalty tier updated](/api-reference/campaign/loyalty-tier-updated "Campaign loyalty tier updated documentation") * Promotion stack events: * Promotion stack created * Promotion stack updated * Referral tier related events: * Referral tier created * Referral tier deleted * Referral tier updated * Reward assignment events: * Reward assignment created * Reward assignment deleted * Reward assignment updated * Voucher generation events: * Voucher generation failed * Voucher generation started ### Project setting webhook payload The list shows a general structure of a webhook payload set in Project settings. Indented bullet points mean that an object contains further properties or objects. * `id` (`string`): Unique identifier of the send out for this webhook. **Example:** `whs_0e16e42bc6e0c65b57` * `project_id` (`string`): Unique identifier of the Voucherify project. **Example:** `proj_5T4Rpl4T1nuM` * `created_at` (`string`): The exact moment when the webhook was created. **Example:** `2024-01-01T11:11:11.111Z` * `type` (`string`): Name of the event that triggered the webhook send out. Available values: `business_validation_rule.assignment.created`, `business_validation_rule.assignment.deleted`, `business_validation_rule.created`, `business_validation_rule.deleted`, `business_validation_rule.updated`, `campaign.created`, `campaign.deleted`, `campaign.disabled`, `campaign.enabled`, `campaign.earning_rule.assigned`, `campaign.earning_rule.deleted`, `campaign.earning_rule.disabled`, `campaign.earning_rule.enabled`, `campaign.earning_rule.updated`, `campaign.loyalty_tier.created`, `campaign.loyalty_tier.deleted`, `campaign.loyalty_tier.updated`, `campaign.promotion_stack.created`, `campaign.promotion_stack.updated`, `campaign.promotion_tier.created`, `campaign.promotion_tier.deleted`, `campaign.promotion_tier.disabled`, `campaign.promotion_tier.enabled`, `campaign.promotion_tier.updated`, `campaign.referral_tier.created`, `campaign.referral_tier.deleted`, `campaign.referral_tier.updated`, `campaign.reward.assignment.created`, `campaign.reward.assignment.deleted`, `campaign.reward.assignment.updated`, `campaign.updated`, `campaign.vouchers.added`, `campaign.vouchers.generation.completed`, `campaign.vouchers.generation.failed`, `campaign.vouchers.generation.started`, `customer.confirmed`, `customer.created`, `customer.updated`, `customer.deleted`, `customer.rewarded`, `customer.rewarded.loyalty_points`, `publication.succeeded`, `redemption.failed`, `redemption.rollback.failed`, `redemption.rollback.succeeded`, `redemption.succeeded`, `voucher.created`, `voucher.deleted`, `voucher.disabled`, `voucher.enabled`, `voucher.gift.balance_added`, `voucher.gift.transaction.created`, `voucher.loyalty_card.pending_points.activated`, `voucher.loyalty_card.pending_points.added`, `voucher.loyalty_card.pending_points.canceled`, `voucher.loyalty_card.pending_points.updated`, `voucher.loyalty_card.points_added`, `voucher.loyalty_card.points_expired`, `voucher.loyalty_card.transaction.created`, `voucher.published`, `voucher.updated` * `data` (`object`): Payload depends on the event that triggered the webhook send out. Project settings cover the following events: * [business\_validation\_rule.assignment.created](/api-reference/validation-rules/assignment-created) * [business\_validation\_rule.assignment.deleted](/api-reference/validation-rules/assignment-deleted) * [business\_validation\_rule.created](/api-reference/validation-rules/created) * [business\_validation\_rule.deleted](/api-reference/validation-rules/deleted) * [business\_validation\_rule.updated](/api-reference/validation-rules/updated) * [campaign.created](/api-reference/campaign/created) * [campaign.deleted](/api-reference/campaign/deleted) * [campaign.disabled](/api-reference/campaign/disabled) * [campaign.enabled](/api-reference/campaign/enabled) * [campaign.updated](/api-reference/campaign/updated) * campaign.earning\_rule.assigned * campaign.earning\_rule.deleted * campaign.earning\_rule.disabled * campaign.earning\_rule.enabled * campaign.earning\_rule.updated * [campaign.loyalty\_tier.created](/api-reference/campaign/loyalty-tier-created) * [campaign.loyalty\_tier.deleted](/api-reference/campaign/loyalty-tier-deleted) * [campaign.loyalty\_tier.updated](/api-reference/campaign/loyalty-tier-updated) * [campaign.promotion\_tier.created](/api-reference/campaign/promotion-tier-created) * [campaign.promotion\_tier.deleted](/api-reference/campaign/promotion-tier-deleted) * [campaign.promotion\_tier.disabled](/api-reference/campaign/promotion-tier-disabled) * [campaign.promotion\_tier.enabled](/api-reference/campaign/promotion-tier-enabled) * [campaign.promotion\_tier.updated](/api-reference/campaign/promotion-tier-updated) * campaign.promotion\_stack.created * campaign.promotion\_stack.updated * campaign.referral\_tier.created * campaign.referral\_tier.deleted * campaign.referral\_tier.updated * campaign.reward.assignment.created * campaign.reward.assignment.deleted * campaign.reward.assignment.updated * [campaign.vouchers.generation.completed](/api-reference/campaign/vouchers-generation-completed) * campaign.vouchers.generation.failed * campaign.vouchers.generation.started * campaign.vouchers.added * [customer.created](/api-reference/customer/created) * [customer.updated](/api-reference/customer/updated) * [customer.deleted](/api-reference/customer/deleted) * customer.confirmed * [customer.rewarded](/api-reference/customer/rewarded) * [customer.rewarded.loyalty\_points](/api-reference/customer/rewarded-loyalty-points) * [publication.succeeded](/api-reference/publication/succeeded) * [redemption.failed](/api-reference/redemption/failed) * [redemption.rollback.failed](/api-reference/redemption/rollback-failed) * [redemption.rollback.succeeded](/api-reference/redemption/rollback-succeeded) * [redemption.succeeded](/api-reference/redemption/succeeded) * [voucher.created](/api-reference/voucher/created) * [voucher.deleted](/api-reference/voucher/deleted) * [voucher.disabled](/api-reference/voucher/disabled) * [voucher.enabled](/api-reference/voucher/enabled) * [voucher.gift.balance\_added](/api-reference/voucher/gift-balance-added) * [voucher.gift.transaction.created](/api-reference/voucher/gift-transaction-created) * [voucher.loyalty\_card.pending\_points.activated](/api-reference/voucher/loyalty-card-pending-points-activated) * [voucher.loyalty\_card.pending\_points.added](/api-reference/voucher/loyalty-card-pending-points-added) * [voucher.loyalty\_card.pending\_points.canceled](/api-reference/voucher/loyalty-card-pending-points-canceled) * [voucher.loyalty\_card.pending\_points.updated](/api-reference/voucher/loyalty-card-pending-points-updated) * [voucher.loyalty\_card.points\_added](/api-reference/voucher/loyalty-card-points-added) * [voucher.loyalty\_card.points\_expired](/api-reference/voucher/loyalty-card-points-expired) * [voucher.loyalty\_card.transaction.created](/api-reference/voucher/loyalty-card-transaction-created) * [voucher.published](/api-reference/voucher/published) * [voucher.updated](/api-reference/voucher/updated) * `source` (`object`): Contains details about the source of the webhook send out. Properties: * `id` (`string`): ID number of the webhook. **Example:** `wh_j56Vfy47Vx9YOX7QYD1fzHnc` * `object` (`string`): Determines the type of the object. Available values: `webhook` **Example:** `webhook` * `target_url` (`string`): The address where the webhook will be sent. * `event` (`object`): Contains other data of the event that triggered the send out. * `id` (`string`): Unique identifier of the event that triggered the send out. **Example:** `evred_1f3611301g3127begb` * `type` (`string`): Determines the type of the event. **Example:** `redemption.succeeded` * `created_at` (`string`): The exact moment when the event was created. **Example:** `2024-01-01T11:11:11.111Z` * `entity_id` (`string`): Unique identifier of the entity that triggered the send out. **Example:** `r_1f3611302bf107befb` * `group_id` (`string`): Unique identifier of the request that triggered the event. **Example:** `v-1f36113948e50fc4ge` * `event_source` (`object`): Contains the source of the object that triggered the send out. Properties: * `channel` (`string`): Determines the channel that triggered the send out. Available values: `USER_PORTAL`, `API`, `CLIENT_API`, `INTERNAL` **Example:** `API` * `user` (`object`): Defines the user who triggered the event. * `id` (`string`): ID of the user who triggered the event. * `api_key` (`object`): Determines the API key used to initiate the send out. Properties: * `name` (`string`): Channel name in the application keys. * `app_id` (`string`): Contains the application ID from the Voucherify API key pair. **Example:** `1XXXX5XX-0XXX-XXXb-X7XX-XX2XXaXXX6XX` ```JSON Voucher published payload example theme={null} { "id": "whs_ID", "project_id": "proj_ID", "created_at": "2025-10-16T16:03:23.071Z", "type": "voucher.published", "data": { "customer": { "id": "cust_ID", "name": "Alex Doe", "email": "alex.doe@doe.alex.io", "source_id": "4lx-d03", "metadata": { "acquisition_channel": "Website" }, "object": "customer" }, "campaign": { "id": "camp_ID", "name": "Autumn-2025", "campaign_type": "DISCOUNT_COUPONS", "type": "STANDALONE", "is_referral_code": false, "voucher": { "type": "DISCOUNT_VOUCHER", "discount": { "type": "AMOUNT", "amount_off": 100, "units": null, "effect": "APPLY_TO_ITEMS" }, "gift": null, "loyalty_card": null, "redemption": { "quantity": null, "redeemed_quantity": 0 }, "code_config": { "pattern": "########", "length": 8, "charset": "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ", "prefix": "", "postfix": "", "min_desired": 1 } }, "auto_join": false, "join_once": false, "active": true, "category_id": null, "category": null, "metadata": {}, "start_date": null, "expiration_date": null, "description": null, "created_at": "2025-10-14T08:45:08.857Z", "updated_at": "2025-10-14T12:39:52.798Z", "object": "campaign" }, "publication": { "id": "pub_ID", "object": "publication", "created_at": "2025-10-16T16:03:23.065Z", "customer_id": "cust_ID", "tracking_id": "4lx-d03", "metadata": {}, "channel": "voucherify-web-ui", "source_id": "manual-publication-2020-02-02-v01", "result": "SUCCESS", "customer": { "id": "cust_ID", "source_id": "4lx-d03", "name": "Alex Doe", "email": "alex.doe@doe.alex.io", "address": null, "summary": null, "loyalty": null, "referrals": null, "metadata": { "acquisition_channel": "Website" }, "object": "customer" }, "vouchers_id": [ "v_ID" ] }, "voucher": { "id": "v_ID", "code": "kUs7oM-cOD3", "discount": { "type": "AMOUNT", "amount_off": 100, "effect": "APPLY_TO_ITEMS" }, "type": "DISCOUNT_VOUCHER", "campaign": "Autumn2025", "campaign_id": "camp_ID", "is_referral_code": false, "holder_id": "cust_ID", "category_id": null, "active": true, "created_at": "2025-10-16T16:02:41.255Z", "updated_at": "2025-10-16T16:03:23.070Z", "redemption": { "quantity": null, "redeemed_quantity": 0 }, "start_date": null, "expiration_date": null, "metadata": {}, "object": "voucher", "categories": [] }, "created_at": "2025-10-16T16:03:23.071Z" }, "source": { "id": "wh_ID", "object": "webhook", "target_url": "https:/your.url.io" }, "event": { "id": "evvou_ID", "type": "voucher.published", "created_at": "2025-10-16T16:03:23.071Z", "entity_id": "v_ID", "group_id": "v-ID", "event_source": { "channel": "USER_PORTAL", "user": { "id": "user_ID" } } } } ``` # Add Promotion Tier to Campaign Source: https://docs.voucherify.io/api-reference/promotions/add-promotion-tier-to-campaign /openapi/promotions.json post /v1/promotions/{campaignId}/tiers This method allows you to add a new promotion tier to an existing campaign. The tier hierarchy will be set as the next consequtive integer following the lowest ranking tier. # Create Promotion Stack Source: https://docs.voucherify.io/api-reference/promotions/create-promotion-stack /openapi/promotions.json post /v1/promotions/{campaignId}/stacks This method creates one promotion stack. The sequence of promotion tier IDs will determine the promotion stacking order. # Delete Promotion Stack Source: https://docs.voucherify.io/api-reference/promotions/delete-promotion-stack /openapi/promotions.json delete /v1/promotions/{campaignId}/stacks/{stackId} This method deletes a promotion stack. # Delete Promotion Tier Source: https://docs.voucherify.io/api-reference/promotions/delete-promotion-tier /openapi/promotions.json delete /v1/promotions/tiers/{promotionTierId} This method deletes a promotion tier. # Disable Promotion Tier Source: https://docs.voucherify.io/api-reference/promotions/disable-promotion-tier /openapi/promotions.json post /v1/promotions/tiers/{promotionTierId}/disable This method disables a promotion tier, i.e. makes the `active` parameter = `false`. # Enable Promotion Tier Source: https://docs.voucherify.io/api-reference/promotions/enable-promotion-tier /openapi/promotions.json post /v1/promotions/tiers/{promotionTierId}/enable This method enables a promotion tier, i.e. makes the `active` parameter = `true`. # Get Promotion Stack Source: https://docs.voucherify.io/api-reference/promotions/get-promotion-stack /openapi/promotions.json get /v1/promotions/{campaignId}/stacks/{stackId} This method returns the details of a promotion stack, including the promotion tiers grouped within the stack. # Get Promotion Tier Source: https://docs.voucherify.io/api-reference/promotions/get-promotion-tier /openapi/promotions.json get /v1/promotions/tiers/{promotionTierId} This method enables you to retrieve a specific promotion tier. # List Promotion Stacks Source: https://docs.voucherify.io/api-reference/promotions/list-promotion-stacks /openapi/promotions.json get /v1/promotions/stacks This method enables you to list promotion stacks irrespective of the campaign they are associated with. You can use filters in the query parameters to specify the stacks to be returned in the response. ## Advanced filters for fetching promotion stacks | **Filters** | **Examples** | | :--- | :--- | | Created Before | - `[created_at][before]=2021-12-30T13:52:18.227Z`
- `[filters][created_at][conditions][$before][0]=2021-12-30T13:52:18.227Z` | | Created After | - `[created_at][after]=2021-12-30T13:52:18.227Z`
- `[filters][created_at][conditions][$after][0]=2021-12-30T13:52:18.227Z` | | Updated Before | - `[updated_at][before]=2021-12-30T13:52:18.227Z`
- `[filters][updated_at][conditions][$before][0]=2021-12-30T13:52:18.227Z` | | Updated After | - `[updated_at][after]=2021-12-30T13:52:18.227Z`
- `[filters][updated_at][conditions][$after][0]=2021-12-30T13:52:18.227Z` | # List Promotion Stacks in Campaign Source: https://docs.voucherify.io/api-reference/promotions/list-promotion-stacks-in-campaign /openapi/promotions.json get /v1/promotions/{campaignId}/stacks This method enables you to list promotion stacks from a specified campaign. # List Promotion Tiers Source: https://docs.voucherify.io/api-reference/promotions/list-promotion-tiers /openapi/promotions.json get /v1/promotions/tiers This method enables you to list promotion tiers. # List Promotion Tiers from Campaign Source: https://docs.voucherify.io/api-reference/promotions/list-promotion-tiers-from-campaign /openapi/promotions.json get /v1/promotions/{campaignId}/tiers This method enables you to list promotion tiers from a specified campaign. # Promotion Tier Object Source: https://docs.voucherify.io/api-reference/promotions/promotion-tier-object

Promotion Tier

Attributes Description

id
string

Unique promotion tier ID.

Example: promo\_63fYCt81Aw0h7lzyRkrGZh9p

created\_at
string

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

Example: 2021-12-15T11:34:01.333Z

updated\_at
string

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

Example: 2022-02-09T09:20:05.603Z

name
string

Name of the promotion tier.

banner
string

Text to be displayed to your customers on your website.

action
object

Contains details about the discount applied by the promotion tier.

Attributes	Description
discount	See: Discount

metadata
object

hierarchy
integer

promotion\_id
string

Promotion unique ID.

campaign
object

Contains details about promotion tier's parent campaign.

Attributes	Description
id `string`	Unique campaign ID.
start\_date `string`	Activation timestamp defines when the campaign starts to be active in ISO 8601 format. Campaign is inactive before this date. Example: 2022-09-22T00:00:00.000Z
expiration\_date `string`	Expiration timestamp defines when the campaign expires in ISO 8601 format. Campaign is inactive after this date. Example: 2022-09-30T00:00:00.000Z
validity\_timeframe	See: Validity Timeframe
validity\_day\_of\_week	See: Validity Day Of Week
validity\_hours	See: Validity Hours
active `boolean`	A flag indicating whether the campaign is active or not active. A campaign can be disabled even though it's within the active period defined by the `start\_date` and `expiration\_date` using the Disable Campaign endpoint. `true` indicates an active campaign `false` indicates an inactive campaign
category\_id `string`	Unique category ID that this campaign belongs to. Example: cat\_0b688929a2476386a6
object `string`	The type of the object represented by the campaign object. This object stores information about the campaign.

campaign\_id
string

Promotion tier's parent campaign's unique ID.

active
boolean

A flag to toggle the promotion tier on or off. You can disable a promotion tier even though it's within the active period defined by the start\_date and expiration\_date.

true indicates an active promotion tier
false indicates an inactive promotion tier

start\_date
string

Activation timestamp defines when the promotion tier starts to be active in ISO 8601 format. Promotion tier is inactive before this date.

Example: 2022-09-23T00:00:00.000Z

expiration\_date
string

Activation timestamp defines when the promotion tier expires in ISO 8601 format. Promotion tier is inactive after this date.

Example: 2022-09-26T00:00:00.000Z

validity\_timeframe

See: Validity Timeframe

validity\_day\_of\_week

See: Validity Day Of Week

validity\_hours

See: Validity Hours

summary
object

Contains statistics about promotion tier redemptions and orders.

Attributes Description

redemptions
object

Contains statistics about promotion tier redemptions.

Attributes	Description
total\_redeemed `integer`	Number of times the promotion tier was redeemed.

orders
object

Contains statistics about orders related to the promotion tier.

Attributes	Description
total\_amount `integer`	Sum of order totals.
total\_discount\_amount `integer`	Sum of total discount applied using the promotion tier.

object
string

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

validation\_rule\_assignments

See: Validation Rule Assignments List

category\_id
string

Promotion tier category ID.

Example: cat\_0c9da30e7116ba6bba

categories
array

Array of Category

Discount

Contains information about discount.

One of:

Amount
Unit
Unit Multiple
Percent
Fixed

Validity Timeframe

Attributes Description

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

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

Validity Day Of Week

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

Validity Hours

Attributes Description

daily
array

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

Array of:

Attributes Description

start\_time
string

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

Example: 12:00

days\_of\_week
array

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

expiration\_time
string

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

Example: 14:00

Validation Rule Assignments List

Attributes	Description
object `string`	The type of the object represented by JSON. This object stores information about validation rule assignments.
data\_ref `string`	Identifies the name of the JSON property that contains the array of validation rule assignments.
data `array`	A dictionary that contains an array of validation rule assignments. Array of Validation Rule Assignment
total `integer`	Total number of validation rule assignments.

Category

Attributes	Description
id `string`	Unique category ID assigned by Voucherify.
name `string`	Category name.
hierarchy `integer`	Category hierarchy. Categories with lower hierarchy are processed before categories with higher hierarchy value.
object `string`	The type of the object represented by the JSON. This object stores information about the category. Available values: `category`
created\_at `string`	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
updated\_at `string`	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

Amount

Attributes	Description
type `string`	Defines the type of the voucher. Available values: `AMOUNT`
amount\_off `number`	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.
amount\_off\_formula `string`	Formula used to dynamically calculate the discount.
aggregated\_amount\_limit `integer`	Maximum discount amount per order.
effect	Defines how the discount is applied to the customer's order. Discount Amount Vouchers Effect Types
is\_dynamic `boolean`	Flag indicating whether the discount was calculated using a formula.

Unit

Attributes	Description
type `string`	Discount type. Available values: `UNIT`
unit\_off `integer`	Number of units to be granted a full value discount.
unit\_off\_formula `string`	Formula used to dynamically calculate the number of units.
effect	Defines how the unit is added to the customer's order. Discount Unit Vouchers Effect Types
unit\_type `string`	The product deemed as free, chosen from product inventory (e.g. time, items).
product	Contains information about the product. Simple Product Discount Unit
sku	See: Simple Sku Discount Unit
is\_dynamic `boolean`	Flag indicating whether the discount was calculated using a formula.

Unit Multiple

Attributes Description

type
string

Discount type.

Available values: UNIT

effect
string

Defines how the discount is applied to the customer's order.

Available values: ADD\_MANY\_ITEMS

units
array

Array of One Unit

Percent

Attributes	Description
type `string`	Defines the type of the voucher. Available values: `PERCENT`
percent\_off `number`	The percent discount that the customer will receive.
percent\_off\_formula `string`	Formula used to dynamically calculate the discount.
amount\_limit `number`	Upper limit allowed to be applied as a discount. Value is multiplied by 100 to precisely represent 2 decimal places. For example, a \$6 maximum discount is written as 600.
aggregated\_amount\_limit `integer`	Maximum discount amount per order.
effect	Defines how the discount is applied to the customer's order. Discount Percent Vouchers Effect Types
is\_dynamic `boolean`	Flag indicating whether the discount was calculated using a formula.

Fixed

Attributes	Description
type `string`	Defines the type of the voucher. Available values: `FIXED`
fixed\_amount `number`	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.
fixed\_amount\_formula `string`	Formula used to dynamically calculate the discount.
effect	Defines how the discount is applied to the customer's order. Discount Fixed Vouchers Effect Types
is\_dynamic `boolean`	Flag indicating whether the discount was calculated using a formula.

Validation Rule Assignment

Attributes	Description
id `string`	Validation rule assignment ID. Example: asgm\_74F7QZoYbUoljwQO
rule\_id `string`	Validation rule ID. Example: val\_4j7DCRm2IS59
related\_object\_id `string`	The resource ID to which the validation rule was assigned. Example: v\_JtWunK6jUo7X2qOFj0SyRHq4p9tgENlT
related\_object\_type `string`	The type of resource to which the validation rule was assigned. Available values: `voucher`, `campaign`, `earning\_rule`, `reward\_assignment`, `promotion\_tier`, `distribution`
created\_at `string`	Timestamp representing the date and time when the validation rule assignment was created. The value is shown in the ISO 8601 format. Example: 2022-02-17T08:18:15.085Z
object `string`	The type of the object represented by the ID. Available values: `validation\_rules\_assignment`

Discount Amount Vouchers Effect Types

Available values: APPLY\_TO\_ORDER, APPLY\_TO\_ITEMS, APPLY\_TO\_ITEMS\_PROPORTIONALLY, APPLY\_TO\_ITEMS\_PROPORTIONALLY\_BY\_QUANTITY, APPLY\_TO\_ITEMS\_BY\_QUANTITY

Discount Unit Vouchers Effect Types

Available values: ADD\_MISSING\_ITEMS, ADD\_NEW\_ITEMS, ADD\_MANY\_ITEMS, ADD\_SAME\_ITEMS

Simple Product Discount Unit

Attributes	Description
id `string`	Unique product ID, assigned by Voucherify.
source\_id `string`	Product's source ID.
name `string`	Product name.

Simple Sku Discount Unit

Attributes	Description
id `string`	Unique SKU ID, assigned by Voucherify.
source\_id `string`	Product variant's source ID.
name `string`	Sku name

One Unit

Attributes	Description
unit\_off `number`	Number of units to be granted a full value discount.
unit\_off\_formula `string`	Formula used to dynamically calculate the number of units.
effect `string`	Defines how the unit is added to the customer's order. Available values: `ADD\_NEW\_ITEMS`, `ADD\_MISSING\_ITEMS`
unit\_type `string`	The product deemed as free, chosen from product inventory (e.g. time, items).
product	Contains information about the product. Simple Product Discount Unit
sku	Contains information about the sku. Simple Sku Discount Unit

Discount Percent Vouchers Effect Types

Available values: APPLY\_TO\_ORDER, APPLY\_TO\_ITEMS

Discount Fixed Vouchers Effect Types

Available values: APPLY\_TO\_ORDER, APPLY\_TO\_ITEMS

# Update Promotion Stack Source: https://docs.voucherify.io/api-reference/promotions/update-promotion-stack /openapi/promotions.json put /v1/promotions/{campaignId}/stacks/{stackId} This methods allows for editing an existing stack. # Update Promotion Tier Source: https://docs.voucherify.io/api-reference/promotions/update-promotion-tier /openapi/promotions.json put /v1/promotions/tiers/{promotionTierId} This method updates a promotion tier. # Succeeded Source: https://docs.voucherify.io/api-reference/publication/succeeded openapi-events/events-publication.json webhook EVENTS.PUBLICATION.SUCCEEDED The `EVENTS.PUBLICATION.SUCCEEDED` event indicates that a voucher code was successfully published to a customer. This event serves as a real-time notification mechanism and it can notify other systems or applications that a voucher was assigned. As a result, the systems can react by, for example, sending a notification about an assignment to a customer. In contrast to [EVENTS.VOUCHER.PUBLISHED](/api-reference/voucher/published), this event includes a `user` object that can be used to track who published a voucher through Voucherify dashboard. This event is used in a webhook configured in Project settings in Voucherify dashboard. This page documents only the event. If you need more details about the webhook payload data that includes this event, go to [Introduction to webhooks](/api-reference/introduction-to-webhooks "Introduction to webhooks v2024-01-01") page. # Create Publication Source: https://docs.voucherify.io/api-reference/publications/create-publication /openapi/publications.json post /v1/publications This method selects vouchers that are suitable for publication, adds a publish entry and returns the publication. A voucher is suitable for publication when it's active and hasn't been published yet. Clearly define the source of the voucher You must clearly define which source you want to publish the voucher code from. It can either be a code from a campaign or a specific voucher identified by a code. Publish multiple vouchers In case you want to publish multiple vouchers within a single publication, you need to specify the campaign name and number of vouchers you want to publish. Auto-update campaign In case you want to ensure the number of publishable codes increases automatically with the number of customers, you should use an **auto-update** campaign. # Create Publication with GET Source: https://docs.voucherify.io/api-reference/publications/create-publication-with-get /openapi/publications.json get /v1/publications/create This method selects vouchers that are suitable for publication, adds a publish entry and returns the publication. A voucher is suitable for publication when it's active and hasn't been published yet. Limited access Access to this endpoint is limited. This endpoint is designed for specific integrations and the API keys need to be configured to access this endpoint. Navigate to the **Dashboard** → **Project Settings** → **General** → **Integration Keys** to set up a pair of API keys and use them to send the request. Clearly define the source of the voucher You must clearly define which source you want to publish the voucher code from. It can either be a code from a campaign or a specific voucher identified by a code. Publish multiple vouchers This endpoint does not support the publishing of multiple vouchers from a single campaign. In case you want to publish multiple vouchers within a single publication, you need to use a [dedicated endpoint](/api-reference/publications/create-publication). Auto-update campaign In case you want to ensure the number of publishable codes increases automatically with the number of customers, you should use an **auto-update** campaign. ## Example Request ```markdown Publication Query /publications/create?campaign[name]=BlackFriday&customer[source_id]=Customer_Source_ID ``` Required Query param `voucher` OR `campaign` MUST be filled out. If you provide both, `campaign` param will be skipped. # List Publications Source: https://docs.voucherify.io/api-reference/publications/list-publications /openapi/publications.json get /v1/publications Retrieve a list of publications. To return a **particular** publication, you can use the `source_id` query parameter and provide the `source_id` of the publication you are looking for specifically. ## Pagination Important! If you want to scroll through a huge set of records, it is recommended to use the [Exports API](/api-reference/exports/create-export). This API will return an error `page_over_limit` if you reach a page above 1000. ## Filter Query The `filters` query parameter allows for joining multiple parameters with logical operators. The syntax looks as follows: ``` "$in" "$not_in" "$is" "$is_not" "$has_value" "$is_unknown" "$contains" "$starts_with" "$ends_with" "$more_than" "$less_than" "$more_than_equal" "$less_than_equal" ``` ### Examples ```url GET /v1/publications?filters[customer_id][conditions][$is][0]=cust_lUET6gRpO5Wxlg5p2j2gRCgL ``` ```url GET /v1/publications?filters[customer_id][conditions][$in][0]=cust_lUET6gRpO5Wxlg5p2j2gRCgL&filters[customer_id][conditions][$in][1]=cust_aR7NfHusxT7PdTMAKMfWDXnc ``` ```url GET /v1/publications?filters[customer_id][conditions][$is][0]=cust_lUET6gRpO5Wxlg5p2j2gRCgL&filters[customer_id][conditions][$is][1]=cust_aR7NfHusxT7PdTMAKMfWDXnc&filters[junction]=OR ``` # Publication Object Source: https://docs.voucherify.io/api-reference/publications/publication-object

Publications Create Response Body

Response body schema for POST v1/publication and GET v1/publications/create.

One of:

Publications Create Voucher Response Body
Publications Create Vouchers Response Body

Publications Create Voucher Response Body

Response body schema for POST v1/publication and GET v1/publications/create.

All of:

Publications Create Base Response Body

Attributes	Description
voucher	See: Voucher

Publications Create Vouchers Response Body

Response body schema for POST v1/publication and GET v1/publications/create.

All of:

Publications Create Base Response Body

Attributes	Description
vouchers `array`	Contains the unique voucher codes that was assigned by Voucherify.

Publications Create Base Response Body

Attributes	Description
id `string`	Unique publication ID, assigned by Voucherify. Example: pub\_BbjAXnmm8e0SIm3zG8qvvFCP0KuLywtp
object `string`	The type of the object represented by the JSON. This object stores information about the `publication`. Available values: `publication`
created\_at `string`	Timestamp representing the date and time when the publication was created. The value is shown in the ISO 8601 format. Example: 2022-09-23T09:57:00.434Z
customer\_id `string`	Unique customer ID of the customer receiving the publication. Example: cust\_eWgXlBBiY6THFRJwX45Iakv4
tracking\_id `string`	Customer's `source\_id`.
metadata `object`	The metadata object stores all custom attributes assigned to the publication. A set of key/value pairs that you can attach to a publication object. It can be useful for storing additional information about the publication in a structured format.
channel `string`	How the publication was originated. It can be your own custom channel or an example value provided here. Available values: `API`
source\_id `string`, `null`	The merchant's publication ID if it is different from the Voucherify publication ID. It's an optional tracking identifier of a publication. It is really useful in case of an integration between multiple systems. It can be a publication ID from a CRM system, database or 3rd-party service.
result `string`	Status of the publication attempt. Available values: `SUCCESS`
customer	See: Customer With Summary Loyalty Referrals
vouchers\_id `array`	Contains the unique internal voucher ID that was assigned by Voucherify.

Voucher

This is an object representing a voucher with categories and validation rules assignments.

All of:

Voucher Base

Attributes	Description
categories `array`	Contains details about the category. Array of Category
validation\_rules\_assignments	See: Validation Rules Assignments List

Customer With Summary Loyalty Referrals

All of:

Customer Response Data

Attributes Description

id
string

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

source\_id
string

summary

Customer Summary

loyalty

Customer Loyalty

referrals

Customer Referrals

system\_metadata
object

Object used to store system metadata information.

created\_at
string

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

Example: 2022-08-30T06:32:07.380Z

updated\_at
string

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

Example: 2022-08-31T06:32:07.380Z

assets
object

Contains information about the customer's cockpit.

⚠️ Warning: Customer cockpits were removed. The customer cockpit URLs redirect to customer preference center.

Attributes	Description
cockpit\_url `string`	URL address to customer preference center. Previously, a customer's cockpit URL address.
cockpit\_preference\_center\_url `string`	URL address to customer preference center.

object
string

The type of the object represented by JSON.

Available values: customer

Customer Base

Voucher Base

Attributes Description

id
string

Assigned by the Voucherify API, identifies the voucher.

Example: v\_mkZN9v7vjYUadXnHrMza8W5c34fE5KiV

code
string

A code that identifies a voucher. Pattern can use all letters of the English alphabet, Arabic numerals, and special characters.

Example: WVPblOYX

campaign
string

A unique campaign name, identifies the voucher's parent campaign.

Example: Gift Card Campaign

campaign\_id
string

Assigned by the Voucherify API, identifies the voucher's parent campaign.

Example: camp\_FNYR4jhqZBM9xTptxDGgeNBV

category
string

Tag defining the category that this voucher belongs to. Useful when listing vouchers using the List Vouchers endpoint.

category\_id
string

Unique category ID assigned by Voucherify.

Example: cat\_0bb343dee3cdb5ec0c

type
string

Defines the type of the voucher.

Available values: GIFT\_VOUCHER, DISCOUNT\_VOUCHER, LOYALTY\_CARD

discount

See: Discount

gift
object

Object representing gift parameters. Child attributes are present only if type is GIFT\_VOUCHER. Defaults to null.

Attributes	Description
amount `integer`	Total gift card income over the lifetime of the card. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `\$100.00`. Example: 10000
subtracted\_amount `integer`	Total amount of subtracted credits over the gift card lifetime. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `\$100.00`.
balance `integer`	Available funds. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `\$100.00`. Example: 500
effect `string`	Defines how the credits are applied to the customer's order. Available values: `APPLY\_TO\_ORDER`, `APPLY\_TO\_ITEMS`

loyalty\_card
object

Object representing loyalty card parameters. Child attributes are present only if type is LOYALTY\_CARD. Defaults to null.

Attributes	Description
points `integer`	Total number of points added to the loyalty card over its lifespan. Example: 7000
balance `integer`	Points available for reward redemption. This is calculated as follows: `balance` \= `points` \- `expired\_points` \- `subtracted\_points` \- `redemption.redeemed\_points`. Example: 6970
next\_expiration\_date `string`	The next closest date when the next set of points are due to expire. Example: 2023-05-30
next\_expiration\_points `integer`	The amount of points that are set to expire next.
pending\_points `integer`	Shows the number of pending points that will be added to the loyalty card when they are activated automatically or manually.
expired\_points `integer`	Shows the total number of expired points over the lifetime of the loyalty card.
subtracted\_points `integer`	Shows the total number of subtracted points over the lifetime of the loyalty card.

start\_date
string

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

Example: 2021-12-01T00:00:00.000Z

expiration\_date
string

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

Example: 2021-12-31T00:00:00.000Z

validity\_timeframe

See: Validity Timeframe

validity\_day\_of\_week

See: Validity Day Of Week

validity\_hours

See: Validity Hours

active
boolean, null

A flag to toggle the voucher on or off. You can disable a voucher even though it's within the active period defined by the start\_date and expiration\_date.

true indicates an active voucher
false indicates an inactive voucher

additional\_info
string

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

metadata
object

assets

See: Voucher Assets

is\_referral\_code
boolean, null

Flag indicating whether this voucher is a referral code; true for campaign type REFERRAL\_PROGRAM.

created\_at
string

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

Example: 2021-12-22T10:13:06.487Z

updated\_at
string

Timestamp representing the date and time when the voucher was last updated in ISO 8601 format.

Example: 2021-12-22T10:14:45.316Z

holder\_id
string

Unique customer identifier of the redeemable holder. It equals to the customer ID assigned by Voucherify.

Example: cust\_eWgXlBBiY6THFRJwX45Iakv4

referrer\_id
string

Unique identifier of the referring person.

Example: cust\_Vzck5i8U3OhcEUFY6MKhN9Rv

object
string

The type of the object represented by JSON. Default is voucher.

publish
object

Stores a summary of publication events: an event counter and endpoint to return details of each event. Publication is an assignment of a code to a customer, e.g. through a distribution.

Attributes Description

object
string

The type of the object represented is by default list. To get this list, you need to make a call to the endpoint returned in the url attribute.

count
integer

Publication events counter.

Example: 0

url
string

The endpoint where this list of publications can be accessed using a GET method. /v1/vouchers//publications

Example: /v1/vouchers/WVPblOYX/publications?page=1\&limit=10

redemption
object

Stores a summary of redemptions that have been applied to the voucher.

Attributes	Description
quantity `integer`	How many times a voucher can be redeemed. A `null` value means unlimited.
redeemed\_quantity `integer`	How many times a voucher has already been redeemed. Example: 1
redeemed\_points `integer`	Total loyalty points redeemed. Example: 100000
object `string`	The type of the object represented is by default `list`. To get this list, you need to make a call to the endpoint returned in the url attribute.
url `string`	The endpoint where this list of redemptions can be accessed using a GET method. `/v1/vouchers//redemptions` Example: /v1/vouchers/WVPblOYX/redemptions?page=1\&limit=10

Category

Attributes	Description
id `string`	Unique category ID assigned by Voucherify.
name `string`	Category name.
hierarchy `integer`	Category hierarchy. Categories with lower hierarchy are processed before categories with higher hierarchy value.
object `string`	The type of the object represented by the JSON. This object stores information about the category. Available values: `category`
created\_at `string`	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
updated\_at `string`	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

Validation Rules Assignments List

Attributes	Description
object `string`	The type of the object represented by JSON. This object stores information about validation rules assignments. Available values: `list`
data\_ref `string`	Identifies the name of the attribute that contains the array of validation rules assignments. Available values: `data`
data `array`	Contains array of validation rules assignments. Array of Business Validation Rule Assignment
total `integer`	Total number of validation rules assignments.

Customer Summary

Attributes	Description
redemptions	See: Customer Summary Redemptions
orders	See: Customer Summary Orders

Customer Loyalty

Attributes Description

points
integer

Customer's loyalty points minus expired for all loyalty cards which the customer has.

referred\_customers
integer

Total number of customers referred by the customer.

campaigns
object

Contains campaigns with details about point balances and how many customers were referred by the customer.

Attributes Description

\[propertyName]
object

Contains details about the point balances left on loyalty cards and the number of referred customers in each campaign.

Attributes Description

points
integer

Remaining point balance in campaign.

loyalty\_tier
string

Customer's loyalty tier within the campaign.

Example: ltr\_UJ5Q54Q0OvEhua87Qfv2Ki5x

referred\_customers
integer

Number of customers referred by the customer in campaign.

Customer Referrals

Attributes Description

total
integer

Total number of times this customer received a referral, i.e. was referred by another customer.

campaigns
array

Contains an array of campaigns that served as the source of a referral for the customer.

Array of:

Customer Referrals Campaigns Item

Attributes	Description
campaign\_id `string`	Unique campaign ID, assigned by Voucherify. Example: camp\_rRsfatlwN7unSeUIJDCYedal
referrer\_id `string`	Unique referrer ID, assigned by Voucherify. This is the customer ID of a customer that is referring this customer. Example: cust\_sehkNIi8Uq2qQuRqSr7xn4Zi
related\_object\_id `string`	Related object id Example: r\_0b9d4cc4aa164dd073
related\_object\_type `string`	Related object type, i.e. `redemption`.
date `string`	Timestamp representing the date and time when the customer was referred in ISO 8601 format. Example: 2022-08-30T10:19:39.196Z

Customer Base

Attributes Description

name
string

Customer's first and last name.

description
string

An arbitrary string that you can attach to a customer object.

email
string

Customer's email address.

phone
string

Customer's phone number. This parameter is mandatory when you try to send out codes to customers via an SMS channel.

birthday
string

Deprecated. ~~Customer's birthdate; format YYYY-MM-DD~~.

birthdate
string

Customer's birthdate; format YYYY-MM-DD.

address
object, null

Customer's address.

Attributes	Description
city `string`	City
state `string`	State
line\_1 `string`	First line of address.
line\_2 `string`	Second line of address.
country `string`	Country.
postal\_code `string`	Postal code.

metadata
object

Discount

Contains information about discount.

One of:

Amount
Unit
Unit Multiple
Percent
Fixed

Validity Timeframe

Attributes Description

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

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

Validity Day Of Week

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

Validity Hours

Attributes Description

daily
array

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

Array of:

Attributes Description

start\_time
string

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

Example: 12:00

days\_of\_week
array

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

expiration\_time
string

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

Example: 14:00

Voucher Assets

Attributes Description

qr
object

Stores Quick Response (QR) representation of encrypted code.

Attributes Description

id
string

Encrypted voucher code ID.

Example: U2FsdGVkX19ucFhvVmBVpVYG5KoswTsjSIaqoKg5L9ie4BK+t4pp7U7oFzjGJzj9q/bmuMOj9mEFiVKDMIkSaruKedMvHbKoPX5Sg+BaZk5QwXMf8k/OzSlOEVybpwSq+AiqPoNtjeuqtIgkDyvT6Q==

url
string

URL to QR code

Optional: Attach query parameters to base URL to customize the image of the encrypted voucher code.

size : integer value from 1 to 100
format : string, either png (default) or svg

barcode
object

Stores barcode representation of encrypted code.

Attributes Description

id
string

Encrypted voucher code ID.

Example: U2FsdGVkX19eJhGfWwUrH9+tulBkON+AnMktic+N6CVWzZ9+fHVxuVx22WakrzxiWXy0skuvvEHSeZIw9HlgyIJ+kJ1iPdUKpyENuNYJKzoZlO0mmTf6WQM6/pFs61apEn9SJx32ttCF6d3oxKISQQ==

url
string

URL to barcode

Optional: Attach query parameters to base URL to customize the image of the encrypted voucher code.

size : integer value from 1 to 100
format : string, either png (default) or svg

Business Validation Rule Assignment

Attributes	Description
id `string`	The unique identifier for a assignment
rule\_id `string`	The unique identifier for a rule
related\_object\_id `string`	The unique identifier for a related object
related\_object\_type `string`	The type of related object
created\_at `string`	Timestamp representing the date and time when the object was created. The value is shown in the ISO 8601 format. Example: 2022-03-09T11:19:04.819Z
updated\_at `string`	Timestamp representing the date and time when the object was last updated in ISO 8601 format. Example: 2022-03-09T11:19:04.819Z
object `string`	The type of the object represented by JSON. Available values: `validation\_rules\_assignment`
validation\_status `string`	The validation status of the assignment Available values: `VALID`, `PARTIALLY\_VALID`, `INVALID`
validation\_omitted\_rules `array`	The list of omitted rules

Customer Summary Redemptions

Attributes Description

total\_redeemed
integer

Total number of redemptions made by the customer.

total\_failed
integer

Total number of redemptions that failed.

total\_succeeded
integer

Total number of redemptions that succeeded.

total\_rolled\_back
integer

Total number of redemptions that were rolled back for the customer.

total\_rollback\_failed
integer

Total number of redemption rollbacks that failed.

total\_rollback\_succeeded
integer

Total number of redemption rollbacks that succeeded.

gift
object

Summary of gift card credits.

Attributes	Description
redeemed\_amount `integer`	Total amount of gift card credits redeemed by customer. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `\$100.00`.
amount\_to\_go `integer`	Remaining gift card balance across all gift cards. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `\$100.00`.

loyalty\_card
object

Summary of loyalty points.

Attributes	Description
redeemed\_points `integer`	Total number of loyalty points redeemed by the customer.
points\_to\_go `integer`	Sum of remaining available point balance across all loyalty cards.

Customer Summary Orders

Attributes	Description
total\_amount `integer`	The total amount spent by the customer. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `\$100.00`.
total\_count `integer`	Total number of orders made by the customer.
average\_amount `integer`	Average amount spent on orders. `total\_amount` ÷ `total\_count`. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `\$100.00`.
last\_order\_amount `integer`	Amount spent on last order. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `\$100.00`.
last\_order\_date `string`	Timestamp representing the date and time of the customer's last order in ISO 8601 format. Example: 2022-08-30T11:51:08.029Z

Amount

Attributes	Description
type `string`	Defines the type of the voucher. Available values: `AMOUNT`
amount\_off `number`	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.
amount\_off\_formula `string`	Formula used to dynamically calculate the discount.
aggregated\_amount\_limit `integer`	Maximum discount amount per order.
effect	Defines how the discount is applied to the customer's order. Discount Amount Vouchers Effect Types
is\_dynamic `boolean`	Flag indicating whether the discount was calculated using a formula.

Unit

Attributes	Description
type `string`	Discount type. Available values: `UNIT`
unit\_off `integer`	Number of units to be granted a full value discount.
unit\_off\_formula `string`	Formula used to dynamically calculate the number of units.
effect	Defines how the unit is added to the customer's order. Discount Unit Vouchers Effect Types
unit\_type `string`	The product deemed as free, chosen from product inventory (e.g. time, items).
product	Contains information about the product. Simple Product Discount Unit
sku	See: Simple Sku Discount Unit
is\_dynamic `boolean`	Flag indicating whether the discount was calculated using a formula.

Unit Multiple

Attributes Description

type
string

Discount type.

Available values: UNIT

effect
string

Defines how the discount is applied to the customer's order.

Available values: ADD\_MANY\_ITEMS

units
array

Array of One Unit

Percent

Attributes	Description
type `string`	Defines the type of the voucher. Available values: `PERCENT`
percent\_off `number`	The percent discount that the customer will receive.
percent\_off\_formula `string`	Formula used to dynamically calculate the discount.
amount\_limit `number`	Upper limit allowed to be applied as a discount. Value is multiplied by 100 to precisely represent 2 decimal places. For example, a \$6 maximum discount is written as 600.
aggregated\_amount\_limit `integer`	Maximum discount amount per order.
effect	Defines how the discount is applied to the customer's order. Discount Percent Vouchers Effect Types
is\_dynamic `boolean`	Flag indicating whether the discount was calculated using a formula.

Fixed

Attributes	Description
type `string`	Defines the type of the voucher. Available values: `FIXED`
fixed\_amount `number`	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.
fixed\_amount\_formula `string`	Formula used to dynamically calculate the discount.
effect	Defines how the discount is applied to the customer's order. Discount Fixed Vouchers Effect Types
is\_dynamic `boolean`	Flag indicating whether the discount was calculated using a formula.

Discount Amount Vouchers Effect Types

Available values: APPLY\_TO\_ORDER, APPLY\_TO\_ITEMS, APPLY\_TO\_ITEMS\_PROPORTIONALLY, APPLY\_TO\_ITEMS\_PROPORTIONALLY\_BY\_QUANTITY, APPLY\_TO\_ITEMS\_BY\_QUANTITY

Discount Unit Vouchers Effect Types

Available values: ADD\_MISSING\_ITEMS, ADD\_NEW\_ITEMS, ADD\_MANY\_ITEMS, ADD\_SAME\_ITEMS

Simple Product Discount Unit

Attributes	Description
id `string`	Unique product ID, assigned by Voucherify.
source\_id `string`	Product's source ID.
name `string`	Product name.

Simple Sku Discount Unit

Attributes	Description
id `string`	Unique SKU ID, assigned by Voucherify.
source\_id `string`	Product variant's source ID.
name `string`	Sku name

One Unit

Attributes	Description
unit\_off `number`	Number of units to be granted a full value discount.
unit\_off\_formula `string`	Formula used to dynamically calculate the number of units.
effect `string`	Defines how the unit is added to the customer's order. Available values: `ADD\_NEW\_ITEMS`, `ADD\_MISSING\_ITEMS`
unit\_type `string`	The product deemed as free, chosen from product inventory (e.g. time, items).
product	Contains information about the product. Simple Product Discount Unit
sku	Contains information about the sku. Simple Sku Discount Unit

Discount Percent Vouchers Effect Types

Available values: APPLY\_TO\_ORDER, APPLY\_TO\_ITEMS

Discount Fixed Vouchers Effect Types

Available values: APPLY\_TO\_ORDER, APPLY\_TO\_ITEMS

# Check Eligibility Source: https://docs.voucherify.io/api-reference/qualifications/check-eligibility /openapi/qualifications.json post /v1/qualifications The Qualifications endpoint ignores the rules checking: - Limit of total redeemed discount amount per campaign - Limit of total redemptions count per campaign - Redemptions per customer - Redemptions per customer in a campaign - Total amount before discount Generate a list of redeemables that are applicable in the context of the customer and order. The new qualifications method is an improved version of [Campaign Qualifications](/api-reference/campaigns/examine-campaign-qualification), [Voucher Qualifications](/api-reference/vouchers/examine-voucher-qualification) API requests. The new qualification method introduces the following improvements: - Qualification results are returned faster - No limit on the number of returned redeemables - Introduces new qualification scenarios, not available in the previous version Scenario Guide Read [the dedicated guide](/guides/checking-eligibility) to learn about some use cases this endpoint can cover. ## Paging The Voucherify Qualifications API request will return to you all of the redeemables available for the customer in batches of up to 50 redeemables per page. To get the next batch of redeemables, you need to use the `starting_after` cursor. To process of paging the redeemables works in the following manner: - You send the first API request for Qualifications without the `starting_after` parameter. - The response will contain a parameter named `has_more`. If the parameter's value is set to `true`, then more redeemables are available. - Get the value of the `created_at` parameter of the last returned redeemable. The value of this parameter will be used as a cursor to retrieve the next page of redeemables. - Send another API request for Qualification with the `starting_after` parameter set to the value taken from the `created_at` parameter from the last returned redeemable. - Voucherify will return the next page of redeemables. - If the `has_more` parameter is set to `true`, apply steps 3-5 to get the next page of redeemables. ## Caching Qualification has a 5-minute cache for the returned results. If you change your campaign settings or validation rules, the changes will apply to qualification results after the cache refreshes. # Qualification Object Source: https://docs.voucherify.io/api-reference/qualifications/qualification-object

Qualifications Check Eligibility Response Body

Attributes Description

redeemables

See: Redeemables

tracking\_id
string

This identifier is generated during voucher qualification based on your internal id (e.g., email, database ID). This is a hashed customer source ID.

order
object

All of:

Order Calculated No Customer Data

Attributes	Description
items `array`	Array of items applied to the order. It can include up to 500 items.

stacking\_rules

See: Stacking Rules

Redeemables

Attributes	Description
object `string`	The type of the object represented by JSON. Default is `list`. Available values: `list`
data\_ref `string`	Identifies the name of the attribute that contains the array of qualified redeemables. Available values: `data`
data `array`	Array of qualified redeemables. Array of Combined response of redeemable object and multiple redeemables within
total `integer`	The number of redeemables returned in the API request. Example: 5
has\_more `boolean`	As results are always limited, the `has\_more` flag indicates if there are more records for given parameters. This lets you know if you can run another request (with different options) to get more records returned in the results.
more\_starting\_after `string`	Timestamp representing the date and time to use in `starting\_after` cursor to get more redeemables. Example: 2023-10-31T12:13:16.374Z

Order Calculated No Customer Data

Attributes Description

id
string

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

source\_id
string, null

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

status
string

The order status.

Available values: CREATED, PAID, CANCELED, FULFILLED

amount
integer

This is the sum of the order items' amounts. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for \$1.00).

initial\_amount
integer

discount\_amount
integer

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\_discount\_amount
integer

Sum of all product-specific discounts applied to the order. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for \$1.00).

total\_discount\_amount
integer

Sum of all order-level AND all product-specific discounts applied to the order. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for \$1.00).

total\_amount
integer

Order amount after undoing all the discounts through the rollback redemption. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for \$1.00).

applied\_discount\_amount
integer

This field shows the order-level discount applied. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for \$1.00).

items\_applied\_discount\_amount
integer

total\_applied\_discount\_amount
integer

metadata
object

object
string

The type of the object represented by JSON.

Available values: order

created\_at
string

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

Example: 2021-12-22T10:13:06.487Z

updated\_at
string, null

Timestamp representing the date and time when the order was last updated in ISO 8601 format.

Example: 2021-12-22T10:14:45.316Z

customer\_id
string, null

Unique customer identifier of the customer making the purchase. The ID is assigned by Voucherify.

Example: cust\_7iUa6ICKyU6gH40dBU25kQU1

referrer\_id
string, null

Unique referrer ID.

Example: cust\_nM4jqPiaXUvQdVSA6vTRUnix

customer

Customer Id

referrer

Referrer Id

redemptions
object

Attributes	Description
\[propertyName]	See: Order Redemptions

Stacking Rules

Attributes Description

redeemables\_limit
integer

Defines how many redeemables can be sent in one request. Note: more redeemables means more processing time.

applicable\_redeemables\_limit
integer

Defines how many redeemables can be applied in one request. The number must be less than or equal to redeemables\_limit. For example, a user can select 30 discounts but only 5 will be applied to the order and the remaining will be SKIPPED according to the redeemables\_sorting\_rule.

applicable\_redeemables\_per\_category\_limit
integer

Defines how many redeemables with the same category can be applied in one request. The number must be less than or equal to applicable\_redeemables\_limit. The ones above the limit will be SKIPPED according to the redeemables\_sorting\_rule.

applicable\_redeemables\_category\_limits
object

Lists categories by category IDs (keys) and defines their limits (values) of applicable redeemables that belong to campaigns with that category.

Attributes	Description
\[propertyName] `integer`	Limit of applicable redeemables per category.

applicable\_exclusive\_redeemables\_limit
integer

Defines how many redeemables with an assigned exclusive category can be applied in one request. The ones above the limit will be SKIPPED according to the redeemables\_sorting\_rule.

applicable\_exclusive\_redeemables\_per\_category\_limit
integer

Defines how many redeemables with an exclusive category per category in stacking rules can be applied in one request. The ones above the limit will be SKIPPED according to the redeemables\_sorting\_rule.

exclusive\_categories
array

Lists the IDs of exclusive categories. A redeemable from a campaign with an exclusive category is the only redeemable to be redeemed when applied with redeemables from other campaigns unless these campaigns are exclusive or joint.

joint\_categories
array

Lists the IDs of the joint categories. A campaign with a joint category is always applied regardless of the exclusivity of other campaigns.

redeemables\_application\_mode
string

Defines the application mode for redeemables.
"ALL" means that all redeemables must be validated for the redemption to be successful.
"PARTIAL" means that only those redeemables that can be validated will be redeemed. The redeemables that fail validaton will be skipped.

Available values: ALL, PARTIAL

redeemables\_sorting\_rule
string

Defines redeemables sorting rule. CATEGORY\_HIERARCHY means that redeemables are applied oaccording to the category priority. REQUESTED\_ORDER means that redeemables are applied in the sequence provided in the request.

Available values: CATEGORY\_HIERARCHY, REQUESTED\_ORDER

redeemables\_products\_application\_mode
string

Defines redeemables products application mode. STACK means that multiple discounts can be applied to a product. ONCE means that only one discount can be applied to the same product.

Available values: STACK, ONCE

redeemables\_no\_effect\_rule
string

Defines redeemables no effect rule. REDEEM\_ANYWAY means that the redeemable will be redeemed regardless of any restrictions or conditions in place. SKIP means that the redeemable will be processed only when an applicable effect is calculated.

Available values: REDEEM\_ANYWAY, SKIP

no\_effect\_skip\_categories
array

Lists category IDs. Redeemables with a given category are skipped even if the redeemables\_no\_effect\_rule is set to REDEEM\_ANYWAY. Category IDs can't overlap with the IDs in no\_effect\_redeem\_anyway\_categories.

no\_effect\_redeem\_anyway\_categories
array

Lists category IDs. Redeemables with a given category are redeemed anyway even if the redeemables\_no\_effect\_rule is set to SKIP. Category IDs can't overlap with the IDs in no\_effect\_skip\_categories.

redeemables\_rollback\_order\_mode
string

Defines the rollback mode for the order. WITH\_ORDER is a default setting. The redemption is rolled back together with the data about the order, including related discount values. WITHOUT\_ORDER allows rolling the redemption back without affecting order data, including the applied discount values.

Available values: WITH\_ORDER, WITHOUT\_ORDER

Combined response of redeemable object and multiple redeemables within

All of:

Single redeemable

Attributes	Description
redeemables `array`	Array of Single redeemable

Customer Id

Attributes Description

id
string

A unique identifier of an existing customer.

object
string

The type of the object represented by JSON.

Available values: customer

Referrer Id

Customer Id

Order Redemptions

Attributes	Description
date `string`	Timestamp representing the date and time when the redemption was created. The value is shown in the ISO 8601 format. Example: 2022-09-02T17:06:56.649Z
rollback\_id `string`	Unique ID of the redemption rollback. Example: rr\_0c63c84eb78ee0a6c0
rollback\_date `string`	Timestamp representing the date and time when the redemption rollback was created. The value is shown in the ISO 8601 format. Example: 2023-01-31T14:18:37.150Z
related\_object\_type `string`	The source of the incentive.
related\_object\_id `string`	Unique ID of the parent redemption. Example: r\_0ba186c4824e4881e1
related\_object\_parent\_id `string`	Represent's the campaign ID of the voucher if the redemption was based on a voucher that was part of bulk codes generated within a campaign. In case of a promotion tier, this represents the campaign ID of the promotion tier's parent campaign.
stacked `array`	Contains a list of unique IDs of child redemptions, which belong to the stacked incentives.
rollback\_stacked `array`	Lists the rollback redemption IDs of the particular child redemptions.

Single redeemable

Attributes Description

id
string

ID of the redeemable. For a voucher, it's its code value.

object
string

Object type of the redeemable.

Available values: campaign, promotion\_tier, promotion\_stack, voucher

created\_at
string

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

Example: 2022-03-09T11:19:04.819Z

result

See: Redeemable Result

order

All of:

Order Calculated No Customer Data

Attributes	Description
items `array`	Array of items applied to the order. It can include up to 500 items.

validation\_rule\_id
string

A unique validation rule identifier assigned by the Voucherify API. The validation rule is verified before points are added to the balance.

applicable\_to

Contains list of items that qualify in the scope of the discount. These are definitions of included products, SKUs, and product collections. These can be discounted.

Applicable To Result List

inapplicable\_to

Contains list of items that do not qualify in the scope of the discount. These are definitions of excluded products, SKUs, and product collections. These CANNOT be discounted.

Inapplicable To Result List

metadata
object

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

categories
array

List of category information.

Array of Category with Stacking Rules Type

banner
string

Name of the earning rule. This is displayed as a header for the earning rule in the Dashboard.

Example: Order Paid - You will get 100 points

name
string

Name of the redeemable.

Example: promotion\_tier\_get\_points

campaign\_name
string

Name of the campaign associated to the redeemable. This field is available only if object is not campaign

Example: PromotionCampaign

campaign\_id
string

Id of the campaign associated to the redeemable. This field is available only if object is not campaign

Example: camp\_Mow7u4gSxagLlZ2oDQ01ZS5N

validation\_rules\_assignments

See: Validation Rules Assignments List

Redeemable Result

Attributes	Description
discount	See: Discount
bundle	See: Bundle Details
gift	See: Redeemable Gift
loyalty\_card	Loyalty Card object response Redeemable Loyalty Card
error	Error in result Error Object

Applicable To Result List

Attributes	Description
data `array`	Contains array of items to which the discount can apply. Array of Applicable To
total `integer`	Total number of objects defining included products, SKUs, or product collections.
object `string`	The type of the object represented by JSON. Available values: `list`
data\_ref `string`	The type of the object represented by JSON. Available values: `data`

Inapplicable To Result List

Attributes	Description
data `array`	Contains array of items to which the discount cannot apply. Array of Inapplicable To
total `integer`	Total number of objects defining included products, SKUs, or product collections.
object `string`	The type of the object represented by JSON. Available values: `list`
data\_ref `string`	The type of the object represented by JSON. Available values: `data`

Category with Stacking Rules Type

Category object with stacking\_rules\_type

All of:

Category

Attributes Description

stacking\_rules\_type
string

The type of the stacking rule eligibility.

Available values: JOINT, EXCLUSIVE

Validation Rules Assignments List

Attributes	Description
object `string`	The type of the object represented by JSON. This object stores information about validation rules assignments. Available values: `list`
data\_ref `string`	Identifies the name of the attribute that contains the array of validation rules assignments. Available values: `data`
data `array`	Contains array of validation rules assignments. Array of Business Validation Rule Assignment
total `integer`	Total number of validation rules assignments.

Discount

Contains information about discount.

One of:

Amount
Unit
Unit Multiple
Percent
Fixed

Bundle Details

Attributes Description

quantity
integer

Determines how many bundles are qualified. If there are missing bundle products, the value is 0. If the bundle is qualified, the value is 1. The maximum number of identified bundles can equal the number set in limit. Also defines the multiplier of the discount for AMOUNT, PERCENT, and UNIT discount types. To inform end-customers that more products can be added to meet additional bundles, compare this parameter with limit.

limit
integer

Determines the maximum number of identified bundles. This also defines the maximum multiplier of the bundle discount.

identified
array

Determines products from the customer's order items that meet bundle conditions. SKUs meet the conditions for their product that is used in the bundle. Returns only the products and their quantity that meet the bundle.

Array of:

Attributes	Description
id `string`	Unique identifier of the product or SKU that meets the bundle condition. This is an ID assigned by Voucherify.
object `string`	Determines the type of the object that meets the bundle condition. Available values: `product`, `sku`
item\_index `integer`	Number assigned to the order line item in accordance with the order sent in the request. It starts with `0` for the first order line item in the request.
item\_quantity `integer`	Quantity of items that meet the bundle conditions. If the quantity in the order is higher than the quantity required by the bundle, this returns only the number that meets the bundle. For example, if the bundle requires `5` coffees, but the order includes `10` coffees, `item\_quantity` returns `5`.

missing
array

Determines products, SKUs, or collections from the bundle that are missing in the customer's order items. Determines also the missing quantity. For collections, this means that order items do not include a sufficient number of items that belong to the collection. Not returned when all required bundle items are in the order.

Array of:

Attributes Description

id
string

Unique identifier of the collection, product, or SKU that is missing in the customer's order items. This is an ID assigned by Voucherify.

object
string

Determines the type of the object that is missing in the customer's order items.

Available values: product, products\_collection, sku

item\_quantity
integer

Quantity of items that are missing in the order items to meet the bundle conditions.

Redeemable Gift

Attributes	Description
balance `number`	Available funds. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `\$100.00`.
credits `number`	The number of credits that the user wants to use from the gift card to fulfil the order. The value of credits cannot be higher than the current balance on the gift card. If the user gives more points than he has on the gift card, the application will return an error code in response. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `\$100.00`.
locked\_credits `number`	The number of credits that are locked under a validation session. This is returned if the qualification request includes `session.type: LOCK` parameter in the body. The value is multiplied by 100 to represent 2 decimal places. For example `10000` for `\$100.00`. Returns `0` if there aren't any active validation sessions for the gift card.

Redeemable Loyalty Card

Attributes	Description
points `integer`	Total number of points added to the loyalty card over its lifespan. Example: 7000
balance `integer`	Points available for reward redemption. This is calculated as follows: `balance` \= `points` \- `expired\_points` \- `subtracted\_points` \- `redemption.redeemed\_points`. Example: 6970
exchange\_ratio `number`	The cash equivalent of the points defined in the points\_ratio property.
points\_ratio `integer`	The number of loyalty points that will map to the predefined cash amount defined by the exchange\_ratio property.
transfers `array`	Array of Loyalties Transfer Points

Error Object

Attributes Description

code
integer

Error's HTTP status code.

key
string

Short string describing the kind of error which occurred.

message
string

A human-readable message providing a short description of the error.

details
string

A human-readable message providing more details about the error.

request\_id
string

This ID is useful when troubleshooting and/or finding the root cause of an error response by our support team.

Example: v-0a885062c80375740f

resource\_id
string

Unique resource ID that can be used in another endpoint to get more details.

Example: rf\_0c5d710a87c8a31f86

resource\_type
string

The resource type.

Example: voucher

error
object

Includes additional information about the error.

Attributes	Description
message `string`	The message configured by the user in a validation rule.

Applicable To

Attributes Description

object
string

This object stores information about the resource to which the discount is applicable.

Available values: product, sku, products\_collection

id
string

Unique product collection, product, or SKU identifier assigned by Voucherify.

source\_id
string

The source identifier from your inventory system.

product\_id
string

Parent product's unique ID assigned by Voucherify.

product\_source\_id
string

Parent product's source ID from your inventory system.

price
number

New fixed price of an item. Value is multiplied by 100 to precisely represent 2 decimal places. For example, a \$10 price is written as 1000. In case of the fixed price being calculated by the formula, i.e. the price\_formula parameter is present in the fixed price 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 fixed price.

price\_formula
number

Formula used to dynamically calculate the discounted price of an item.

effect

Defines how the discount is applied to the customer's order.

Applicable To Effect

quantity\_limit
integer

The maximum number of units allowed to be discounted per order line item.

aggregated\_quantity\_limit
integer

The maximum number of units allowed to be discounted combined across all matched order line items.

amount\_limit
integer

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

product\_campaign\_quantity\_limit
integer

Limits the number of discounted item units (product, SKU, collection) that all customers can receive in a given campaign. If a product is selected, the limit covers all discounts across all SKUs belonging to that product. If a product collection is selected, the limit covers all products/SKUs within the collection.

This limit is available on demand as part of campaign budget limits. Contact Voucherify support or your account manager to learn more.

product\_campaign\_quantity\_limit\_formula
string

Formula used to dynamically calculate the maximum units per campaign.

This limit is available on demand as part of campaign budget limits. Contact Voucherify support or your account manager to learn more.

product\_customer\_campaign\_quantity\_limit
integer

Limits the number of discounted item units (product, SKU, collection) that one customer can receive in a given campaign.

This limit is available on demand as part of campaign budget limits. Contact Voucherify support or your account manager to learn more.

product\_customer\_campaign\_quantity\_limit\_formula
string

Formula used to dynamically calculate the maximum units per customer in a campaign.

This limit is available on demand as part of campaign budget limits. Contact Voucherify support or your account manager to learn more.

product\_in\_collection\_campaign\_quantity\_limit
integer

Limits the number of discounted item units of a given product in a collection that all customers can receive in a given campaign.

This limit is available on demand as part of campaign budget limits. Contact Voucherify support or your account manager to learn more.

product\_in\_collection\_campaign\_quantity\_limit\_formula
string

Formula used to dynamically calculate the maximum units per campaign for a product in a collection.

This limit is available on demand as part of campaign budget limits. Contact Voucherify support or your account manager to learn more.

product\_in\_collection\_customer\_campaign\_quantity\_limit
integer

Limits the number of discounted item units of a given product in a collection that one customer can receive in a campaign.

This limit is available on demand as part of campaign budget limits. Contact Voucherify support or your account manager to learn more.

product\_in\_collection\_customer\_campaign\_quantity\_limit\_formula
string

Formula used to dynamically calculate the maximum units per customer for a product in a collection.

This limit is available on demand as part of campaign budget limits. Contact Voucherify support or your account manager to learn more.

product\_promotion\_tier\_quantity\_limit
integer

Limits the number of discounted item units that all customers can receive in a promotion tier.

This limit is available on demand as part of campaign budget limits. Contact Voucherify support or your account manager to learn more.

product\_promotion\_tier\_quantity\_limit\_formula
string

Formula used to dynamically calculate the maximum units per promotion tier.

This limit is available on demand as part of campaign budget limits. Contact Voucherify support or your account manager to learn more.

product\_customer\_promotion\_tier\_quantity\_limit
integer

Limits the number of discounted item units that one customer can receive in a given promotion tier.

This limit is available on demand as part of campaign budget limits. Contact Voucherify support or your account manager to learn more.

product\_customer\_promotion\_tier\_quantity\_limit\_formula
string

Formula used to dynamically calculate the maximum units per customer in a promotion tier.

This limit is available on demand as part of campaign budget limits. Contact Voucherify support or your account manager to learn more.

product\_in\_collection\_promotion\_tier\_quantity\_limit
integer

Limits the number of discounted item units of a given product in a collection that all customers can receive in a given promotion tier.

This limit is available on demand as part of campaign budget limits. Contact Voucherify support or your account manager to learn more.

product\_in\_collection\_promotion\_tier\_quantity\_limit\_formula
string

Formula used to dynamically calculate the maximum units per promotion tier for a product in a collection.

This limit is available on demand as part of campaign budget limits. Contact Voucherify support or your account manager to learn more.

product\_in\_collection\_customer\_promotion\_tier\_quantity\_limit
integer

Limits the number of discounted item units of a given product in a collection that one customer can receive in a promotion tier.

This limit is available on demand as part of campaign budget limits. Contact Voucherify support or your account manager to learn more.

product\_in\_collection\_customer\_promotion\_tier\_quantity\_limit\_formula
string

Formula used to dynamically calculate the maximum units per customer in a promotion tier for a product in a collection.

This limit is available on demand as part of campaign budget limits. Contact Voucherify support or your account manager to learn more.

order\_item\_indices
array

Lists which order lines are (not) covered by the discount. The order in the array is determined by the sequence of applied discounts, while the numbers correspond to the order lines sent in the order object in the request. The first order line is assigned 0, the second order line is assigned 1, and so on.

order\_item\_units
array

Lists which units within order lines are covered by the discount. The order line items are listed according to sequence of applied discounts while the index corresponds to the order line sent in the order object in the request.

Array of:

Attributes	Description
index `integer`	Number assigned to the order line item in accordance with the order sent in the request.
units `array`	Numbers of units in the order line covered by the discount; e.g. `2, 5, 8` for 10 units with the setting `"skip\_initially": 1`, `"repeat": 3`. The counting of units starts from `1`. The maximum quantity of all handled units is 1000. If the quantity of all order items exceeds 1000, this array is not returned, but `units\_limit\_exceeded: true`. However, the discount is calculated properly for all relevant units.
units\_limit\_exceeded `boolean`	Returned as `true` only when the sum total of `quantity` of all order items exceeds 1000.

repeat
integer

Determines the recurrence of the discount, e.g. "repeat": 3 means that the discount is applied to every third item.

skip\_initially
integer

Determines how many items are skipped before the discount is applied.

target
string

Determines to which kinds of objects the discount is applicable. ITEM includes products and SKUs. UNIT means particular units within an order line.

Available values: ITEM, UNIT

Inapplicable To

Applicable To

Category

Attributes	Description
id `string`	Unique category ID assigned by Voucherify.
name `string`	Category name.
hierarchy `integer`	Category hierarchy. Categories with lower hierarchy are processed before categories with higher hierarchy value.
object `string`	The type of the object represented by the JSON. This object stores information about the category. Available values: `category`
created\_at `string`	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
updated\_at `string`	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

Business Validation Rule Assignment

Attributes	Description
id `string`	The unique identifier for a assignment
rule\_id `string`	The unique identifier for a rule
related\_object\_id `string`	The unique identifier for a related object
related\_object\_type `string`	The type of related object
created\_at `string`	Timestamp representing the date and time when the object was created. The value is shown in the ISO 8601 format. Example: 2022-03-09T11:19:04.819Z
updated\_at `string`	Timestamp representing the date and time when the object was last updated in ISO 8601 format. Example: 2022-03-09T11:19:04.819Z
object `string`	The type of the object represented by JSON. Available values: `validation\_rules\_assignment`
validation\_status `string`	The validation status of the assignment Available values: `VALID`, `PARTIALLY\_VALID`, `INVALID`
validation\_omitted\_rules `array`	The list of omitted rules

Amount

Attributes	Description
type `string`	Defines the type of the voucher. Available values: `AMOUNT`
amount\_off `number`	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.
amount\_off\_formula `string`	Formula used to dynamically calculate the discount.
aggregated\_amount\_limit `integer`	Maximum discount amount per order.
effect	Defines how the discount is applied to the customer's order. Discount Amount Vouchers Effect Types
is\_dynamic `boolean`	Flag indicating whether the discount was calculated using a formula.

Unit

Attributes	Description
type `string`	Discount type. Available values: `UNIT`
unit\_off `integer`	Number of units to be granted a full value discount.
unit\_off\_formula `string`	Formula used to dynamically calculate the number of units.
effect	Defines how the unit is added to the customer's order. Discount Unit Vouchers Effect Types
unit\_type `string`	The product deemed as free, chosen from product inventory (e.g. time, items).
product	Contains information about the product. Simple Product Discount Unit
sku	See: Simple Sku Discount Unit
is\_dynamic `boolean`	Flag indicating whether the discount was calculated using a formula.

Unit Multiple

Attributes Description

type
string

Discount type.

Available values: UNIT

effect
string

Defines how the discount is applied to the customer's order.

Available values: ADD\_MANY\_ITEMS

units
array

Array of One Unit

Percent

Attributes	Description
type `string`	Defines the type of the voucher. Available values: `PERCENT`
percent\_off `number`	The percent discount that the customer will receive.
percent\_off\_formula `string`	Formula used to dynamically calculate the discount.
amount\_limit `number`	Upper limit allowed to be applied as a discount. Value is multiplied by 100 to precisely represent 2 decimal places. For example, a \$6 maximum discount is written as 600.
aggregated\_amount\_limit `integer`	Maximum discount amount per order.
effect	Defines how the discount is applied to the customer's order. Discount Percent Vouchers Effect Types
is\_dynamic `boolean`	Flag indicating whether the discount was calculated using a formula.

Fixed

Attributes	Description
type `string`	Defines the type of the voucher. Available values: `FIXED`
fixed\_amount `number`	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.
fixed\_amount\_formula `string`	Formula used to dynamically calculate the discount.
effect	Defines how the discount is applied to the customer's order. Discount Fixed Vouchers Effect Types
is\_dynamic `boolean`	Flag indicating whether the discount was calculated using a formula.

Loyalties Transfer Points

Attributes	Description
code `string`	Unique loyalty card code from which the user wants to transfer loyalty points (source).
points `integer`	The number of loyalty points that the user wants to transfer to another loyalty card. The number of points cannot be higher than the current balance on the loyalty card (source).
reason `string`	Reason for the transfer.
source\_id `string`	The merchant's transaction ID if it is different from the Voucherify transaction ID. It is really useful in case of an integration between multiple systems. It can be a transaction ID from a CRM system, database or 3rd-party service.

Applicable To Effect

Available values: APPLY\_TO\_EVERY, APPLY\_TO\_CHEAPEST, APPLY\_FROM\_CHEAPEST, APPLY\_TO\_MOST\_EXPENSIVE, APPLY\_FROM\_MOST\_EXPENSIVE

Discount Amount Vouchers Effect Types

Available values: APPLY\_TO\_ORDER, APPLY\_TO\_ITEMS, APPLY\_TO\_ITEMS\_PROPORTIONALLY, APPLY\_TO\_ITEMS\_PROPORTIONALLY\_BY\_QUANTITY, APPLY\_TO\_ITEMS\_BY\_QUANTITY

Discount Unit Vouchers Effect Types

Available values: ADD\_MISSING\_ITEMS, ADD\_NEW\_ITEMS, ADD\_MANY\_ITEMS, ADD\_SAME\_ITEMS

Simple Product Discount Unit

Attributes	Description
id `string`	Unique product ID, assigned by Voucherify.
source\_id `string`	Product's source ID.
name `string`	Product name.

Simple Sku Discount Unit

Attributes	Description
id `string`	Unique SKU ID, assigned by Voucherify.
source\_id `string`	Product variant's source ID.
name `string`	Sku name

One Unit

Attributes	Description
unit\_off `number`	Number of units to be granted a full value discount.
unit\_off\_formula `string`	Formula used to dynamically calculate the number of units.
effect `string`	Defines how the unit is added to the customer's order. Available values: `ADD\_NEW\_ITEMS`, `ADD\_MISSING\_ITEMS`
unit\_type `string`	The product deemed as free, chosen from product inventory (e.g. time, items).
product	Contains information about the product. Simple Product Discount Unit
sku	Contains information about the sku. Simple Sku Discount Unit

Discount Percent Vouchers Effect Types

Available values: APPLY\_TO\_ORDER, APPLY\_TO\_ITEMS

Discount Fixed Vouchers Effect Types

Available values: APPLY\_TO\_ORDER, APPLY\_TO\_ITEMS

# Failed Source: https://docs.voucherify.io/api-reference/redemption/failed openapi-events/events-redemption.json webhook EVENTS.REDEMPTION.FAILED The `EVENTS.REDEMPTION.FAILED` event indicates that the redemption process encountered issues while applying the voucher codes or promotions tiers. As a result, the redemption was unsuccessful. This event is used in a webhook configured in Project settings in Voucherify dashboard. This page documents only the event. If you need more details about the webhook payload data that includes this event, go to [Introduction to webhooks](/api-reference/introduction-to-webhooks "Introduction to webhooks v2024-01-01") page. # Rollback Failed Source: https://docs.voucherify.io/api-reference/redemption/rollback-failed openapi-events/events-redemption.json webhook EVENTS.REDEMPTION.ROLLBACK.FAILED The `EVENTS.REDEMPTION.ROLLBACK.FAILED` event indicates that a redemption was unsuccessfully reverted. This occurs when the system encounters difficulties in rolling back a previously redeemed voucher code or promotional tier. The main reasons are that a rollback was applied to a redemption created more than 3 months ago or an attempt was made to rollback a redemption that had been rolled back already. This event is used in a webhook configured in Project settings in Voucherify dashboard. This page documents only the event. If you need more details about the webhook payload data that includes this event, go to [Introduction to webhooks](/api-reference/introduction-to-webhooks "Introduction to webhooks v2024-01-01") page. # Rollback Succeeded Source: https://docs.voucherify.io/api-reference/redemption/rollback-succeeded openapi-events/events-redemption.json webhook EVENTS.REDEMPTION.ROLLBACK.SUCCEEDED The `EVENTS.REDEMPTION.ROLLBACK.SUCCEEDED` event indicates a redemption was successfully reversed. This occurs when a previously redeemed voucher code or promotional tier has been rolled back or undone. This event is used in a webhook configured in Project settings in Voucherify dashboard. This page documents only the event. If you need more details about the webhook payload data that includes this event, go to [Introduction to webhooks](/api-reference/introduction-to-webhooks "Introduction to webhooks v2024-01-01") page. # Succeeded Source: https://docs.voucherify.io/api-reference/redemption/succeeded openapi-events/events-redemption.json webhook EVENTS.REDEMPTION.SUCCEEDED The `EVENTS.REDEMPTION.SUCCEEDED` event indicates that the redemption process was successful. It confirms that the associated voucher codes and promotional tiers have been effectively applied. A **redeemable stack** sends **one `redemption.succeeded` webhook for each redeemable**, plus **one extra webhook** for the whole stack. **Example** 5 redeemables → 6 `redemption.succeeded` webhooks This event is used in a webhook configured in Project settings in Voucherify dashboard. This page documents only the event. If you need more details about the webhook payload data that includes this event, go to [Introduction to webhooks](/api-reference/introduction-to-webhooks "Introduction to webhooks v2024-01-01") page. # Get Redemption Source: https://docs.voucherify.io/api-reference/redemptions/get-redemption /openapi/redemptions.json get /v1/redemptions/{redemptionId} Return a redemption or redemption rollback object. This object can either be a successfull or failed redemption or redemption rollback. # Get Voucher's Redemptions Source: https://docs.voucherify.io/api-reference/redemptions/get-vouchers-redemptions /openapi/redemptions.json get /v1/vouchers/{code}/redemption Retrieve the number of times a voucher was redeemed and each of the redemption details. # List Redemptions Source: https://docs.voucherify.io/api-reference/redemptions/list-redemptions /openapi/redemptions.json get /v1/redemptions Returns a list of redemptions previously created. The redemptions are returned in a sorted order, with the most recent redemptions appearing first. The response returns a list of redemptions of all vouchers. ## Filtering results The result can be narrowed according to specified (or default) filters, for example, you can sort redemptions by date: `https://api.voucherify.io/v1/redemptions?limit=3&[created_at][before]=2017-09-08T13:52:18.227Z`. A filter based on the object `created_at` field narrows down the results and lists redemptions done before or after a particular date time. You can use the following options: `[created_at][after]`, `[created_at][before]`. A date value must be presented in ISO 8601 format (`2016-11-16T14:14:31Z` or `2016-11-16`). An example: `[created_at][before]=2017-09-08T13:52:18.227Z`. ## Failed Redemptions A redemption may fail for various reasons. You can figure out an exact reason from the `failure_code`: - `resource_not_found` - voucher with given code does not exist - `voucher_not_active` - voucher is not active yet (before start date) - `voucher_expired` - voucher has already expired (after expiration date) - `voucher_disabled` - voucher has been disabled (`active: false`) - `quantity_exceeded` - voucher's redemptions limit has been exceeded - `gift_amount_exceeded` - gift amount has been exceeded - `customer_rules_violated` - customer did not match the segment - `order_rules_violated` - order did not match validation rules - `invalid_order` - order was specified incorrectly - `invalid_amount` - order amount was specified incorrectly - `missing_amount` - order amount was not specified - `missing_order_items` - order items were not specified - `missing_customer` - customer was not specified # Redeem Promotion Source: https://docs.voucherify.io/api-reference/redemptions/redeem-promotion /openapi/redemptions.json post /v1/promotions/tiers/{promotionTierId}/redemption Deprecated This endpoint represents the deprecated version of the API responsible for promotion tier redemption, and we do not recommend using it. The new [Stackable Discounts API](/api-reference/redemptions/redeem-stackable-discounts) introduces additional features and improvements while maintaining backward compatibility, including applying a combination of coupon codes and promotion tiers. 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. To redeem a promotion, you create a redemption object passing a context. You can retrieve a list of active promotions through the [Validate Promotions](/api-reference/validations/validate-promotion-tier) endpoint. That validation method will return a list of active promotion tiers identified by thier IDs. Redemption rollback Do you need to undo a redemption? You can do it with [redemption rollback](/api-reference/redemptions/rollback-redemption). # Redeem Stackable Discounts Source: https://docs.voucherify.io/api-reference/redemptions/redeem-stackable-discounts /openapi/redemptions.json post /v1/redemptions In the table below, you can see the logic the API follows to calculate discounts and amounts: | **Field** | **Calculation** | **Description** | |:---|:---|:---| | amount | N/A | This field shows the order amount before applying any discount | | total_amount | `total_amount` = `amount` - `total_discount_amount` | This field shows the order amount after applying all the discounts | | discount_amount | `discount_amount` = `previous_discount_amount` + `applied_discount_amount` | This field sums up all order-level discounts up to and including the specific discount being calculated for the stacked redemption. | | items_discount_amount | sum(items, i => i.discount_amount) | This field sums up all product-specific discounts | | total_discount_amount | `total_discount_amount` = `discount_amount` + `items_discount_amount` | This field sums up all order-level and all product-specific discounts | | applied_discount_amount | N/A | This field shows the order-level discount applied in a particular request | | items_applied_discount_amount | sum(items, i => i.applied_discount_amount) | This field sums up all product-specific discounts applied in a particular request | | total_applied_discount_amount | `total_applied_discount_amount` = `applied_discount_amount` + `items_applied_discount_amount` | This field sums up all order-level and all product-specific discounts applied in a particular request | API keys with a Merchant role can't use this endpoint. Rollbacks You can't roll back a child redemption. When you call rollback on a stacked redemption, all child redemptions will be rolled back. You need to refer to a parent redemption ID in your [rollback request](/api-reference/redemptions/rollback-stackable-redemptions). Also available on client-side This method is also accessible through public keys which you can use in client-side apps: mobile and web browser apps. Go to the dedicated [endpoint](/api-reference/client-side/redeem-stackable-discounts-client-side) to learn more. # Redeem Voucher Source: https://docs.voucherify.io/api-reference/redemptions/redeem-voucher /openapi/redemptions.json post /v1/vouchers/{code}/redemption Deprecated This endpoint represents the deprecated version of the API responsible for voucher redemption, and we do not recommend using it. The new [Stackable Discounts API](/api-reference/redemptions/redeem-stackable-discounts) introduces additional features and improvements while maintaining backward compatibility, including applying a combination of coupon codes and promotion tiers. 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. To redeem a voucher, you create a redemption object. It increments the redemption counter and updates the history of the voucher. ## How discounts and order amounts are calculated in the API response? In the table below, you can see the logic the API follows to calculate discounts and amounts: | **Field** | **Calculation** | **Description** | |:---|:---|:---| | amount | N/A | This field shows the order amount before applying any discount | | total_amount | total_amount = amount - total_discount_amount | This field shows the order amount after applying all the discounts | | discount_amount | discount_amount = previous_discount_amount + applied_discount_amount | This field sums up all order-level discounts applied to a patricular order | | items_discount_amount | sum(items, i => i.discount_amount) | This field sums up all product-specific discounts applied to this order | | total_discount_amount | total_discount_amount = discount_amount + items_discount_amount | This field sums up all order-level and all product-specific discounts applied to this order | | applied_discount_amount | N/A | This field shows order-level discount applied in a particular request | | items_applied_discount_amount | sum(items, i => i.applied_discount_amount) | This field sums up all product-specific discounts applied in a particular request | | total_applied_discount_amount | total_applied_discount_amount = applied_discount_amount + items_applied_discount_amount | This field sums up all order-level and all product-specific discounts applied in a particular request | # Redemption Object Source: https://docs.voucherify.io/api-reference/redemptions/redemption-object

Redemption

This is an object representing a redemption for POST v1/redemptions and POST /client/v1/redemptions.

All of:

Redemption Base

Attributes

Description

voucher

Defines the details of the voucher being redeemed.

All of:

Voucher with categories and validation rules assignments
Voucher Holder

Redemption Base

Attributes Description

id
string

Unique redemption ID.

Example: r\_0bc92f81a6801f9bca

object
string

The type of the object represented by the JSON

Available values: redemption

date
string

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

Example: 2021-12-22T10:13:06.487Z

customer\_id
string, null

Unique customer ID of the redeeming customer.

Example: cust\_i8t5Tt6eiKG5K79KQlJ0Vs64

tracking\_id
string, null

Hashed customer source ID.

metadata
object, null

The metadata object stores all custom attributes assigned to the redemption.

amount
integer

Example: 10000

redemption
string, null

Unique redemption ID of the parent redemption.

Example: r\_0c656311b5878a2031

result
string

Redemption result.

Available values: SUCCESS, FAILURE

status
string

Redemption status.

Available values: SUCCEEDED, FAILED, ROLLED\_BACK

session
object

Contains details about the redemption session lock. Sessions can be established only for discount vouchers, promotions, and gift cards.

Attributes	Description
key `string`	The session unique ID assigned by Voucherify or your own unique session ID sent in the request.

related\_redemptions
object

Attributes Description

rollbacks
array

Array of:

Redemption Related Redemptions Rollbacks Item

Attributes Description

id
string

Unique rollback redemption ID.

Example: rr\_0bc92f81a6801f9bca

date
string

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

Example: 2021-12-22T10:13:06.487Z

rollback\_order\_mode
string

Available values: WITH\_ORDER, WITHOUT\_ORDER

redemptions
array

Array of:

Redemption Related Redemptions Item

Attributes Description

id
string

Unique redemption ID.

Example: r\_0bc92f81a6801f9bca

date
string

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

Example: 2021-12-22T10:13:06.487Z

failure\_code
string

If the result is FAILURE, this parameter will provide a generic reason as to why the redemption failed.

Example: customer\_rules\_violated

failure\_message
string

If the result is FAILURE, this parameter will provide a more expanded reason as to why the redemption failed.

order

All of:

Order Calculated No Customer Data

Attributes	Description
items `array`	Array of items applied to the order. It can include up to 500 items.

channel
object

Defines the details of the channel through which the redemption was issued.

Attributes Description

channel\_id
string

Unique channel ID of the user performing the redemption. This is either a user ID from a user using the Voucherify Dashboard or an X-APP-Id of a user using the API. For AUTO\_REDEEM, it is the reward assignment ID.

Example: user\_g24UoRO3Caxu7FCT4n5tpYEa3zUG0FrH

channel\_type
string

The source of the channel for the redemption. A USER corresponds to the Voucherify Dashboard, API corresponds to the API, and AUTO\_REDEEM corresponds to a loyalty campaign reward that has been redeemed automatically.

Available values: USER, API, AUTO\_REDEEM

customer

Simple Customer

related\_object\_type
string

Defines the related object.

Available values: voucher, promotion\_tier, redemption

related\_object\_id
string

Unique related object ID assigned by Voucherify, i.e. v\_lfZi4rcEGe0sN9gmnj40bzwK2FH6QUno for a voucher.

promotion\_tier

Contains details of the promotion tier and the parent campaign.

Promotion Tier

reward

See: Redemption Reward Result

gift
object

Contains the amount subtracted from the gift card for the redemption.

Attributes	Description
amount `integer`	Amount subtracted from the gift card as a result of the redemption. The amount is expressed as the smallest currency unit (e.g. 100 cents for \$1.00).

loyalty\_card
object

Contains the number of points subtracted from the loyalty card for the redemption.

Attributes	Description
points `integer`	Number of points subtracted from the loyalty card as a result of the redemption.

Voucher with categories and validation rules assignments

This is an object representing a voucher with categories and validation rules assignments for POST v1/qualifications, POST v1/redemptions, and POST v1/validations.

All of:

Voucher Base

Attributes	Description
categories `array`	Contains details about the category. Array of Category with Stacking Rules Type
validation\_rules\_assignments	See: Validation Rules Assignments List

Voucher Holder

Attributes	Description
holder	See: Simple Customer

Order Calculated No Customer Data

Attributes Description

id
string

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

source\_id
string, null

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

status
string

The order status.

Available values: CREATED, PAID, CANCELED, FULFILLED

amount
integer

This is the sum of the order items' amounts. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for \$1.00).

initial\_amount
integer

discount\_amount
integer

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\_discount\_amount
integer

Sum of all product-specific discounts applied to the order. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for \$1.00).

total\_discount\_amount
integer

Sum of all order-level AND all product-specific discounts applied to the order. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for \$1.00).

total\_amount
integer

Order amount after undoing all the discounts through the rollback redemption. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for \$1.00).

applied\_discount\_amount
integer

This field shows the order-level discount applied. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for \$1.00).

items\_applied\_discount\_amount
integer

total\_applied\_discount\_amount
integer

metadata
object

object
string

The type of the object represented by JSON.

Available values: order

created\_at
string

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

Example: 2021-12-22T10:13:06.487Z

updated\_at
string, null

Timestamp representing the date and time when the order was last updated in ISO 8601 format.

Example: 2021-12-22T10:14:45.316Z

customer\_id
string, null

Unique customer identifier of the customer making the purchase. The ID is assigned by Voucherify.

Example: cust\_7iUa6ICKyU6gH40dBU25kQU1

referrer\_id
string, null

Unique referrer ID.

Example: cust\_nM4jqPiaXUvQdVSA6vTRUnix

customer

Customer Id

referrer

Referrer Id

redemptions
object

Attributes	Description
\[propertyName]	See: Order Redemptions

Simple Customer

Attributes	Description
id `string`	Unique identifier of an existing customer. It is assigned by Voucherify.
name `string`	Customer's first and last name.
email `string`	Customer's email address.
source\_id `string`	A unique identifier of the customer. It can be a customer ID or email from a CRM system, database, or a third-party service.
metadata `object`	A set of custom key/value pairs that are attached to the customer. It stores all custom attributes assigned to the customer.
object `string`	The type of the object represented by JSON. Available values: `customer`

Promotion Tier

Attributes Description

id
string

Unique promotion tier ID.

Example: promo\_63fYCt81Aw0h7lzyRkrGZh9p

created\_at
string

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

Example: 2021-12-15T11:34:01.333Z

updated\_at
string

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

Example: 2022-02-09T09:20:05.603Z

name
string

Name of the promotion tier.

banner
string

Text to be displayed to your customers on your website.

action
object

Contains details about the discount applied by the promotion tier.

Attributes	Description
discount	See: Discount

metadata
object

hierarchy
integer

promotion\_id
string

Promotion unique ID.

campaign
object

Contains details about promotion tier's parent campaign.

Attributes	Description
id `string`	Unique campaign ID.
start\_date `string`	Activation timestamp defines when the campaign starts to be active in ISO 8601 format. Campaign is inactive before this date. Example: 2022-09-22T00:00:00.000Z
expiration\_date `string`	Expiration timestamp defines when the campaign expires in ISO 8601 format. Campaign is inactive after this date. Example: 2022-09-30T00:00:00.000Z
validity\_timeframe	See: Validity Timeframe
validity\_day\_of\_week	See: Validity Day Of Week
validity\_hours	See: Validity Hours
active `boolean`	A flag indicating whether the campaign is active or not active. A campaign can be disabled even though it's within the active period defined by the `start\_date` and `expiration\_date` using the Disable Campaign endpoint. `true` indicates an active campaign `false` indicates an inactive campaign
category\_id `string`	Unique category ID that this campaign belongs to. Example: cat\_0b688929a2476386a6
object `string`	The type of the object represented by the campaign object. This object stores information about the campaign.

campaign\_id
string

Promotion tier's parent campaign's unique ID.

active
boolean

A flag to toggle the promotion tier on or off. You can disable a promotion tier even though it's within the active period defined by the start\_date and expiration\_date.

true indicates an active promotion tier
false indicates an inactive promotion tier

start\_date
string

Activation timestamp defines when the promotion tier starts to be active in ISO 8601 format. Promotion tier is inactive before this date.

Example: 2022-09-23T00:00:00.000Z

expiration\_date
string

Activation timestamp defines when the promotion tier expires in ISO 8601 format. Promotion tier is inactive after this date.

Example: 2022-09-26T00:00:00.000Z

validity\_timeframe

See: Validity Timeframe

validity\_day\_of\_week

See: Validity Day Of Week

validity\_hours

See: Validity Hours

summary
object

Contains statistics about promotion tier redemptions and orders.

Attributes Description

redemptions
object

Contains statistics about promotion tier redemptions.

Attributes	Description
total\_redeemed `integer`	Number of times the promotion tier was redeemed.

orders
object

Contains statistics about orders related to the promotion tier.

Attributes	Description
total\_amount `integer`	Sum of order totals.
total\_discount\_amount `integer`	Sum of total discount applied using the promotion tier.

object
string

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

validation\_rule\_assignments

See: Validation Rule Assignments List

category\_id
string

Promotion tier category ID.

Example: cat\_0c9da30e7116ba6bba

categories
array

Array of Category

Redemption Reward Result

Attributes Description

customer

Simple Customer

assignment\_id
string, null

Unique reward assignment ID assigned by Voucherify.

voucher

Voucher

product

Product

sku

SKU Object

loyalty\_tier\_id
string, null

Unique loyalty tier ID assigned by Voucherify.

id
string

Unique reward ID.

Example: rew\_0bc92f81a6801f9bca

name
string

Name of the reward.

Example: Reward Name

object
string

The type of the object represented by the JSON

Available values: reward

created\_at
string

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

Example: 2021-12-22T10:13:06.487Z

updated\_at
string

Timestamp in ISO 8601 format indicating when the reward was updated.

Example: 2022-10-03T12:24:58.008Z

parameters
object

These are parameters representing a material reward.

Attributes Description

campaign
object

Defines the product redeemed as a reward.

Attributes Description

id
string

Campaign unique ID.

Example: camp\_13BbZ0kQsNinhqsX3wUts2UP

balance
integer

Points available for reward redemption. This is calculated as follows: balance \= points \- expired\_points \- subtracted\_points \- redemption.redeemed\_points.

type
string

Defines the type of the campaign.

product
object

Defines the product redeemed as a reward.

Attributes Description

id
string

Unique product ID, assigned by Voucherify.

Example: prod\_0b7d7dfb05cbe5c616

sku\_id
string

Unique identifier of the SKU. It is assigned by Voucherify.

Example: sku\_0a41e31c7b41c28358

coin
object

Defines the ratio by mapping the number of loyalty points in points\_ratio to a predefined cash amount in exchange\_ratio.

Attributes	Description
exchange\_ratio `integer`	The cash equivalent of the points defined in the `points\_ratio` property.
points\_ratio `integer`	The number of loyalty points that will map to the predefined cash amount defined by the `exchange\_ratio` property.

metadata
object

A set of custom key/value pairs that you can attach to a reward. The metadata object stores all custom attributes assigned to the reward.

type
string

Reward type.

Available values: CAMPAIGN, COIN, MATERIAL

Voucher Base

Attributes Description

id
string

Assigned by the Voucherify API, identifies the voucher.

Example: v\_mkZN9v7vjYUadXnHrMza8W5c34fE5KiV

code
string

A code that identifies a voucher. Pattern can use all letters of the English alphabet, Arabic numerals, and special characters.

Example: WVPblOYX

campaign
string

A unique campaign name, identifies the voucher's parent campaign.

Example: Gift Card Campaign

campaign\_id
string

Assigned by the Voucherify API, identifies the voucher's parent campaign.

Example: camp\_FNYR4jhqZBM9xTptxDGgeNBV

category
string

Tag defining the category that this voucher belongs to. Useful when listing vouchers using the List Vouchers endpoint.

category\_id
string

Unique category ID assigned by Voucherify.

Example: cat\_0bb343dee3cdb5ec0c

type
string

Defines the type of the voucher.

Available values: GIFT\_VOUCHER, DISCOUNT\_VOUCHER, LOYALTY\_CARD

discount

See: Discount

gift
object

Object representing gift parameters. Child attributes are present only if type is GIFT\_VOUCHER. Defaults to null.

Attributes	Description
amount `integer`	Total gift card income over the lifetime of the card. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `\$100.00`. Example: 10000
subtracted\_amount `integer`	Total amount of subtracted credits over the gift card lifetime. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `\$100.00`.
balance `integer`	Available funds. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `\$100.00`. Example: 500
effect `string`	Defines how the credits are applied to the customer's order. Available values: `APPLY\_TO\_ORDER`, `APPLY\_TO\_ITEMS`

loyalty\_card
object

Object representing loyalty card parameters. Child attributes are present only if type is LOYALTY\_CARD. Defaults to null.

Attributes	Description
points `integer`	Total number of points added to the loyalty card over its lifespan. Example: 7000
balance `integer`	Points available for reward redemption. This is calculated as follows: `balance` \= `points` \- `expired\_points` \- `subtracted\_points` \- `redemption.redeemed\_points`. Example: 6970
next\_expiration\_date `string`	The next closest date when the next set of points are due to expire. Example: 2023-05-30
next\_expiration\_points `integer`	The amount of points that are set to expire next.
pending\_points `integer`	Shows the number of pending points that will be added to the loyalty card when they are activated automatically or manually.
expired\_points `integer`	Shows the total number of expired points over the lifetime of the loyalty card.
subtracted\_points `integer`	Shows the total number of subtracted points over the lifetime of the loyalty card.

start\_date
string

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

Example: 2021-12-01T00:00:00.000Z

expiration\_date
string

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

Example: 2021-12-31T00:00:00.000Z

validity\_timeframe

See: Validity Timeframe

validity\_day\_of\_week

See: Validity Day Of Week

validity\_hours

See: Validity Hours

active
boolean, null

A flag to toggle the voucher on or off. You can disable a voucher even though it's within the active period defined by the start\_date and expiration\_date.

true indicates an active voucher
false indicates an inactive voucher

additional\_info
string

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

metadata
object

assets

See: Voucher Assets

is\_referral\_code
boolean, null

Flag indicating whether this voucher is a referral code; true for campaign type REFERRAL\_PROGRAM.

created\_at
string

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

Example: 2021-12-22T10:13:06.487Z

updated\_at
string

Timestamp representing the date and time when the voucher was last updated in ISO 8601 format.

Example: 2021-12-22T10:14:45.316Z

holder\_id
string

Unique customer identifier of the redeemable holder. It equals to the customer ID assigned by Voucherify.

Example: cust\_eWgXlBBiY6THFRJwX45Iakv4

referrer\_id
string

Unique identifier of the referring person.

Example: cust\_Vzck5i8U3OhcEUFY6MKhN9Rv

object
string

The type of the object represented by JSON. Default is voucher.

publish
object

Stores a summary of publication events: an event counter and endpoint to return details of each event. Publication is an assignment of a code to a customer, e.g. through a distribution.

Attributes Description

object
string

The type of the object represented is by default list. To get this list, you need to make a call to the endpoint returned in the url attribute.

count
integer

Publication events counter.

Example: 0

url
string

The endpoint where this list of publications can be accessed using a GET method. /v1/vouchers//publications

Example: /v1/vouchers/WVPblOYX/publications?page=1\&limit=10

redemption
object

Stores a summary of redemptions that have been applied to the voucher.

Attributes	Description
quantity `integer`	How many times a voucher can be redeemed. A `null` value means unlimited.
redeemed\_quantity `integer`	How many times a voucher has already been redeemed. Example: 1
redeemed\_points `integer`	Total loyalty points redeemed. Example: 100000
object `string`	The type of the object represented is by default `list`. To get this list, you need to make a call to the endpoint returned in the url attribute.
url `string`	The endpoint where this list of redemptions can be accessed using a GET method. `/v1/vouchers//redemptions` Example: /v1/vouchers/WVPblOYX/redemptions?page=1\&limit=10

Category with Stacking Rules Type

Category object with stacking\_rules\_type

All of:

Category

Attributes Description

stacking\_rules\_type
string

The type of the stacking rule eligibility.

Available values: JOINT, EXCLUSIVE

Validation Rules Assignments List

Attributes	Description
object `string`	The type of the object represented by JSON. This object stores information about validation rules assignments. Available values: `list`
data\_ref `string`	Identifies the name of the attribute that contains the array of validation rules assignments. Available values: `data`
data `array`	Contains array of validation rules assignments. Array of Business Validation Rule Assignment
total `integer`	Total number of validation rules assignments.

Customer Id

Attributes Description

id
string

A unique identifier of an existing customer.

object
string

The type of the object represented by JSON.

Available values: customer

Referrer Id

Customer Id

Order Redemptions

Attributes	Description
date `string`	Timestamp representing the date and time when the redemption was created. The value is shown in the ISO 8601 format. Example: 2022-09-02T17:06:56.649Z
rollback\_id `string`	Unique ID of the redemption rollback. Example: rr\_0c63c84eb78ee0a6c0
rollback\_date `string`	Timestamp representing the date and time when the redemption rollback was created. The value is shown in the ISO 8601 format. Example: 2023-01-31T14:18:37.150Z
related\_object\_type `string`	The source of the incentive.
related\_object\_id `string`	Unique ID of the parent redemption. Example: r\_0ba186c4824e4881e1
related\_object\_parent\_id `string`	Represent's the campaign ID of the voucher if the redemption was based on a voucher that was part of bulk codes generated within a campaign. In case of a promotion tier, this represents the campaign ID of the promotion tier's parent campaign.
stacked `array`	Contains a list of unique IDs of child redemptions, which belong to the stacked incentives.
rollback\_stacked `array`	Lists the rollback redemption IDs of the particular child redemptions.

Discount

Contains information about discount.

One of:

Amount
Unit
Unit Multiple
Percent
Fixed

Validity Timeframe

Attributes Description

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

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

Validity Day Of Week

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

Validity Hours

Attributes Description

daily
array

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

Array of:

Attributes Description

start\_time
string

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

Example: 12:00

days\_of\_week
array

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

expiration\_time
string

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

Example: 14:00

Validation Rule Assignments List

Attributes	Description
object `string`	The type of the object represented by JSON. This object stores information about validation rule assignments.
data\_ref `string`	Identifies the name of the JSON property that contains the array of validation rule assignments.
data `array`	A dictionary that contains an array of validation rule assignments. Array of Validation Rule Assignment
total `integer`	Total number of validation rule assignments.

Category

Attributes	Description
id `string`	Unique category ID assigned by Voucherify.
name `string`	Category name.
hierarchy `integer`	Category hierarchy. Categories with lower hierarchy are processed before categories with higher hierarchy value.
object `string`	The type of the object represented by the JSON. This object stores information about the category. Available values: `category`
created\_at `string`	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
updated\_at `string`	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

Voucher

This is an object representing a voucher with categories and validation rules assignments.

All of:

Voucher Base

Attributes	Description
categories `array`	Contains details about the category. Array of Category
validation\_rules\_assignments	See: Validation Rules Assignments List

Product

This is an object representing a product.

This entity should be used to map product items from your inventory management system. The aim of products is to build which reflect product-specific campaigns.

All of:

Product without Skus Object

Attributes	Description
skus	See: Skus List For Product

SKU Object

Attributes	Description
id `string`	A unique identifier that represents the SKU and is assigned by Voucherify. Example: sku\_0b1621b319d248b79f
source\_id `string`, `null`	A unique SKU identifier from your inventory system. Example: sku\_source\_id\_4
product\_id `string`	The parent product's unique ID. Example: prod\_0b15f6b9f650c16990
sku `string`, `null`	Unique user-defined SKU name. Example: Large Pink Shirt
price `integer`, `null`	Unit price. It is represented by a value multiplied by 100 to accurately reflect 2 decimal places, such as `\$100.00` being expressed as `10000`.
currency `string`, `null`	SKU price currency. Example: USD
attributes `object`	The attributes object stores values for all custom attributes inherited by the SKU from the parent product. A set of key/value pairs that are attached to a SKU object and are unique to each SKU within a product family.
image\_url `string`, `null`	The HTTPS URL pointing to the .png or .jpg file that will be used to render the SKU image.
metadata `object`	The metadata object stores all custom attributes assigned to the SKU. A set of key/value pairs that you can attach to a SKU object. It can be useful for storing additional information about the SKU in a structured format. It can be used to create product collections.
created\_at `string`	Timestamp representing the date and time when the SKU was created. The value is shown in the ISO 8601 format. Example: 2022-05-17T10:36:30.187Z
updated\_at `string`, `null`	Timestamp representing the date and time when the SKU was updated. The value is shown in the ISO 8601 format. Example: 2022-05-17T10:55:09.137Z
object `string`	The type of the object represented by JSON. This object stores information about the `SKU`. Available values: `sku`

Voucher Assets

Attributes Description

qr
object

Stores Quick Response (QR) representation of encrypted code.

Attributes Description

id
string

Encrypted voucher code ID.

Example: U2FsdGVkX19ucFhvVmBVpVYG5KoswTsjSIaqoKg5L9ie4BK+t4pp7U7oFzjGJzj9q/bmuMOj9mEFiVKDMIkSaruKedMvHbKoPX5Sg+BaZk5QwXMf8k/OzSlOEVybpwSq+AiqPoNtjeuqtIgkDyvT6Q==

url
string

URL to QR code

Optional: Attach query parameters to base URL to customize the image of the encrypted voucher code.

size : integer value from 1 to 100
format : string, either png (default) or svg

barcode
object

Stores barcode representation of encrypted code.

Attributes Description

id
string

Encrypted voucher code ID.

Example: U2FsdGVkX19eJhGfWwUrH9+tulBkON+AnMktic+N6CVWzZ9+fHVxuVx22WakrzxiWXy0skuvvEHSeZIw9HlgyIJ+kJ1iPdUKpyENuNYJKzoZlO0mmTf6WQM6/pFs61apEn9SJx32ttCF6d3oxKISQQ==

url
string

URL to barcode

Optional: Attach query parameters to base URL to customize the image of the encrypted voucher code.

size : integer value from 1 to 100
format : string, either png (default) or svg

Business Validation Rule Assignment

Attributes	Description
id `string`	The unique identifier for a assignment
rule\_id `string`	The unique identifier for a rule
related\_object\_id `string`	The unique identifier for a related object
related\_object\_type `string`	The type of related object
created\_at `string`	Timestamp representing the date and time when the object was created. The value is shown in the ISO 8601 format. Example: 2022-03-09T11:19:04.819Z
updated\_at `string`	Timestamp representing the date and time when the object was last updated in ISO 8601 format. Example: 2022-03-09T11:19:04.819Z
object `string`	The type of the object represented by JSON. Available values: `validation\_rules\_assignment`
validation\_status `string`	The validation status of the assignment Available values: `VALID`, `PARTIALLY\_VALID`, `INVALID`
validation\_omitted\_rules `array`	The list of omitted rules

Amount

Attributes	Description
type `string`	Defines the type of the voucher. Available values: `AMOUNT`
amount\_off `number`	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.
amount\_off\_formula `string`	Formula used to dynamically calculate the discount.
aggregated\_amount\_limit `integer`	Maximum discount amount per order.
effect	Defines how the discount is applied to the customer's order. Discount Amount Vouchers Effect Types
is\_dynamic `boolean`	Flag indicating whether the discount was calculated using a formula.

Unit

Attributes	Description
type `string`	Discount type. Available values: `UNIT`
unit\_off `integer`	Number of units to be granted a full value discount.
unit\_off\_formula `string`	Formula used to dynamically calculate the number of units.
effect	Defines how the unit is added to the customer's order. Discount Unit Vouchers Effect Types
unit\_type `string`	The product deemed as free, chosen from product inventory (e.g. time, items).
product	Contains information about the product. Simple Product Discount Unit
sku	See: Simple Sku Discount Unit
is\_dynamic `boolean`	Flag indicating whether the discount was calculated using a formula.

Unit Multiple

Attributes Description

type
string

Discount type.

Available values: UNIT

effect
string

Defines how the discount is applied to the customer's order.

Available values: ADD\_MANY\_ITEMS

units
array

Array of One Unit

Percent

Attributes	Description
type `string`	Defines the type of the voucher. Available values: `PERCENT`
percent\_off `number`	The percent discount that the customer will receive.
percent\_off\_formula `string`	Formula used to dynamically calculate the discount.
amount\_limit `number`	Upper limit allowed to be applied as a discount. Value is multiplied by 100 to precisely represent 2 decimal places. For example, a \$6 maximum discount is written as 600.
aggregated\_amount\_limit `integer`	Maximum discount amount per order.
effect	Defines how the discount is applied to the customer's order. Discount Percent Vouchers Effect Types
is\_dynamic `boolean`	Flag indicating whether the discount was calculated using a formula.

Fixed

Attributes	Description
type `string`	Defines the type of the voucher. Available values: `FIXED`
fixed\_amount `number`	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.
fixed\_amount\_formula `string`	Formula used to dynamically calculate the discount.
effect	Defines how the discount is applied to the customer's order. Discount Fixed Vouchers Effect Types
is\_dynamic `boolean`	Flag indicating whether the discount was calculated using a formula.

Validation Rule Assignment

Attributes	Description
id `string`	Validation rule assignment ID. Example: asgm\_74F7QZoYbUoljwQO
rule\_id `string`	Validation rule ID. Example: val\_4j7DCRm2IS59
related\_object\_id `string`	The resource ID to which the validation rule was assigned. Example: v\_JtWunK6jUo7X2qOFj0SyRHq4p9tgENlT
related\_object\_type `string`	The type of resource to which the validation rule was assigned. Available values: `voucher`, `campaign`, `earning\_rule`, `reward\_assignment`, `promotion\_tier`, `distribution`
created\_at `string`	Timestamp representing the date and time when the validation rule assignment was created. The value is shown in the ISO 8601 format. Example: 2022-02-17T08:18:15.085Z
object `string`	The type of the object represented by the ID. Available values: `validation\_rules\_assignment`

Product without Skus Object

Attributes	Description
id `string`	Unique product ID assigned by Voucherify. Example: prod\_0b1da8105693710357
source\_id `string`, `null`	Unique product source ID. Example: productSourceID16
name `string`, `null`	Unique user-defined product name. Example: T-shirt
price `integer`, `null`	Unit price. It is represented by a value multiplied by 100 to accurately reflect 2 decimal places, such as `\$100.00` being expressed as `10000`.
attributes `array`	A list of product attributes whose values you can customize for given SKUs: `\["color","size","ranking"]`. Each child SKU can have a unique value for a given attribute.
metadata `object`	The metadata object stores all custom attributes assigned to the product. A set of key/value pairs that you can attach to a product object. It can be useful for storing additional information about the product in a structured format. It can be used to create product collections.
image\_url `string`, `null`	The HTTPS URL pointing to the .png or .jpg file that will be used to render the product image. Example: [https://images.com/original.jpg](https://images.com/original.jpg)
created\_at `string`	Timestamp representing the date and time when the product was created. The value is shown in the ISO 8601 format. Example: 2022-05-23T06:52:55.008Z
updated\_at `string`, `null`	Timestamp representing the date and time when the product was updated. The value is shown in the ISO 8601 format. Example: 2022-05-23T09:24:07.405Z
object `string`	The type of the object represented by JSON. This object stores information about the product. Available values: `product`

Skus List For Product

Attributes	Description
object `string`	The type of the object represented by JSON. This object stores information about SKUs.
data\_ref `string`	Identifies the name of the JSON property that contains the array of SKUs.
data `array`	A dictionary that contains an array of SKUs. Array of SKU Object
total `integer`	Total number of SKUs in the product.

Discount Amount Vouchers Effect Types

Available values: APPLY\_TO\_ORDER, APPLY\_TO\_ITEMS, APPLY\_TO\_ITEMS\_PROPORTIONALLY, APPLY\_TO\_ITEMS\_PROPORTIONALLY\_BY\_QUANTITY, APPLY\_TO\_ITEMS\_BY\_QUANTITY

Discount Unit Vouchers Effect Types

Available values: ADD\_MISSING\_ITEMS, ADD\_NEW\_ITEMS, ADD\_MANY\_ITEMS, ADD\_SAME\_ITEMS

Simple Product Discount Unit

Attributes	Description
id `string`	Unique product ID, assigned by Voucherify.
source\_id `string`	Product's source ID.
name `string`	Product name.

Simple Sku Discount Unit

Attributes	Description
id `string`	Unique SKU ID, assigned by Voucherify.
source\_id `string`	Product variant's source ID.
name `string`	Sku name

One Unit

Attributes	Description
unit\_off `number`	Number of units to be granted a full value discount.
unit\_off\_formula `string`	Formula used to dynamically calculate the number of units.
effect `string`	Defines how the unit is added to the customer's order. Available values: `ADD\_NEW\_ITEMS`, `ADD\_MISSING\_ITEMS`
unit\_type `string`	The product deemed as free, chosen from product inventory (e.g. time, items).
product	Contains information about the product. Simple Product Discount Unit
sku	Contains information about the sku. Simple Sku Discount Unit

Discount Percent Vouchers Effect Types

Available values: APPLY\_TO\_ORDER, APPLY\_TO\_ITEMS

Discount Fixed Vouchers Effect Types

Available values: APPLY\_TO\_ORDER, APPLY\_TO\_ITEMS

# Redemption Rollback Object Source: https://docs.voucherify.io/api-reference/redemptions/redemption-rollback-object

Redemption Rollback

Attributes Description

id
string

Unique identifier of the redemption rollback.

Example: rr\_0efeb3dab05e62e599

object
string

The type of the object represented by the JSON

Available values: redemption\_rollback

date
string

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

Example: 2021-12-22T10:13:06.487Z

customer\_id
string, null

Unique customer ID of the redeeming customer.

Example: cust\_i8t5Tt6eiKG5K79KQlJ0Vs64

tracking\_id
string, null

Hashed customer source ID.

metadata
object, null

The metadata object stores all custom attributes assigned to the redemption.

amount
integer

For gift cards, this represents the number of the credits restored to the card in the rolledback redemption. The number is a negative integer in the smallest currency unit, e.g. -100 cents for \$1.00 added back to the card.
For loyalty cards, this represents the number of loyalty points restored to the card in the rolledback redemption. The number is a negative integer.

Example: -10000

redemption
string, null

Unique redemption ID of the parent redemption.

Example: r\_0c656311b5878a2031

reason
string

System generated cause for the redemption being invalid in the context of the provided parameters.

result
string

Redemption result.

Available values: SUCCESS, FAILURE

status
string

Redemption status.

Available values: SUCCEEDED, FAILED

failure\_code
string

If the result is FAILURE, this parameter will provide a generic reason as to why the redemption failed.

Example: customer\_rules\_violated

failure\_message
string

If the result is FAILURE, this parameter will provide a more expanded reason as to why the redemption failed.

order

All of:

Order Calculated No Customer Data

Attributes	Description
items `array`	Array of items applied to the order. It can include up to 500 items. Array of Order Item Calculated

channel
object

Defines the details of the channel through which the redemption was issued.

Attributes Description

channel\_id
string

Unique identifier of the channel which was used by the user performing the redemption rollback. This is either a user ID from the user using the Voucherify Dashboard or an X-APP-Id of a user using the API.

Example: user\_g24UoRO3Caxu7FCT4n5tpYEa3zUG0FrH

channel\_type
string

The source of the channel for the redemption. A USER corresponds to the Voucherify Dashboard and an API corresponds to the API.

Available values: USER, API

customer

Simple Customer

related\_object\_type
string

Defines the related object.

Available values: voucher, promotion\_tier, redemption

related\_object\_id
string

Unique identifier of the related object. It is assigned by Voucherify, i.e. v\_lfZi4rcEGe0sN9gmnj40bzwK2FH6QUno for a voucher.

voucher

Defines the details of the voucher being originally redeemed.

Voucher

promotion\_tier

Contains details of the promotion tier and the parent campaign.

Promotion Tier

reward

See: Redemption Reward Result

gift
object

Contains the amount returned to the gift card in the redemption rollback. It is expressed as a negative integer.

Attributes	Description
amount `integer`	Amount returned to the gift card as a result of the redemption rollback and expressed as a negative integer. The amount is expressed as the smallest currency unit (e.g. -100 cents for \$1.00 returned).

loyalty\_card
object

Contains the number of points returned to the loyalty card in the reward redemption rollback. It is expressed as a negative integer.

Attributes	Description
points `integer`	Number of points being returned to the loyalty card for the reward redemption rollback. It is expressed as a negative integer.

Order Calculated No Customer Data

Attributes Description

id
string

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

source\_id
string, null

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

status
string

The order status.

Available values: CREATED, PAID, CANCELED, FULFILLED

amount
integer

This is the sum of the order items' amounts. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for \$1.00).

initial\_amount
integer

discount\_amount
integer

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\_discount\_amount
integer

Sum of all product-specific discounts applied to the order. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for \$1.00).

total\_discount\_amount
integer

Sum of all order-level AND all product-specific discounts applied to the order. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for \$1.00).

total\_amount
integer

Order amount after undoing all the discounts through the rollback redemption. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for \$1.00).

applied\_discount\_amount
integer

This field shows the order-level discount applied. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for \$1.00).

items\_applied\_discount\_amount
integer

total\_applied\_discount\_amount
integer

metadata
object

object
string

The type of the object represented by JSON.

Available values: order

created\_at
string

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

Example: 2021-12-22T10:13:06.487Z

updated\_at
string, null

Timestamp representing the date and time when the order was last updated in ISO 8601 format.

Example: 2021-12-22T10:14:45.316Z

customer\_id
string, null

Unique customer identifier of the customer making the purchase. The ID is assigned by Voucherify.

Example: cust\_7iUa6ICKyU6gH40dBU25kQU1

referrer\_id
string, null

Unique referrer ID.

Example: cust\_nM4jqPiaXUvQdVSA6vTRUnix

customer

Customer Id

referrer

Referrer Id

redemptions
object

Attributes	Description
\[propertyName]	See: Order Redemptions

Order Item Calculated

Attributes Description

id
string

Unique identifier of the order line item.

sku\_id
string

Unique identifier of the SKU. It is assigned by Voucherify.

product\_id
string

Unique identifier of the product. It is assigned by Voucherify.

related\_object
string

Used along with the source\_id property, can be set to either sku or product.

Available values: product, sku

source\_id
string

quantity
integer

The quantity of the particular item in the cart.

discount\_quantity
integer

Number of dicounted items.

initial\_quantity
integer

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
integer

The total amount of the order item (price \* quantity).

discount\_amount
integer

Sum of all order-item-level discounts applied to the order.

applied\_discount\_amount
integer

This field shows the order-level discount applied.

applied\_discount\_quantity
integer

Number of the discounted items applied in the transaction.

applied\_quantity
integer

Quantity of items changed by the application of a new quantity items. It can be positive when an item is added or negative if an item is replaced.

applied\_quantity\_amount
integer

Amount for the items changed by the application of a new quantity items. It can be positive when an item is added or negative if an item is replaced.

initial\_amount
integer

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
integer

Unit price of an item. The value is multiplied by 100 to represent 2 decimal places. For example 10000 cents for \$100.00.

subtotal\_amount
integer

product
object

An object containing details of the related product.

Attributes	Description
id `string`	A unique identifier that represents the product and is assigned by Voucherify.
source\_id `string`	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 `boolean`	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.
name `string`	Product name.
metadata `object`	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 `number`	Product price. A positive integer in the smallest currency unit (e.g. 100 cents for \$1.00).

sku
object

An object containing details of the related SKU.

Attributes	Description
id `string`	A unique identifier that represents the SKU and is assigned by Voucherify.
source\_id `string`	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 `boolean`	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 `string`	The SKU name.
price `number`	SKU price. A positive integer in the smallest currency unit (e.g. 100 cents for \$1.00).
metadata `object`	A set of custom key/value pairs that you can attach to an SKU. It can be useful for storing additional information about the SKU in a structured format. It can be used to create product collections.

object
string

The type of the object represented by JSON.

Available values: order\_item

metadata
object

Simple Customer

Attributes	Description
id `string`	Unique identifier of an existing customer. It is assigned by Voucherify.
name `string`	Customer's first and last name.
email `string`	Customer's email address.
source\_id `string`	A unique identifier of the customer. It can be a customer ID or email from a CRM system, database, or a third-party service.
metadata `object`	A set of custom key/value pairs that are attached to the customer. It stores all custom attributes assigned to the customer.
object `string`	The type of the object represented by JSON. Available values: `customer`

Voucher

This is an object representing a voucher with categories and validation rules assignments.

All of:

Voucher Base

Attributes	Description
categories `array`	Contains details about the category. Array of Category
validation\_rules\_assignments	See: Validation Rules Assignments List

Promotion Tier

Attributes Description

id
string

Unique promotion tier ID.

Example: promo\_63fYCt81Aw0h7lzyRkrGZh9p

created\_at
string

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

Example: 2021-12-15T11:34:01.333Z

updated\_at
string

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

Example: 2022-02-09T09:20:05.603Z

name
string

Name of the promotion tier.

banner
string

Text to be displayed to your customers on your website.

action
object

Contains details about the discount applied by the promotion tier.

Attributes	Description
discount	See: Discount

metadata
object

hierarchy
integer

promotion\_id
string

Promotion unique ID.

campaign
object

Contains details about promotion tier's parent campaign.

Attributes	Description
id `string`	Unique campaign ID.
start\_date `string`	Activation timestamp defines when the campaign starts to be active in ISO 8601 format. Campaign is inactive before this date. Example: 2022-09-22T00:00:00.000Z
expiration\_date `string`	Expiration timestamp defines when the campaign expires in ISO 8601 format. Campaign is inactive after this date. Example: 2022-09-30T00:00:00.000Z
validity\_timeframe	See: Validity Timeframe
validity\_day\_of\_week	See: Validity Day Of Week
validity\_hours	See: Validity Hours
active `boolean`	A flag indicating whether the campaign is active or not active. A campaign can be disabled even though it's within the active period defined by the `start\_date` and `expiration\_date` using the Disable Campaign endpoint. `true` indicates an active campaign `false` indicates an inactive campaign
category\_id `string`	Unique category ID that this campaign belongs to. Example: cat\_0b688929a2476386a6
object `string`	The type of the object represented by the campaign object. This object stores information about the campaign.

campaign\_id
string

Promotion tier's parent campaign's unique ID.

active
boolean

A flag to toggle the promotion tier on or off. You can disable a promotion tier even though it's within the active period defined by the start\_date and expiration\_date.

true indicates an active promotion tier
false indicates an inactive promotion tier

start\_date
string

Activation timestamp defines when the promotion tier starts to be active in ISO 8601 format. Promotion tier is inactive before this date.

Example: 2022-09-23T00:00:00.000Z

expiration\_date
string

Activation timestamp defines when the promotion tier expires in ISO 8601 format. Promotion tier is inactive after this date.

Example: 2022-09-26T00:00:00.000Z

validity\_timeframe

See: Validity Timeframe

validity\_day\_of\_week

See: Validity Day Of Week

validity\_hours

See: Validity Hours

summary
object

Contains statistics about promotion tier redemptions and orders.

Attributes Description

redemptions
object

Contains statistics about promotion tier redemptions.

Attributes	Description
total\_redeemed `integer`	Number of times the promotion tier was redeemed.

orders
object

Contains statistics about orders related to the promotion tier.

Attributes	Description
total\_amount `integer`	Sum of order totals.
total\_discount\_amount `integer`	Sum of total discount applied using the promotion tier.

object
string

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

validation\_rule\_assignments

See: Validation Rule Assignments List

category\_id
string

Promotion tier category ID.

Example: cat\_0c9da30e7116ba6bba

categories
array

Array of Category

Redemption Reward Result

Attributes Description

customer

Simple Customer

assignment\_id
string, null

Unique reward assignment ID assigned by Voucherify.

voucher

Voucher

product

Product

sku

SKU Object

loyalty\_tier\_id
string, null

Unique loyalty tier ID assigned by Voucherify.

id
string

Unique reward ID.

Example: rew\_0bc92f81a6801f9bca

name
string

Name of the reward.

Example: Reward Name

object
string

The type of the object represented by the JSON

Available values: reward

created\_at
string

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

Example: 2021-12-22T10:13:06.487Z

updated\_at
string

Timestamp in ISO 8601 format indicating when the reward was updated.

Example: 2022-10-03T12:24:58.008Z

parameters
object

These are parameters representing a material reward.

Attributes Description

campaign
object

Defines the product redeemed as a reward.

Attributes Description

id
string

Campaign unique ID.

Example: camp\_13BbZ0kQsNinhqsX3wUts2UP

balance
integer

Points available for reward redemption. This is calculated as follows: balance \= points \- expired\_points \- subtracted\_points \- redemption.redeemed\_points.

type
string

Defines the type of the campaign.

product
object

Defines the product redeemed as a reward.

Attributes Description

id
string

Unique product ID, assigned by Voucherify.

Example: prod\_0b7d7dfb05cbe5c616

sku\_id
string

Unique identifier of the SKU. It is assigned by Voucherify.

Example: sku\_0a41e31c7b41c28358

coin
object

Defines the ratio by mapping the number of loyalty points in points\_ratio to a predefined cash amount in exchange\_ratio.

Attributes	Description
exchange\_ratio `integer`	The cash equivalent of the points defined in the `points\_ratio` property.
points\_ratio `integer`	The number of loyalty points that will map to the predefined cash amount defined by the `exchange\_ratio` property.

metadata
object

A set of custom key/value pairs that you can attach to a reward. The metadata object stores all custom attributes assigned to the reward.

type
string

Reward type.

Available values: CAMPAIGN, COIN, MATERIAL

Customer Id

Attributes Description

id
string

A unique identifier of an existing customer.

object
string

The type of the object represented by JSON.

Available values: customer

Referrer Id

Customer Id

Order Redemptions

Attributes	Description
date `string`	Timestamp representing the date and time when the redemption was created. The value is shown in the ISO 8601 format. Example: 2022-09-02T17:06:56.649Z
rollback\_id `string`	Unique ID of the redemption rollback. Example: rr\_0c63c84eb78ee0a6c0
rollback\_date `string`	Timestamp representing the date and time when the redemption rollback was created. The value is shown in the ISO 8601 format. Example: 2023-01-31T14:18:37.150Z
related\_object\_type `string`	The source of the incentive.
related\_object\_id `string`	Unique ID of the parent redemption. Example: r\_0ba186c4824e4881e1
related\_object\_parent\_id `string`	Represent's the campaign ID of the voucher if the redemption was based on a voucher that was part of bulk codes generated within a campaign. In case of a promotion tier, this represents the campaign ID of the promotion tier's parent campaign.
stacked `array`	Contains a list of unique IDs of child redemptions, which belong to the stacked incentives.
rollback\_stacked `array`	Lists the rollback redemption IDs of the particular child redemptions.

Voucher Base

Attributes Description

id
string

Assigned by the Voucherify API, identifies the voucher.

Example: v\_mkZN9v7vjYUadXnHrMza8W5c34fE5KiV

code
string

A code that identifies a voucher. Pattern can use all letters of the English alphabet, Arabic numerals, and special characters.

Example: WVPblOYX

campaign
string

A unique campaign name, identifies the voucher's parent campaign.

Example: Gift Card Campaign

campaign\_id
string

Assigned by the Voucherify API, identifies the voucher's parent campaign.

Example: camp\_FNYR4jhqZBM9xTptxDGgeNBV

category
string

Tag defining the category that this voucher belongs to. Useful when listing vouchers using the List Vouchers endpoint.

category\_id
string

Unique category ID assigned by Voucherify.

Example: cat\_0bb343dee3cdb5ec0c

type
string

Defines the type of the voucher.

Available values: GIFT\_VOUCHER, DISCOUNT\_VOUCHER, LOYALTY\_CARD

discount

See: Discount

gift
object

Object representing gift parameters. Child attributes are present only if type is GIFT\_VOUCHER. Defaults to null.

Attributes	Description
amount `integer`	Total gift card income over the lifetime of the card. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `\$100.00`. Example: 10000
subtracted\_amount `integer`	Total amount of subtracted credits over the gift card lifetime. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `\$100.00`.
balance `integer`	Available funds. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `\$100.00`. Example: 500
effect `string`	Defines how the credits are applied to the customer's order. Available values: `APPLY\_TO\_ORDER`, `APPLY\_TO\_ITEMS`

loyalty\_card
object

Object representing loyalty card parameters. Child attributes are present only if type is LOYALTY\_CARD. Defaults to null.

Attributes	Description
points `integer`	Total number of points added to the loyalty card over its lifespan. Example: 7000
balance `integer`	Points available for reward redemption. This is calculated as follows: `balance` \= `points` \- `expired\_points` \- `subtracted\_points` \- `redemption.redeemed\_points`. Example: 6970
next\_expiration\_date `string`	The next closest date when the next set of points are due to expire. Example: 2023-05-30
next\_expiration\_points `integer`	The amount of points that are set to expire next.
pending\_points `integer`	Shows the number of pending points that will be added to the loyalty card when they are activated automatically or manually.
expired\_points `integer`	Shows the total number of expired points over the lifetime of the loyalty card.
subtracted\_points `integer`	Shows the total number of subtracted points over the lifetime of the loyalty card.

start\_date
string

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

Example: 2021-12-01T00:00:00.000Z

expiration\_date
string

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

Example: 2021-12-31T00:00:00.000Z

validity\_timeframe

See: Validity Timeframe

validity\_day\_of\_week

See: Validity Day Of Week

validity\_hours

See: Validity Hours

active
boolean, null

A flag to toggle the voucher on or off. You can disable a voucher even though it's within the active period defined by the start\_date and expiration\_date.

true indicates an active voucher
false indicates an inactive voucher

additional\_info
string

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

metadata
object

assets

See: Voucher Assets

is\_referral\_code
boolean, null

Flag indicating whether this voucher is a referral code; true for campaign type REFERRAL\_PROGRAM.

created\_at
string

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

Example: 2021-12-22T10:13:06.487Z

updated\_at
string

Timestamp representing the date and time when the voucher was last updated in ISO 8601 format.

Example: 2021-12-22T10:14:45.316Z

holder\_id
string

Unique customer identifier of the redeemable holder. It equals to the customer ID assigned by Voucherify.

Example: cust\_eWgXlBBiY6THFRJwX45Iakv4

referrer\_id
string

Unique identifier of the referring person.

Example: cust\_Vzck5i8U3OhcEUFY6MKhN9Rv

object
string

The type of the object represented by JSON. Default is voucher.

publish
object

Stores a summary of publication events: an event counter and endpoint to return details of each event. Publication is an assignment of a code to a customer, e.g. through a distribution.

Attributes Description

object
string

The type of the object represented is by default list. To get this list, you need to make a call to the endpoint returned in the url attribute.

count
integer

Publication events counter.

Example: 0

url
string

The endpoint where this list of publications can be accessed using a GET method. /v1/vouchers//publications

Example: /v1/vouchers/WVPblOYX/publications?page=1\&limit=10

redemption
object

Stores a summary of redemptions that have been applied to the voucher.

Attributes	Description
quantity `integer`	How many times a voucher can be redeemed. A `null` value means unlimited.
redeemed\_quantity `integer`	How many times a voucher has already been redeemed. Example: 1
redeemed\_points `integer`	Total loyalty points redeemed. Example: 100000
object `string`	The type of the object represented is by default `list`. To get this list, you need to make a call to the endpoint returned in the url attribute.
url `string`	The endpoint where this list of redemptions can be accessed using a GET method. `/v1/vouchers//redemptions` Example: /v1/vouchers/WVPblOYX/redemptions?page=1\&limit=10

Category

Attributes	Description
id `string`	Unique category ID assigned by Voucherify.
name `string`	Category name.
hierarchy `integer`	Category hierarchy. Categories with lower hierarchy are processed before categories with higher hierarchy value.
object `string`	The type of the object represented by the JSON. This object stores information about the category. Available values: `category`
created\_at `string`	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
updated\_at `string`	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

Validation Rules Assignments List

Attributes	Description
object `string`	The type of the object represented by JSON. This object stores information about validation rules assignments. Available values: `list`
data\_ref `string`	Identifies the name of the attribute that contains the array of validation rules assignments. Available values: `data`
data `array`	Contains array of validation rules assignments. Array of Business Validation Rule Assignment
total `integer`	Total number of validation rules assignments.

Discount

Contains information about discount.

One of:

Amount
Unit
Unit Multiple
Percent
Fixed

Validity Timeframe

Attributes Description

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

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

Validity Day Of Week

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

Validity Hours

Attributes Description

daily
array

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

Array of:

Attributes Description

start\_time
string

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

Example: 12:00

days\_of\_week
array

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

expiration\_time
string

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

Example: 14:00

Validation Rule Assignments List

Attributes	Description
object `string`	The type of the object represented by JSON. This object stores information about validation rule assignments.
data\_ref `string`	Identifies the name of the JSON property that contains the array of validation rule assignments.
data `array`	A dictionary that contains an array of validation rule assignments. Array of Validation Rule Assignment
total `integer`	Total number of validation rule assignments.

Product

This is an object representing a product.

This entity should be used to map product items from your inventory management system. The aim of products is to build which reflect product-specific campaigns.

All of:

Product without Skus Object

Attributes	Description
skus	See: Skus List For Product

SKU Object

Attributes	Description
id `string`	A unique identifier that represents the SKU and is assigned by Voucherify. Example: sku\_0b1621b319d248b79f
source\_id `string`, `null`	A unique SKU identifier from your inventory system. Example: sku\_source\_id\_4
product\_id `string`	The parent product's unique ID. Example: prod\_0b15f6b9f650c16990
sku `string`, `null`	Unique user-defined SKU name. Example: Large Pink Shirt
price `integer`, `null`	Unit price. It is represented by a value multiplied by 100 to accurately reflect 2 decimal places, such as `\$100.00` being expressed as `10000`.
currency `string`, `null`	SKU price currency. Example: USD
attributes `object`	The attributes object stores values for all custom attributes inherited by the SKU from the parent product. A set of key/value pairs that are attached to a SKU object and are unique to each SKU within a product family.
image\_url `string`, `null`	The HTTPS URL pointing to the .png or .jpg file that will be used to render the SKU image.
metadata `object`	The metadata object stores all custom attributes assigned to the SKU. A set of key/value pairs that you can attach to a SKU object. It can be useful for storing additional information about the SKU in a structured format. It can be used to create product collections.
created\_at `string`	Timestamp representing the date and time when the SKU was created. The value is shown in the ISO 8601 format. Example: 2022-05-17T10:36:30.187Z
updated\_at `string`, `null`	Timestamp representing the date and time when the SKU was updated. The value is shown in the ISO 8601 format. Example: 2022-05-17T10:55:09.137Z
object `string`	The type of the object represented by JSON. This object stores information about the `SKU`. Available values: `sku`

Voucher Assets

Attributes Description

qr
object

Stores Quick Response (QR) representation of encrypted code.

Attributes Description

id
string

Encrypted voucher code ID.

Example: U2FsdGVkX19ucFhvVmBVpVYG5KoswTsjSIaqoKg5L9ie4BK+t4pp7U7oFzjGJzj9q/bmuMOj9mEFiVKDMIkSaruKedMvHbKoPX5Sg+BaZk5QwXMf8k/OzSlOEVybpwSq+AiqPoNtjeuqtIgkDyvT6Q==

url
string

URL to QR code

Optional: Attach query parameters to base URL to customize the image of the encrypted voucher code.

size : integer value from 1 to 100
format : string, either png (default) or svg

barcode
object

Stores barcode representation of encrypted code.

Attributes Description

id
string

Encrypted voucher code ID.

Example: U2FsdGVkX19eJhGfWwUrH9+tulBkON+AnMktic+N6CVWzZ9+fHVxuVx22WakrzxiWXy0skuvvEHSeZIw9HlgyIJ+kJ1iPdUKpyENuNYJKzoZlO0mmTf6WQM6/pFs61apEn9SJx32ttCF6d3oxKISQQ==

url
string

URL to barcode

Optional: Attach query parameters to base URL to customize the image of the encrypted voucher code.

size : integer value from 1 to 100
format : string, either png (default) or svg

Business Validation Rule Assignment

Attributes	Description
id `string`	The unique identifier for a assignment
rule\_id `string`	The unique identifier for a rule
related\_object\_id `string`	The unique identifier for a related object
related\_object\_type `string`	The type of related object
created\_at `string`	Timestamp representing the date and time when the object was created. The value is shown in the ISO 8601 format. Example: 2022-03-09T11:19:04.819Z
updated\_at `string`	Timestamp representing the date and time when the object was last updated in ISO 8601 format. Example: 2022-03-09T11:19:04.819Z
object `string`	The type of the object represented by JSON. Available values: `validation\_rules\_assignment`
validation\_status `string`	The validation status of the assignment Available values: `VALID`, `PARTIALLY\_VALID`, `INVALID`
validation\_omitted\_rules `array`	The list of omitted rules

Amount

Attributes	Description
type `string`	Defines the type of the voucher. Available values: `AMOUNT`
amount\_off `number`	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.
amount\_off\_formula `string`	Formula used to dynamically calculate the discount.
aggregated\_amount\_limit `integer`	Maximum discount amount per order.
effect	Defines how the discount is applied to the customer's order. Discount Amount Vouchers Effect Types
is\_dynamic `boolean`	Flag indicating whether the discount was calculated using a formula.

Unit

Attributes	Description
type `string`	Discount type. Available values: `UNIT`
unit\_off `integer`	Number of units to be granted a full value discount.
unit\_off\_formula `string`	Formula used to dynamically calculate the number of units.
effect	Defines how the unit is added to the customer's order. Discount Unit Vouchers Effect Types
unit\_type `string`	The product deemed as free, chosen from product inventory (e.g. time, items).
product	Contains information about the product. Simple Product Discount Unit
sku	See: Simple Sku Discount Unit
is\_dynamic `boolean`	Flag indicating whether the discount was calculated using a formula.

Unit Multiple

Attributes Description

type
string

Discount type.

Available values: UNIT

effect
string

Defines how the discount is applied to the customer's order.

Available values: ADD\_MANY\_ITEMS

units
array

Array of One Unit

Percent

Attributes	Description
type `string`	Defines the type of the voucher. Available values: `PERCENT`
percent\_off `number`	The percent discount that the customer will receive.
percent\_off\_formula `string`	Formula used to dynamically calculate the discount.
amount\_limit `number`	Upper limit allowed to be applied as a discount. Value is multiplied by 100 to precisely represent 2 decimal places. For example, a \$6 maximum discount is written as 600.
aggregated\_amount\_limit `integer`	Maximum discount amount per order.
effect	Defines how the discount is applied to the customer's order. Discount Percent Vouchers Effect Types
is\_dynamic `boolean`	Flag indicating whether the discount was calculated using a formula.

Fixed

Attributes	Description
type `string`	Defines the type of the voucher. Available values: `FIXED`
fixed\_amount `number`	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.
fixed\_amount\_formula `string`	Formula used to dynamically calculate the discount.
effect	Defines how the discount is applied to the customer's order. Discount Fixed Vouchers Effect Types
is\_dynamic `boolean`	Flag indicating whether the discount was calculated using a formula.

Validation Rule Assignment

Attributes	Description
id `string`	Validation rule assignment ID. Example: asgm\_74F7QZoYbUoljwQO
rule\_id `string`	Validation rule ID. Example: val\_4j7DCRm2IS59
related\_object\_id `string`	The resource ID to which the validation rule was assigned. Example: v\_JtWunK6jUo7X2qOFj0SyRHq4p9tgENlT
related\_object\_type `string`	The type of resource to which the validation rule was assigned. Available values: `voucher`, `campaign`, `earning\_rule`, `reward\_assignment`, `promotion\_tier`, `distribution`
created\_at `string`	Timestamp representing the date and time when the validation rule assignment was created. The value is shown in the ISO 8601 format. Example: 2022-02-17T08:18:15.085Z
object `string`	The type of the object represented by the ID. Available values: `validation\_rules\_assignment`

Product without Skus Object

Attributes	Description
id `string`	Unique product ID assigned by Voucherify. Example: prod\_0b1da8105693710357
source\_id `string`, `null`	Unique product source ID. Example: productSourceID16
name `string`, `null`	Unique user-defined product name. Example: T-shirt
price `integer`, `null`	Unit price. It is represented by a value multiplied by 100 to accurately reflect 2 decimal places, such as `\$100.00` being expressed as `10000`.
attributes `array`	A list of product attributes whose values you can customize for given SKUs: `\["color","size","ranking"]`. Each child SKU can have a unique value for a given attribute.
metadata `object`	The metadata object stores all custom attributes assigned to the product. A set of key/value pairs that you can attach to a product object. It can be useful for storing additional information about the product in a structured format. It can be used to create product collections.
image\_url `string`, `null`	The HTTPS URL pointing to the .png or .jpg file that will be used to render the product image. Example: [https://images.com/original.jpg](https://images.com/original.jpg)
created\_at `string`	Timestamp representing the date and time when the product was created. The value is shown in the ISO 8601 format. Example: 2022-05-23T06:52:55.008Z
updated\_at `string`, `null`	Timestamp representing the date and time when the product was updated. The value is shown in the ISO 8601 format. Example: 2022-05-23T09:24:07.405Z
object `string`	The type of the object represented by JSON. This object stores information about the product. Available values: `product`

Skus List For Product

Attributes	Description
object `string`	The type of the object represented by JSON. This object stores information about SKUs.
data\_ref `string`	Identifies the name of the JSON property that contains the array of SKUs.
data `array`	A dictionary that contains an array of SKUs. Array of SKU Object
total `integer`	Total number of SKUs in the product.

Discount Amount Vouchers Effect Types

Available values: APPLY\_TO\_ORDER, APPLY\_TO\_ITEMS, APPLY\_TO\_ITEMS\_PROPORTIONALLY, APPLY\_TO\_ITEMS\_PROPORTIONALLY\_BY\_QUANTITY, APPLY\_TO\_ITEMS\_BY\_QUANTITY

Discount Unit Vouchers Effect Types

Available values: ADD\_MISSING\_ITEMS, ADD\_NEW\_ITEMS, ADD\_MANY\_ITEMS, ADD\_SAME\_ITEMS

Simple Product Discount Unit

Attributes	Description
id `string`	Unique product ID, assigned by Voucherify.
source\_id `string`	Product's source ID.
name `string`	Product name.

Simple Sku Discount Unit

Attributes	Description
id `string`	Unique SKU ID, assigned by Voucherify.
source\_id `string`	Product variant's source ID.
name `string`	Sku name

One Unit

Attributes	Description
unit\_off `number`	Number of units to be granted a full value discount.
unit\_off\_formula `string`	Formula used to dynamically calculate the number of units.
effect `string`	Defines how the unit is added to the customer's order. Available values: `ADD\_NEW\_ITEMS`, `ADD\_MISSING\_ITEMS`
unit\_type `string`	The product deemed as free, chosen from product inventory (e.g. time, items).
product	Contains information about the product. Simple Product Discount Unit
sku	Contains information about the sku. Simple Sku Discount Unit

Discount Percent Vouchers Effect Types

Available values: APPLY\_TO\_ORDER, APPLY\_TO\_ITEMS

Discount Fixed Vouchers Effect Types

Available values: APPLY\_TO\_ORDER, APPLY\_TO\_ITEMS

# Rollback Redemption Source: https://docs.voucherify.io/api-reference/redemptions/rollback-redemption /openapi/redemptions.json post /v1/redemptions/{redemptionId}/rollback Your business logic may include a case when you need to undo a redemption. You can revert a redemption by calling this API endpoint. This endpoint rolls back only single redemptions, meaning those that are not stacked. Stacked redemptions belong to a parent redemption. To roll back a parent redemption, including all of its individual redemptions, use the [POST Rollback Stackable Redemptions](/api-reference/redemptions/rollback-stackable-redemptions) You can roll back a redemption up to 3 months back. ## Effect The operation - creates a rollback entry in voucher's redemption history (`redemption.redemption_entries`) and - gives 1 redemption back to the pool (decreases `redeemed_quantity` by 1). ## Returned funds In case of *gift card vouchers*, this method returns funds back according to the source redemption. In case of *loyalty card vouchers*, this method returns points back according to the source redemption. # Rollback Stackable Redemptions Source: https://docs.voucherify.io/api-reference/redemptions/rollback-stackable-redemptions /openapi/redemptions.json post /v1/redemptions/{parentRedemptionId}/rollbacks Rollback a stackable redemption. When you roll back a stacked redemption, all child redemptions will be rolled back. Provide the parent redemption ID as the path parameter. However, you can use this endpoint to roll back a single redemption that does not have a parent, similarly to [POST Rollback redemption](/api-reference/redemptions/rollback-redemption). You can roll back a redemption up to 3 months back. # Stackable Redemptions Object Source: https://docs.voucherify.io/api-reference/redemptions/stackable-redemptions-object

Redemptions Redeem Response Body

Attributes Description

redemptions
array

Array of Redemption

parent\_redemption

See: Redemption

order

Contains the order details associated with the redemption.

All of:

Order Calculated No Customer Data

Attributes	Description
items `array`	Array of items applied to the order. It can include up to 500 items.

inapplicable\_redeemables
array

Lists validation results of each inapplicable redeemable.

Array of Inapplicable Redeemable

skipped\_redeemables
array

Lists validation results of each redeemable. If a redeemable can be applied, the API returns "status": "APPLICABLE".

Array of Skipped Redeemable

Redemption

This is an object representing a redemption for POST v1/redemptions and POST /client/v1/redemptions.

All of:

Redemption Base

Attributes

Description

voucher

Defines the details of the voucher being redeemed.

All of:

Voucher with categories and validation rules assignments
Voucher Holder

Order Calculated No Customer Data

Attributes Description

id
string

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

source\_id
string, null

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

status
string

The order status.

Available values: CREATED, PAID, CANCELED, FULFILLED

amount
integer

This is the sum of the order items' amounts. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for \$1.00).

initial\_amount
integer

discount\_amount
integer

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\_discount\_amount
integer

Sum of all product-specific discounts applied to the order. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for \$1.00).

total\_discount\_amount
integer

Sum of all order-level AND all product-specific discounts applied to the order. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for \$1.00).

total\_amount
integer

Order amount after undoing all the discounts through the rollback redemption. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for \$1.00).

applied\_discount\_amount
integer

This field shows the order-level discount applied. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for \$1.00).

items\_applied\_discount\_amount
integer

total\_applied\_discount\_amount
integer

metadata
object

object
string

The type of the object represented by JSON.

Available values: order

created\_at
string

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

Example: 2021-12-22T10:13:06.487Z

updated\_at
string, null

Timestamp representing the date and time when the order was last updated in ISO 8601 format.

Example: 2021-12-22T10:14:45.316Z

customer\_id
string, null

Unique customer identifier of the customer making the purchase. The ID is assigned by Voucherify.

Example: cust\_7iUa6ICKyU6gH40dBU25kQU1

referrer\_id
string, null

Unique referrer ID.

Example: cust\_nM4jqPiaXUvQdVSA6vTRUnix

customer

Customer Id

referrer

Referrer Id

redemptions
object

Attributes	Description
\[propertyName]	See: Order Redemptions

Inapplicable Redeemable

Attributes Description

status
string

Indicates whether the redeemable can be applied or not applied based on the validation rules.

Available values: INAPPLICABLE

id
string

Redeemable ID, i.e. the voucher code.

object
string

Redeemable's object type.

Available values: voucher, promotion\_tier

result
object

Includes the error object with details about the reason why the redeemable is inapplicable

Attributes Description

error

See: Error Object

details
object

Provides details about the reason why the redeemable is inapplicable.

Attributes	Description
message `string`	Generic message from the `message` string shown in the `error` object or the message configured in a validation rule.
key `string`	Generic message from the `key` string shown in the `error` object.

bundle

See: Bundle Details

metadata
object

The metadata object stores all custom attributes in the form of key/value pairs assigned to the redeemable.

categories
array

Array of Category with Stacking Rules Type

campaign\_name
string

Campaign name. Displayed only if the options.expand is passed with a redeemable value in the validation request body.

campaign\_id
string

Unique campaign ID assigned by Voucherify. Displayed only if the options.expand is passed with a redeemable value in the validation request body.

Example: camp\_pqZjuhG6Mgtp4GD0zD7b8hA3

name
string

Name of the promotion tier. Displayed only if the options.expand is passed with a redeemable value in the validation request body.

Skipped Redeemable

Attributes Description

status
string

Indicates whether the redeemable can be applied or not applied based on the validation rules.

Available values: SKIPPED

id
string

Redeemable ID, i.e. the voucher code.

object
string

Redeemable's object type.

Available values: voucher, promotion\_tier

result
object

Provides details about the reason why the redeemable is skipped.

Attributes

Description

details

One of:

Validations Redeemable Skipped Result Limit Exceeded
Validations Redeemable Skipped Result Category Limit Exceeded
Validations Redeemable Skipped Result Redeemables Limit Exceeded
Validations Redeemable Skipped Result Redeemables Category Limit Exceeded
Validations Redeemable Skipped Result Exclusion Rules Not Met
Validations Redeemable Skipped Result Preceding Validation Failed
Validations Redeemable Skipped Result No Effect

metadata
object

The metadata object stores all custom attributes in the form of key/value pairs assigned to the redeemable.

categories
array

Array of Category with Stacking Rules Type

campaign\_name
string

Campaign name. Displayed only if the options.expand is passed with a redeemable value in the validation request body.

campaign\_id
string

Unique campaign ID assigned by Voucherify. Displayed only if the options.expand is passed with a redeemable value in the validation request body.

Example: camp\_pqZjuhG6Mgtp4GD0zD7b8hA3

name
string

Name of the promotion tier. Displayed only if the options.expand is passed with a redeemable value in the validation request body.

Redemption Base

Attributes Description

id
string

Unique redemption ID.

Example: r\_0bc92f81a6801f9bca

object
string

The type of the object represented by the JSON

Available values: redemption

date
string

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

Example: 2021-12-22T10:13:06.487Z

customer\_id
string, null

Unique customer ID of the redeeming customer.

Example: cust\_i8t5Tt6eiKG5K79KQlJ0Vs64

tracking\_id
string, null

Hashed customer source ID.

metadata
object, null

The metadata object stores all custom attributes assigned to the redemption.

amount
integer

Example: 10000

redemption
string, null

Unique redemption ID of the parent redemption.

Example: r\_0c656311b5878a2031

result
string

Redemption result.

Available values: SUCCESS, FAILURE

status
string

Redemption status.

Available values: SUCCEEDED, FAILED, ROLLED\_BACK

session
object

Contains details about the redemption session lock. Sessions can be established only for discount vouchers, promotions, and gift cards.

Attributes	Description
key `string`	The session unique ID assigned by Voucherify or your own unique session ID sent in the request.

related\_redemptions
object

Attributes Description

rollbacks
array

Array of:

Redemption Related Redemptions Rollbacks Item

Attributes Description

id
string

Unique rollback redemption ID.

Example: rr\_0bc92f81a6801f9bca

date
string

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

Example: 2021-12-22T10:13:06.487Z

rollback\_order\_mode
string

Available values: WITH\_ORDER, WITHOUT\_ORDER

redemptions
array

Array of:

Redemption Related Redemptions Item

Attributes Description

id
string

Unique redemption ID.

Example: r\_0bc92f81a6801f9bca

date
string

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

Example: 2021-12-22T10:13:06.487Z

failure\_code
string

If the result is FAILURE, this parameter will provide a generic reason as to why the redemption failed.

Example: customer\_rules\_violated

failure\_message
string

If the result is FAILURE, this parameter will provide a more expanded reason as to why the redemption failed.

order

All of:

Order Calculated No Customer Data

Attributes	Description
items `array`	Array of items applied to the order. It can include up to 500 items.

channel
object

Defines the details of the channel through which the redemption was issued.

Attributes Description

channel\_id
string

Example: user\_g24UoRO3Caxu7FCT4n5tpYEa3zUG0FrH

channel\_type
string

Available values: USER, API, AUTO\_REDEEM

customer

Simple Customer

related\_object\_type
string

Defines the related object.

Available values: voucher, promotion\_tier, redemption

related\_object\_id
string

Unique related object ID assigned by Voucherify, i.e. v\_lfZi4rcEGe0sN9gmnj40bzwK2FH6QUno for a voucher.

promotion\_tier

Contains details of the promotion tier and the parent campaign.

Promotion Tier

reward

See: Redemption Reward Result

gift
object

Contains the amount subtracted from the gift card for the redemption.

Attributes	Description
amount `integer`	Amount subtracted from the gift card as a result of the redemption. The amount is expressed as the smallest currency unit (e.g. 100 cents for \$1.00).

loyalty\_card
object

Contains the number of points subtracted from the loyalty card for the redemption.

Attributes	Description
points `integer`	Number of points subtracted from the loyalty card as a result of the redemption.

Voucher with categories and validation rules assignments

This is an object representing a voucher with categories and validation rules assignments for POST v1/qualifications, POST v1/redemptions, and POST v1/validations.

All of:

Voucher Base

Attributes	Description
categories `array`	Contains details about the category. Array of Category with Stacking Rules Type
validation\_rules\_assignments	See: Validation Rules Assignments List

Voucher Holder

Attributes	Description
holder	See: Simple Customer

Customer Id

Attributes Description

id
string

A unique identifier of an existing customer.

object
string

The type of the object represented by JSON.

Available values: customer

Referrer Id

Customer Id

Order Redemptions

Attributes	Description
date `string`	Timestamp representing the date and time when the redemption was created. The value is shown in the ISO 8601 format. Example: 2022-09-02T17:06:56.649Z
rollback\_id `string`	Unique ID of the redemption rollback. Example: rr\_0c63c84eb78ee0a6c0
rollback\_date `string`	Timestamp representing the date and time when the redemption rollback was created. The value is shown in the ISO 8601 format. Example: 2023-01-31T14:18:37.150Z
related\_object\_type `string`	The source of the incentive.
related\_object\_id `string`	Unique ID of the parent redemption. Example: r\_0ba186c4824e4881e1
related\_object\_parent\_id `string`	Represent's the campaign ID of the voucher if the redemption was based on a voucher that was part of bulk codes generated within a campaign. In case of a promotion tier, this represents the campaign ID of the promotion tier's parent campaign.
stacked `array`	Contains a list of unique IDs of child redemptions, which belong to the stacked incentives.
rollback\_stacked `array`	Lists the rollback redemption IDs of the particular child redemptions.

Error Object

Attributes Description

code
integer

Error's HTTP status code.

key
string

Short string describing the kind of error which occurred.

message
string

A human-readable message providing a short description of the error.

details
string

A human-readable message providing more details about the error.

request\_id
string

This ID is useful when troubleshooting and/or finding the root cause of an error response by our support team.

Example: v-0a885062c80375740f

resource\_id
string

Unique resource ID that can be used in another endpoint to get more details.

Example: rf\_0c5d710a87c8a31f86

resource\_type
string

The resource type.

Example: voucher

error
object

Includes additional information about the error.

Attributes	Description
message `string`	The message configured by the user in a validation rule.

Bundle Details

Attributes Description

quantity
integer

limit
integer

Determines the maximum number of identified bundles. This also defines the maximum multiplier of the bundle discount.

identified
array

Array of:

Attributes	Description
id `string`	Unique identifier of the product or SKU that meets the bundle condition. This is an ID assigned by Voucherify.
object `string`	Determines the type of the object that meets the bundle condition. Available values: `product`, `sku`
item\_index `integer`	Number assigned to the order line item in accordance with the order sent in the request. It starts with `0` for the first order line item in the request.
item\_quantity `integer`	Quantity of items that meet the bundle conditions. If the quantity in the order is higher than the quantity required by the bundle, this returns only the number that meets the bundle. For example, if the bundle requires `5` coffees, but the order includes `10` coffees, `item\_quantity` returns `5`.

missing
array

Array of:

Attributes Description

id
string

Unique identifier of the collection, product, or SKU that is missing in the customer's order items. This is an ID assigned by Voucherify.

object
string

Determines the type of the object that is missing in the customer's order items.

Available values: product, products\_collection, sku

item\_quantity
integer

Quantity of items that are missing in the order items to meet the bundle conditions.

Category with Stacking Rules Type

Category object with stacking\_rules\_type

All of:

Category

Attributes Description

stacking\_rules\_type
string

The type of the stacking rule eligibility.

Available values: JOINT, EXCLUSIVE

Validations Redeemable Skipped Result Limit Exceeded

Attributes	Description
key `string`	Available values: `applicable\_redeemables\_limit\_exceeded`
message `string`	Example: Applicable redeemables limit exceeded

Validations Redeemable Skipped Result Category Limit Exceeded

Attributes	Description
key `string`	Available values: `applicable\_redeemables\_per\_category\_limit\_exceeded`
message `string`	Example: Applicable redeemables limit per category exceeded

Validations Redeemable Skipped Result Redeemables Limit Exceeded

Attributes	Description
key `string`	Available values: `applicable\_exclusive\_redeemables\_limit\_exceeded`
message `string`	Example: Applicable exclusive redeemables limit exceeded

Validations Redeemable Skipped Result Redeemables Category Limit Exceeded

Attributes	Description
key `string`	Available values: `applicable\_exclusive\_redeemables\_per\_category\_limit\_exceeded`
message `string`	Example: Applicable exclusive redeemables limit per category exceeded

Validations Redeemable Skipped Result Exclusion Rules Not Met

Attributes	Description
key `string`	Available values: `exclusion\_rules\_not\_met`
message `string`	Example: Redeemable cannot be applied due to exclusion rules

Validations Redeemable Skipped Result Preceding Validation Failed

Attributes	Description
key `string`	Available values: `preceding\_validation\_failed`
message `string`	Example: Redeemable cannot be applied due to preceding validation failure

Validations Redeemable Skipped Result No Effect

Attributes	Description
key `string`	Available values: `no\_effect`
message `string`	Example: Redeemable cannot be applied due to no effect

Simple Customer

Attributes	Description
id `string`	Unique identifier of an existing customer. It is assigned by Voucherify.
name `string`	Customer's first and last name.
email `string`	Customer's email address.
source\_id `string`	A unique identifier of the customer. It can be a customer ID or email from a CRM system, database, or a third-party service.
metadata `object`	A set of custom key/value pairs that are attached to the customer. It stores all custom attributes assigned to the customer.
object `string`	The type of the object represented by JSON. Available values: `customer`

Promotion Tier

Attributes Description

id
string

Unique promotion tier ID.

Example: promo\_63fYCt81Aw0h7lzyRkrGZh9p

created\_at
string

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

Example: 2021-12-15T11:34:01.333Z

updated\_at
string

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

Example: 2022-02-09T09:20:05.603Z

name
string

Name of the promotion tier.

banner
string

Text to be displayed to your customers on your website.

action
object

Contains details about the discount applied by the promotion tier.

Attributes	Description
discount	See: Discount

metadata
object

hierarchy
integer

promotion\_id
string

Promotion unique ID.

campaign
object

Contains details about promotion tier's parent campaign.

Attributes	Description
id `string`	Unique campaign ID.
start\_date `string`	Activation timestamp defines when the campaign starts to be active in ISO 8601 format. Campaign is inactive before this date. Example: 2022-09-22T00:00:00.000Z
expiration\_date `string`	Expiration timestamp defines when the campaign expires in ISO 8601 format. Campaign is inactive after this date. Example: 2022-09-30T00:00:00.000Z
validity\_timeframe	See: Validity Timeframe
validity\_day\_of\_week	See: Validity Day Of Week
validity\_hours	See: Validity Hours
active `boolean`	A flag indicating whether the campaign is active or not active. A campaign can be disabled even though it's within the active period defined by the `start\_date` and `expiration\_date` using the Disable Campaign endpoint. `true` indicates an active campaign `false` indicates an inactive campaign
category\_id `string`	Unique category ID that this campaign belongs to. Example: cat\_0b688929a2476386a6
object `string`	The type of the object represented by the campaign object. This object stores information about the campaign.

campaign\_id
string

Promotion tier's parent campaign's unique ID.

active
boolean

A flag to toggle the promotion tier on or off. You can disable a promotion tier even though it's within the active period defined by the start\_date and expiration\_date.

true indicates an active promotion tier
false indicates an inactive promotion tier

start\_date
string

Activation timestamp defines when the promotion tier starts to be active in ISO 8601 format. Promotion tier is inactive before this date.

Example: 2022-09-23T00:00:00.000Z

expiration\_date
string

Activation timestamp defines when the promotion tier expires in ISO 8601 format. Promotion tier is inactive after this date.

Example: 2022-09-26T00:00:00.000Z

validity\_timeframe

See: Validity Timeframe

validity\_day\_of\_week

See: Validity Day Of Week

validity\_hours

See: Validity Hours

summary
object

Contains statistics about promotion tier redemptions and orders.

Attributes Description

redemptions
object

Contains statistics about promotion tier redemptions.

Attributes	Description
total\_redeemed `integer`	Number of times the promotion tier was redeemed.

orders
object

Contains statistics about orders related to the promotion tier.

Attributes	Description
total\_amount `integer`	Sum of order totals.
total\_discount\_amount `integer`	Sum of total discount applied using the promotion tier.

object
string

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

validation\_rule\_assignments

See: Validation Rule Assignments List

category\_id
string

Promotion tier category ID.

Example: cat\_0c9da30e7116ba6bba

categories
array

Array of Category

Redemption Reward Result

Attributes Description

customer

Simple Customer

assignment\_id
string, null

Unique reward assignment ID assigned by Voucherify.

voucher

Voucher

product

Product

sku

SKU Object

loyalty\_tier\_id
string, null

Unique loyalty tier ID assigned by Voucherify.

id
string

Unique reward ID.

Example: rew\_0bc92f81a6801f9bca

name
string

Name of the reward.

Example: Reward Name

object
string

The type of the object represented by the JSON

Available values: reward

created\_at
string

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

Example: 2021-12-22T10:13:06.487Z

updated\_at
string

Timestamp in ISO 8601 format indicating when the reward was updated.

Example: 2022-10-03T12:24:58.008Z

parameters
object

These are parameters representing a material reward.

Attributes Description

campaign
object

Defines the product redeemed as a reward.

Attributes Description

id
string

Campaign unique ID.

Example: camp\_13BbZ0kQsNinhqsX3wUts2UP

balance
integer

Points available for reward redemption. This is calculated as follows: balance \= points \- expired\_points \- subtracted\_points \- redemption.redeemed\_points.

type
string

Defines the type of the campaign.

product
object

Defines the product redeemed as a reward.

Attributes Description

id
string

Unique product ID, assigned by Voucherify.

Example: prod\_0b7d7dfb05cbe5c616

sku\_id
string

Unique identifier of the SKU. It is assigned by Voucherify.

Example: sku\_0a41e31c7b41c28358

coin
object

Defines the ratio by mapping the number of loyalty points in points\_ratio to a predefined cash amount in exchange\_ratio.

Attributes	Description
exchange\_ratio `integer`	The cash equivalent of the points defined in the `points\_ratio` property.
points\_ratio `integer`	The number of loyalty points that will map to the predefined cash amount defined by the `exchange\_ratio` property.

metadata
object

A set of custom key/value pairs that you can attach to a reward. The metadata object stores all custom attributes assigned to the reward.

type
string

Reward type.

Available values: CAMPAIGN, COIN, MATERIAL

Voucher Base

Attributes Description

id
string

Assigned by the Voucherify API, identifies the voucher.

Example: v\_mkZN9v7vjYUadXnHrMza8W5c34fE5KiV

code
string

A code that identifies a voucher. Pattern can use all letters of the English alphabet, Arabic numerals, and special characters.

Example: WVPblOYX

campaign
string

A unique campaign name, identifies the voucher's parent campaign.

Example: Gift Card Campaign

campaign\_id
string

Assigned by the Voucherify API, identifies the voucher's parent campaign.

Example: camp\_FNYR4jhqZBM9xTptxDGgeNBV

category
string

Tag defining the category that this voucher belongs to. Useful when listing vouchers using the List Vouchers endpoint.

category\_id
string

Unique category ID assigned by Voucherify.

Example: cat\_0bb343dee3cdb5ec0c

type
string

Defines the type of the voucher.

Available values: GIFT\_VOUCHER, DISCOUNT\_VOUCHER, LOYALTY\_CARD

discount

See: Discount

gift
object

Object representing gift parameters. Child attributes are present only if type is GIFT\_VOUCHER. Defaults to null.

Attributes	Description
amount `integer`	Total gift card income over the lifetime of the card. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `\$100.00`. Example: 10000
subtracted\_amount `integer`	Total amount of subtracted credits over the gift card lifetime. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `\$100.00`.
balance `integer`	Available funds. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `\$100.00`. Example: 500
effect `string`	Defines how the credits are applied to the customer's order. Available values: `APPLY\_TO\_ORDER`, `APPLY\_TO\_ITEMS`

loyalty\_card
object

Object representing loyalty card parameters. Child attributes are present only if type is LOYALTY\_CARD. Defaults to null.

Attributes	Description
points `integer`	Total number of points added to the loyalty card over its lifespan. Example: 7000
balance `integer`	Points available for reward redemption. This is calculated as follows: `balance` \= `points` \- `expired\_points` \- `subtracted\_points` \- `redemption.redeemed\_points`. Example: 6970
next\_expiration\_date `string`	The next closest date when the next set of points are due to expire. Example: 2023-05-30
next\_expiration\_points `integer`	The amount of points that are set to expire next.
pending\_points `integer`	Shows the number of pending points that will be added to the loyalty card when they are activated automatically or manually.
expired\_points `integer`	Shows the total number of expired points over the lifetime of the loyalty card.
subtracted\_points `integer`	Shows the total number of subtracted points over the lifetime of the loyalty card.

start\_date
string

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

Example: 2021-12-01T00:00:00.000Z

expiration\_date
string

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

Example: 2021-12-31T00:00:00.000Z

validity\_timeframe

See: Validity Timeframe

validity\_day\_of\_week

See: Validity Day Of Week

validity\_hours

See: Validity Hours

active
boolean, null

A flag to toggle the voucher on or off. You can disable a voucher even though it's within the active period defined by the start\_date and expiration\_date.

true indicates an active voucher
false indicates an inactive voucher

additional\_info
string

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

metadata
object

assets

See: Voucher Assets

is\_referral\_code
boolean, null

Flag indicating whether this voucher is a referral code; true for campaign type REFERRAL\_PROGRAM.

created\_at
string

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

Example: 2021-12-22T10:13:06.487Z

updated\_at
string

Timestamp representing the date and time when the voucher was last updated in ISO 8601 format.

Example: 2021-12-22T10:14:45.316Z

holder\_id
string

Unique customer identifier of the redeemable holder. It equals to the customer ID assigned by Voucherify.

Example: cust\_eWgXlBBiY6THFRJwX45Iakv4

referrer\_id
string

Unique identifier of the referring person.

Example: cust\_Vzck5i8U3OhcEUFY6MKhN9Rv

object
string

The type of the object represented by JSON. Default is voucher.

publish
object

Stores a summary of publication events: an event counter and endpoint to return details of each event. Publication is an assignment of a code to a customer, e.g. through a distribution.

Attributes Description

object
string

The type of the object represented is by default list. To get this list, you need to make a call to the endpoint returned in the url attribute.

count
integer

Publication events counter.

Example: 0

url
string

The endpoint where this list of publications can be accessed using a GET method. /v1/vouchers//publications

Example: /v1/vouchers/WVPblOYX/publications?page=1\&limit=10

redemption
object

Stores a summary of redemptions that have been applied to the voucher.

Attributes	Description
quantity `integer`	How many times a voucher can be redeemed. A `null` value means unlimited.
redeemed\_quantity `integer`	How many times a voucher has already been redeemed. Example: 1
redeemed\_points `integer`	Total loyalty points redeemed. Example: 100000
object `string`	The type of the object represented is by default `list`. To get this list, you need to make a call to the endpoint returned in the url attribute.
url `string`	The endpoint where this list of redemptions can be accessed using a GET method. `/v1/vouchers//redemptions` Example: /v1/vouchers/WVPblOYX/redemptions?page=1\&limit=10

Validation Rules Assignments List

Attributes	Description
object `string`	The type of the object represented by JSON. This object stores information about validation rules assignments. Available values: `list`
data\_ref `string`	Identifies the name of the attribute that contains the array of validation rules assignments. Available values: `data`
data `array`	Contains array of validation rules assignments. Array of Business Validation Rule Assignment
total `integer`	Total number of validation rules assignments.

Category

Attributes	Description
id `string`	Unique category ID assigned by Voucherify.
name `string`	Category name.
hierarchy `integer`	Category hierarchy. Categories with lower hierarchy are processed before categories with higher hierarchy value.
object `string`	The type of the object represented by the JSON. This object stores information about the category. Available values: `category`
created\_at `string`	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
updated\_at `string`	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

Discount

Contains information about discount.

One of:

Amount
Unit
Unit Multiple
Percent
Fixed

Validity Timeframe

Attributes Description

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

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

Validity Day Of Week

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

Validity Hours

Attributes Description

daily
array

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

Array of:

Attributes Description

start\_time
string

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

Example: 12:00

days\_of\_week
array

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

expiration\_time
string

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

Example: 14:00

Validation Rule Assignments List

Attributes	Description
object `string`	The type of the object represented by JSON. This object stores information about validation rule assignments.
data\_ref `string`	Identifies the name of the JSON property that contains the array of validation rule assignments.
data `array`	A dictionary that contains an array of validation rule assignments. Array of Validation Rule Assignment
total `integer`	Total number of validation rule assignments.

Voucher

This is an object representing a voucher with categories and validation rules assignments.

All of:

Voucher Base

Attributes	Description
categories `array`	Contains details about the category. Array of Category
validation\_rules\_assignments	See: Validation Rules Assignments List

Product

This is an object representing a product.

This entity should be used to map product items from your inventory management system. The aim of products is to build which reflect product-specific campaigns.

All of:

Product without Skus Object

Attributes	Description
skus	See: Skus List For Product

SKU Object

Attributes	Description
id `string`	A unique identifier that represents the SKU and is assigned by Voucherify. Example: sku\_0b1621b319d248b79f
source\_id `string`, `null`	A unique SKU identifier from your inventory system. Example: sku\_source\_id\_4
product\_id `string`	The parent product's unique ID. Example: prod\_0b15f6b9f650c16990
sku `string`, `null`	Unique user-defined SKU name. Example: Large Pink Shirt
price `integer`, `null`	Unit price. It is represented by a value multiplied by 100 to accurately reflect 2 decimal places, such as `\$100.00` being expressed as `10000`.
currency `string`, `null`	SKU price currency. Example: USD
attributes `object`	The attributes object stores values for all custom attributes inherited by the SKU from the parent product. A set of key/value pairs that are attached to a SKU object and are unique to each SKU within a product family.
image\_url `string`, `null`	The HTTPS URL pointing to the .png or .jpg file that will be used to render the SKU image.
metadata `object`	The metadata object stores all custom attributes assigned to the SKU. A set of key/value pairs that you can attach to a SKU object. It can be useful for storing additional information about the SKU in a structured format. It can be used to create product collections.
created\_at `string`	Timestamp representing the date and time when the SKU was created. The value is shown in the ISO 8601 format. Example: 2022-05-17T10:36:30.187Z
updated\_at `string`, `null`	Timestamp representing the date and time when the SKU was updated. The value is shown in the ISO 8601 format. Example: 2022-05-17T10:55:09.137Z
object `string`	The type of the object represented by JSON. This object stores information about the `SKU`. Available values: `sku`

Voucher Assets

Attributes Description

qr
object

Stores Quick Response (QR) representation of encrypted code.

Attributes Description

id
string

Encrypted voucher code ID.

Example: U2FsdGVkX19ucFhvVmBVpVYG5KoswTsjSIaqoKg5L9ie4BK+t4pp7U7oFzjGJzj9q/bmuMOj9mEFiVKDMIkSaruKedMvHbKoPX5Sg+BaZk5QwXMf8k/OzSlOEVybpwSq+AiqPoNtjeuqtIgkDyvT6Q==

url
string

URL to QR code

Optional: Attach query parameters to base URL to customize the image of the encrypted voucher code.

size : integer value from 1 to 100
format : string, either png (default) or svg

barcode
object

Stores barcode representation of encrypted code.

Attributes Description

id
string

Encrypted voucher code ID.

Example: U2FsdGVkX19eJhGfWwUrH9+tulBkON+AnMktic+N6CVWzZ9+fHVxuVx22WakrzxiWXy0skuvvEHSeZIw9HlgyIJ+kJ1iPdUKpyENuNYJKzoZlO0mmTf6WQM6/pFs61apEn9SJx32ttCF6d3oxKISQQ==

url
string

URL to barcode

Optional: Attach query parameters to base URL to customize the image of the encrypted voucher code.

size : integer value from 1 to 100
format : string, either png (default) or svg

Business Validation Rule Assignment

Attributes	Description
id `string`	The unique identifier for a assignment
rule\_id `string`	The unique identifier for a rule
related\_object\_id `string`	The unique identifier for a related object
related\_object\_type `string`	The type of related object
created\_at `string`	Timestamp representing the date and time when the object was created. The value is shown in the ISO 8601 format. Example: 2022-03-09T11:19:04.819Z
updated\_at `string`	Timestamp representing the date and time when the object was last updated in ISO 8601 format. Example: 2022-03-09T11:19:04.819Z
object `string`	The type of the object represented by JSON. Available values: `validation\_rules\_assignment`
validation\_status `string`	The validation status of the assignment Available values: `VALID`, `PARTIALLY\_VALID`, `INVALID`
validation\_omitted\_rules `array`	The list of omitted rules

Amount

Attributes	Description
type `string`	Defines the type of the voucher. Available values: `AMOUNT`
amount\_off `number`	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.
amount\_off\_formula `string`	Formula used to dynamically calculate the discount.
aggregated\_amount\_limit `integer`	Maximum discount amount per order.
effect	Defines how the discount is applied to the customer's order. Discount Amount Vouchers Effect Types
is\_dynamic `boolean`	Flag indicating whether the discount was calculated using a formula.

Unit

Attributes	Description
type `string`	Discount type. Available values: `UNIT`
unit\_off `integer`	Number of units to be granted a full value discount.
unit\_off\_formula `string`	Formula used to dynamically calculate the number of units.
effect	Defines how the unit is added to the customer's order. Discount Unit Vouchers Effect Types
unit\_type `string`	The product deemed as free, chosen from product inventory (e.g. time, items).
product	Contains information about the product. Simple Product Discount Unit
sku	See: Simple Sku Discount Unit
is\_dynamic `boolean`	Flag indicating whether the discount was calculated using a formula.

Unit Multiple

Attributes Description

type
string

Discount type.

Available values: UNIT

effect
string

Defines how the discount is applied to the customer's order.

Available values: ADD\_MANY\_ITEMS

units
array

Array of One Unit

Percent

Attributes	Description
type `string`	Defines the type of the voucher. Available values: `PERCENT`
percent\_off `number`	The percent discount that the customer will receive.
percent\_off\_formula `string`	Formula used to dynamically calculate the discount.
amount\_limit `number`	Upper limit allowed to be applied as a discount. Value is multiplied by 100 to precisely represent 2 decimal places. For example, a \$6 maximum discount is written as 600.
aggregated\_amount\_limit `integer`	Maximum discount amount per order.
effect	Defines how the discount is applied to the customer's order. Discount Percent Vouchers Effect Types
is\_dynamic `boolean`	Flag indicating whether the discount was calculated using a formula.

Fixed

Attributes	Description
type `string`	Defines the type of the voucher. Available values: `FIXED`
fixed\_amount `number`	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.
fixed\_amount\_formula `string`	Formula used to dynamically calculate the discount.
effect	Defines how the discount is applied to the customer's order. Discount Fixed Vouchers Effect Types
is\_dynamic `boolean`	Flag indicating whether the discount was calculated using a formula.

Validation Rule Assignment

Attributes	Description
id `string`	Validation rule assignment ID. Example: asgm\_74F7QZoYbUoljwQO
rule\_id `string`	Validation rule ID. Example: val\_4j7DCRm2IS59
related\_object\_id `string`	The resource ID to which the validation rule was assigned. Example: v\_JtWunK6jUo7X2qOFj0SyRHq4p9tgENlT
related\_object\_type `string`	The type of resource to which the validation rule was assigned. Available values: `voucher`, `campaign`, `earning\_rule`, `reward\_assignment`, `promotion\_tier`, `distribution`
created\_at `string`	Timestamp representing the date and time when the validation rule assignment was created. The value is shown in the ISO 8601 format. Example: 2022-02-17T08:18:15.085Z
object `string`	The type of the object represented by the ID. Available values: `validation\_rules\_assignment`

Product without Skus Object

Attributes	Description
id `string`	Unique product ID assigned by Voucherify. Example: prod\_0b1da8105693710357
source\_id `string`, `null`	Unique product source ID. Example: productSourceID16
name `string`, `null`	Unique user-defined product name. Example: T-shirt
price `integer`, `null`	Unit price. It is represented by a value multiplied by 100 to accurately reflect 2 decimal places, such as `\$100.00` being expressed as `10000`.
attributes `array`	A list of product attributes whose values you can customize for given SKUs: `\["color","size","ranking"]`. Each child SKU can have a unique value for a given attribute.
metadata `object`	The metadata object stores all custom attributes assigned to the product. A set of key/value pairs that you can attach to a product object. It can be useful for storing additional information about the product in a structured format. It can be used to create product collections.
image\_url `string`, `null`	The HTTPS URL pointing to the .png or .jpg file that will be used to render the product image. Example: [https://images.com/original.jpg](https://images.com/original.jpg)
created\_at `string`	Timestamp representing the date and time when the product was created. The value is shown in the ISO 8601 format. Example: 2022-05-23T06:52:55.008Z
updated\_at `string`, `null`	Timestamp representing the date and time when the product was updated. The value is shown in the ISO 8601 format. Example: 2022-05-23T09:24:07.405Z
object `string`	The type of the object represented by JSON. This object stores information about the product. Available values: `product`

Skus List For Product

Attributes	Description
object `string`	The type of the object represented by JSON. This object stores information about SKUs.
data\_ref `string`	Identifies the name of the JSON property that contains the array of SKUs.
data `array`	A dictionary that contains an array of SKUs. Array of SKU Object
total `integer`	Total number of SKUs in the product.

Discount Amount Vouchers Effect Types

Available values: APPLY\_TO\_ORDER, APPLY\_TO\_ITEMS, APPLY\_TO\_ITEMS\_PROPORTIONALLY, APPLY\_TO\_ITEMS\_PROPORTIONALLY\_BY\_QUANTITY, APPLY\_TO\_ITEMS\_BY\_QUANTITY

Discount Unit Vouchers Effect Types

Available values: ADD\_MISSING\_ITEMS, ADD\_NEW\_ITEMS, ADD\_MANY\_ITEMS, ADD\_SAME\_ITEMS

Simple Product Discount Unit

Attributes	Description
id `string`	Unique product ID, assigned by Voucherify.
source\_id `string`	Product's source ID.
name `string`	Product name.

Simple Sku Discount Unit

Attributes	Description
id `string`	Unique SKU ID, assigned by Voucherify.
source\_id `string`	Product variant's source ID.
name `string`	Sku name

One Unit

Attributes	Description
unit\_off `number`	Number of units to be granted a full value discount.
unit\_off\_formula `string`	Formula used to dynamically calculate the number of units.
effect `string`	Defines how the unit is added to the customer's order. Available values: `ADD\_NEW\_ITEMS`, `ADD\_MISSING\_ITEMS`
unit\_type `string`	The product deemed as free, chosen from product inventory (e.g. time, items).
product	Contains information about the product. Simple Product Discount Unit
sku	Contains information about the sku. Simple Sku Discount Unit

Discount Percent Vouchers Effect Types

Available values: APPLY\_TO\_ORDER, APPLY\_TO\_ITEMS

Discount Fixed Vouchers Effect Types

Available values: APPLY\_TO\_ORDER, APPLY\_TO\_ITEMS

# Add Referral Code Holders Source: https://docs.voucherify.io/api-reference/referrals/add-referral-code-holders /openapi/referrals.json post /v1/referrals/members/{memberId}/holders Adds new holders to a referral code as **referees**. The data sent in the request is upserted into the customer data. If the request returns an error even for one customer, you have to resend the whole request. Customer data is upserted if the data for all customers is correct. To use this endpoint, you must have the following permissions: - Create and modify Customers and Segments (`customers.modify`) - Publish Voucher (`vouchers.publish`) To add a holder as a referrer, use the [Create Publication](/api-reference/publications/create-publication) endpoint. Alternative endpoint This endpoint is an alternative to the [Add Referral Code Holders endpoint](/api-reference/referrals/add-referral-code-holders-with-campaign-id). The URL was re-designed to retrieve the referral member holders without providing the `campaignId` as a path paremeter. # Add Referral Code Holders with Campaign ID Source: https://docs.voucherify.io/api-reference/referrals/add-referral-code-holders-with-campaign-id /openapi/referrals.json post /v1/referrals/{campaignId}/members/{memberId}/holders Adds new holders to a referral code as **referees**. The data sent in the request is upserted into the customer data. If the request returns an error even for one customer, you have to resend the whole request. Customer data is upserted if the data for all customers is correct. To use this endpoint, you must have the following permissions: - Create and modify Customers and Segments (`customers.modify`) - Publish Voucher (`vouchers.publish`) To add a holder as a referrer, use the [Create Publication](/api-reference/publications/create-publication) endpoint. # List Referral Code Holders Source: https://docs.voucherify.io/api-reference/referrals/list-referral-code-holders /openapi/referrals.json get /v1/referrals/members/{memberId}/holders Retrieves the holders of the referral code from a referral campaign. To use this endpoint, you must have the following permissions: - Read Customers (`customers.details.read`) Alternative endpoint This endpoint is an alternative to the [List Member Holders endpoint](/api-reference/referrals/list-referral-code-holders-with-campaign-id). The URL was re-designed to retrieve the referral member holders without providing the `campaignId` as a path paremeter. # List Referral Code Holders with campaign ID Source: https://docs.voucherify.io/api-reference/referrals/list-referral-code-holders-with-campaign-id /openapi/referrals.json get /v1/referrals/{campaignId}/members/{memberId}/holders Retrieves all the redeemables that have been assigned to the customer. To use this endpoint, you must have the following permissions: - Read Customers (`customers.details.read`) # Remove Referral Card Holder Source: https://docs.voucherify.io/api-reference/referrals/remove-referral-card-holder /openapi/referrals.json delete /v1/referrals/members/{memberId}/holders/{holderId} Removes the holder from a referral card. You can remove a referee only. To use this endpoint, you must have the following permissions: - Create and modify Customers and Segments (`customers.modify`) - Publish Voucher (`vouchers.publish`) Alternative endpoint This endpoint is an alternative to the [Remove Referral Card Holder endpoint](/api-reference/referrals/remove-referral-card-holder-with-campaign-id). The URL was re-designed to retrieve the referral member holders without providing the `campaignId` as a path paremeter. # Remove Referral Card Holder with campaign ID Source: https://docs.voucherify.io/api-reference/referrals/remove-referral-card-holder-with-campaign-id /openapi/referrals.json delete /v1/referrals/{campaignId}/members/{memberId}/holders/{holderId} Removes the holder from a referral card. You can remove a referee only. To use this endpoint, you must have the following permissions: - Create and modify Customers and Segments (`customers.modify`) - Publish Voucher (`vouchers.publish`) # Activate reward Source: https://docs.voucherify.io/api-reference/rewards/activate-reward /openapi/loyalties-v2.json post /v2/loyalties/rewards/{rewardId}/activate Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Moves the reward to the ACTIVE status. Allowed from DRAFT or INACTIVE status; other transitions are rejected with a conflict error. This endpoint takes no request body. # Create a reward Source: https://docs.voucherify.io/api-reference/rewards/create-a-reward /openapi/loyalties-v2.json post /v2/loyalties/rewards Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Creates a new reward. `name`, `type` and `costs` are required. When `type` is `MATERIAL` the `material` object is required and `digital` must be null; when `type` is `DIGITAL` the `digital` object is required and `material` must be null. The reward can be created directly in `DRAFT` (default) or `ACTIVE` status. When `validity_hours` is not provided it defaults to `{ "type": "ANY_TIME" }`. # Create Reward Source: https://docs.voucherify.io/api-reference/rewards/create-reward /openapi/rewards.json post /v1/rewards Create a new reward. # Create Reward Assignment Source: https://docs.voucherify.io/api-reference/rewards/create-reward-assignment /openapi/rewards.json post /v1/rewards/{rewardId}/assignments Assigns a reward to a specified loyalty campaign. # Deactivate reward Source: https://docs.voucherify.io/api-reference/rewards/deactivate-reward /openapi/loyalties-v2.json post /v2/loyalties/rewards/{rewardId}/deactivate Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Moves the reward to the INACTIVE status. Allowed only from ACTIVE status; other transitions are rejected with a conflict error. This endpoint takes no request body. # Delete a reward Source: https://docs.voucherify.io/api-reference/rewards/delete-a-reward /openapi/loyalties-v2.json delete /v2/loyalties/rewards/{rewardId} Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Deletes a reward (moves it to the DELETED status). Returns the deleted reward. # Delete Reward Source: https://docs.voucherify.io/api-reference/rewards/delete-reward /openapi/rewards.json delete /v1/rewards/{rewardId} Delete a reward. # Delete Reward Assignment Source: https://docs.voucherify.io/api-reference/rewards/delete-reward-assignment /openapi/rewards.json delete /v1/rewards/{rewardId}/assignments/{assignmentId} This method deletes a reward assignment for a particular reward. # Get Reward Source: https://docs.voucherify.io/api-reference/rewards/get-reward /openapi/rewards.json get /v1/rewards/{rewardId} Retrieve a reward by the reward ID. # Get Reward Assignment Source: https://docs.voucherify.io/api-reference/rewards/get-reward-assignment /openapi/rewards.json get /v1/rewards/{rewardId}/assignments/{assignmentId} Retrieve a reward assignment. # Get reward by ID Source: https://docs.voucherify.io/api-reference/rewards/get-reward-by-id /openapi/loyalties-v2.json get /v2/loyalties/rewards/{rewardId} Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Returns a single reward by its ID. # List reward activities Source: https://docs.voucherify.io/api-reference/rewards/list-reward-activities /openapi/loyalties-v2.json get /v2/loyalties/rewards/{rewardId}/activities Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Returns a cursor-paginated list of activities recorded for the given reward (created, updated, deleted, assigned, unassigned, activated, deactivated, drafted). Returns `404` when the reward does not exist. # List Reward Assignments Source: https://docs.voucherify.io/api-reference/rewards/list-reward-assignments /openapi/rewards.json get /v1/rewards/{rewardId}/assignments Retrieve reward assignments by the reward ID. # List Rewards Source: https://docs.voucherify.io/api-reference/rewards/list-rewards /openapi/rewards.json get /v1/rewards Retrieve rewards. # List rewards v2 Source: https://docs.voucherify.io/api-reference/rewards/list-rewards-v2 /openapi/loyalties-v2.json get /v2/loyalties/rewards Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Returns a cursor-paginated list of rewards. Results can be filtered by id, name, type and created_at, and ordered by created_at or name (ascending or descending). The same field cannot be ordered both ascending and descending at the same time. # Move reward back to draft Source: https://docs.voucherify.io/api-reference/rewards/move-reward-back-to-draft /openapi/loyalties-v2.json post /v2/loyalties/rewards/{rewardId}/draft Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Moves the reward back to the DRAFT status. Allowed only from `ACTIVE` status; other transitions are rejected with a conflict error. The reward can't be assigned to a loyalty program. This endpoint takes no request body. # Reward Assignment Object Source: https://docs.voucherify.io/api-reference/rewards/reward-assignment-object

Reward Assignment

All of:

Reward Assignment Base
Digital or Material Reward - Parameters

Reward Assignment Base

Attributes	Description
id `string`	Unique reward assignment ID, assigned by Voucherify. Example: rewa\_PbIRoMXpwe5QhobW4JKu0VjH
reward\_id `string`	Associated reward ID. Example: rew\_C7wS9eHFDN4CIbXI5PpLSkGY
created\_at `string`	Timestamp representing the date and time when the reward assignment was created. The value is shown in the ISO 8601 format. Example: 2022-08-11T14:49:22.586Z
updated\_at `string`, `null`	Timestamp representing the date and time when the reward assignment was updated. The value is shown in the ISO 8601 format. Example: 2022-08-11T16:01:34.885Z
object `string`	The type of the object represented by the JSON. This object stores information about the reward assignment. Available values: `reward\_assignment`
related\_object\_id `string`	Related object ID to which the reward was assigned. Example: camp\_wciTvaOfYmAa3EmIIW3QpXXZ
related\_object\_type `string`	Related object type to which the reward was assigned. Available values: `campaign`

Digital or Material Reward - Parameters

Attributes Description

parameters
object

Defines the cost of the reward.

Attributes Description

loyalty
object

Defines the equivalent points value of the reward.

Attributes	Description
points `integer`	The number of points required to redeem the reward.
auto\_redeem `boolean`, `null`	Determines if the reward is redeemed automatically when the customer reaches the sufficient number of points to redeem it. Value `true` means that the automatic reward redemption is active. Only one reward can be set to be redeemed automatically in a loyalty campaign, i.e. only one can have the value `true`.

# Reward Object Source: https://docs.voucherify.io/api-reference/rewards/reward-object

Reward

Attributes Description

id
string

Unique reward ID, assigned by Voucherify.

Example: rew\_nIy4gHpQHle2c3pNMwuj7G6j

name
string

Reward name.

stock
integer, null

Configurable for material rewards. The number of units of the product that you want to share as a reward. Use this parameter to code a stock-taking logic.

redeemed
integer, null

Defines the number of already invoked (successful) reward redemptions.

attributes
object

These properties are configurable for material rewards.

Attributes	Description
image\_url `string`	The HTTPS URL pointing to the .png or .jpg file.
description `string`	An arbitrary string that you can attach to a material reward.

metadata
object

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

type
string

Reward type.

Available values: CAMPAIGN, COIN, MATERIAL

parameters

Defines how the reward is generated.

Reward type

created\_at
string

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

Example: 2022-08-11T14:49:22.586Z

updated\_at
string, null

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

Example: 2022-08-11T16:01:34.885Z

object

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

Available values: reward

Reward type

One of:

Digital
Pay with Points
Material

Digital

Attributes Description

campaign
object

Objects stores information about the campaign related to the reward.

Attributes Description

id
string

Unique campaign ID, assigned by Voucherify.

balance
integer

The number of points to be added to a loyalty card or the amount to be added to the current balance on the gift card.

For gift cards, the value is multiplied by 100 to precisely represent 2 decimal places. For example, \$100 amount is written as 10000.

type
string

Campaign type.

Available values: DISCOUNT\_COUPONS, GIFT\_VOUCHERS, LOYALTY\_PROGRAM

Pay with Points

Attributes Description

coin
object

Defines the ratio by mapping the number of loyalty points in points\_ratio to a predefined cash amount in exchange\_ratio.

Attributes	Description
exchange\_ratio `number`	The cash equivalent of the points defined in the points\_ratio property.
points\_ratio `integer`	The number of loyalty points that will map to the predefined cash amount defined by the exchange\_ratio property.

Material

Attributes Description

product
object

Contains information about the product given as a reward.

Attributes Description

id
string

Unique product ID, assigned by Voucherify.

Example: prod\_0b7d7dfb05cbe5c616

sku\_id
string, null

Unique SKU ID, assigned by Voucherify, of the SKU given as a reward.

Example: sku\_0b7d7dfb090be5c619

# Update a reward Source: https://docs.voucherify.io/api-reference/rewards/update-a-reward /openapi/loyalties-v2.json put /v2/loyalties/rewards/{rewardId} Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Updates an existing reward. When `type` is provided as `MATERIAL` the `material` object is required and `digital` must be null; when `type` is provided as `DIGITAL` the `digital` object is required and `material` must be null. In `DRAFT` status all properties can be updated. In `ACTIVE`/`INACTIVE` status only the following properties can be updated: `name`, `metadata`, `refunds`, `validity_hours`, `start_date`, `end_date`, `costs`. # Update Reward Source: https://docs.voucherify.io/api-reference/rewards/update-reward /openapi/rewards.json put /v1/rewards/{rewardId} Update the details of a reward. # Update Reward Assignment Source: https://docs.voucherify.io/api-reference/rewards/update-reward-assignment /openapi/rewards.json put /v1/rewards/{rewardId}/assignments/{assignmentId} Update the number of points needed to successfully redeem the reward. # Create Segment Source: https://docs.voucherify.io/api-reference/segments/create-segment /openapi/segments.json post /v1/segments Create a customer segment. Limit on static segments There is a cap on the number of customers that you can assign to a static segment: **20,000**. If you would like to create a bigger segment, then you can use the unlimited `auto-update` or `passive` segment instead and use some customer metadata to build this segment. Limit on Active and Passive segments You can create a maximum of 100 passive and active segments. # Delete Segment Source: https://docs.voucherify.io/api-reference/segments/delete-segment /openapi/segments.json delete /v1/segments/{segmentId} This method deletes a customer segment. # Get Segment Source: https://docs.voucherify.io/api-reference/segments/get-segment /openapi/segments.json get /v1/segments/{segmentId} Retrieves the segment with a given segment ID. This method doesn't return the customers that belong to the segment. To return a list of customers who belong to a segment, use [GET List customers](/api-reference/customers/list-customers) endpoint with the `segment_id` query parameter. # List segments Source: https://docs.voucherify.io/api-reference/segments/list-segments /openapi/segments.json get /v1/segments Retrieves a list of segments. The list doesn't include the customers that belong to respective segments. To return a list of customers who belong to a segment, use [GET List customers](/api-reference/customers/list-customers) endpoint with the `segment_id` query parameter. To return a list of different results, use the `filters[created_at][conditions][$before]` and `filters[created_at][conditions][$after]` query parameters as pagination. # Segment Object Source: https://docs.voucherify.io/api-reference/segments/segment-object

Segment

Attributes	Description
id `string`	Unique segment ID. Example: seg\_1wc52c5z6r1kQ81brO8j9Hk2
name `string`	Segment name.
created\_at `string`	Timestamp representing the date and time when the segment was created. The value is shown in the ISO 8601 format. Example: 2022-05-12T13:01:56.896Z
updated\_at `string`	Timestamp in ISO 8601 format indicating when the segment was updated. Example: 2022-10-03T12:24:58.008Z
type `string`	Defines whether the segment is: Active ( `auto-update` ): customers enter and leave the segment based on the defined filters and the `customer.segment.entered` and `customer.segment.left` events are triggered, Passive ( `passive` ): customers enter and leave the segment based on the defined filters, but the `customer.segment.entered` and `customer.segment.left` events are not triggered, Static ( `static` ): manually selected customers. Available values: `auto-update`, `passive`, `static`
filter `object`, `null`	Defines a set of criteria for an `auto-update` or `passive` segment type.
object `string`	The type of the object represented by JSON. This object stores information about the customer segment. Available values: `segment`

# Add Promotion Tier From Template Source: https://docs.voucherify.io/api-reference/templates/add-promotion-tier-from-template /openapi/templates.json post /v1/templates/campaigns/{campaignTemplateId}/tier-setup Creates a promotion tier out of a discount campaign template and adds it to an existing promotion campaign. To add a promotion tier to a campaign, you need to provide the name in the request and the campaign ID. Other fields are optional. If no other fields are sent, the configuration from the template will be used. You can send new values of the fields listed below to replace the settings saved in the template. However, you cannot assign an action or an existing validation rule or create a new one in the request. If the template has a validation rule, a new validation rule is always created for the promotion tier. When the promotion tier has been created, then you can: - [Update the validation rule](/api-reference/validation-rules/update-validation-rule), - [Unassign the validation rule](/api-reference/validation-rules/delete-validation-rule-assignment), - [Assign an existing validation rule](/api-reference/validation-rules/create-validation-rule-assignment). Promotion Tiers and Campaign Templates You can create a campaign template out of a promotion tier. Promotion tiers are converted to a discount campaign with the `DISCOUNT_COUPON` type. You can use this template to create: - [Discount campaign](/api-reference/templates/create-campaign-from-template) - [Promotion tier](/api-reference/templates/add-promotion-tier-from-template) Campaign Templates – Documentation Read the [Campaign Templates documentation](/build/campaign-templates) to learn more about this feature. # Create Campaign From Template Source: https://docs.voucherify.io/api-reference/templates/create-campaign-from-template /openapi/templates.json post /v1/templates/campaigns/{campaignTemplateId}/campaign-setup Creates a campaign out of a campaign template. To create a campaign, you need to provide the name in the request, while other fields are optional. If no other fields are sent, the configuration from the template will be used. You can send new values of the fields listed below to replace the settings saved in the template. However, you cannot assign an existing validation rule or create a new one in the request. If the template has a validation rule, a new validation rule is always created for the campaign. When the campaign has been created, then you can: - [Update the validation rule](/api-reference/validation-rules/update-validation-rule), - [Unassign the validation rule](/api-reference/validation-rules/delete-validation-rule-assignment), - [Assign an existing validation rule](/api-reference/validation-rules/create-validation-rules-assignments). Promotion Tiers and Campaign Templates You can create a campaign template out of a promotion tier. Promotion tiers are converted to a discount campaign with the `DISCOUNT_COUPON` type. You can use this template to create: - [Discount campaign](/api-reference/templates/create-campaign-from-template) - [Promotion tier](/api-reference/templates/add-promotion-tier-from-template) Campaign Templates – Documentation Read the [Campaign Templates documentation](/build/campaign-templates) to learn more about this feature. # Create Campaign Template Source: https://docs.voucherify.io/api-reference/templates/create-campaign-template /openapi/templates.json post /v1/templates/campaigns Creates a template for a discount or gift campaign, or a promotion tier. A template stores campaign configuration **without** the following details: - Campaign name - Category - Code count The following elements are not supported by campaign templates: - Redeeming API keys - Redeeming users - Customer loyalty tier - Static segments Promotion Tiers and Campaign Templates You can create a campaign template out of a promotion tier. Promotion tiers are converted to a discount campaign with the `DISCOUNT_COUPON` type. You can use this template to create: - [Discount campaign](/api-reference/templates/create-campaign-from-template), - [Promotion tier](/api-reference/templates/add-promotion-tier-from-template). Campaign Templates – Documentation Read the [Campaign Templates documentation](/build/campaign-templates) to learn more about this feature. # Delete Campaign Template Source: https://docs.voucherify.io/api-reference/templates/delete-campaign-template /openapi/templates.json delete /v1/templates/campaigns/{campaignTemplateId} Deletes the campaign template permanently. Campaign Templates – Documentation Read the [Campaign Templates documentation](/build/campaign-templates) to learn more about this feature. # Get Campaign Template Source: https://docs.voucherify.io/api-reference/templates/get-campaign-template /openapi/templates.json get /v1/templates/campaigns/{campaignTemplateId} Retrieves a campaign template available in the project. Campaign Templates – Documentation Read the [Campaign Templates documentation](/build/campaign-templates) to learn more about this feature. # List Campaign Templates Source: https://docs.voucherify.io/api-reference/templates/list-campaign-templates /openapi/templates.json get /v1/templates/campaigns Lists all campaign templates available in the project. Campaign Templates – Documentation Read the [Campaign Templates documentation](/build/campaign-templates) to learn more about this feature. # Update Campaign Template Source: https://docs.voucherify.io/api-reference/templates/update-campaign-template /openapi/templates.json put /v1/templates/campaigns/{campaignTemplateId} Updates the name or description of the campaign template. Campaign Templates – Documentation Read the [Campaign Templates documentation](/build/campaign-templates) to learn more about this feature. # Activate tier structure Source: https://docs.voucherify.io/api-reference/tier-structures/activate-tier-structure /openapi/loyalties-v2.json post /v2/loyalties/tier-structures/{tierStructureId}/activate Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Moves the tier structure to the `ACTIVE` status. Allowed state transitions: `DRAFT` -> `ACTIVE` and `INACTIVE` -> `ACTIVE`. No request body. # Create tier Source: https://docs.voucherify.io/api-reference/tier-structures/create-tier /openapi/loyalties-v2.json post /v2/loyalties/tier-structures/{tierStructureId}/tiers Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Creates a tier within the tier structure. If `downgrade` is omitted it defaults to `{ "type": "INHERIT" }`. A tier structure can hold at most 10 tiers. # Create tier structure Source: https://docs.voucherify.io/api-reference/tier-structures/create-tier-structure /openapi/loyalties-v2.json post /v2/loyalties/tier-structures Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Creates a new tier structure. Depending on `type`, either `point_balance` (for `POINT_BALANCE`) or `point_earned` (for `POINT_EARNED`) is required and the other must be null/omitted. If `expiration` is omitted it defaults to `{ "type": "NO_RETENTION" }`; if `downgrade` is omitted it defaults to `{ "type": "NO_DOWNGRADE" }`; if `status` is omitted it defaults to `DRAFT`. # Deactivate tier structure Source: https://docs.voucherify.io/api-reference/tier-structures/deactivate-tier-structure /openapi/loyalties-v2.json post /v2/loyalties/tier-structures/{tierStructureId}/deactivate Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Moves the tier structure to the `INACTIVE` status. Allowed state transition: `ACTIVE` -> `INACTIVE`. No request body. # Delete tier Source: https://docs.voucherify.io/api-reference/tier-structures/delete-tier /openapi/loyalties-v2.json delete /v2/loyalties/tier-structures/{tierStructureId}/tiers/{tierId} Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Deletes a tier from the tier structure and returns the deleted resource. # Delete tier structure Source: https://docs.voucherify.io/api-reference/tier-structures/delete-tier-structure /openapi/loyalties-v2.json delete /v2/loyalties/tier-structures/{tierStructureId} Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Deletes a tier structure and returns the deleted resource. # Get tier structure Source: https://docs.voucherify.io/api-reference/tier-structures/get-tier-structure /openapi/loyalties-v2.json get /v2/loyalties/tier-structures/{tierStructureId} Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Returns a single tier structure by its id. # List tier structure activities Source: https://docs.voucherify.io/api-reference/tier-structures/list-tier-structure-activities /openapi/loyalties-v2.json get /v2/loyalties/tier-structures/{tierStructureId}/activities Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Returns a cursor-paginated list of activities recorded for the tier structure (creation, updates, state transitions, assignments, and nested tier changes). The same field cannot be requested in both ascending and descending order at once. Default order is `-created_at`. # List tier structures Source: https://docs.voucherify.io/api-reference/tier-structures/list-tier-structures /openapi/loyalties-v2.json get /v2/loyalties/tier-structures Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Returns a cursor-paginated list of tier structures. The same field cannot be requested in both ascending and descending order at once. Default order is `-created_at`. # List tiers Source: https://docs.voucherify.io/api-reference/tier-structures/list-tiers /openapi/loyalties-v2.json get /v2/loyalties/tier-structures/{tierStructureId}/tiers Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Returns a cursor-paginated list of tiers belonging to the tier structure. This endpoint does not support a `filters` parameter. The same field cannot be requested in both ascending and descending order at once. Default order is `-created_at`. # Move tier structure to draft Source: https://docs.voucherify.io/api-reference/tier-structures/move-tier-structure-to-draft /openapi/loyalties-v2.json post /v2/loyalties/tier-structures/{tierStructureId}/draft Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Moves the tier structure back to the `DRAFT` status. Allowed state transition: `ACTIVE` -> `DRAFT`. No request body. # Update tier Source: https://docs.voucherify.io/api-reference/tier-structures/update-tier /openapi/loyalties-v2.json put /v2/loyalties/tier-structures/{tierStructureId}/tiers/{tierId} Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Updates a tier within the tier structure. All properties are optional. When the parent tier structure is not in `DRAFT` status, only `name` and `metadata` may be updated. # Update tier structure Source: https://docs.voucherify.io/api-reference/tier-structures/update-tier-structure /openapi/loyalties-v2.json put /v2/loyalties/tier-structures/{tierStructureId} Documentation in progress This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager. Updates a tier structure. All properties are optional; provided values are merged with the existing tier structure. When `type` is provided as `POINT_EARNED`, `point_earned` is required and `point_balance` must be null; when `type` is `POINT_BALANCE`, `point_balance` is required and `point_earned` must be null. When the tier structure is not in `DRAFT` status, only `name` and `metadata` may be updated; attempting to update other properties results in a validation error. # Assignment Created Source: https://docs.voucherify.io/api-reference/validation-rules/assignment-created openapi-events/events-bus_val_rule.json webhook EVENTS.BUS_VAL_RULE.ASSIGNMENT.CREATED The `EVENTS.BUS_VAL_RULE.ASSIGNMENT.CREATED` event indicates that a business validation rule has been assigned. A business validation rule can be assigned to a: * Campaign, * Voucher code, * Promotion tier, * Earning rule, * Or any other entity that can be associated with a validation rule within Voucherify. This event is used in a webhook configured in Project settings in Voucherify dashboard. This page documents only the event. If you need more details about the webhook payload data that includes this event, go to [Introduction to webhooks](/api-reference/introduction-to-webhooks "Introduction to webhooks v2024-01-01") page. # Assignment Deleted Source: https://docs.voucherify.io/api-reference/validation-rules/assignment-deleted openapi-events/events-bus_val_rule.json webhook EVENTS.BUS_VAL_RULE.ASSIGNMENT.DELETED The `EVENTS.BUS_VAL_RULE.ASSIGNMENT.DELETED` event indicates that a business validation rule has been successfully unassigned. This event is used in a webhook configured in Project settings in Voucherify dashboard. This page documents only the event. If you need more details about the webhook payload data that includes this event, go to [Introduction to webhooks](/api-reference/introduction-to-webhooks "Introduction to webhooks v2024-01-01") page. # Create Validation Rules Source: https://docs.voucherify.io/api-reference/validation-rules/create-validation-rules /openapi/validation-rules.json post /v1/validation-rules Create a validation rule. Managing validation rules It is recommended to [create or update validation rules](/personalize/create-validation-rules) in the Voucherify dashboard. The rule builder in the dashboard helps configuring the desired conditions in a convenient way. The API should not be used as a preferable way to create and manage validation rules. # Create Validation Rules Assignments Source: https://docs.voucherify.io/api-reference/validation-rules/create-validation-rules-assignments /openapi/validation-rules.json post /v1/validation-rules/{validationRuleId}/assignments Assign validation rule to either one of the following objects: voucher, campaign, promotion tier, earning rule, reward, distribution. # Created Source: https://docs.voucherify.io/api-reference/validation-rules/created openapi-events/events-bus_val_rule.json webhook EVENTS.BUS_VAL_RULE.CREATED The `EVENTS.BUS_VAL_RULE.CREATED` event indicates that a new business validation rule has been successfully created in Voucherify. This event provides, among others, the following details about the newly created rule: * ID, * Conditions, * Logic. This event is used in a webhook configured in Project settings in Voucherify dashboard. This page documents only the event. If you need more details about the webhook payload data that includes this event, go to [Introduction to webhooks](/api-reference/introduction-to-webhooks "Introduction to webhooks v2024-01-01") page. # Delete Validation Rule Source: https://docs.voucherify.io/api-reference/validation-rules/delete-validation-rule /openapi/validation-rules.json delete /v1/validation-rules/{validationRuleId} This method deletes a validation rule. # Delete Validation Rule Assignment Source: https://docs.voucherify.io/api-reference/validation-rules/delete-validation-rule-assignment /openapi/validation-rules.json delete /v1/validation-rules/{validationRuleId}/assignments/{assignmentId} This method deletes a validation rule assignment. # Deleted Source: https://docs.voucherify.io/api-reference/validation-rules/deleted openapi-events/events-bus_val_rule.json webhook EVENTS.BUS_VAL_RULE.DELETED The `EVENTS.BUS_VAL_RULE.DELETED` event indicates that a business validation rule has been successfully deleted from Voucherify. This event is used in a webhook configured in Project settings in Voucherify dashboard. This page documents only the event. If you need more details about the webhook payload data that includes this event, go to [Introduction to webhooks](/api-reference/introduction-to-webhooks "Introduction to webhooks v2024-01-01") page. # Get Validation Rule Source: https://docs.voucherify.io/api-reference/validation-rules/get-validation-rule /openapi/validation-rules.json get /v1/validation-rules/{validationRuleId} Retrieve the details of a validation rule. # List Validation Rule Assignments Source: https://docs.voucherify.io/api-reference/validation-rules/list-validation-rule-assignments /openapi/validation-rules.json get /v1/validation-rules/{validationRuleId}/assignments Retrieve validation rule assignments for a specific validation rule. # List Validation Rules Source: https://docs.voucherify.io/api-reference/validation-rules/list-validation-rules /openapi/validation-rules.json get /v1/validation-rules Retrieve validation rules. # List Validation Rules' Assignment(s) Source: https://docs.voucherify.io/api-reference/validation-rules/list-validation-rules-assignments /openapi/validation-rules.json get /v1/validation-rules-assignments List all validation rules' assignments or filter the results using the related object ID or the validation rule ID query parameters. # Update Validation Rule Source: https://docs.voucherify.io/api-reference/validation-rules/update-validation-rule /openapi/validation-rules.json put /v1/validation-rules/{validationRuleId} Update validation rule parameters. Managing validation rules It is recommended to [create or update validation rules](/personalize/create-validation-rules) in the Voucherify dashboard. The rule builder in the dashboard helps configuring the desired conditions in a convenient way. The API should not be used as a preferable way to create and manage validation rules. # Updated Source: https://docs.voucherify.io/api-reference/validation-rules/updated openapi-events/events-bus_val_rule.json webhook EVENTS.BUS_VAL_RULE.UPDATED The `EVENTS.BUS_VAL_RULE.UPDATED` event indicates that an existing business validation rule has been successfully modified. The event provides the details about the business validation rule with the changes included. This event is used in a webhook configured in Project settings in Voucherify dashboard. This page documents only the event. If you need more details about the webhook payload data that includes this event, go to [Introduction to webhooks](/api-reference/introduction-to-webhooks "Introduction to webhooks v2024-01-01") page. # Validation Rule Assignment Object Source: https://docs.voucherify.io/api-reference/validation-rules/validation-rule-assignment-object

Validation Rule Assignment

Attributes	Description
id `string`	Validation rule assignment ID. Example: asgm\_74F7QZoYbUoljwQO
rule\_id `string`	Validation rule ID. Example: val\_4j7DCRm2IS59
related\_object\_id `string`	The resource ID to which the validation rule was assigned. Example: v\_JtWunK6jUo7X2qOFj0SyRHq4p9tgENlT
related\_object\_type `string`	The type of resource to which the validation rule was assigned. Available values: `voucher`, `campaign`, `earning\_rule`, `reward\_assignment`, `promotion\_tier`, `distribution`
created\_at `string`	Timestamp representing the date and time when the validation rule assignment was created. The value is shown in the ISO 8601 format. Example: 2022-02-17T08:18:15.085Z
object `string`	The type of the object represented by the ID. Available values: `validation\_rules\_assignment`

# Validation Rule Object Source: https://docs.voucherify.io/api-reference/validation-rules/validation-rule-object

Validation Rule

All of:

Validation Rule Base

Validation Rule

Attributes	Description
id `string`	Unique validation rule ID. Example: val\_eR1c41hu0vUU
created\_at `string`	Timestamp representing the date and time when the validation rule was created. The value is shown in the ISO 8601 format. Example: 2022-03-23T07:44:00.444Z
updated\_at `string`	Timestamp representing the date and time when the validation rule was updated. The value is shown in the ISO 8601 format. Example: 2022-04-26T08:35:54.960Z
assignments\_count `integer`	The number of instances the validation rule has been assigned to different types of redeemables.
object `string`	The type of the object represented by JSON. This object stores information about the validation rule.

Validation Rule Base

Attributes Description

name
string

Custom, unique name for set of validation rules.

Example: Business Validation Rule

rules

See: Validation Rule Rules

bundle\_rules

See: Validation Rule Bundle Rules

error
object

Contains the error message returned from API when validation / redemption fails to meet requirements of defined rules.

Attributes	Description
message `string`	The error message returned from API when validation / redemption fails to meet requirements of defined rules.

applicable\_to
object

Attributes	Description
excluded `array`	Defines which items are excluded from a discount. Array of Applicable To
included `array`	Defines which items are included in a discount. Array of Applicable To
included\_all `boolean`	Indicates whether all items are included in the discount.

type
string

Type of validation rule.

Available values: expression, basic, advanced, complex

context\_type
string

Validation rule context type.

Context Type	Definition
earning\_rule.order.paid
earning\_rule.custom\_event
earning\_rule.customer.segment.entered
campaign.discount\_coupons
campaign.discount\_coupons.discount.apply\_to\_order
campaign.discount\_coupons.discount.apply\_to\_items
campaign.discount\_coupons.discount.apply\_to\_items\_proportionally
campaign.discount\_coupons.discount.apply\_to\_items\_proportionally\_by\_quantity
campaign.discount\_coupons.discount.fixed.apply\_to\_items
campaign.gift\_vouchers
campaign.gift\_vouchers.gift.apply\_to\_order
campaign.gift\_vouchers.gift.apply\_to\_items
campaign.referral\_program
campaign.referral\_program.discount.apply\_to\_order
campaign.referral\_program.discount.apply\_to\_items
campaign.referral\_program.discount.apply\_to\_items\_proportionally
campaign.referral\_program.discount.apply\_to\_items\_proportionally\_by\_quantity
campaign.referral\_program.discount.fixed.apply\_to\_items
campaign.promotion
campaign.promotion.discount.apply\_to\_order
campaign.promotion.discount.apply\_to\_items
campaign.promotion.discount.apply\_to\_items\_proportionally
campaign.promotion.discount.apply\_to\_items\_proportionally\_by\_quantity
campaign.promotion.discount.fixed.apply\_to\_items
campaign.loyalty\_program
voucher.discount\_voucher
voucher.discount\_voucher.discount.apply\_to\_order
voucher.discount\_voucher.discount.apply\_to\_items
voucher.discount\_voucher.discount.apply\_to\_items\_proportionally
voucher.discount\_voucher.discount.apply\_to\_items\_proportionally\_by\_quantity
voucher.discount\_voucher.discount.fixed.apply\_to\_items
voucher.gift\_voucher
voucher.gift\_voucher.gift.apply\_to\_order
voucher.gift\_voucher.gift.apply\_to\_items
voucher.loyalty\_card
distribution.custom\_event
reward\_assignment.pay\_with\_points
global

Available values: earning\_rule.order.paid, earning\_rule.custom\_event, earning\_rule.customer.segment.entered, earning\_rule.customer.tier.joined, earning\_rule.customer.tier.left, earning\_rule.customer.tier.upgraded, earning\_rule.customer.tier.downgraded, earning\_rule.customer.tier.prolonged, campaign.discount\_coupons, campaign.discount\_coupons.discount.apply\_to\_order, campaign.discount\_coupons.discount.apply\_to\_items, campaign.discount\_coupons.discount.apply\_to\_items\_proportionally, campaign.discount\_coupons.discount.apply\_to\_items\_proportionally\_by\_quantity, campaign.discount\_coupons.discount.apply\_to\_items\_by\_quantity, campaign.discount\_coupons.discount.fixed.apply\_to\_items, campaign.discount\_coupons.discount.percent.apply\_to\_items, campaign.gift\_vouchers, campaign.gift\_vouchers.gift.apply\_to\_order, campaign.gift\_vouchers.gift.apply\_to\_items, campaign.referral\_program, campaign.referral\_program.discount.apply\_to\_order, campaign.referral\_program.discount.apply\_to\_items, campaign.referral\_program.discount.apply\_to\_items\_proportionally, campaign.referral\_program.discount.apply\_to\_items\_proportionally\_by\_quantity, campaign.referral\_program.discount.apply\_to\_items\_by\_quantity, campaign.referral\_program.discount.fixed.apply\_to\_items, campaign.referral\_program.discount.percent.apply\_to\_items, campaign.promotion, campaign.promotion.discount.apply\_to\_order, campaign.promotion.discount.apply\_to\_items, campaign.promotion.discount.apply\_to\_items\_proportionally, campaign.promotion.discount.apply\_to\_items\_proportionally\_by\_quantity, campaign.promotion.discount.apply\_to\_items\_by\_quantity, campaign.promotion.discount.fixed.apply\_to\_items, campaign.promotion.discount.percent.apply\_to\_items, campaign.loyalty\_program, voucher.discount\_voucher, voucher.discount\_voucher.discount.apply\_to\_order, voucher.discount\_voucher.discount.apply\_to\_items, voucher.discount\_voucher.discount.apply\_to\_items\_proportionally, voucher.discount\_voucher.discount.apply\_to\_items\_proportionally\_by\_quantity, voucher.discount\_voucher.discount.apply\_to\_items\_by\_quantity, voucher.discount\_voucher.discount.fixed.apply\_to\_items, voucher.discount\_voucher.discount.percent.apply\_to\_items, voucher.gift\_voucher, voucher.gift\_voucher.gift.apply\_to\_order, voucher.gift\_voucher.gift.apply\_to\_items, voucher.loyalty\_card, distribution.custom\_event, distribution.order.paid, distribution.order.created, distribution.order.canceled, distribution.order.updated, reward\_assignment.pay\_with\_points, global

Validation Rule Rules

Attributes Description

logic
string

Defines the logic between the rules.

Example: (1 and 2) and (3)

\[propertyName]
object

Contains the name of the validation rule.

Attributes Description

name
string

Voucherify's specific rule name. Read Validation rule reference to learn how specific rules work. The list of available names is provided below.

Type	Name
Customer	customer.segment customer.metadata\*
Order	order.amount order.total\_amount order.initial\_amount order.items.count order.items.price\_any order.items.price\_each order.items.metadata\_any order.items.metadata\_each order.metadata\*
Campaign	campaign.orders.amount\_discounted campaign.orders.amount campaign.redemptions.count campaign.redemptions.count.daily campaign.redemptions.count.weekly campaign.redemptions.count.monthly campaign.redemptions.customers\_count campaign.redemptions.customers\_count.daily campaign.redemptions.customers\_count.weekly campaign.redemptions.customers\_count.monthly
Redemption	redemption.gift.amount redemption.count.daily redemption.count.weekly redemption.count.monthly redemption.count.per\_customer redemption.count.per\_customer.daily redemption.count.per\_customer.weekly redemption.count.per\_customer.monthly redemption.api\_key redemption.count.per\_api\_key redemption.user.login redemption.count.per\_user redemption.metadata redemption.reward.pay\_with\_points.points\_used
Product	product.id product.price product.quantity product.discount\_applicable product.metadata\* product.metadata.aggregated\_quantity product.metadata.aggregated\_amount product.metadata.discount\_applicable product.metadata.match\_all
SKU	sku.id sku.price sku.quantity sku.discount\_applicable
Publication	publication.redeemable\_by\_linked\_customer
Custom Event	custom\_event.metadata\*
Order items	order.items.every order.items.any order.items.none order.items.cheapest order.items.most\_expensive

\*Requires the property field to be defined.

property
string, null

Custom name for a metadata property associated with the condition to be satisfied. Required if the property name is any of the following:
customer\_metadata
custom\_event\_metadata
order\_items\_metadata
order\_metadata
product\_metadata
redemption\_metadata

conditions

See: Validation Rule Conditions

rules

See: Validation Rule Rules

error
object

Contains the error message returned from API when validation / redemption fails to meet requirements of defined rule.

Attributes	Description
message `string`	The error message returned from API when validation / redemption fails to meet requirements of defined rule.

Validation Rule Bundle Rules

Attributes Description

limit
integer, null

Defines how many bundles can be identified in the order and the maximum multiplier of the discount per identified bundle. For example, if the order meets 3 bundles, but limit: 2, the discount will be multiplied by 2.

\[propertyName]
object

Contains the name of the bundle rule.

Attributes Description

name
string

Voucherify's specific bundle rule name. Currently, it is only order.items.any.

Available values: order.items.any

conditions
object

Defines the conditions of the bundle rule. The order items in the customer's cart must meet the conditions. Because the rule concerns order items, the only permissible condition is \$is.

Attributes Description

\$is
array

Array of:

Attributes Description

id
string

Unique identifier of the product, SKU, or collection assigned by Voucherify.

type
string

Type of the order item. It can be a product\_or\_sku or products\_collection

Available values: product\_or\_sku, products\_collection

object
string

Object used in the bundle rule. It can be a products\_collection, product, or sku.

Available values: products\_collection, product, sku

rules

error
object

CURRENTLY UNSUPPORTED. Contains the error message returned from API when validation / redemption fails to meet requirements of defined rule.

Attributes	Description
message `string`	The error message returned from API when validation / redemption fails to meet requirements of defined rule.

Applicable To

Attributes Description

object
string

This object stores information about the resource to which the discount is applicable.

Available values: product, sku, products\_collection

id
string

Unique product collection, product, or SKU identifier assigned by Voucherify.

source\_id
string

The source identifier from your inventory system.

product\_id
string

Parent product's unique ID assigned by Voucherify.

product\_source\_id
string

Parent product's source ID from your inventory system.

price
number

price\_formula
number

Formula used to dynamically calculate the discounted price of an item.

effect

Defines how the discount is applied to the customer's order.

Applicable To Effect

quantity\_limit
integer

The maximum number of units allowed to be discounted per order line item.

aggregated\_quantity\_limit
integer

The maximum number of units allowed to be discounted combined across all matched order line items.

amount\_limit
integer

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
integer

APPLY\_TO\_ITEMS (each item subtotal is discounted equally)
APPLY\_TO\_ITEMS\_BY\_QUANTITY (each unit of matched products has the same discount value)