{
"openapi": "3.0.1",
"info": {
"title": "Voucherify API - Client-side",
"version": "v2018-08-01",
"description": "Voucherify promotion engine REST API. Please see https://docs.voucherify.io/docs for more details.",
"contact": {
"name": "Voucherify Team",
"url": "https://www.voucherify.io/contact-support",
"email": "support@voucherify.io"
},
"termsOfService": "https://www.voucherify.io/legal/subscription-agreement",
"license": {
"name": "MIT",
"url": "https://github.com/voucherifyio/voucherify-js-sdk/blob/main/LICENSE"
}
},
"servers": [
{
"url": "https://{cluster}.voucherify.io",
"description": "Base URL",
"variables": {
"cluster": {
"default": "api",
"enum": [
"api",
"us1.api",
"as1.api",
"download",
"us1.download",
"as1.download"
]
}
}
}
],
"paths": {
"/client/v1/qualifications": {
"post": {
"operationId": "check-eligibility-client-side",
"tags": [
"Client-side"
],
"summary": "Check Eligibility (client-side)",
"description": "Generate a list of redeemables that are applicable in the context of the customer and order.\n\nThe 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:\n\n- Qualification results are returned faster\n- No limit on the number of returned redeemables\n- Introduces new qualification scenarios, not available in the previous version\n\n\n\nScenario Guide\n\nRead our dedicated guide to learn about some use cases this endpoint can cover [here](/guides/checking-eligibility).\n\n\n\n## Paging \n\nThe 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.\n\nTo process of paging the redeemables works in the following manner:\n\n- You send the first API request for Qualifications without the `starting_after` parameter.\n- The response will contain a parameter named `has_more`. If the parameter's value is set to `true`, then more redeemables are available.\n- 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.\n- 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.\n- Voucherify will return the next page of redeemables.\n- If the `has_more` parameter is set to `true`, apply steps 3-5 to get the next page of redeemables.\n\n## Caching\n\nQualification 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.",
"parameters": [],
"security": [
{
"X-Client-Application-Id": [],
"X-Client-Token": []
},
{
"X-Voucherify-OAuth": [
"client_api",
"client_qualifications"
]
}
],
"requestBody": {
"description": "Define order and customer context.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ClientQualificationsCheckEligibilityRequestBody"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Returns a qualifications object.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ClientQualificationsCheckEligibilityResponseBody"
}
}
}
}
}
}
},
"/client/v1/promotions/tiers": {
"get": {
"operationId": "list-promotion-tiers-client-side",
"tags": [
"Client-side"
],
"summary": "List Promotion Tiers (client-side)",
"description": "This method enables you to list promotion tiers.",
"parameters": [
{
"schema": {
"$ref": "#/components/schemas/ParameterBoolean"
},
"in": "query",
"name": "is_available",
"description": "This parameter allows filtering promotions that are only available at the moment. When set to `true`, it selects only non-expired and active promotions."
},
{
"schema": {
"$ref": "#/components/schemas/ParameterLimit"
},
"in": "query",
"name": "limit",
"description": "Limits the number of objects to be returned. The limit can range between 1 and 100 items."
},
{
"schema": {
"$ref": "#/components/schemas/ParameterInteger"
},
"in": "query",
"description": "Which page of results to return. The lowest value is `1`.",
"name": "page"
},
{
"schema": {
"$ref": "#/components/schemas/ParameterOrderListPromotionTiersClientSide"
},
"in": "query",
"name": "order",
"description": "Sorts the results using one of the filtering options, where the dash `-` preceding a sorting option means sorting in a descending order."
},
{
"$ref": "#/components/parameters/origin"
}
],
"security": [
{
"X-Client-Application-Id": [],
"X-Client-Token": []
},
{
"X-Voucherify-OAuth": [
"client_api",
"client_promotions"
]
}
],
"responses": {
"200": {
"description": "Returns a dictionary with a `tiers` property that contains an array of promotion tiers.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ClientPromotionsTiersListResponseBody"
},
"examples": {
"Example": {
"value": {
"object": "list",
"data_ref": "tiers",
"tiers": [
{
"id": "promo_NzjTc3ZXTe7md5SziK3uYtei",
"created_at": "2022-09-21T11:38:34.962Z",
"name": "Order more than $100",
"banner": "Order more than $100",
"action": {
"discount": {
"type": "AMOUNT",
"amount_off": 3000,
"effect": "APPLY_TO_ORDER"
}
},
"metadata": {},
"hierarchy": 1,
"promotion_id": "camp_VEL7UX0jZjrvLx3hfNZBVzpq",
"campaign": {
"id": "camp_VEL7UX0jZjrvLx3hfNZBVzpq",
"start_date": "2022-09-21T00:00:00.000Z",
"expiration_date": "2022-09-30T00:00:00.000Z",
"validity_timeframe": {
"interval": "P3D",
"duration": "P2D"
},
"validity_day_of_week": [
1,
2,
3,
4,
5
],
"active": true,
"category_id": "cat_0bb81a481615a37b5e",
"object": "campaign"
},
"campaign_id": "camp_VEL7UX0jZjrvLx3hfNZBVzpq",
"active": true,
"start_date": "2022-09-21T00:00:00.000Z",
"expiration_date": "2022-09-30T00:00:00.000Z",
"validity_timeframe": {
"interval": "P3D",
"duration": "P2D"
},
"validity_day_of_week": [
1,
2
],
"summary": {
"redemptions": {
"total_redeemed": 0
},
"orders": {
"total_amount": 0,
"total_discount_amount": 0
}
},
"object": "promotion_tier",
"validation_rule_assignments": null
},
{
"id": "promo_RaYHtUBre5jU8frUXOvYBtlN",
"created_at": "2021-12-15T11:34:01.358Z",
"updated_at": "2022-02-09T09:20:08.619Z",
"name": "Hot Promotion - Tier 2",
"banner": "Get Tier 2 Discount $20 Off",
"action": {
"discount": {
"type": "AMOUNT",
"amount_off": 2000,
"effect": "APPLY_TO_ORDER"
}
},
"metadata": {},
"hierarchy": 2,
"promotion_id": "camp_5h0wc453_5",
"campaign": {
"id": "camp_5h0wc453_5",
"start_date": null,
"expiration_date": null,
"active": true,
"category_id": "cat_0b688929a2476386a6",
"object": "campaign"
},
"campaign_id": "camp_5h0wc453_5",
"active": true,
"summary": {
"redemptions": {
"total_redeemed": 33
},
"orders": {
"total_amount": 519200,
"total_discount_amount": 66000
}
},
"object": "promotion_tier",
"validation_rule_assignments": {
"object": "list",
"data_ref": "data",
"data": [
{
"id": "asgm_pEe1inoYSfmO12p7",
"rule_id": "val_5h0wc453_5",
"related_object_id": "promo_RaYHtUBre5jU8frUXOvYBtlN",
"related_object_type": "promotion_tier",
"created_at": "2021-12-15T11:34:01.358Z",
"object": "validation_rules_assignment"
}
],
"total": 1
}
},
{
"id": "promo_63fYCt81Aw0h7lzyRkrGZh9p",
"created_at": "2021-12-15T11:34:01.333Z",
"updated_at": "2022-02-09T09:20:05.603Z",
"name": "Hot Promotion - Tier 1",
"banner": "Get Tier 1 Discount 10zl",
"action": {
"discount": {
"type": "AMOUNT",
"amount_off": 1000,
"effect": "APPLY_TO_ORDER"
}
},
"metadata": {
"ProductionMetaData": "Hot Promotion - Tier 1"
},
"hierarchy": 1,
"promotion_id": "camp_5h0wc453_5",
"campaign": {
"id": "camp_5h0wc453_5",
"start_date": null,
"expiration_date": null,
"active": true,
"category_id": "cat_0b688929a2476386a6",
"object": "campaign"
},
"campaign_id": "camp_5h0wc453_5",
"active": true,
"summary": {
"redemptions": {
"total_redeemed": 11
},
"orders": {
"total_amount": 1414979,
"total_discount_amount": 11000
}
},
"object": "promotion_tier",
"validation_rule_assignments": {
"object": "list",
"data_ref": "data",
"data": [
{
"id": "asgm_QqYs7GGVy7cuh3L9",
"rule_id": "val_5h0wc453_4",
"related_object_id": "promo_63fYCt81Aw0h7lzyRkrGZh9p",
"related_object_type": "promotion_tier",
"created_at": "2021-12-15T11:34:01.333Z",
"object": "validation_rules_assignment"
}
],
"total": 1
}
}
],
"total": 3
}
}
}
}
}
}
}
}
},
"/client/v1/redemptions": {
"post": {
"operationId": "redeem-stacked-discounts-client-side",
"tags": [
"Client-side"
],
"summary": "Redeem Stackable Discounts (client-side)",
"description": "This method is accessible through public keys which you can use in client side requests coming from mobile and web browser applications.\n\n## How API returns calculated discounts and order amounts in the response\n\nIn the table below, you can see the logic the API follows to calculate discounts and amounts:\n\n| **Field** | **Calculation** | **Description** |\n|:---|:---|:---|\n| amount | N/A | This field shows the order amount before applying any discount |\n| total_amount | `total_amount` = `amount` - `total_discount_amount` | This field shows the order amount after applying all the discounts |\n| 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. |\n| items_discount_amount | sum(items, i => i.discount_amount) | This field sums up all product-specific discounts |\n| total_discount_amount | `total_discount_amount` = `discount_amount` + `items_discount_amount` | This field sums up all order-level and all product-specific discounts |\n| applied_discount_amount | N/A | This field shows the order-level discount applied in a particular request |\n| items_applied_discount_amount | sum(items, i => i.applied_discount_amount) | This field sums up all product-specific discounts applied in a particular request |\n| 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 |\n\n\n\n\nRollbacks\n\nYou 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).\n\n",
"parameters": [
{
"$ref": "#/components/parameters/origin"
}
],
"security": [
{
"X-Client-Application-Id": [],
"X-Client-Token": []
},
{
"X-Voucherify-OAuth": [
"client_api",
"client_redemptions"
]
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ClientRedemptionsRedeemRequestBody"
},
"examples": {
"Example": {
"value": {
"customer": {
"source_id": "sample_customer",
"metadata": {
"key": "value"
}
},
"options": {
"expand": [
"order",
"redeemable",
"category"
]
},
"redeemables": [
{
"object": "voucher",
"id": "voucher-code"
}
],
"session": {
"type": "LOCK",
"key": "session_key"
},
"order": {
"amount": 55000,
"status": "PAID",
"items": [
{
"quantity": 2,
"price": 20000,
"source_id": "sample product1",
"related_object": "product",
"product": {
"metadata": {
"key": "value"
}
}
},
{
"quantity": 1,
"price": 15000,
"source_id": "sample product2",
"related_object": "product",
"product": {
"metadata": {
"key": "value"
}
}
}
],
"metadata": {
"key": "value"
}
}
}
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Depending on your project settings: all redeemables must be valid or just one must be valid to result as valid redemption. Read more in the [Stacking Rule Documentation](/orchestrate/stacking-rules).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ClientRedemptionsRedeemResponseBody"
}
}
}
}
}
}
},
"/client/v1/validations": {
"post": {
"operationId": "validate-stacked-discounts-client-side",
"tags": [
"Client-side"
],
"summary": "Validate Stackable Discounts (client-side)",
"description": "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.",
"parameters": [
{
"$ref": "#/components/parameters/origin"
}
],
"security": [
{
"X-Client-Application-Id": [],
"X-Client-Token": []
},
{
"X-Voucherify-OAuth": [
"client_api",
"client_validations"
]
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ClientValidationsValidateRequestBody"
},
"examples": {
"1 Redeemable": {
"value": {
"customer": {
"source_id": "sample_customer",
"metadata": {
"key": "value"
}
},
"options": {
"expand": [
"order",
"redeemable",
"category"
]
},
"redeemables": [
{
"object": "voucher",
"id": "voucher-code"
}
],
"session": {
"type": "LOCK"
},
"order": {
"amount": 55000,
"status": "PAID",
"items": [
{
"quantity": 2,
"price": 20000,
"source_id": "sample product1",
"related_object": "product",
"product": {
"metadata": {
"key": "value"
}
}
},
{
"quantity": 1,
"price": 15000,
"source_id": "sample product2",
"related_object": "product",
"product": {
"metadata": {
"key": "value"
}
}
}
],
"metadata": {
"key": "value"
}
}
}
},
"5 Redeemables": {
"value": {
"customer": {
"source_id": "36_bob"
},
"options": {
"expand": [
"order",
"redeemable",
"category"
]
},
"redeemables": [
{
"object": "voucher",
"id": "GNcuPKGe"
},
{
"object": "voucher",
"id": "AnsvocvP",
"reward": {
"id": "rew_EPx1hCTpqzF0HW1z9NKckZH4"
}
},
{
"object": "voucher",
"id": "M3X8IwW8",
"gift": {
"credits": 100
}
},
{
"object": "promotion_tier",
"id": "promo_DE1N30D731Tg2F6NoMwNas2W"
},
{
"object": "promotion_tier",
"id": "promo_NDHgTg4VnOLYNjk9r7WOmQxf"
}
],
"session": {
"type": "LOCK"
},
"order": {
"items": [
{
"sku_id": "sku_0a3efc90375d1217e2",
"quantity": 1
},
{
"product_id": "prod_0bc3bd8a4e072c5275",
"quantity": 1
}
]
}
}
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Depending on your project settings: all redeemables must be valid or just one must be valid to result as valid validation. Read more in the [Stacking Rule Documentation](/orchestrate/stacking-rules).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ClientValidationsValidateResponseBody"
}
}
}
},
"400": {
"description": "Returns an error if the payload is missing an `\"object\"` or `\"id\"` property in the redeemables array, if you add more than one promotion stack or attempt to join stacks with vouchers/promotion tiers.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/e_400_invalid_payload"
},
"examples": {
"Invalid payload": {
"value": {
"code": 400,
"key": "invalid_payload",
"message": "Invalid payload",
"details": "Property .redeemables[1] should have required property 'id'",
"request_id": "v-0b4ff38ab8c8164573"
}
},
"Duplicated Redeemables": {
"value": {
"code": 400,
"key": "duplicated_redeemables",
"message": "Duplicated redeemables detected",
"details": "Duplicated redeemables detected in one redemption",
"request_id": "v-0b4ffecfb408165300"
}
},
"Invalid Redeemables": {
"value": {
"code": 400,
"key": "invalid_redeemables",
"message": "Invalid redeemables",
"details": "Promotion Stack cannot be use with other redeemables",
"request_id": "v-0b5007812f48165d6b"
}
}
}
}
}
}
}
}
},
"/client/v1/events": {
"post": {
"operationId": "track-custom-event-client-side",
"tags": [
"Client-side"
],
"summary": "Track Custom Event (client-side)",
"description": "To track a custom event, you create an event object. \n\nThe 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.",
"parameters": [
{
"$ref": "#/components/parameters/origin"
}
],
"security": [
{
"X-Client-Application-Id": [],
"X-Client-Token": []
},
{
"X-Voucherify-OAuth": [
"client_api",
"client_events"
]
}
],
"requestBody": {
"description": "Specify the details of the custom event.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ClientEventsCreateRequestBody"
},
"examples": {
"Referral triggered by custom event": {
"value": {
"event": "user_subscribed",
"customer": {
"source_id": "source_customer_event"
},
"referral": {
"code": "46jL0kYI",
"referrer_id": "cust_Vzck5i8U3OhcEUFY6MKhN9Rv"
},
"metadata": {
"login": "bob",
"pricing_plan": "PP1",
"volume_number": 4
}
}
},
"Earning rule triggered by custom event": {
"value": {
"event": "cart_abandoned",
"customer": {
"source_id": "source_customer_event"
},
"loyalty": {
"code": "6CB4KDAu"
},
"metadata": {
"date": "2022-12-01",
"flag": true,
"text": "Cart abandoned event",
"date_time": "2022-12-01T09:24:33.061Z",
"number": 1
}
}
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Returns the event type if the event was received by the application.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ClientEventsCreateResponseBody"
},
"examples": {
"Example": {
"value": {
"object": "event",
"type": "cart_abandoned",
"customer": {
"id": "cust_ypePCF6IU6fnUvec6RMXZuH4",
"name": "John Doe",
"email": "john@voucherify.io",
"source_id": "source_customer_event",
"metadata": {
"prop": "value"
},
"object": "customer"
},
"referral": null,
"loyalty": null
}
}
}
}
}
},
"400": {
"description": "Returns an error if the request payload is incomplete.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"Invalid payload": {
"value": {
"code": 400,
"key": "invalid_payload",
"message": "Invalid payload",
"details": "Property .referral should have required property 'code'",
"request_id": "v-0c15694e0e022146dd"
}
}
}
}
}
}
}
}
},
"/client/v1/validate": {
"get": {
"operationId": "validate-voucher-client-side",
"deprecated": true,
"tags": [
"Client-side"
],
"summary": "Validate Voucher (client-side)",
"description": "\n\nDeprecated\n\nThis 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.\n\n\n\nTo 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.\n\n\n\nSpecifying gift credits and loyalty points\n\nThis 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.\n\n\n\n### Set customer identity (optional)\n\nVoucherify 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.\n\nVoucherify 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.\n\nThe 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.\n\n### Sample workflow\n\nCustomer tracking workflow in a nutshell:\n\n**Client-side:**\n * A customer visits your website.\n * 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`.\n\n**Backend:**\n * 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.\n * A customer object is created and within the redemption response, you get a customer `id`.\n * You can use the customer `id` or the customer `source_id` to fetch or modify the customer details.\n \nA 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). \n\n\n\n\n\nCustomer identifier\n\nThe 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.\n\n\n\n\n\n\n### Examples with Query Parameters\n\n| **Query Parameters** | **Example URL** |\n|:---|:---|\n| Shortcut - `customer` query param instead of `customer[source_id]` | `https://api.voucherify.io/client/v1/validate?code=sKKFCKLZ&amount=10100&customer=customer_id` |\n| 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` |\n| 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` |\n\n### Reasons why a validation might fail\n\nVoucher validation might fail because of one of these reasons:\n\n* `voucher not found` - voucher doesn't exist or was [deleted](/api-reference/vouchers/delete-voucher)\n* `voucher expired` - voucher is out of [start date - expiration date] timeframe\n* `voucher is disabled` - learn more about [disabled vouchers](/api-reference/vouchers/disable-voucher)\n* `customer does not match segment rules` - learn more about [customer tracking](/api-reference/customers/customer-object)\n* `order does not match validation rules` - learn more about [validation rules](/api-reference/validations/validation-object)",
"parameters": [
{
"$ref": "#/components/parameters/origin"
},
{
"schema": {
"$ref": "#/components/schemas/ParameterCode"
},
"in": "query",
"name": "code",
"description": "A code that identifies the voucher."
},
{
"schema": {
"$ref": "#/components/schemas/ParameterString"
},
"in": "query",
"name": "tracking_id",
"description": "A tracking identifier of a user that validated the voucher. This identifier is generated during voucher validation based on your internal ID (e.g., email, database ID) during the first request. This is a hashed customer source ID. If the request is performed for the first time, pass the internal ID to track the customer. **Although not all information is required, the extra information helps prevent fraud.**"
},
{
"schema": {
"$ref": "#/components/schemas/ParameterString"
},
"in": "query",
"name": "amount",
"description": "A positive integer in the smallest currency unit (e.g. 100 cents for $1.00) representing the total amount of the order. This is the sum of the order items' amounts."
},
{
"schema": {
"$ref": "#/components/schemas/ParameterSessionKey"
},
"in": "query",
"name": "session_key",
"description": "The session unique ID assigned by Voucherify or your own unique session ID. Sending an existing ID will result in overwriting an existing session. If no session key is provided, then a new ID will be generated."
},
{
"schema": {
"$ref": "#/components/schemas/ParameterInteger"
},
"in": "query",
"name": "session_ttl",
"description": "Value for the period of time that the session is active. Units for this parameter are defined by the `session_ttl_unit` parameter."
},
{
"schema": {
"$ref": "#/components/schemas/ParameterSessionTtlUnit"
},
"in": "query",
"name": "session_ttl_unit",
"description": "Defines the type of unit in which the session time is counted."
},
{
"$ref": "#/components/parameters/metadata"
},
{
"$ref": "#/components/parameters/item"
},
{
"schema": {
"$ref": "#/components/schemas/ParameterString"
},
"in": "query",
"name": "session_type",
"description": "The session is required to establish a session between multiple parallel validation and redemption requests. This parameter is required to establish a new session. The session locks the **redemption quantity by 1** and additionally the redemption **gift credits** specified within the request for a gift card and the **loyalty points** for a loyalty card."
},
{
"name": "customer",
"in": "query",
"required": false,
"schema": {
"$ref": "#/components/schemas/ParameterCustomerValidateVoucherClientSide"
},
"description": "Customer details."
},
{
"name": "order",
"in": "query",
"required": false,
"schema": {
"$ref": "#/components/schemas/ParameterOrderMetadata"
},
"style": "deepObject",
"explode": true,
"description": "Order details."
}
],
"security": [
{
"X-Client-Application-Id": [],
"X-Client-Token": []
},
{
"X-Voucherify-OAuth": [
"client_api",
"client_validate"
]
}
],
"responses": {
"200": {
"description": "Returns information whether the voucher is valid in the context of the parameter values provided in the query parameters. Moreover, it returns a hashed source identifier which can be used as tracking ID in future calls. If a validation session is established, then the session details will be returned as well. Read more on [validation sessions](/guides/locking-validation-session).",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/schemas/6_res_validate_voucher"
},
{
"$ref": "#/components/schemas/6_res_validate_voucher_false"
}
]
},
"examples": {
"Wrong customer": {
"value": {
"valid": false,
"reason": "customer does not match validation rules",
"error": {
"message": "Only the gift card owner can apply credits from the gift card to the order."
},
"tracking_id": "track_0nmdnu/6xIb6NTN0Ea40oFmM4wD5QYlxAgKdSn6wh+o",
"code": "GIFT-CARD-kW4aEsfB",
"metadata": {}
}
},
"Validation Rule Not Satisfied": {
"value": {
"valid": false,
"reason": "redemption does not match validation rules",
"error": {
"code": 400,
"key": "redemption_rules_violated",
"message": "redemption does not match validation rules",
"details": "Discount Coupon cannot be redeemed because of violated validation rules: val_WuupvE7OVXyo",
"request_id": "v-0be54f4afa0357c12f"
},
"tracking_id": "track_0nmdnu/6xIb6NTN0Ea40oFmM4wD5QYlxAgKdSn6wh+oychk",
"code": "PAYINEUROS",
"metadata": {
"shoutout": "Pay in euros to get 10 Euros off, any other currency to get 5 off in that currency."
}
}
},
"Validate Discount Coupon": {
"value": {
"valid": true,
"applicable_to": {
"data": [],
"total": 0,
"data_ref": "data",
"object": "list"
},
"inapplicable_to": {
"data": [],
"total": 0,
"data_ref": "data",
"object": "list"
},
"tracking_id": "track_rynPcKGW2z7+kd2Vry4p12+Rx2NtyXZyiApdGWEXPrdX+44Fg6LRBQ==",
"session": {
"key": "A",
"type": "LOCK",
"ttl": 1,
"ttl_unit": "NANOSECONDS"
},
"order": {
"amount": 13000,
"discount_amount": 1000,
"total_discount_amount": 1000,
"total_amount": 12000,
"applied_discount_amount": 1000,
"total_applied_discount_amount": 1000,
"items": [
{
"object": "order_item",
"source_id": "webinar_BF_sweater_pink_sweater",
"related_object": "product",
"quantity": 2,
"amount": 13000,
"price": 6500,
"subtotal_amount": 13000,
"product": {
"id": "prod_0bd76ca337954ca116",
"source_id": "webinar_BF_sweater_pink_sweater",
"name": "Pink Sweater",
"price": 6500
}
}
],
"metadata": {
"currency": "EUR"
},
"customer_id": null,
"referrer_id": null,
"object": "order"
},
"code": "PAYINEUROS",
"discount": {
"type": "AMOUNT",
"effect": "APPLY_TO_ORDER",
"amount_off": 1000
},
"metadata": {
"shoutout": "Pay in euros to get 10 Euros off, any other currency to get 5 off in that currency."
}
}
},
"Validate Loyalty Card": {
"value": {
"valid": true,
"applicable_to": {
"data": [],
"total": 0,
"data_ref": "data",
"object": "list"
},
"inapplicable_to": {
"data": [],
"total": 0,
"data_ref": "data",
"object": "list"
},
"tracking_id": "track_Mcg5qK0jIStHAopLoM+nM6ua9crMFQrLt+qSe2YCbmTrTT8932kSlg==",
"session": {
"key": "A",
"type": "LOCK",
"ttl": 1,
"ttl_unit": "NANOSECONDS"
},
"order": {
"amount": 121700,
"discount_amount": 5000,
"total_discount_amount": 5000,
"total_amount": 116700,
"applied_discount_amount": 5000,
"total_applied_discount_amount": 5000,
"items": [
{
"object": "order_item",
"source_id": "webinar_BF_sweater_pink_sweater",
"related_object": "product",
"quantity": 2,
"amount": 13000,
"price": 6500,
"subtotal_amount": 13000,
"product": {
"id": "prod_0bd76ca337954ca116",
"source_id": "webinar_BF_sweater_pink_sweater",
"name": "Pink Sweater",
"price": 6500
}
},
{
"object": "order_item",
"source_id": "webinar_BF_pants_gray_sweat_pants",
"related_object": "product",
"quantity": 2,
"amount": 10000,
"price": 5000,
"subtotal_amount": 10000,
"product": {
"id": "prod_0bd76b8656956a183f",
"source_id": "webinar_BF_pants_gray_sweat_pants",
"name": "Gray Sweat Pants",
"price": 5000
}
},
{
"object": "order_item",
"product_id": "prod_0bd76bb4aa003890cb",
"quantity": 2,
"amount": 9000,
"price": 4500,
"subtotal_amount": 9000,
"product": {
"id": "prod_0bd76bb4aa003890cb",
"source_id": "webinar_BF_pants_black_sweat_pants",
"name": "Black Sweat Pants",
"price": 4500
}
},
{
"object": "order_item",
"source_id": "M0E20000000ELDH",
"related_object": "sku",
"product_id": "prod_0b661d4bd2c7ec7d1f",
"quantity": 3,
"amount": 89700,
"price": 29900,
"subtotal_amount": 89700,
"product": {
"id": "prod_0b661d4bd2c7ec7d1f",
"source_id": "facdc58f-ff7c-40c4-a22f-ab0a084a9107",
"name": "Casual jacket Michael Kors beige"
},
"sku": {
"id": "sku_0b661e41fc8d35a8f8",
"source_id": "M0E20000000ELDH",
"sku": "Casual jacket Michael Kors beige",
"price": 29900
}
}
],
"metadata": {
"currency": "EUR"
},
"customer_id": null,
"referrer_id": null,
"object": "order"
},
"code": "LOYALTY-CARD-ng3Kb9tM",
"loyalty": {
"points_cost": 1000
},
"reward": {
"id": "rew_4ZF6Y69U2PXE3GLIZxfozgg1",
"assignment_id": "rewa_WkeBlLhj0sRae70J5AAvLbmy"
},
"metadata": {},
"campaign": "Loyalty Campaign",
"campaign_id": "camp_ZNb23Xtw1WuGCm7gdax84PUi"
}
},
"Validate Gift Card": {
"value": {
"valid": true,
"applicable_to": {
"data": [],
"total": 0,
"data_ref": "data",
"object": "list"
},
"inapplicable_to": {
"data": [],
"total": 0,
"data_ref": "data",
"object": "list"
},
"tracking_id": "track_Mcg5qK0jIStHAopLoM+nM6ua9crMFQrLt+qSe2YCbmTrTT8932kSlg==",
"session": {
"key": "A",
"type": "LOCK",
"ttl": 1,
"ttl_unit": "NANOSECONDS"
},
"order": {
"amount": 165700,
"discount_amount": 21500,
"total_discount_amount": 21500,
"total_amount": 144200,
"applied_discount_amount": 21500,
"total_applied_discount_amount": 21500,
"items": [
{
"object": "order_item",
"source_id": "webinar_BF_sweater_pink_sweater",
"related_object": "product",
"quantity": 2,
"amount": 13000,
"price": 6500,
"subtotal_amount": 13000,
"product": {
"id": "prod_0bd76ca337954ca116",
"source_id": "webinar_BF_sweater_pink_sweater",
"name": "Pink Sweater",
"price": 6500
}
},
{
"object": "order_item",
"source_id": "webinar_BF_pants_gray_sweat_pants",
"related_object": "product",
"quantity": 2,
"amount": 10000,
"price": 5000,
"subtotal_amount": 10000,
"product": {
"id": "prod_0bd76b8656956a183f",
"source_id": "webinar_BF_pants_gray_sweat_pants",
"name": "Gray Sweat Pants",
"price": 5000
}
},
{
"object": "order_item",
"product_id": "prod_0bd76bb4aa003890cb",
"quantity": 2,
"amount": 9000,
"price": 4500,
"subtotal_amount": 9000,
"product": {
"id": "prod_0bd76bb4aa003890cb",
"source_id": "webinar_BF_pants_black_sweat_pants",
"name": "Black Sweat Pants",
"price": 4500
}
},
{
"object": "order_item",
"source_id": "M0E20000000ELDH",
"related_object": "sku",
"product_id": "prod_0b661d4bd2c7ec7d1f",
"quantity": 3,
"amount": 89700,
"price": 29900,
"subtotal_amount": 89700,
"product": {
"id": "prod_0b661d4bd2c7ec7d1f",
"source_id": "facdc58f-ff7c-40c4-a22f-ab0a084a9107",
"name": "Casual jacket Michael Kors beige"
},
"sku": {
"id": "sku_0b661e41fc8d35a8f8",
"source_id": "M0E20000000ELDH",
"sku": "Casual jacket Michael Kors beige",
"price": 29900
}
},
{
"object": "order_item",
"product_id": "prod_0b661d4bd347ec7d26",
"sku_id": "sku_0b661e41fc0d35a8f1",
"quantity": 4,
"amount": 44000,
"price": 11000,
"subtotal_amount": 44000,
"product": {
"id": "prod_0b661d4bd347ec7d26",
"source_id": "975193eb-1911-444a-a0f0-f567efce1a8b",
"name": "Pumps ”Flex” Michael Kors black"
},
"sku": {
"id": "sku_0b661e41fc0d35a8f1",
"source_id": "M0E20000000DMVX",
"sku": "Pumps ”Flex” Michael Kors black",
"price": 11000
}
}
],
"metadata": {
"currency": "EUR"
},
"customer_id": null,
"referrer_id": null,
"object": "order"
},
"code": "GIFT-CARD-kW4aEsfB",
"gift": {
"amount": 32000,
"balance": 21500,
"effect": "APPLY_TO_ORDER"
},
"metadata": {},
"campaign": "Gift Card Campaign",
"campaign_id": "camp_ZjoZEdmnyUCPYwMPN0IVbvDK"
}
},
"Validate Referral Code": {
"value": {
"valid": true,
"applicable_to": {
"data": [],
"total": 0,
"data_ref": "data",
"object": "list"
},
"inapplicable_to": {
"data": [],
"total": 0,
"data_ref": "data",
"object": "list"
},
"tracking_id": "track_p6hPsnZj2VSvyXDjH9o6aQ==",
"order": {
"amount": 10000,
"discount_amount": 3000,
"total_discount_amount": 3000,
"total_amount": 7000,
"applied_discount_amount": 3000,
"total_applied_discount_amount": 3000,
"items": [],
"metadata": {},
"referrer": {
"id": "cust_nM4jqPiaXUvQdVSA6vTRUnix",
"object": "customer"
},
"customer_id": null,
"referrer_id": "cust_nM4jqPiaXUvQdVSA6vTRUnix",
"object": "order"
},
"code": "REFERRAL-CODE-OxBakPYf",
"discount": {
"type": "PERCENT",
"effect": "APPLY_TO_ORDER",
"percent_off": 30
},
"metadata": {},
"campaign": "Referral Campaign",
"campaign_id": "camp_TnOf5NB4Jtjxwoq38WckMJfy"
}
}
}
}
}
},
"400": {
"description": "Returns an error if missing required parameters or tracking IDs come from the same origin.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"Missing customer": {
"value": {
"code": 400,
"key": "missing_customer",
"message": "Missing customer",
"details": "Customer is required to validate rules",
"request_id": "v-0be548ae620abb0a73"
}
},
"Ambiguous tracking ID": {
"value": {
"code": 400,
"key": "ambiguous_tracking_id",
"message": "Ambiguous trackingId ('track_0nmdnu/6xIb6NTN0Ea40oFmM4wD5QYlxAgKdSn6wh+oychkbEcMNB5RhcTj+zcKBEcGnUZkAXxg=' vs. 'track_Mcg5qK0jIStHAopLoM+nM6ua9crMFQrLt+qSe2YCbmTrTT8932kSlg==')",
"details": "The customer cannot be identified as two different identifiers have been used between requests from same origin.",
"request_id": "v-0be550a5a84abb30f8"
}
}
}
}
}
}
}
}
},
"/client/v1/redeem": {
"post": {
"operationId": "redeem-voucher-client-side",
"deprecated": true,
"tags": [
"Client-side"
],
"summary": "Redeem Voucher (client-side)",
"description": "\n\n\nDeprecated\n\nThis 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.\n\n\n\nTo 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). \n\nThe 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.\n\n\n\n\nOpt-in\n\nBy default this feature is disabled. If you want to use it, you will need to enable the function explicitly in **Project Settings**.\n\n\n\n\n\n\nSecurity Threat\n\nBe 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.\n\n\n\n### Expand Response\nYou may expand the response by adding the following object to your request body. The expanded response will include the category details of the voucher.\n\n```json\n{\n \"options\": {\n \"expand\": [\n \"category\"\n ]\n }\n}\n```",
"parameters": [
{
"$ref": "#/components/parameters/origin"
},
{
"schema": {
"$ref": "#/components/schemas/ParameterCode"
},
"in": "query",
"name": "code",
"description": "Voucher code being redeemed.",
"required": true
},
{
"schema": {
"$ref": "#/components/schemas/ParameterString"
},
"in": "query",
"name": "tracking_id",
"description": "A tracking identifier of a user that redeemed a voucher. Identifier generated during voucher validation based on your internal id (e.g., email, database ID). This is a hashed customer source ID. If you also pass a customer ID, the tracking ID must be the ID of a source of the customer object. Otherwise, if you do not pass a customer ID, the tracking you provide must either be a token, like the ones returned by [voucher validation](/api-reference/validations/validate-voucher), or a string identifying customer, with the options described below. Although not all information is required, the extra info helps prevent fraud."
}
],
"security": [
{
"X-Client-Application-Id": [],
"X-Client-Token": []
},
{
"X-Voucherify-OAuth": [
"client_api",
"client_redeem"
]
}
],
"requestBody": {
"description": "Provide the redemption context in the request body.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/7_req_redeem_voucher"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Returns a redemption object if the redeem operation succeeded.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/7_res_redeem_voucher"
},
"examples": {
"Gift Voucher": {
"value": {
"id": "r_0c5e8a38730ccec0d5",
"object": "redemption",
"date": "2023-01-27T12:34:57.100Z",
"customer_id": "cust_eWgXlBBiY6THFRJwX45Iakv4",
"tracking_id": "track_9B0kB92+bJa8a+PegaWREw==",
"metadata": null,
"amount": 2000,
"result": "SUCCESS",
"order": {
"id": "ord_S4BvUj64TlGqVZDOeud7z3rU",
"source_id": null,
"created_at": "2023-01-27T12:34:57.086Z",
"updated_at": null,
"status": "PAID",
"amount": 6000,
"discount_amount": 2000,
"total_discount_amount": 2000,
"total_amount": 4000,
"applied_discount_amount": 2000,
"total_applied_discount_amount": 2000,
"items": [
{
"object": "order_item",
"product_id": "prod_0a9f9ab4ab019a42d5",
"quantity": 1,
"amount": 3300,
"price": 3000,
"subtotal_amount": 3300
},
{
"object": "order_item",
"product_id": "prod_0a9f9aeddb019a42db",
"quantity": 2,
"amount": 3400,
"price": 3000,
"subtotal_amount": 3400
}
],
"metadata": {},
"customer": {
"id": "cust_eWgXlBBiY6THFRJwX45Iakv4",
"object": "customer"
},
"customer_id": "cust_eWgXlBBiY6THFRJwX45Iakv4",
"referrer_id": null,
"object": "order",
"redemptions": {
"r_0c5e8a38730ccec0d5": {
"date": "2023-01-27T12:34:57.100Z",
"related_object_type": "voucher",
"related_object_id": "v_UFAc7FTVO0HtJV2hWZls4O7eqHMyn62g",
"related_object_parent_id": "camp_B2Gx83JsSbmvj05MOwxYbNm6"
}
}
},
"customer": {
"id": "cust_eWgXlBBiY6THFRJwX45Iakv4",
"name": "Bob Jones",
"email": "bob.jones@email.com",
"source_id": "36_bob",
"metadata": {
"age": 26,
"favorite_brands": [
"Nike",
"Adidas",
"Reebok"
],
"accepts_marketing": false,
"acquisition_channel": "Facebook"
},
"object": "customer"
},
"related_object_type": "voucher",
"related_object_id": "v_UFAc7FTVO0HtJV2hWZls4O7eqHMyn62g",
"voucher": {
"id": "v_UFAc7FTVO0HtJV2hWZls4O7eqHMyn62g",
"code": "CODE14",
"campaign": "Gift Card Campaign",
"campaign_id": "camp_B2Gx83JsSbmvj05MOwxYbNm6",
"category": "Second",
"category_id": "cat_0bb343dee3cdb5ec0c",
"categories": [],
"type": "GIFT_VOUCHER",
"discount": null,
"gift": {
"amount": 2000,
"balance": 0,
"effect": null
},
"loyalty_card": null,
"start_date": "2020-08-16T00:00:00.000Z",
"expiration_date": null,
"validity_timeframe": null,
"validity_day_of_week": null,
"active": true,
"additional_info": "secret-code1",
"metadata": {
"region": "APAC",
"season": "Fall"
},
"assets": {
"qr": {
"id": "U2FsdGVkX1+VibJ6VGxrSVw5qmdbPMP3aP8HfcngMxtQc9Bm649CK1dK36e8YR820Ct26IkvDemEDzV8ozhB3F2BpazbgvCmhAo2Gvmo2WtwBwPh2ISAPJiXQCHRjwmKiqogjqQaNKWLxwDIBUc2jQ==",
"url": "{{internalVoucherifyURL}}"
},
"barcode": {
"id": "U2FsdGVkX1/GVIi0p5fL5hxAY/ZBmuAU7nYYS03umjd30dwI5v5ZbpNc3Q5MiYbMuIOIT0H2fUTTwd//S4R9AB+60T/x4kSKu3lgfa9KgJmbyrzXm7Ggly06/qph4/asJaZVZIXEba4WJCeHqXCEgg==",
"url": "{{internalVoucherifyURL}}"
}
},
"is_referral_code": false,
"created_at": "2022-09-23T11:05:42.164Z",
"updated_at": "2023-01-27T12:34:57.102Z",
"validation_rules_assignments": {
"object": "list",
"data_ref": "data",
"data": [],
"total": 0
},
"redemption": {
"quantity": 18,
"redeemed_quantity": 1,
"redeemed_amount": 2000,
"object": "list",
"url": "/v1/vouchers/CODE14/redemptions?page=1&limit=10"
},
"publish": {
"object": "list",
"count": 0,
"url": "/v1/vouchers/CODE14/publications?page=1&limit=10"
},
"object": "voucher",
"applicable_to": {
"data": [],
"total": 0,
"data_ref": "data",
"object": "list"
},
"inapplicable_to": {
"data": [],
"total": 0,
"data_ref": "data",
"object": "list"
}
},
"gift": {
"amount": 2000
}
}
},
"Discount Coupon": {
"value": {
"id": "r_0c5e8ef10842da0aad",
"object": "redemption",
"date": "2023-01-27T12:55:34.689Z",
"customer_id": "cust_eWgXlBBiY6THFRJwX45Iakv4",
"tracking_id": "track_9B0kB92+bJa8a+PegaWREw==",
"metadata": null,
"result": "SUCCESS",
"order": {
"id": "ord_J5ogV1Gkk2yfxmBEhYIg4O65",
"source_id": null,
"created_at": "2023-01-27T12:55:34.673Z",
"updated_at": null,
"status": "PAID",
"amount": 6000,
"items_discount_amount": 300,
"total_discount_amount": 300,
"total_amount": 5700,
"items_applied_discount_amount": 300,
"total_applied_discount_amount": 300,
"items": [
{
"object": "order_item",
"product_id": "prod_0a9f9ab4ab019a42d5",
"quantity": 1,
"amount": 3300,
"discount_amount": 148,
"applied_discount_amount": 148,
"price": 3000,
"subtotal_amount": 3152
},
{
"object": "order_item",
"product_id": "prod_0a9f9aeddb019a42db",
"quantity": 2,
"amount": 3400,
"discount_amount": 152,
"applied_discount_amount": 152,
"price": 3000,
"subtotal_amount": 3248
}
],
"metadata": {},
"customer": {
"id": "cust_eWgXlBBiY6THFRJwX45Iakv4",
"object": "customer"
},
"customer_id": "cust_eWgXlBBiY6THFRJwX45Iakv4",
"referrer_id": null,
"object": "order",
"redemptions": {
"r_0c5e8ef10842da0aad": {
"date": "2023-01-27T12:55:34.689Z",
"related_object_type": "voucher",
"related_object_id": "v_TzD19aeNiqGc9LWciMWknyEZT8IW7u4u"
}
}
},
"customer": {
"id": "cust_eWgXlBBiY6THFRJwX45Iakv4",
"name": "Bob Jones",
"email": "bob.jones@email.com",
"source_id": "36_bob",
"metadata": {
"age": 26,
"favorite_brands": [
"Nike",
"Adidas",
"Reebok"
],
"accepts_marketing": false,
"acquisition_channel": "Facebook"
},
"object": "customer"
},
"related_object_type": "voucher",
"related_object_id": "v_TzD19aeNiqGc9LWciMWknyEZT8IW7u4u",
"voucher": {
"id": "v_TzD19aeNiqGc9LWciMWknyEZT8IW7u4u",
"code": "2CpRCE2c",
"campaign": null,
"campaign_id": null,
"category": null,
"category_id": null,
"categories": [],
"type": "DISCOUNT_VOUCHER",
"discount": {
"type": "AMOUNT",
"amount_off": 300,
"effect": "APPLY_TO_ITEMS_PROPORTIONALLY"
},
"gift": null,
"loyalty_card": null,
"start_date": null,
"expiration_date": null,
"validity_timeframe": null,
"validity_day_of_week": null,
"active": true,
"additional_info": null,
"metadata": {},
"assets": {
"qr": {
"id": "U2FsdGVkX1+ro/6HLsfI9E/rz0QEoYv+rcVIEERdbV3gB4104zYyGfpydtSxS1WfpbuiDUfMizQAl1EMzoYsud5XTKBBwUkGkI5IPl84lPz+WQtg4nKpjUS0wcA7AuIbz2zb870YfJO/r5UBS5gCqQ==",
"url": "{{internalVoucherifyURL}}"
},
"barcode": {
"id": "U2FsdGVkX19SWjP3ZUbFh26gCGb4xm3K95jhzfk1XXlKcYlHPtDTYR3/4dYbig4xxRmkgpQLa93Woz9Hq3h4JBQ+aTlftkEzL4D4OSAWi1aWlfxVikrJd6TMFLh9mmbmskodjs4MIdOFlluDWyarlw==",
"url": "{{internalVoucherifyURL}}"
}
},
"is_referral_code": false,
"created_at": "2022-09-19T10:06:07.932Z",
"updated_at": "2023-01-27T12:55:34.690Z",
"validation_rules_assignments": {
"object": "list",
"data_ref": "data",
"data": [
{
"id": "asgm_HesdqEzt5e9c0T56",
"rule_id": "val_gZft0NKZSUWK",
"related_object_id": "v_TzD19aeNiqGc9LWciMWknyEZT8IW7u4u",
"related_object_type": "voucher",
"object": "validation_rules_assignment"
}
],
"total": 1
},
"redemption": {
"quantity": null,
"redeemed_quantity": 2,
"object": "list",
"url": "/v1/vouchers/2CpRCE2c/redemptions?page=1&limit=10"
},
"publish": {
"object": "list",
"count": 0,
"url": "/v1/vouchers/2CpRCE2c/publications?page=1&limit=10"
},
"object": "voucher",
"applicable_to": {
"data": [
{
"object": "product",
"id": "prod_0a9f9ab4ab019a42d5",
"source_id": "prod_0a9f9ab4ab019a42d5",
"effect": "APPLY_TO_EVERY"
},
{
"object": "product",
"id": "prod_0a9f9aeddb019a42db",
"source_id": "prod_0a9f9aeddb019a42db",
"effect": "APPLY_TO_EVERY"
}
],
"total": 2,
"data_ref": "data",
"object": "list"
},
"inapplicable_to": {
"data": [],
"total": 0,
"data_ref": "data",
"object": "list"
}
}
}
},
"Loyalty Card": {
"value": {
"id": "r_0c5e8f2cd78497a372",
"object": "redemption",
"date": "2023-01-27T12:56:35.934Z",
"customer_id": "cust_eWgXlBBiY6THFRJwX45Iakv4",
"tracking_id": "track_9B0kB92+bJa8a+PegaWREw==",
"metadata": null,
"amount": 300,
"result": "SUCCESS",
"order": {
"id": "ord_MGTimoN4VtSj7iT75bP01FsH",
"source_id": null,
"created_at": "2023-01-27T12:56:35.923Z",
"updated_at": null,
"status": "PAID",
"amount": 6000,
"discount_amount": 6000,
"total_discount_amount": 6000,
"total_amount": 0,
"applied_discount_amount": 6000,
"total_applied_discount_amount": 6000,
"items": [
{
"object": "order_item",
"product_id": "prod_0a9f9ab4ab019a42d5",
"quantity": 1,
"amount": 3300,
"price": 3000,
"subtotal_amount": 3300
},
{
"object": "order_item",
"product_id": "prod_0a9f9aeddb019a42db",
"quantity": 2,
"amount": 3400,
"price": 3000,
"subtotal_amount": 3400
}
],
"metadata": {},
"customer": {
"id": "cust_eWgXlBBiY6THFRJwX45Iakv4",
"object": "customer"
},
"customer_id": "cust_eWgXlBBiY6THFRJwX45Iakv4",
"referrer_id": null,
"object": "order",
"redemptions": {
"r_0c5e8f2cd78497a372": {
"date": "2023-01-27T12:56:35.934Z",
"related_object_type": "voucher",
"related_object_id": "v_u3dRiZ0XHqX5Euhy5ezB5UQ5Sf85VXFP",
"related_object_parent_id": "camp_22noMlhTADb7Fq2UL3vWu3d1"
}
}
},
"customer": {
"id": "cust_eWgXlBBiY6THFRJwX45Iakv4",
"name": "Bob Jones",
"email": "bob.jones@email.com",
"source_id": "36_bob",
"metadata": {
"age": 26,
"favorite_brands": [
"Nike",
"Adidas",
"Reebok"
],
"accepts_marketing": false,
"acquisition_channel": "Facebook"
},
"object": "customer"
},
"related_object_type": "voucher",
"related_object_id": "v_u3dRiZ0XHqX5Euhy5ezB5UQ5Sf85VXFP",
"voucher": {
"id": "v_u3dRiZ0XHqX5Euhy5ezB5UQ5Sf85VXFP",
"code": "AnsvocvP",
"campaign": "Loyalty Campaign - Test Points",
"campaign_id": "camp_22noMlhTADb7Fq2UL3vWu3d1",
"category": null,
"category_id": "cat_0bb81a481615a37b5e",
"categories": [],
"type": "LOYALTY_CARD",
"discount": null,
"gift": null,
"loyalty_card": {
"points": 6500,
"balance": 5086
},
"start_date": null,
"expiration_date": null,
"validity_timeframe": null,
"validity_day_of_week": null,
"active": true,
"additional_info": null,
"metadata": {},
"assets": {
"qr": {
"id": "U2FsdGVkX1/Au841M0T7UjYYRxYTzCRbNdZW6jW5YRNcV9PgblvN2MD5hdRuZfBRHEAm+d2pvzc2FOVHFkuh9BQoaIq4KVyvy0FvkWtKkMLe4zO+qL4ocNUIbaRMSLeY6Xiz4hjxKNq918oLyGrp9w==",
"url": "{{internalVoucherifyURL}}"
},
"barcode": {
"id": "U2FsdGVkX1+xG42zWo9nivfp6tg5jNuFCYOIFtw7iwas8kcA/8H4gu04dxO/hrbD41gFvxDhCuTSnIKwIPg9dEXzOvh8qy9VWN0UwDc6PL7lfNQuY+8Os7dqVsyNhoRned9pBo1uO6V4pjNu1gRTrw==",
"url": "{{internalVoucherifyURL}}"
}
},
"is_referral_code": false,
"created_at": "2022-11-10T06:28:59.970Z",
"updated_at": "2023-01-27T12:56:35.935Z",
"holder_id": "cust_eWgXlBBiY6THFRJwX45Iakv4",
"holder": {
"id": "cust_eWgXlBBiY6THFRJwX45Iakv4",
"source_id": "36_bob",
"metadata": {
"age": 26,
"favorite_brands": [
"Nike",
"Adidas",
"Reebok"
],
"accepts_marketing": false,
"acquisition_channel": "Facebook"
},
"object": "customer"
},
"validation_rules_assignments": {
"object": "list",
"data_ref": "data",
"data": [],
"total": 0
},
"redemption": {
"quantity": null,
"redeemed_quantity": 10,
"redeemed_points": 1414,
"object": "list",
"url": "/v1/vouchers/AnsvocvP/redemptions?page=1&limit=10"
},
"publish": {
"object": "list",
"count": 1,
"url": "/v1/vouchers/AnsvocvP/publications?page=1&limit=10"
},
"object": "voucher",
"applicable_to": {
"data": [],
"total": 0,
"data_ref": "data",
"object": "list"
},
"inapplicable_to": {
"data": [],
"total": 0,
"data_ref": "data",
"object": "list"
}
},
"reward": {
"customer": {
"id": "cust_eWgXlBBiY6THFRJwX45Iakv4",
"name": "Bob Jones",
"email": "bob.jones@email.com",
"source_id": "36_bob",
"metadata": {
"age": 26,
"favorite_brands": [
"Nike",
"Adidas",
"Reebok"
],
"accepts_marketing": false,
"acquisition_channel": "Facebook"
},
"object": "customer"
},
"assignment_id": "rewa_YAIuU7AY6LNJVlUbRxSbNgiD",
"id": "rew_INt3fGH3n7xIr3ZQcq4kkUZ1",
"object": "reward",
"name": "100 = $20",
"created_at": "2022-11-10T06:28:39.582Z",
"updated_at": null,
"parameters": {
"coin": {
"exchange_ratio": 20,
"points_ratio": 100
}
},
"type": "COIN"
},
"loyalty_card": {
"points": 300
}
}
}
}
}
}
},
"400": {
"description": "Returns an error if something goes wrong. A common source of error is an invalid or expired voucher, or a valid gift card with insufficient available balance.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/e_error_expanded"
},
"examples": {
"Voucher disabled": {
"value": {
"code": 400,
"key": "voucher_disabled",
"message": "voucher is disabled",
"details": "AnsvocvP",
"request_id": "v-0c5d710a63c4110ae9",
"resource_id": "rf_0c5d710a87c8a31f86",
"resource_type": "redemption",
"error": {
"message": "The voucher has been disabled and cannot be used."
}
}
},
"Invalid Customer": {
"value": {
"code": 400,
"key": "invalid_customer",
"message": "Customer must be a holder of a loyalty card.",
"details": "AnsvocvP",
"request_id": "v-0c5e628bd14411244b",
"resource_id": "rf_0c5e628bf841c7f248",
"resource_type": "redemption",
"error": {
"message": "The customer is invalid."
}
}
},
"Voucher Inactive": {
"value": {
"code": 400,
"key": "voucher_not_active_now",
"message": "voucher not active now",
"details": "CODE14",
"request_id": "v-0c5e89b9300d820994",
"resource_id": "rf_0c5e89b945d33b9c02",
"resource_type": "redemption",
"error": {
"message": "The voucher is not active in the given timeframe."
}
}
}
}
}
}
}
}
}
},
"/client/v1/publish": {
"post": {
"operationId": "create-publication-client-side",
"tags": [
"Client-side"
],
"summary": "Create Publication (client-side)",
"description": "This method selects vouchers that are suitable for publication, adds a publish entry and returns the publication.\n\nA voucher is suitable for publication when it's active and hasn't been published yet. \n\n\n\n\nClearly define the source of the voucher\n\nYou 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.\n\n\n\n\n\nPublish multiple vouchers\n\nIn 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.\n\n\n\n\n\n\nAuto-update campaign\n\nIn case you want to ensure the number of publishable codes increases automatically with the number of customers, you should use an **auto-update** campaign.\n\n",
"parameters": [
{
"schema": {
"$ref": "#/components/schemas/ParameterBoolean"
},
"in": "query",
"name": "join_once",
"description": "Through this flag, you can control if a particular person gets only one and always the same code even if the app sends multiple publication requests. It means that if you have a referral program, a referrer is assigned only to one code if an integration sends publication requests more than once for the same customer."
}
],
"security": [
{
"X-App-Id": [],
"X-App-Token": []
},
{
"X-Voucherify-OAuth": [
"client_api",
"client_publish"
]
}
],
"requestBody": {
"description": "Specify the publication parameters.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ClientPublicationsCreateRequestBody"
},
"examples": {
"Example - Specific Voucher": {
"value": {
"campaign": {
"name": "campaign-name"
},
"customer": {
"source_id": "source-id",
"Name": "Customer Name",
"email": "customer email"
},
"voucher": "voucher-code",
"metadata": {
"key": "value"
}
}
},
"Example - Random Voucher": {
"value": {
"campaign": {
"name": "campaign-name",
"count": 1
},
"customer": {
"source_id": "source-id",
"Name": "Customer Name",
"email": "customer email"
},
"voucher": "voucher-code",
"metadata": {
"key": "value"
}
}
},
"Example 3": {
"value": {
"source_id": "publication_source_ID_10",
"campaign": "Test - Discount Effect - Amount - Items",
"channel": "myown",
"customer": {
"source_id": "pub_source_customer_5",
"name": "Bob Jones",
"description": "A frequent customer",
"email": "bob.smith@email.com",
"phone": "+1 933 222 3333",
"address": {
"city": "New York",
"country": "United States",
"line_1": "123 Main St.",
"line_2": "APT 3 BLG 5",
"postal_code": "10001",
"state": "NY"
},
"metadata": {
"lang": "en",
"test": true
},
"birthday": "1901-12-01"
},
"metadata": {
"year": 2022
}
}
}
}
}
},
"required": true
},
"responses": {
"200": {
"description": "Returns a publication object if a valid identifier was provided.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ClientPublicationsCreateResponseBody"
},
"examples": {
"Example": {
"value": {
"id": "pub_ocaXCa023ayJ3WL1ARxUeKgIvg3JcEGh",
"object": "publication",
"created_at": "2022-09-30T16:30:32.924Z",
"customer_id": "cust_BB6F97yf0XqCe7hxVUV7M4sS",
"tracking_id": "pub_source_customer_5",
"metadata": {
"year": 2022
},
"channel": "myown",
"source_id": "publication_source_ID_10",
"result": "SUCCESS",
"customer": {
"id": "cust_BB6F97yf0XqCe7hxVUV7M4sS",
"name": "Bob Jones",
"email": "bob.smith@email.com",
"source_id": "pub_source_customer_5",
"metadata": {
"lang": "en",
"test": true
},
"object": "customer"
},
"voucher": {
"id": "v_6Hy5FdNlu3dP65fJu5BgXma31Sl3rgkf",
"code": "cEsMn0uA",
"campaign": "Test - Discount Effect - Amount - Items",
"campaign_id": "camp_dphuwqH7BOVkgh4JmpDtS32l",
"category": null,
"category_id": null,
"type": "DISCOUNT_VOUCHER",
"discount": {
"type": "AMOUNT",
"amount_off": 300,
"effect": "APPLY_TO_ITEMS"
},
"gift": null,
"loyalty_card": null,
"start_date": null,
"expiration_date": null,
"validity_timeframe": null,
"validity_day_of_week": null,
"active": true,
"additional_info": null,
"metadata": {},
"assets": {
"qr": {
"id": "U2FsdGVkX188XVmOotyCyR2j3G8sJR8HzS3DQ+6J1OElPWSmjlEnthuJc7rkc7WIVxjT4pTl1JVVkHEuGXNXdzRik11H8S18HQeQFJFiuwLZ2mzEC2zZitEinyUxtZwhnEHoi0eGAgYCG7iVMNuOQA==",
"url": "{{internalVoucherifyURL}}"
},
"barcode": {
"id": "U2FsdGVkX18wDd9CcLM0Ef7aBfUSXZUoCQpuNpk4CHGOipbn+wFkfzcIZGBtUlxrI2KsXciCqF+c93AKzsymq5Yw8eEAFF/FK5f94z4/sgzaLDvyBmPCXHuS11Ew9S4ZEMjdTkUJftER2IlxWaCARA==",
"url": "{{internalVoucherifyURL}}"
}
},
"is_referral_code": false,
"created_at": "2022-09-30T16:30:32.956Z",
"updated_at": null,
"holder_id": "cust_BB6F97yf0XqCe7hxVUV7M4sS",
"redemption": {
"quantity": 1,
"redeemed_quantity": 0,
"object": "list",
"url": "/v1/vouchers/cEsMn0uA/redemptions?page=1&limit=10"
},
"publish": {
"object": "list",
"count": 1,
"url": "/v1/vouchers/cEsMn0uA/publications?page=1&limit=10"
},
"object": "voucher"
},
"vouchers_id": [
"v_6Hy5FdNlu3dP65fJu5BgXma31Sl3rgkf"
]
}
}
}
}
}
},
"400": {
"description": "Returns an error if a publication with the same source ID already exists in the system or some request body parameter is missing.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"Missing Parameters": {
"value": {
"code": 400,
"key": "missing_vouchers",
"message": "Missing vouchers",
"details": "Either Campaign or Voucher is required"
}
},
"Already published": {
"value": {
"code": 400,
"key": "voucher_already_published",
"message": "Voucher already published",
"details": "Voucher 'v_Y5P4UZ1yilkiYOIJmAAgWazUi1wfkNwF' has already been published",
"request_id": "v-0bc40bb800d5651137"
}
},
"Duplicate Source ID": {
"value": {
"code": 400,
"key": "duplicate_source_id",
"message": "Duplicate source_id",
"details": "Publication with source_id: 'publication_source_ID_1' already exists",
"request_id": "v-0bc40bf81555651191"
}
}
}
}
}
},
"404": {
"description": "Returns an error if a resource is not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"Campaign Not Found": {
"value": {
"code": 404,
"key": "not_found",
"message": "Resource not found",
"details": "Cannot find campaign with id 1",
"request_id": "v-0bc40546e5d56508e5",
"resource_id": "1",
"resource_type": "campaign"
}
}
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"ClientQualificationsCheckEligibilityRequestBody": {
"description": "Request body schema for **POST** `v1/qualifications`.",
"type": "object",
"title": "Client Qualifications Check Eligibility Request Body",
"properties": {
"customer": {
"description": "Customer's information.",
"allOf": [
{
"$ref": "#/components/schemas/Customer"
}
]
},
"order": {
"description": "Order information.",
"allOf": [
{
"$ref": "#/components/schemas/Order"
}
]
},
"tracking_id": {
"description": "Is correspondent to Customer's source_id",
"type": "string"
},
"scenario": {
"type": "string",
"description": "Defines the scenario Voucherify should consider during the qualification process.\n\n- `ALL` - Scenario that returns all redeemables available for the customer in one API request. This scenario is used by default when no value is selected.\n- `CUSTOMER_WALLET` - returns vouchers applicable to the customer's cart based on the vouchers assigned to the customer's profile.\n- `AUDIENCE_ONLY` - returns all vouchers, promotion tiers, and campaigns available to the customer. Voucherify validates the rules based on the customer profile only.\n- `PRODUCTS` - returns all promotions available for the products (when a discount is defined to be applied to the item or when the item is required in the validation rule).\n- `PRODUCTS_DISCOUNT` - returns all promotions available for products when a discount is defined as applicable to specific item(s).\n- `PROMOTION_STACKS` - returns the applicable promotion stacks.\n- `PRODUCTS_BY_CUSTOMER` - returns all promotions available for a customer for the products (when a discount is defined to be applied to the item or when the item is required in the validation rule).\n- `PRODUCTS_DISCOUNT_BY_CUSTOMER` - returns all promotions available for a customer for products when a discount is defined as applicable to specific item(s).",
"enum": [
"ALL",
"CUSTOMER_WALLET",
"AUDIENCE_ONLY",
"PRODUCTS",
"PRODUCTS_DISCOUNT",
"PROMOTION_STACKS",
"PRODUCTS_BY_CUSTOMER",
"PRODUCTS_DISCOUNT_BY_CUSTOMER"
]
},
"options": {
"allOf": [
{
"$ref": "#/components/schemas/QualificationsOption"
}
]
},
"session": {
"type": "object",
"description": "Parameter to return details about `locked_credits` on a gift card which has locked credits under a validation session.",
"properties": {
"type": {
"type": "string",
"description": "Parameter required to return the details about the `locked_credits`.",
"enum": [
"LOCK"
]
}
}
},
"metadata": {
"type": "object",
"description": "A set of key/value pairs that you can send in the request body to check against redeemables requiring **redemption** metadata validation rules to be satisfied. The validation runs against rules that are defined through the [Create Validation Rules](/api-reference/validation-rules/create-validation-rules) endpoint or with the [Validation Rule Builder](/personalize/create-validation-rules) in the the Dashboard."
}
}
},
"ClientQualificationsCheckEligibilityResponseBody": {
"description": "Response body schema for **POST** `v1/qualifications`.",
"title": "Client Qualifications Check Eligibility Response Body",
"type": "object",
"properties": {
"redeemables": {
"$ref": "#/components/schemas/QualificationsRedeemables"
},
"tracking_id": {
"type": "string",
"description": "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": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/OrderCalculated"
},
{
"type": "object",
"properties": {
"items": {
"type": "array",
"description": "Array of items applied to the order. It can include up to 500 items.",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/OrderCalculatedItem"
},
{
"type": "object",
"properties": {
"application_details": {
"$ref": "#/components/schemas/ApplicationDetails"
}
}
}
]
}
}
}
}
]
},
"stacking_rules": {
"$ref": "#/components/schemas/StackingRules"
}
}
},
"ParameterBoolean": {
"type": "boolean"
},
"ParameterLimit": {
"type": "integer",
"maximum": 100,
"minimum": 1
},
"ParameterInteger": {
"type": "integer"
},
"ParameterOrderListPromotionTiersClientSide": {
"type": "string",
"enum": [
"created_at",
"-created_at",
"updated_at",
"-updated_at"
]
},
"ClientPromotionsTiersListResponseBody": {
"type": "object",
"title": "Promotions Tiers List Response Body",
"description": "Response body schema for **GET** `v1/client/v1/promotions/tiers`.",
"allOf": [
{
"$ref": "#/components/schemas/PromotionTiersList"
}
]
},
"ClientRedemptionsRedeemRequestBody": {
"description": "Response body schema for **POST** `v1/redemptions`.",
"type": "object",
"title": "Client Redemptions Redeem Request Body",
"allOf": [
{
"type": "object",
"properties": {
"options": {
"type": "object",
"description": "Configure parameters returned in the response.",
"properties": {
"expand": {
"type": "array",
"description": "Expand array lets you configure params included in the response. Depending on the strings included in the array, the response will contain different details. \n\n| **Expand Option** | **Response Body** |\n|:---|:---|\n| [\"order\"] | - Same response as fallback response (without an options object).
- Order data with calculated discounts are listed in each child redeemable object.
- Metadata not included for each discount type. |\n| [\"redeemable\"] | Expands redeemable objects by including `metadata` for each discount type. |\n| [\"order\", \"redeemable\"] | - Order data with calculated discounts are listed in each child redeemable object.
- Includes `metadata` for each discount type. |\n| [\"redeemable\", \"redemption\", \"category\"] | - Returns each discount type's `metadata` in each child redemption object.
- Returns redemption object `metadata`.
- Returns an expanded `categories` object, showing details about the category. |",
"items": {
"type": "string",
"enum": [
"order",
"redemption",
"redeemable",
"category"
]
}
}
}
}
}
},
{
"$ref": "#/components/schemas/StackableValidateRedeemBase"
}
]
},
"ClientRedemptionsRedeemResponseBody": {
"description": "Response body schema for **POST** `v1/redemptions`.",
"type": "object",
"title": "Client Redemptions Redeem Response Body",
"properties": {
"redemptions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Redemption"
}
},
"parent_redemption": {
"$ref": "#/components/schemas/Redemption"
},
"order": {
"description": "Contains the order details associated with the redemption.",
"allOf": [
{
"$ref": "#/components/schemas/OrderCalculated"
},
{
"type": "object",
"properties": {
"items": {
"type": "array",
"description": "Array of items applied to the order. It can include up to 500 items.",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/OrderCalculatedItem"
},
{
"type": "object",
"properties": {
"application_details": {
"$ref": "#/components/schemas/ApplicationDetails"
}
}
}
]
}
}
}
}
]
},
"inapplicable_redeemables": {
"type": "array",
"description": "Lists validation results of each inapplicable redeemable.",
"items": {
"$ref": "#/components/schemas/ValidationsRedeemableInapplicable"
}
},
"skipped_redeemables": {
"type": "array",
"description": "Lists validation results of each redeemable. If a redeemable can be applied, the API returns `\"status\": \"APPLICABLE\"`.",
"items": {
"$ref": "#/components/schemas/ValidationsRedeemableSkipped"
}
}
}
},
"ClientValidationsValidateRequestBody": {
"description": "Request body schema for **POST** `v1/validations`.",
"title": "Client Validations Validate Request Body",
"allOf": [
{
"type": "object",
"properties": {
"options": {
"type": "object",
"description": "Configure parameters returned in the response.",
"properties": {
"expand": {
"type": "array",
"description": "The expand array lets you configure the parameters included in the response. Depending on the strings included in the array, the response will contain different details. \n\n| **Expand Option** | **Response Body** |\n|:---|:---|\n| [\"order\"] | - Same response as fallback response (without an options object).
- Order data with calculated discounts are listed in each child redeemable object.
- Metadata not included for each discount type. |\n| [\"redeemable\"] | Expands redeemable objects by including `metadata` for each discount type. |\n| [\"order\", \"redeemable\"] | - Order data with calculated discounts are listed in each child redeemable object.
- Includes `metadata` for each discount type. |\n| [\"category\"] | - Returns an expanded `categories` object, showing details about the category. |",
"items": {
"type": "string",
"enum": [
"order",
"redemption",
"redeemable",
"category"
]
}
}
}
}
}
},
{
"$ref": "#/components/schemas/StackableValidateRedeemBase"
}
]
},
"ClientValidationsValidateResponseBody": {
"description": "Response body schema for **POST** `/validations`.",
"title": "Client Validations Validate Response Body",
"allOf": [
{
"$ref": "#/components/schemas/ValidationsValidateResponseBody"
}
]
},
"e_400_invalid_payload": {
"title": "Invalid Payload",
"type": "object",
"description": "Error: Bad Request → Invalid Payload",
"properties": {
"code": {
"type": "integer",
"default": 400,
"description": "Error's HTTP status code."
},
"key": {
"type": "string",
"default": "invalid_payload",
"description": "Short string describing the kind of error which occurred."
},
"message": {
"type": "string",
"default": "Invalid payload",
"description": "A human-readable message providing a short description of the error."
},
"details": {
"type": "string",
"description": "A human-readable message providing more details about the error."
},
"request_id": {
"type": "string",
"example": "v-0a884c6be8c3756f42",
"description": "This ID is useful when troubleshooting and/or finding the root cause of an error response by our support team."
}
}
},
"ClientEventsCreateRequestBody": {
"description": "Request body schema for **POST** `v1/events`.",
"title": "Client Events Create Request Body",
"type": "object",
"properties": {
"event": {
"type": "string",
"description": "Event name. This is the same name that you used to define a custom event in the **Dashboard** > **Project Settings** > **Event Schema**.",
"minLength": 1,
"maxLength": 300
},
"customer": {
"description": "Customer's information.",
"allOf": [
{
"$ref": "#/components/schemas/Customer"
}
]
},
"referral": {
"type": "object",
"description": "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. ",
"properties": {
"code": {
"type": "string",
"description": "A code through which a new visitor has been referred to a service."
},
"referrer_id": {
"type": "string",
"description": "Unique ID of the referring person - it is optional and not required if the referral **code** is provided.",
"example": "cust_Vzck5i8U3OhcEUFY6MKhN9Rv"
}
},
"required": [
"code"
]
},
"loyalty": {
"type": "object",
"description": "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.",
"properties": {
"code": {
"type": "string",
"description": "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"
}
},
"required": [
"code"
]
},
"metadata": {
"type": "object",
"description": "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**."
}
},
"required": [
"event",
"customer"
]
},
"ClientEventsCreateResponseBody": {
"description": "Response body schema for **POST** `v1/events`.",
"title": "Client Events Create Response Body",
"type": "object",
"properties": {
"object": {
"type": "string",
"default": "event",
"description": "The object represented is an `event`.",
"enum": [
"event"
]
},
"type": {
"type": "string",
"description": "The event name."
},
"customer": {
"description": "A simple customer object",
"allOf": [
{
"$ref": "#/components/schemas/SimpleCustomerRequiredObjectType"
}
]
},
"referral": {
"type": "object",
"nullable": true,
"default": null,
"description": "A `null` referral object."
},
"loyalty": {
"type": "object",
"nullable": true,
"default": null,
"description": "A `null` loyalty object."
},
"metadata": {
"type": "object"
}
},
"required": [
"object",
"type",
"customer",
"referral",
"loyalty",
"metadata"
]
},
"Error": {
"title": "Error Object",
"type": "object",
"description": "Error details",
"properties": {
"code": {
"type": "integer",
"description": "Error's HTTP status code."
},
"key": {
"type": "string",
"description": "Short string describing the kind of error which occurred."
},
"message": {
"type": "string",
"description": "A human-readable message providing a short description of the error."
},
"details": {
"type": "string",
"description": "A human-readable message providing more details about the error."
},
"request_id": {
"type": "string",
"example": "v-0a885062c80375740f",
"description": "This ID is useful when troubleshooting and/or finding the root cause of an error response by our support team."
},
"resource_id": {
"type": "string",
"description": "Unique resource ID that can be used in another endpoint to get more details.",
"example": "rf_0c5d710a87c8a31f86"
},
"resource_type": {
"type": "string",
"description": "The resource type.",
"example": "voucher"
},
"error": {
"type": "object",
"description": "Includes additional information about the error.",
"properties": {
"message": {
"type": "string",
"description": "The message configured by the user in a validation rule."
}
}
}
},
"required": [
"code",
"message"
]
},
"ParameterCode": {
"type": "string",
"example": "2CpRCE2c"
},
"ParameterString": {
"type": "string"
},
"ParameterSessionKey": {
"type": "string",
"example": "ssn_yQGMTeKBSw8OOuFPwlBEjzGy8d8VA9Ts"
},
"ParameterSessionTtlUnit": {
"type": "string",
"enum": [
"HOURS",
"DAYS",
"MINUTES",
"SECONDS",
"MILLISECONDS",
"MICROSECONDS",
"NANOSECONDS"
]
},
"ParameterCustomerValidateVoucherClientSide": {
"oneOf": [
{
"type": "object",
"title": "Customer details",
"description": "Customer source ID and/or customer metadata.",
"properties": {
"source_id": {
"type": "string",
"description": "Customer source ID.",
"example": "name.lastname@email.com"
},
"metadata": {
"type": "object",
"description": "A set of custom key/value pairs that you can attach to a customer. The metadata object stores all custom attributes assigned to the customer. It can be useful for storing additional information about the customer in a structured format. This metadata can be used for validating whether the customer qualifies for a discount or it can be used in building customer segments."
}
}
},
{
"type": "string",
"title": "Customer ID",
"description": "Unique customer ID assigned by Voucherify, i.e. `cust_eWgXlBBiY6THFRJwX45Iakv4`.",
"example": "cust_eWgXlBBiY6THFRJwX45Iakv4"
}
]
},
"ParameterOrderMetadata": {
"type": "object",
"title": "Order details",
"description": "Order details.",
"properties": {
"metadata": {
"type": "object",
"description": "The metadata object stores all custom attributes assigned to the order. A set of key/value pairs that are attached to an order object. Stores additional information about the order in a structured format."
}
}
},
"6_res_validate_voucher": {
"title": "Valid",
"description": "Response schema model for validating a voucher using **POST** `v1/vouchers/{code}/validate`.",
"oneOf": [
{
"$ref": "#/components/schemas/6_res_validate_voucher_discount_code"
},
{
"$ref": "#/components/schemas/6_res_validate_voucher_gift_card"
},
{
"$ref": "#/components/schemas/6_res_validate_voucher_loyalty_card"
}
]
},
"6_res_validate_voucher_false": {
"type": "object",
"title": "Not Valid",
"description": "Response schema for a voucher that is not valid.",
"properties": {
"valid": {
"type": "boolean",
"default": false,
"description": "Indicates whether the voucher is valid within the context of the parameters provided in the request body."
},
"reason": {
"type": "string",
"description": "System generated cause for the voucher being invalid in the context of the provided parameters."
},
"error": {
"type": "object",
"description": "Detailed failure cause for the invalid voucher if the reason has a translation defined in the Dashboard → Project Settings → Error Messages.",
"properties": {
"message": {
"type": "string",
"description": "Customized error message."
}
}
},
"tracking_id": {
"type": "string",
"description": "Hashed customer source ID."
},
"code": {
"type": "string",
"description": "Voucher code."
},
"metadata": {
"type": "object",
"description": "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."
}
}
},
"7_req_redeem_voucher": {
"title": "Redeem Voucher Request Body",
"description": "Request body schema for redeeming a voucher using **POST** `v1/vouchers/{code}/redemption`.",
"oneOf": [
{
"$ref": "#/components/schemas/7_req_redeem_voucher_discount_code"
},
{
"$ref": "#/components/schemas/7_req_redeem_voucher_gift_card"
},
{
"$ref": "#/components/schemas/7_req_redeem_voucher_loyalty_card"
}
]
},
"7_res_redeem_voucher": {
"title": "Redeem Voucher Response Body",
"description": "Response body schema for **POST** `v1/vouchers/{code}/redemption`.",
"allOf": [
{
"$ref": "#/components/schemas/7_obj_redemption_object_voucher_extended"
}
]
},
"e_error_expanded": {
"title": "Error Object",
"type": "object",
"description": "Error details",
"properties": {
"code": {
"type": "integer",
"description": "Error's HTTP status code."
},
"key": {
"type": "string",
"description": "Short string describing the kind of error which occurred."
},
"message": {
"type": "string",
"description": "A human-readable message providing a short description of the error."
},
"details": {
"type": "string",
"description": "A human-readable message providing more details about the error."
},
"request_id": {
"type": "string",
"example": "v-0a885062c80375740f",
"description": "This ID is useful when troubleshooting and/or finding the root cause of an error response by our support team."
},
"resource_id": {
"type": "string",
"description": "Unique resource ID that can be used in another endpoint to get more details.",
"example": "rf_0c5d710a87c8a31f86"
},
"resource_type": {
"type": "string",
"description": "The resource type.",
"example": "redemption"
},
"error": {
"type": "object",
"description": "Contains custom user-defined error message translation.",
"properties": {
"message": {
"type": "string",
"description": "Error message translation defined in Dashboard → Project Settings → Error Messages"
}
}
}
}
},
"ClientPublicationsCreateRequestBody": {
"title": "Client Publications Create Request Body",
"description": "Request body schema for **POST** `v1/publish`.",
"oneOf": [
{
"$ref": "#/components/schemas/CreatePublicationWithSpecificVoucher"
},
{
"$ref": "#/components/schemas/CreatePublicationWithCampaign"
}
]
},
"ClientPublicationsCreateResponseBody": {
"title": "Client Publications Create Response Body",
"type": "object",
"description": "Response body schema for **POST** `v1/publish`",
"oneOf": [
{
"$ref": "#/components/schemas/PublicationsCreateVoucherResponseBody"
},
{
"$ref": "#/components/schemas/PublicationsCreateVouchersResponseBody"
}
]
},
"Customer": {
"title": "Customer",
"allOf": [
{
"type": "object",
"title": "Customer Id And Source Id",
"properties": {
"id": {
"type": "string",
"description": "The ID of an existing customer."
},
"source_id": {
"type": "string",
"description": "A unique identifier of the customer who validates a voucher. It can be a customer ID or email from a CRM system, database, or a third-party service. If you also pass a customer ID (unique ID assigned by Voucherify), the source ID will be ignored."
}
}
},
{
"$ref": "#/components/schemas/CustomerBase"
}
]
},
"Order": {
"title": "Order",
"type": "object",
"description": "Order information.",
"allOf": [
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique ID assigned by Voucherify of an existing order that will be linked to the redemption of this request."
}
}
},
{
"$ref": "#/components/schemas/OrderBase"
}
]
},
"QualificationsOption": {
"type": "object",
"description": "Configure parameters returned in the response.",
"properties": {
"limit": {
"type": "integer",
"description": "The maximum number of redeemables to be returned in the API request. The actual number of returned redeemables will be determined by the API. The default value is set to 5",
"maximum": 50
},
"starting_after": {
"type": "string",
"nullable": true,
"example": "2021-09-08T13:52:18.227Z",
"format": "date-time",
"description": "Cursor used for paging."
},
"filters": {
"type": "object",
"description": "A set of filters to return only a specific category or type of redeemable.",
"properties": {
"junction": {
"$ref": "#/components/schemas/Junction"
},
"category_id": {
"$ref": "#/components/schemas/QualificationsFieldConditions"
},
"campaign_id": {
"$ref": "#/components/schemas/QualificationsFieldConditions"
},
"campaign_type": {
"title": "Qualifications Campaign Type Conditions",
"type": "object",
"description": "Returns both campaigns and their vouchers or promotion tiers. Use other filters, e.g. `resource_type`, to narrow down the results.",
"properties": {
"conditions": {
"description": "Data filters used to narrow down the data records to be returned in the result.",
"type": "object",
"properties": {
"$is": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ParameterCampaignType"
}
},
"$is_not": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ParameterCampaignType"
}
},
"$in": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ParameterCampaignType"
}
},
"$not_in": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ParameterCampaignType"
}
}
}
}
}
},
"resource_id": {
"$ref": "#/components/schemas/QualificationsFieldConditions"
},
"resource_type": {
"type": "object",
"properties": {
"conditions": {
"description": "Data filters used to narrow down the data records to be returned in the result.\n- `campaign` refers to campaigns;\n- `voucher` refers to generic (standalone) vouchers or published vouchers;\n- `promotion_tier` refers to promotion tiers.",
"type": "object",
"properties": {
"$is": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ResourceTypes"
}
},
"$is_not": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ResourceTypes"
}
},
"$in": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ResourceTypes"
}
},
"$not_in": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ResourceTypes"
}
}
}
}
}
},
"voucher_type": {
"$ref": "#/components/schemas/QualificationsFieldConditions"
},
"code": {
"$ref": "#/components/schemas/QualificationsFieldConditions"
},
"holder_role": {
"title": "Holder Role Field Conditions",
"type": "object",
"properties": {
"conditions": {
"description": "Data filters used to narrow down the data records to be returned in the result.",
"type": "object",
"properties": {
"$is": {
"type": "array",
"description": "Will return records only for the first value in the array.",
"items": {
"enum": [
"OWNER",
"REFERRER",
"REFEREE"
]
}
},
"$is_not": {
"type": "array",
"description": "Will return records only for the first value in the array.",
"items": {
"enum": [
"OWNER",
"REFERRER",
"REFEREE"
]
}
},
"$in": {
"type": "array",
"description": "Will return records for the values in the array.",
"items": {
"enum": [
"OWNER",
"REFERRER",
"REFEREE"
]
}
},
"$not_in": {
"type": "array",
"description": "Will return records for the values in the array.",
"items": {
"enum": [
"OWNER",
"REFERRER",
"REFEREE"
]
}
}
}
}
}
}
}
},
"expand": {
"type": "array",
"description": "The expand array lets you configure the parameters included in the response. Depending on the strings included in the array, the response will contain different details. \n\n| **Expand Option** | **Response Body** |\n|:---|:---|\n| [`\"redeemable\"`] | Returns the redeemables':
- metadata
- redeemable name,
- campaign name,
- campaign ID|\n| [`\"category\"`] | - Returns an expanded `categories` object, showing details about the category. |\n| [`\"validation_rules\"`] | - Returns an expanded `validation_rules` object, showing details about the validation rules. |",
"items": {
"type": "string",
"enum": [
"redeemable",
"category",
"validation_rules"
]
}
},
"sorting_rule": {
"type": "string",
"description": "Is used to determine the order in which data is displayed in the result array. \n\n - `DEFAULT` - Sorting descending by `created_at` \n - `BEST_DEAL` - Sorting descending by `total_applied_discount_amount` \n - `LEAST_DEAL` - Sorting ascending by `total_applied_discount_amount`",
"enum": [
"BEST_DEAL",
"LEAST_DEAL",
"DEFAULT"
]
}
}
},
"QualificationsRedeemables": {
"title": "Redeemables",
"type": "object",
"description": "List of redeemables for examine qualification.",
"properties": {
"object": {
"type": "string",
"default": "list",
"description": "The type of the object represented by JSON. Default is `list`.",
"enum": [
"list"
]
},
"data_ref": {
"type": "string",
"default": "data",
"description": "Identifies the name of the attribute that contains the array of qualified redeemables.",
"enum": [
"data"
]
},
"data": {
"type": "array",
"description": "Array of qualified redeemables.",
"items": {
"$ref": "#/components/schemas/QualificationsRedeemable"
}
},
"total": {
"type": "integer",
"example": 5,
"description": "The number of redeemables returned in the API request."
},
"has_more": {
"type": "boolean",
"description": "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": {
"type": "string",
"description": "Timestamp representing the date and time to use in `starting_after` cursor to get more redeemables.",
"format": "date-time",
"example": "2023-10-31T12:13:16.374Z"
}
},
"required": [
"object",
"data_ref",
"data",
"total",
"has_more"
]
},
"OrderCalculated": {
"title": "Order Calculated No Customer Data",
"type": "object",
"description": "Order information.",
"properties": {
"id": {
"type": "string",
"description": "Unique ID assigned by Voucherify of an existing order that will be linked to the redemption of this request."
},
"source_id": {
"type": "string",
"nullable": true,
"description": "Unique source ID of an existing order that will be linked to the redemption of this request."
},
"status": {
"type": "string",
"description": "The order status.",
"enum": [
"CREATED",
"PAID",
"CANCELED",
"FULFILLED"
]
},
"amount": {
"type": "integer",
"description": "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": {
"type": "integer",
"description": "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": {
"type": "integer",
"description": "Sum of all order-level discounts applied to the order. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for $1.00)."
},
"items_discount_amount": {
"type": "integer",
"description": "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": {
"type": "integer",
"description": "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": {
"type": "integer",
"description": "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": {
"type": "integer",
"description": "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": {
"type": "integer",
"description": "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). \n`sum(items, i => i.applied_discount_amount)`"
},
"total_applied_discount_amount": {
"type": "integer",
"description": "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). \n`total_applied_discount_amount` = `applied_discount_amount` + `items_applied_discount_amount`"
},
"metadata": {
"type": "object",
"description": "A set of custom key/value pairs that you can attach to an order. It can be useful for storing additional information about the order in a structured format. It can be used to define business validation rules or discount formulas."
},
"object": {
"type": "string",
"description": "The type of the object represented by JSON.",
"default": "order",
"enum": [
"order"
]
},
"created_at": {
"type": "string",
"example": "2021-12-22T10:13:06.487Z",
"description": "Timestamp representing the date and time when the order was created. The value is shown in the ISO 8601 format.",
"format": "date-time"
},
"updated_at": {
"type": "string",
"nullable": true,
"example": "2021-12-22T10:14:45.316Z",
"format": "date-time",
"description": "Timestamp representing the date and time when the order was last updated in ISO 8601 format."
},
"customer_id": {
"type": "string",
"nullable": true,
"description": "Unique customer identifier of the customer making the purchase. The ID is assigned by Voucherify.",
"example": "cust_7iUa6ICKyU6gH40dBU25kQU1"
},
"referrer_id": {
"type": "string",
"nullable": true,
"description": "Unique referrer ID.",
"example": "cust_nM4jqPiaXUvQdVSA6vTRUnix"
},
"customer": {
"allOf": [
{
"$ref": "#/components/schemas/CustomerId"
}
]
},
"referrer": {
"allOf": [
{
"$ref": "#/components/schemas/ReferrerId"
}
]
},
"redemptions": {
"type": "object",
"additionalProperties": {
"$ref": "#/components/schemas/OrderRedemptionsEntry"
}
}
}
},
"OrderCalculatedItem": {
"type": "object",
"title": "Order Item Calculated",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the order line item."
},
"sku_id": {
"type": "string",
"description": "Unique identifier of the SKU. It is assigned by Voucherify."
},
"product_id": {
"type": "string",
"description": "Unique identifier of the product. It is assigned by Voucherify."
},
"related_object": {
"type": "string",
"enum": [
"product",
"sku"
],
"description": "Used along with the source_id property, can be set to either sku or product."
},
"source_id": {
"type": "string",
"description": "The merchant's product/SKU ID (if it is different from the Voucherify product/SKU ID). It is useful in the integration between multiple systems. It can be an ID from an eCommerce site, a database, or a third-party service."
},
"quantity": {
"type": "integer",
"description": "The quantity of the particular item in the cart."
},
"discount_quantity": {
"type": "integer",
"description": "Number of dicounted items."
},
"initial_quantity": {
"type": "integer",
"description": "A positive integer in the smallest unit quantity representing the total amount of the order; this is the sum of the order items' quantity."
},
"amount": {
"type": "integer",
"description": "The total amount of the order item (price * quantity)."
},
"discount_amount": {
"type": "integer",
"description": "Sum of all order-item-level discounts applied to the order."
},
"applied_discount_amount": {
"type": "integer",
"description": "This field shows the order-level discount applied."
},
"applied_discount_quantity": {
"type": "integer",
"description": "Number of the discounted items applied in the transaction."
},
"applied_quantity": {
"type": "integer",
"description": "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": {
"type": "integer",
"description": "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": {
"type": "integer",
"description": "A positive integer in the smallest currency unit (e.g. 100 cents for $1.00) representing the total amount of the order. This is the sum of the order items' amounts."
},
"price": {
"type": "integer",
"description": "Unit price of an item. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `$100.00`."
},
"subtotal_amount": {
"type": "integer",
"description": "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`. \n`subtotal_amount`=`amount`-`applied_discount_amount`"
},
"product": {
"type": "object",
"description": "An object containing details of the related product.",
"properties": {
"id": {
"type": "string",
"description": "A unique identifier that represents the product and is assigned by Voucherify."
},
"source_id": {
"type": "string",
"description": "The merchant's product ID (if it is different than Voucherify's product ID). It is really useful in case of integration between multiple systems. It can be an ID from an eCommerce site, a database or a 3rd party service."
},
"override": {
"type": "boolean",
"description": "The override set to `true` is used to store the product information in the system. If the product does not exist, it will be created with a source_id; if it does exist, the provided values for the name, price, and metadata will replace those already stored in the system."
},
"name": {
"type": "string",
"description": "Product name."
},
"metadata": {
"type": "object",
"description": "A set of custom key/value pairs that you can attach to a product. It can be useful for storing additional information about the product in a structured format. It can be used to create product collections."
},
"price": {
"type": "number",
"description": "Product price. A positive integer in the smallest currency unit (e.g. 100 cents for $1.00)."
}
}
},
"sku": {
"type": "object",
"description": "An object containing details of the related SKU.",
"properties": {
"id": {
"type": "string",
"description": "A unique identifier that represents the SKU and is assigned by Voucherify."
},
"source_id": {
"type": "string",
"description": "The merchant's SKU ID (if it is different than Voucherify's SKU ID). It is really useful in case of integration between multiple systems. It can be an ID from an eCommerce site, a database or a 3rd party service."
},
"override": {
"type": "boolean",
"description": "The override set to `true` is used to store the product information in the system. If the product does not exist, it will be created with a source_id; if it does exist, the provided values for the name, price, and metadata will replace those already stored in the system."
},
"sku": {
"type": "string",
"description": "The SKU name."
},
"price": {
"type": "number",
"description": "SKU price. A positive integer in the smallest currency unit (e.g. 100 cents for $1.00)."
},
"metadata": {
"type": "object",
"description": "A set of custom key/value pairs that you can attach to an 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": {
"type": "string",
"default": "order_item",
"enum": [
"order_item"
],
"description": "The type of the object represented by JSON."
},
"metadata": {
"type": "object",
"description": "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."
}
},
"required": [
"object"
]
},
"ApplicationDetails": {
"type": "array",
"description": "Array containing details about the items that are replaced and the items that are replacements for discounts with the `REPLACE_ITEMS` effect.",
"items": {
"type": "object",
"description": "Object representing item replacement.",
"properties": {
"source_index": {
"type": "integer",
"description": "Index number of the source item that is replaced. The enumeration starts from `0`, which represents the first item in the request, e.g., if the replaced item is passed as the second in the request, `source_index` equals `3`.",
"minimum": 0
},
"source_applied_quantity": {
"type": "integer",
"description": "Number of source units that are replaced.",
"maximum": -1
},
"source_applied_quantity_amount": {
"type": "integer",
"description": "Amount equal to the price of the units that are replaced. Determines the change of the amount of the source item quantity.",
"maximum": 0
},
"target_index": {
"type": "integer",
"description": "Index number of the target item that is a replacement of the source item. The enumeration continues the values for the order items, e.g. if there are three items in the request, `target_index` equals `3`, as enumeration starts from `0`."
},
"target_applied_quantity": {
"type": "integer",
"description": "Number of added target units that are replacements."
},
"target_applied_quantity_amount": {
"type": "integer",
"description": "Amount equal to the price of the units that are replacements. Determines the change in the amount of the target item quantity."
},
"target_applied_discount_amount": {
"type": "integer",
"description": "Discount amount applied to the target item with regard to the replacement. Equals the `target_applied_quantity_amount` minus `source_applied_quantity_amount`."
}
}
}
},
"StackingRules": {
"type": "object",
"title": "Stacking Rules",
"description": "Defines stacking rules for redeemables. Read more in the [Stacking Rule Documentation](/orchestrate/stacking-rules).",
"properties": {
"redeemables_limit": {
"type": "integer",
"description": "Defines how many redeemables can be sent in one request. Note: more redeemables means more processing time.",
"default": 30,
"maximum": 30,
"minimum": 1
},
"applicable_redeemables_limit": {
"type": "integer",
"description": "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`.",
"default": 5,
"maximum": 30,
"minimum": 1
},
"applicable_redeemables_per_category_limit": {
"type": "integer",
"description": "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`.",
"default": 1,
"maximum": 30,
"minimum": 1
},
"applicable_redeemables_category_limits": {
"type": "object",
"description": "Lists categories by category IDs (keys) and defines their limits (values) of applicable redeemables that belong to campaigns with that category.",
"additionalProperties": {
"type": "integer",
"description": "Limit of applicable redeemables per category.",
"minimum": 1,
"maximum": 10
}
},
"applicable_exclusive_redeemables_limit": {
"type": "integer",
"description": "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`.",
"default": 1,
"maximum": 5,
"minimum": 1
},
"applicable_exclusive_redeemables_per_category_limit": {
"type": "integer",
"description": "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`.",
"default": 1,
"maximum": 5,
"minimum": 1
},
"exclusive_categories": {
"type": "array",
"description": "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.",
"items": {
"type": "string"
}
},
"joint_categories": {
"type": "array",
"description": "Lists the IDs of the joint categories. A campaign with a joint category is always applied regardless of the exclusivity of other campaigns.",
"items": {
"type": "string"
}
},
"redeemables_application_mode": {
"type": "string",
"description": "Defines the application mode for redeemables.\n`\"ALL\"` means that all redeemables must be validated for the redemption to be successful.\n`\"PARTIAL\"` means that only those redeemables that can be validated will be redeemed. The redeemables that fail validaton will be skipped.",
"enum": [
"ALL",
"PARTIAL"
]
},
"redeemables_sorting_rule": {
"type": "string",
"description": "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.",
"enum": [
"CATEGORY_HIERARCHY",
"REQUESTED_ORDER"
],
"default": "REQUESTED_ORDER"
},
"redeemables_products_application_mode": {
"type": "string",
"description": "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.",
"enum": [
"STACK",
"ONCE"
]
},
"redeemables_no_effect_rule": {
"type": "string",
"description": "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.",
"enum": [
"REDEEM_ANYWAY",
"SKIP"
]
},
"no_effect_skip_categories": {
"type": "array",
"description": "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`.",
"items": {
"type": "string"
}
},
"no_effect_redeem_anyway_categories": {
"type": "array",
"description": "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`.",
"items": {
"type": "string"
}
},
"redeemables_rollback_order_mode": {
"type": "string",
"description": "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.",
"enum": [
"WITH_ORDER",
"WITHOUT_ORDER"
]
}
},
"required": [
"redeemables_limit",
"applicable_redeemables_limit",
"applicable_exclusive_redeemables_limit",
"applicable_redeemables_per_category_limit",
"applicable_redeemables_category_limits",
"exclusive_categories",
"joint_categories",
"redeemables_application_mode",
"redeemables_sorting_rule",
"redeemables_no_effect_rule",
"no_effect_skip_categories",
"no_effect_redeem_anyway_categories",
"redeemables_products_application_mode",
"redeemables_rollback_order_mode"
]
},
"ParameterOrigin": {
"type": "string",
"format": "hostname"
},
"PromotionTiersList": {
"type": "object",
"description": "Promotion Tiers",
"title": "Promotion Tiers",
"properties": {
"object": {
"type": "string",
"default": "list",
"description": "The type of the object represented by JSON. This object stores information about promotion tiers in a dictionary."
},
"data_ref": {
"type": "string",
"default": "tiers",
"description": "Identifies the name of the attribute that contains the array of promotion tier objects."
},
"tiers": {
"type": "array",
"description": "Contains array of promotion tier objects.",
"items": {
"$ref": "#/components/schemas/PromotionTier"
}
},
"total": {
"type": "integer",
"description": "Total number of promotion tiers."
},
"has_more": {
"type": "boolean",
"description": "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."
}
}
},
"StackableValidateRedeemBase": {
"title": "Stackable Validate Redeem Base",
"type": "object",
"properties": {
"redeemables": {
"type": "array",
"minItems": 1,
"maxItems": 30,
"description": "An array of redeemables. You can combine `voucher`(s) and `promotion_tier`(s). Alternatively, send one unique`promotion_stack` in the array. Each unique redeemable can be sent in one request only once.",
"items": {
"title": "Stackable Validate Redeem Base Redeemables Item",
"oneOf": [
{
"$ref": "#/components/schemas/RedeemVoucher"
},
{
"$ref": "#/components/schemas/RedeemPromotionTier"
},
{
"$ref": "#/components/schemas/RedeemPromotionStack"
},
{
"$ref": "#/components/schemas/RedeemGiftCard"
},
{
"$ref": "#/components/schemas/RedeemLoyaltyCard"
}
]
}
},
"order": {
"description": "Order information.",
"allOf": [
{
"$ref": "#/components/schemas/Order"
}
]
},
"customer": {
"description": "Customer's information.",
"allOf": [
{
"$ref": "#/components/schemas/Customer"
}
]
},
"session": {
"description": "Schema model for session lock object. The session object is required to establish a session between multiple parallel validation and redemption requests. If you only send the type parameter in the request, then by default the session lock will be established for 7 days. Read more on establishing a validation session.",
"allOf": [
{
"$ref": "#/components/schemas/Session"
}
]
},
"tracking_id": {
"description": "Is correspondent to Customer's source_id",
"type": "string"
},
"metadata": {
"type": "object",
"description": "A set of key/value pairs that you can attach to a redemption object. It can be useful for storing additional information about the redemption in a structured format."
}
},
"required": [
"redeemables"
]
},
"Redemption": {
"title": "Redemption",
"type": "object",
"description": "This is an object representing a redemption for **POST** `v1/redemptions` and **POST** `/client/v1/redemptions`.",
"allOf": [
{
"$ref": "#/components/schemas/RedemptionBase"
},
{
"type": "object",
"properties": {
"voucher": {
"description": "Defines the details of the voucher being redeemed.",
"allOf": [
{
"$ref": "#/components/schemas/VoucherWithStackingRulesTypeCategories"
},
{
"$ref": "#/components/schemas/VoucherHolder"
}
]
}
}
}
]
},
"ValidationsRedeemableInapplicable": {
"type": "object",
"title": "Inapplicable Redeemable",
"properties": {
"status": {
"type": "string",
"default": "INAPPLICABLE",
"enum": [
"INAPPLICABLE"
],
"description": "Indicates whether the redeemable can be applied or not applied based on the validation rules."
},
"id": {
"type": "string",
"description": "Redeemable ID, i.e. the voucher code."
},
"object": {
"type": "string",
"description": "Redeemable's object type.",
"enum": [
"voucher",
"promotion_tier"
]
},
"result": {
"type": "object",
"description": "Includes the error object with details about the reason why the redeemable is inapplicable",
"properties": {
"error": {
"$ref": "#/components/schemas/Error"
},
"details": {
"type": "object",
"description": "Provides details about the reason why the redeemable is inapplicable.",
"properties": {
"message": {
"type": "string",
"description": "Generic message from the `message` string shown in the `error` object or the message configured in a validation rule."
},
"key": {
"type": "string",
"description": "Generic message from the `key` string shown in the `error` object."
}
}
},
"bundle": {
"$ref": "#/components/schemas/Bundle"
}
}
},
"metadata": {
"type": "object",
"description": "The metadata object stores all custom attributes in the form of key/value pairs assigned to the redeemable."
},
"categories": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CategoryWithStackingRulesType"
}
},
"campaign_name": {
"type": "string",
"description": "Campaign name. Displayed only if the `options.expand` is passed with a `redeemable` value in the validation request body."
},
"campaign_id": {
"type": "string",
"description": "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": {
"type": "string",
"description": "Name of the promotion tier. Displayed only if the `options.expand` is passed with a `redeemable` value in the validation request body."
}
},
"required": [
"status",
"id",
"object",
"result"
]
},
"ValidationsRedeemableSkipped": {
"type": "object",
"title": "Skipped Redeemable",
"properties": {
"status": {
"type": "string",
"default": "SKIPPED",
"enum": [
"SKIPPED"
],
"description": "Indicates whether the redeemable can be applied or not applied based on the validation rules."
},
"id": {
"type": "string",
"description": "Redeemable ID, i.e. the voucher code."
},
"object": {
"type": "string",
"description": "Redeemable's object type.",
"enum": [
"voucher",
"promotion_tier"
]
},
"result": {
"type": "object",
"description": "Provides details about the reason why the redeemable is skipped.",
"properties": {
"details": {
"oneOf": [
{
"$ref": "#/components/schemas/ValidationsRedeemableSkippedResultLimitExceeded"
},
{
"$ref": "#/components/schemas/ValidationsRedeemableSkippedResultCategoryLimitExceeded"
},
{
"$ref": "#/components/schemas/ValidationsRedeemableSkippedResultRedeemablesLimitExceeded"
},
{
"$ref": "#/components/schemas/ValidationsRedeemableSkippedResultRedeemablesCategoryLimitExceeded"
},
{
"$ref": "#/components/schemas/ValidationsRedeemableSkippedResultExclusionRulesNotMet"
},
{
"$ref": "#/components/schemas/ValidationsRedeemableSkippedResultPrecedingValidationFailed"
},
{
"$ref": "#/components/schemas/ValidationsRedeemableSkippedResultNoEffect"
}
]
}
}
},
"metadata": {
"type": "object",
"description": "The metadata object stores all custom attributes in the form of key/value pairs assigned to the redeemable."
},
"categories": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CategoryWithStackingRulesType"
}
},
"campaign_name": {
"type": "string",
"description": "Campaign name. Displayed only if the `options.expand` is passed with a `redeemable` value in the validation request body."
},
"campaign_id": {
"type": "string",
"description": "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": {
"type": "string",
"description": "Name of the promotion tier. Displayed only if the `options.expand` is passed with a `redeemable` value in the validation request body."
}
},
"required": [
"status",
"id",
"object",
"result"
]
},
"ValidationsValidateResponseBody": {
"title": "Validations Validate Response Body",
"description": "Response body schema for **POST** `v1/validations`.",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the validation, assigned by Voucherify.",
"example": "valid_101740aa2869354c6d"
},
"valid": {
"type": "boolean",
"description": "The result of the validation. It takes all of the redeemables into account and returns a `false` if at least one redeemable is inapplicable. Returns `true` if all redeemables are applicable."
},
"redeemables": {
"type": "array",
"description": "Lists validation results of each redeemable. If `redeemables_application_mode` is `PARTIAL` in the `stacking_rules` object, all redeemables here will be `APPLICABLE`. Read more in [the Stacking rules article](/orchestrate/stacking-rules).",
"items": {
"title": "Validations Validate All Response Body Redeemables Item",
"oneOf": [
{
"$ref": "#/components/schemas/ValidationsRedeemableApplicable"
},
{
"$ref": "#/components/schemas/ValidationsRedeemableInapplicable"
},
{
"$ref": "#/components/schemas/ValidationsRedeemableSkipped"
}
]
}
},
"skipped_redeemables": {
"type": "array",
"description": "Lists validation results of each skipped redeemable.",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/ValidationsRedeemableSkipped"
}
]
}
},
"inapplicable_redeemables": {
"type": "array",
"description": "Lists validation results of each inapplicable redeemable.",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/ValidationsRedeemableInapplicable"
}
]
}
},
"order": {
"allOf": [
{
"$ref": "#/components/schemas/OrderCalculated"
},
{
"type": "object",
"properties": {
"items": {
"type": "array",
"description": "Array of items applied to the order. It can include up to 500 items.",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/OrderCalculatedItem"
},
{
"type": "object",
"properties": {
"application_details": {
"$ref": "#/components/schemas/ApplicationDetails"
}
}
}
]
}
}
}
}
]
},
"tracking_id": {
"type": "string",
"example": "track_VAVo1/z+G2GI2LPw==",
"description": "Hashed customer source ID."
},
"session": {
"$ref": "#/components/schemas/Session"
},
"stacking_rules": {
"description": "Defines stacking rules for redeemables. Read more in the [Stacking Rule Documentation](/orchestrate/stacking-rules).",
"allOf": [
{
"$ref": "#/components/schemas/StackingRules"
}
]
}
},
"required": [
"valid",
"redeemables",
"stacking_rules"
]
},
"SimpleCustomerRequiredObjectType": {
"type": "object",
"description": "This is an object representing a customer with limited properties used in Event Tracking endpoints.",
"title": "Customer Object Required Object Type",
"properties": {
"id": {
"type": "string",
"description": "The unique ID of a customer that is assigned by Voucherify.",
"example": "cust_CSnYd37MXmrbS19XCrghjBsv"
},
"source_id": {
"type": "string",
"description": "The merchant's customer ID if it is different from the Voucherify customer ID. It is really useful in case of an integration between multiple systems. It can be a customer ID from a CRM system, database or 3rd-party service."
},
"name": {
"type": "string",
"description": "Customer's first and last name."
},
"email": {
"type": "string",
"description": "Customer's email address."
},
"metadata": {
"type": "object",
"description": "A set of custom key/value pairs that you can attach to a customer. The metadata object stores all custom attributes assigned to the customer. It can be useful for storing additional information about the customer in a structured format. This metadata can be used for validating whether the customer qualifies for a discount or it can be used in building customer segments. "
},
"object": {
"type": "string",
"description": "The type of the object represented by the JSON. This object stores information about the customer.",
"default": "customer"
}
},
"required": [
"object"
]
},
"ParameterObject": {
"type": "object"
},
"6_query_validate_voucher_client_side_orders_order_item": {
"type": "array",
"items": {
"type": "object",
"title": "Order Item",
"description": "This object represents an order line item.",
"properties": {
"source_id": {
"type": "string",
"description": "The merchant's product/SKU ID (if it is different from the Voucherify product/SKU ID). It is useful in the integration between multiple systems. It can be an ID from an eCommerce site, a database, or a third-party service."
},
"related_object": {
"type": "string",
"description": "Used along with the `source_id` property, can be set to either `sku` or `product`."
},
"product_id": {
"type": "string",
"description": "Unique identifier of the product. It is assigned by Voucherify.",
"example": "prod_0a7e62db1fca8322a2"
},
"sku_id": {
"type": "string",
"description": "Unique identifier of the SKU. It is assigned by Voucherify.",
"example": "sku_0a41e31c7b41c28358"
},
"quantity": {
"type": "string",
"description": "The quantity of the particular item in the cart."
},
"price": {
"type": "string",
"description": "The unit price of the item."
},
"amount": {
"type": "string",
"description": "The total amount of the order item (`price` * `quantity`)."
}
}
}
},
"6_res_validate_voucher_discount_code": {
"type": "object",
"title": "Valid - Discount Code",
"description": "Response schema model for validating a discount code using **POST** `v1/vouchers/{code}/validate`.",
"properties": {
"valid": {
"type": "boolean",
"description": "Indicates whether the voucher is valid within the context of the parameters provided in the request body."
},
"applicable_to": {
"$ref": "#/components/schemas/6_res_applicable_to_object"
},
"inapplicable_to": {
"$ref": "#/components/schemas/6_res_inapplicable_to_object"
},
"tracking_id": {
"type": "string",
"description": "Hashed customer source ID."
},
"order": {
"$ref": "#/components/schemas/6_obj_order_object"
},
"code": {
"type": "string",
"description": "Voucher code."
},
"discount": {
"oneOf": [
{
"$ref": "#/components/schemas/6_res_validate_voucher_discount_amount"
},
{
"$ref": "#/components/schemas/6_res_validate_voucher_discount_percent"
},
{
"$ref": "#/components/schemas/6_res_validate_voucher_discount_fixed"
},
{
"$ref": "#/components/schemas/6_res_validate_voucher_discount_unit"
},
{
"$ref": "#/components/schemas/6_res_validate_voucher_discount_unit_multiple"
},
{
"$ref": "#/components/schemas/6_res_validate_voucher_discount_shipping"
}
],
"description": "Contains information about the discount to be applied to the order."
},
"metadata": {
"type": "object",
"description": "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."
},
"start_date": {
"type": "string",
"format": "date-time",
"example": "2022-10-04T00:00:00.000Z",
"description": "Activation timestamp defines when the voucher starts to be active in ISO 8601 format. Voucher is _inactive_ before this date."
},
"expiration_date": {
"type": "string",
"format": "date-time",
"example": "2022-10-31T00:00:00.000Z",
"description": "Expiration timestamp defines when the voucher expires in ISO 8601 format. Voucher is _inactive_ after this date."
},
"campaign": {
"type": "string",
"description": "Voucher's parent campaign name."
},
"campaign_id": {
"type": "string",
"example": "camp_W8DJVd8J0btqXT6FBwn7BSkC",
"description": "Voucher's parent campaign's unique ID."
},
"session": {
"$ref": "#/components/schemas/6_res_session_lock_discount_voucher"
}
}
},
"6_res_validate_voucher_gift_card": {
"type": "object",
"title": "Valid - Gift Card",
"description": "Response schema model for validating a gift card using **POST** `v1/vouchers/{code}/validate`.",
"properties": {
"valid": {
"type": "boolean",
"description": "Indicates whether the voucher is valid within the context of the parameters provided in the request body."
},
"applicable_to": {
"$ref": "#/components/schemas/6_res_applicable_to_object"
},
"inapplicable_to": {
"$ref": "#/components/schemas/6_res_inapplicable_to_object"
},
"tracking_id": {
"type": "string",
"description": "Hashed customer source ID."
},
"order": {
"$ref": "#/components/schemas/6_obj_order_object"
},
"code": {
"type": "string",
"description": "Voucher code."
},
"gift": {
"type": "object",
"description": "Contains current gift card balance information.",
"properties": {
"amount": {
"type": "integer",
"description": "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`."
},
"balance": {
"type": "integer",
"description": "Available funds. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `$100.00`."
},
"effect": {
"type": "string",
"enum": [
"APPLY_TO_ORDER",
"APPLY_TO_ITEMS"
],
"description": "Defines how the credits are applied to the customer's order."
}
}
},
"metadata": {
"type": "object",
"description": "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."
},
"start_date": {
"type": "string",
"format": "date-time",
"example": "2022-10-04T00:00:00.000Z",
"description": "Activation timestamp defines when the voucher starts to be active in ISO 8601 format. Voucher is _inactive_ before this date."
},
"expiration_date": {
"type": "string",
"format": "date-time",
"example": "2022-10-31T00:00:00.000Z",
"description": "Expiration timestamp defines when the voucher expires in ISO 8601 format. Voucher is _inactive_ after this date."
},
"campaign": {
"type": "string",
"description": "Voucher's parent campaign name."
},
"campaign_id": {
"type": "string",
"example": "camp_W8DJVd8J0btqXT6FBwn7BSkC",
"description": "Voucher's parent campaign's unique ID."
},
"session": {
"$ref": "#/components/schemas/6_res_session_lock_gift_card"
}
}
},
"6_res_validate_voucher_loyalty_card": {
"type": "object",
"title": "Valid - Loyalty Card",
"description": "Response schema model for validating a loyalty card using **POST** `v1/vouchers/{code}/validate`.",
"properties": {
"valid": {
"type": "boolean",
"description": "Indicates whether the voucher is valid within the context of the parameters provided in the request body."
},
"applicable_to": {
"$ref": "#/components/schemas/6_res_applicable_to_object"
},
"inapplicable_to": {
"$ref": "#/components/schemas/6_res_inapplicable_to_object"
},
"tracking_id": {
"type": "string",
"description": "Hashed customer source ID."
},
"order": {
"$ref": "#/components/schemas/6_obj_order_object_apply_to_order"
},
"code": {
"type": "string",
"description": "Voucher code."
},
"loyalty": {
"type": "object",
"description": "Contains the cost of reward in points.",
"properties": {
"points_cost": {
"type": "integer",
"description": "Number of points that wlil be deducted from loyaty card for the associated reward."
}
}
},
"reward": {
"type": "object",
"description": "Contains information about the reward that is being validated.",
"properties": {
"id": {
"type": "string",
"description": "Unique reward ID assigned by Voucherify.",
"example": "rew_Crmu3hu2FKZWZIML59AeAs1n"
},
"assignment_id": {
"type": "string",
"example": "rewa_xZr6Ks0j5AHeMRVdELmpI9sc",
"description": "Unique reward assignment ID assigned by Voucherify."
},
"points": {
"type": "integer",
"description": "Number of points applied to the reward."
}
}
},
"metadata": {
"type": "object",
"description": "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."
},
"start_date": {
"type": "string",
"format": "date-time",
"example": "2022-10-04T00:00:00.000Z",
"description": "Activation timestamp defines when the voucher starts to be active in ISO 8601 format. Voucher is _inactive_ before this date."
},
"expiration_date": {
"type": "string",
"format": "date-time",
"example": "2022-10-31T00:00:00.000Z",
"description": "Expiration timestamp defines when the voucher expires in ISO 8601 format. Voucher is _inactive_ after this date."
},
"campaign": {
"type": "string",
"description": "Voucher's parent campaign name."
},
"campaign_id": {
"type": "string",
"example": "camp_W8DJVd8J0btqXT6FBwn7BSkC",
"description": "Voucher's parent campaign's unique ID."
},
"session": {
"$ref": "#/components/schemas/6_res_session_lock_loyalty_card"
}
}
},
"7_req_redeem_voucher_discount_code": {
"title": "Discount Code",
"type": "object",
"description": "Redeem a discount code.",
"properties": {
"session": {
"$ref": "#/components/schemas/6_req_session_lock_discount_code"
},
"customer": {
"oneOf": [
{
"$ref": "#/components/schemas/6_req_validate_voucher_customer_id"
},
{
"$ref": "#/components/schemas/6_req_validate_voucher_customer_source_id"
},
{
"$ref": "#/components/schemas/9_req_create_customer"
}
],
"description": "Customer's information."
},
"order": {
"oneOf": [
{
"$ref": "#/components/schemas/6_req_validate_voucher_order_id"
},
{
"$ref": "#/components/schemas/6_req_validate_voucher_order_source_id"
},
{
"$ref": "#/components/schemas/OrdersCreateRequestBody"
}
],
"description": "Order information."
},
"metadata": {
"type": "object",
"description": "A set of key/value pairs that you can send in the request body to check against vouchers requiring **redemption** metadata validation rules to be satisfied. The validation runs against rules that are defined through the [Create Validation Rules](/api-reference/validation-rules/create-validation-rules) endpoint or via the Dashboard; in the _Advanced Rule Builder_ → _Advanced_ → _Redemption metadata satisfy_ or _Basic Builder_ → _Attributes match_ → _REDEMPTION METADATA_. [Read more](/personalize/create-validation-rules)."
},
"options": {
"type": "object",
"description": "Configure parameters returned in the response.",
"properties": {
"expand": {
"type": "array",
"description": "The expand array lets you configure the parameters included in the response. Depending on the strings included in the array, the response will contain different details. Add `category` as a string in the array to include a `categories` object in the response.",
"items": {
"type": "string",
"default": "category",
"enum": [
"category"
],
"example": "category"
}
}
}
}
}
},
"7_req_redeem_voucher_gift_card": {
"title": "Gift Card",
"type": "object",
"description": "Redeem a gift card.",
"properties": {
"session": {
"$ref": "#/components/schemas/6_req_session_lock_gift_card"
},
"gift": {
"type": "object",
"description": "Contains information on the number of gift card credits that the customer wants to apply to the order.",
"properties": {
"credits": {
"type": "integer",
"description": "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`."
}
}
},
"customer": {
"oneOf": [
{
"$ref": "#/components/schemas/6_req_validate_voucher_customer_id"
},
{
"$ref": "#/components/schemas/6_req_validate_voucher_customer_source_id"
},
{
"$ref": "#/components/schemas/9_req_create_customer"
}
],
"description": "Customer's information."
},
"order": {
"oneOf": [
{
"$ref": "#/components/schemas/6_req_validate_voucher_order_id"
},
{
"$ref": "#/components/schemas/6_req_validate_voucher_order_source_id"
},
{
"$ref": "#/components/schemas/OrdersCreateRequestBody"
}
],
"description": "Order information."
},
"metadata": {
"type": "object",
"description": "A set of key/value pairs that you can send in the request body to check against vouchers requiring **redemption** metadata validation rules to be satisfied. The validation runs against rules that are defined through the [Create Validation Rules](/api-reference/validation-rules/create-validation-rules) endpoint or via the Dashboard; in the _Advanced Rule Builder_ → _Advanced_ → _Redemption metadata satisfy_ or _Basic Builder_ → _Attributes match_ → _REDEMPTION METADATA_. [Read more](/personalize/create-validation-rules)."
},
"options": {
"type": "object",
"description": "Configure parameters returned in the response.",
"properties": {
"expand": {
"type": "array",
"description": "The expand array lets you configure the parameters included in the response. Depending on the strings included in the array, the response will contain different details. Add `category` as a string in the array to include a `categories` object in the response.",
"items": {
"type": "string",
"default": "category",
"enum": [
"category"
],
"example": "category"
}
}
}
}
}
},
"7_req_redeem_voucher_loyalty_card": {
"title": "Loyalty Card",
"type": "object",
"description": "Redeem a loyalty card.",
"properties": {
"session": {
"$ref": "#/components/schemas/6_req_session_lock_loyalty_card"
},
"reward": {
"type": "object",
"description": "Contains information about the reward that the customer wants to redeem and the number of points the customer is choosing to use for the reward.",
"properties": {
"id": {
"type": "string",
"description": "Unique reward ID assigned by Voucherify. The reward must be assigned to the campaign in order for the user to be able to use the reward."
},
"points": {
"type": "integer",
"description": "The number of loyalty points that the user wants to spend in order to fulfill the order. The number of points cannot be higher than the current balance on the loyalty card. If the user gives more points than he/she has on the loyalty card, the application will return an error code in response."
}
}
},
"customer": {
"oneOf": [
{
"$ref": "#/components/schemas/6_req_validate_voucher_customer_id"
},
{
"$ref": "#/components/schemas/6_req_validate_voucher_customer_source_id"
},
{
"$ref": "#/components/schemas/9_req_create_customer"
}
],
"description": "Customer's information."
},
"order": {
"oneOf": [
{
"$ref": "#/components/schemas/6_req_validate_voucher_order_id"
},
{
"$ref": "#/components/schemas/6_req_validate_voucher_order_source_id"
},
{
"$ref": "#/components/schemas/OrdersCreateRequestBody"
}
],
"description": "Order information."
},
"metadata": {
"type": "object",
"description": "A set of key/value pairs that you can send in the request body to check against vouchers requiring **redemption** metadata validation rules to be satisfied. The validation runs against rules that are defined through the [Create Validation Rules](/api-reference/validation-rules/create-validation-rules) endpoint or via the Dashboard; in the _Advanced Rule Builder_ → _Advanced_ → _Redemption metadata satisfy_ or _Basic Builder_ → _Attributes match_ → _REDEMPTION METADATA_. [Read more](/personalize/create-validation-rules)."
},
"options": {
"type": "object",
"description": "Configure parameters returned in the response.",
"properties": {
"expand": {
"type": "array",
"description": "The expand array lets you configure the parameters included in the response. Depending on the strings included in the array, the response will contain different details. Add `category` as a string in the array to include a `categories` object in the response.",
"items": {
"type": "string",
"default": "category",
"enum": [
"category"
],
"example": "category"
}
}
}
}
}
},
"7_obj_redemption_object_voucher_extended": {
"title": "Redemption Object",
"description": "This is an object representing an attempted or successful voucher redemption.",
"oneOf": [
{
"$ref": "#/components/schemas/7_obj_redemption_object_discount_voucher_extended"
},
{
"$ref": "#/components/schemas/7_obj_redemption_object_loyalty_card_extended"
},
{
"$ref": "#/components/schemas/7_obj_redemption_object_gift_card_extended"
}
]
},
"CreatePublicationWithSpecificVoucher": {
"title": "Create Publication With Specific Voucher",
"type": "object",
"description": "Create publication with specific voucher.",
"allOf": [
{
"title": "Voucher code",
"type": "object",
"properties": {
"voucher": {
"description": "Code of the voucher being published.",
"type": "string"
}
},
"required": [
"voucher"
]
},
{
"$ref": "#/components/schemas/CreatePublicationBase"
}
]
},
"CreatePublicationWithCampaign": {
"title": "Create Publication With Campaign",
"type": "object",
"description": "Create publication with campaign.",
"allOf": [
{
"title": "Campaign",
"type": "object",
"properties": {
"campaign": {
"$ref": "#/components/schemas/CreatePublicationCampaign"
}
},
"required": [
"campaign"
]
},
{
"$ref": "#/components/schemas/CreatePublicationBase"
}
]
},
"PublicationsCreateVoucherResponseBody": {
"title": "Publications Create Voucher Response Body",
"type": "object",
"description": "Response body schema for **POST** `v1/publication` and **GET** `v1/publications/create`.",
"allOf": [
{
"$ref": "#/components/schemas/PublicationsCreateBaseResponseBody"
},
{
"type": "object",
"properties": {
"voucher": {
"$ref": "#/components/schemas/Voucher"
}
},
"required": [
"voucher"
]
}
]
},
"PublicationsCreateVouchersResponseBody": {
"title": "Publications Create Vouchers Response Body",
"description": "Response body schema for **POST** `v1/publication` and **GET** `v1/publications/create`.",
"allOf": [
{
"$ref": "#/components/schemas/PublicationsCreateBaseResponseBody"
},
{
"type": "object",
"properties": {
"vouchers": {
"type": "array",
"description": "Contains the unique voucher codes that was assigned by Voucherify.",
"items": {
"type": "string",
"example": "Q1K4XT5S"
}
}
},
"required": [
"vouchers"
]
}
]
},
"CustomerBase": {
"title": "Customer Base",
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Customer's first and last name."
},
"description": {
"type": "string",
"description": "An arbitrary string that you can attach to a customer object."
},
"email": {
"type": "string",
"description": "Customer's email address."
},
"phone": {
"type": "string",
"description": "Customer's phone number. This parameter is mandatory when you try to send out codes to customers via an SMS channel."
},
"birthday": {
"type": "string",
"description": "`Deprecated`. ~~Customer's birthdate; format YYYY-MM-DD~~.",
"format": "date"
},
"birthdate": {
"type": "string",
"description": "Customer's birthdate; format YYYY-MM-DD.",
"format": "date"
},
"address": {
"type": "object",
"nullable": true,
"description": "Customer's address.",
"properties": {
"city": {
"type": "string",
"description": "City"
},
"state": {
"type": "string",
"description": "State"
},
"line_1": {
"type": "string",
"description": "First line of address."
},
"line_2": {
"type": "string",
"description": "Second line of address."
},
"country": {
"type": "string",
"description": "Country."
},
"postal_code": {
"type": "string",
"description": "Postal code."
}
}
},
"metadata": {
"type": "object",
"description": "A set of custom key/value pairs that you can attach to a customer. The metadata object stores all custom attributes assigned to the customer. It can be useful for storing additional information about the customer in a structured format. This metadata can be used for validating whether the customer qualifies for a discount or it can be used in building customer segments."
}
}
},
"OrderBase": {
"title": "Order Base",
"type": "object",
"description": "Order information.",
"properties": {
"source_id": {
"type": "string",
"nullable": true,
"description": "Unique source ID of an existing order that will be linked to the redemption of this request.\n\nFor validation and redemption, if `source_id` is used with an existing order, the original order data will be used, like `items`, `amount`, and so on, not the one sent in the new request."
},
"status": {
"type": "string",
"description": "The order status.",
"enum": [
"CREATED",
"PAID",
"CANCELED",
"FULFILLED"
]
},
"amount": {
"type": "integer",
"description": "A positive integer in the smallest currency unit (e.g. 100 cents for $1.00) representing the total amount of the order. This is the sum of the order items' amounts."
},
"initial_amount": {
"type": "integer",
"description": "A positive integer in the smallest currency unit (e.g. 100 cents for $1.00) representing the total amount of the order. This is the sum of the order items' amounts."
},
"discount_amount": {
"type": "integer",
"description": "Sum of all order-level discounts applied to the order. It is expressed as an integer in the smallest currency unit (e.g. 100 cents for $1.00)."
},
"items": {
"type": "array",
"description": "Array of items applied to the order. It can include up to 500 items.",
"items": {
"$ref": "#/components/schemas/OrderItem"
}
},
"metadata": {
"type": "object",
"description": "A set of custom key/value pairs that you can attach to an order. It can be useful for storing additional information about the order in a structured format. It can be used to define business validation rules or discount formulas."
}
}
},
"Junction": {
"title": "Junction",
"description": "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.",
"enum": [
"and",
"or"
],
"type": "string"
},
"QualificationsFieldConditions": {
"title": "Qualifications Field Conditions",
"type": "object",
"properties": {
"conditions": {
"description": "Data filters used to narrow down the data records to be returned in the result.",
"allOf": [
{
"$ref": "#/components/schemas/QualificationsFiltersCondition"
}
]
}
}
},
"ParameterCampaignType": {
"type": "string",
"enum": [
"PROMOTION",
"GIFT_VOUCHERS",
"REFERRAL_PROGRAM",
"DISCOUNT_COUPONS",
"LOYALTY_PROGRAM"
]
},
"ResourceTypes": {
"title": "Resource Types",
"description": "Types of usable resources.",
"type": "string",
"enum": [
"campaign",
"voucher",
"promotion_tier"
]
},
"QualificationsRedeemable": {
"title": "Combined response of redeemable object and multiple redeemables within",
"allOf": [
{
"$ref": "#/components/schemas/QualificationsRedeemableBase"
},
{
"type": "object",
"title": "",
"properties": {
"redeemables": {
"type": "array",
"items": {
"$ref": "#/components/schemas/QualificationsRedeemableBase"
}
}
}
}
]
},
"CustomerId": {
"title": "Customer Id",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "A unique identifier of an existing customer."
},
"object": {
"type": "string",
"description": "The type of the object represented by JSON.",
"default": "customer",
"enum": [
"customer"
]
}
},
"required": [
"id",
"object"
]
},
"ReferrerId": {
"title": "Referrer Id",
"allOf": [
{
"$ref": "#/components/schemas/CustomerId"
}
]
},
"OrderRedemptionsEntry": {
"title": "Order Redemptions",
"type": "object",
"properties": {
"date": {
"type": "string",
"description": "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",
"format": "date-time"
},
"rollback_id": {
"type": "string",
"description": "Unique ID of the redemption rollback.",
"example": "rr_0c63c84eb78ee0a6c0"
},
"rollback_date": {
"type": "string",
"description": "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",
"format": "date-time"
},
"related_object_type": {
"type": "string",
"description": "The source of the incentive.",
"default": "redemption"
},
"related_object_id": {
"type": "string",
"description": "Unique ID of the parent redemption.",
"example": "r_0ba186c4824e4881e1"
},
"related_object_parent_id": {
"type": "string",
"description": "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": {
"type": "array",
"description": "Contains a list of unique IDs of child redemptions, which belong to the stacked incentives.",
"items": {
"type": "string"
}
},
"rollback_stacked": {
"type": "array",
"description": "Lists the rollback redemption IDs of the particular child redemptions.",
"items": {
"type": "string"
}
}
}
},
"PromotionTier": {
"type": "object",
"description": "This is an object representing a promotion tier. Promotion tiers are always assigned to a campaign and cannot be used standalone.",
"title": "Promotion Tier",
"properties": {
"id": {
"type": "string",
"example": "promo_63fYCt81Aw0h7lzyRkrGZh9p",
"description": "Unique promotion tier ID."
},
"created_at": {
"type": "string",
"example": "2021-12-15T11:34:01.333Z",
"format": "date-time",
"description": "Timestamp representing the date and time when the promotion tier was created. The value is shown in the ISO 8601 format."
},
"updated_at": {
"type": "string",
"example": "2022-02-09T09:20:05.603Z",
"format": "date-time",
"description": "Timestamp representing the date and time when the promotion tier was updated. The value is shown in the ISO 8601 format."
},
"name": {
"type": "string",
"description": "Name of the promotion tier."
},
"banner": {
"type": "string",
"description": "Text to be displayed to your customers on your website."
},
"action": {
"type": "object",
"description": "Contains details about the discount applied by the promotion tier.",
"properties": {
"discount": {
"$ref": "#/components/schemas/Discount"
}
}
},
"metadata": {
"type": "object",
"description": "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": {
"type": "integer",
"description": "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": {
"type": "string",
"description": "Promotion unique ID."
},
"campaign": {
"type": "object",
"description": "Contains details about promotion tier's parent campaign.",
"properties": {
"id": {
"type": "string",
"description": "Unique campaign ID."
},
"start_date": {
"type": "string",
"description": "Activation timestamp defines when the campaign starts to be active in ISO 8601 format. Campaign is *inactive before* this date. ",
"format": "date-time",
"example": "2022-09-22T00:00:00.000Z"
},
"expiration_date": {
"type": "string",
"format": "date-time",
"description": "Expiration timestamp defines when the campaign expires in ISO 8601 format. Campaign is *inactive after* this date.",
"example": "2022-09-30T00:00:00.000Z"
},
"validity_timeframe": {
"$ref": "#/components/schemas/ValidityTimeframe"
},
"validity_day_of_week": {
"$ref": "#/components/schemas/ValidityDayOfWeek"
},
"validity_hours": {
"$ref": "#/components/schemas/ValidityHours"
},
"active": {
"type": "boolean",
"description": "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](/api-reference/disable-campaign) endpoint. \n\n- `true` indicates an *active* campaign\n- `false` indicates an *inactive* campaign"
},
"category_id": {
"type": "string",
"example": "cat_0b688929a2476386a6",
"description": "Unique category ID that this campaign belongs to."
},
"object": {
"type": "string",
"description": "The type of the object represented by the campaign object. This object stores information about the campaign.",
"default": "campaign"
}
}
},
"campaign_id": {
"type": "string",
"description": "Promotion tier's parent campaign's unique ID."
},
"active": {
"type": "boolean",
"description": "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`. \n\n- `true` indicates an *active* promotion tier\n- `false` indicates an *inactive* promotion tier"
},
"start_date": {
"type": "string",
"description": "Activation timestamp defines when the promotion tier starts to be active in ISO 8601 format. Promotion tier is *inactive before* this date. ",
"format": "date-time",
"example": "2022-09-23T00:00:00.000Z"
},
"expiration_date": {
"type": "string",
"description": "Activation timestamp defines when the promotion tier expires in ISO 8601 format. Promotion tier is *inactive after* this date. ",
"format": "date-time",
"example": "2022-09-26T00:00:00.000Z"
},
"validity_timeframe": {
"$ref": "#/components/schemas/ValidityTimeframe"
},
"validity_day_of_week": {
"$ref": "#/components/schemas/ValidityDayOfWeek"
},
"validity_hours": {
"$ref": "#/components/schemas/ValidityHours"
},
"summary": {
"type": "object",
"description": "Contains statistics about promotion tier redemptions and orders.",
"properties": {
"redemptions": {
"type": "object",
"description": "Contains statistics about promotion tier redemptions.",
"properties": {
"total_redeemed": {
"type": "integer",
"description": "Number of times the promotion tier was redeemed."
}
}
},
"orders": {
"type": "object",
"description": "Contains statistics about orders related to the promotion tier.",
"properties": {
"total_amount": {
"type": "integer",
"description": "Sum of order totals."
},
"total_discount_amount": {
"type": "integer",
"description": "Sum of total discount applied using the promotion tier."
}
}
}
}
},
"object": {
"type": "string",
"default": "promotion_tier",
"description": "The type of the object represented by JSON. This object stores information about the promotion tier."
},
"validation_rule_assignments": {
"$ref": "#/components/schemas/ValidationRuleAssignmentsList"
},
"category_id": {
"type": "string",
"description": "Promotion tier category ID.",
"example": "cat_0c9da30e7116ba6bba"
},
"categories": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Category"
}
}
}
},
"RedeemVoucher": {
"title": "Voucher Redeemable",
"type": "object",
"description": "Validate or redeem a discount code.",
"properties": {
"object": {
"type": "string",
"description": "Redeemable object type.",
"default": "voucher",
"enum": [
"voucher"
]
},
"id": {
"type": "string",
"description": "Redeemable code."
}
},
"required": [
"object",
"id"
]
},
"RedeemPromotionTier": {
"title": "Promotion Tier Redeemable",
"type": "object",
"description": "Validate or redeem a promotion tier.",
"properties": {
"object": {
"type": "string",
"description": "Redeemable object type.",
"default": "promotion_tier",
"enum": [
"promotion_tier"
]
},
"id": {
"type": "string",
"description": "Promotion tier unique id, such as: promo_Mwy9XpA0TLctSGriM5kum0qp"
}
},
"required": [
"object",
"id"
]
},
"RedeemPromotionStack": {
"title": "Promotion Stack Redeemable",
"type": "object",
"description": "Validate or redeem a promotion stack.",
"properties": {
"object": {
"type": "string",
"description": "Redeemable object type.",
"default": "promotion_stack",
"enum": [
"promotion_stack"
]
},
"id": {
"type": "string",
"description": "Promotion stack unique id, such as: stack_KxSD0GahLUg9ULB6TseGfUHJ"
}
},
"required": [
"object",
"id"
]
},
"RedeemGiftCard": {
"title": "Gift Card Redeemable",
"description": "Validate or redeem a gift card",
"allOf": [
{
"$ref": "#/components/schemas/RedeemVoucher"
},
{
"type": "object",
"properties": {
"gift": {
"type": "object",
"description": "Contains information on the number of gift card credits that the customer wants to apply to the order.",
"properties": {
"credits": {
"type": "integer",
"description": "The number of credits that the user wants to use from the gift card to fulfill the order. The value of credits cannot be higher than the current balance on the gift card. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `$100.00`."
}
}
}
}
}
]
},
"RedeemLoyaltyCard": {
"title": "Loyalty Card Redeemable",
"description": "Validate or redeem a loyalty card",
"allOf": [
{
"$ref": "#/components/schemas/RedeemVoucher"
},
{
"type": "object",
"properties": {
"reward": {
"type": "object",
"description": "Contains information about the reward that the customer wants to redeem and the number of points the customer is choosing to use for the reward.",
"properties": {
"id": {
"type": "string",
"description": "Unique reward ID assigned by Voucherify. The reward must be assigned to the campaign in order for the user to be able to use the reward.",
"example": "rew_EPx1hCTpqzF0HW1z9NKckZH4"
},
"points": {
"type": "integer",
"description": "The number of loyalty points that the user wants to spend in order to fulfill the order using a **pay with points** reward. The number of points cannot be higher than the current balance on the loyalty card."
}
}
}
}
}
]
},
"Session": {
"type": "object",
"title": "Session",
"properties": {
"key": {
"type": "string",
"description": "The session unique ID assigned by Voucherify or your own unique session ID. Sending an existing ID will result in overwriting an existing session. If no session key is provided, then a new ID will be generated."
},
"type": {
"type": "string",
"default": "LOCK",
"enum": [
"LOCK"
],
"description": "This parameter is required to establish a new session."
},
"ttl": {
"type": "number",
"description": "Value for the period of time that the session is active. Units for this parameter are defined by the session.ttl_unit parameter."
},
"ttl_unit": {
"type": "string",
"enum": [
"DAYS",
"HOURS",
"MICROSECONDS",
"MILLISECONDS",
"MINUTES",
"NANOSECONDS",
"SECONDS"
],
"description": "Defines the type of unit in which the session time is counted."
}
}
},
"RedemptionBase": {
"title": "Redemption Base",
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "r_0bc92f81a6801f9bca",
"description": "Unique redemption ID."
},
"object": {
"type": "string",
"description": "The type of the object represented by the JSON",
"default": "redemption",
"enum": [
"redemption"
]
},
"date": {
"type": "string",
"example": "2021-12-22T10:13:06.487Z",
"description": "Timestamp representing the date and time when the object was created. The value is shown in the ISO 8601 format.",
"format": "date-time"
},
"customer_id": {
"type": "string",
"nullable": true,
"example": "cust_i8t5Tt6eiKG5K79KQlJ0Vs64",
"description": "Unique customer ID of the redeeming customer."
},
"tracking_id": {
"type": "string",
"nullable": true,
"description": "Hashed customer source ID."
},
"metadata": {
"type": "object",
"nullable": true,
"description": "The metadata object stores all custom attributes assigned to the redemption."
},
"amount": {
"type": "integer",
"description": "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.\nFor loyalty cards, this is the number of loyalty points used in the transaction.",
"example": 10000
},
"redemption": {
"nullable": true,
"type": "string",
"description": "Unique redemption ID of the parent redemption.",
"example": "r_0c656311b5878a2031"
},
"result": {
"type": "string",
"enum": [
"SUCCESS",
"FAILURE"
],
"description": "Redemption result."
},
"status": {
"type": "string",
"enum": [
"SUCCEEDED",
"FAILED",
"ROLLED_BACK"
],
"description": "Redemption status."
},
"session": {
"type": "object",
"description": "Contains details about the redemption session lock. Sessions can be established only for discount vouchers, promotions, and gift cards.",
"properties": {
"key": {
"type": "string",
"description": "The session unique ID assigned by Voucherify or your own unique session ID sent in the request."
}
}
},
"related_redemptions": {
"type": "object",
"properties": {
"rollbacks": {
"type": "array",
"items": {
"title": "Redemption Related Redemptions Rollbacks Item",
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "rr_0bc92f81a6801f9bca",
"description": "Unique rollback redemption ID."
},
"date": {
"type": "string",
"example": "2021-12-22T10:13:06.487Z",
"description": "Timestamp representing the date and time when the object was created. The value is shown in the ISO 8601 format.",
"format": "date-time"
},
"rollback_order_mode": {
"type": "string",
"description": "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. This is returned only in GET `v1/redemptions/` and GET `v1/redemptions/{redemptionId}` endpoints.",
"enum": [
"WITH_ORDER",
"WITHOUT_ORDER"
]
}
}
}
},
"redemptions": {
"type": "array",
"items": {
"title": "Redemption Related Redemptions Item",
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "r_0bc92f81a6801f9bca",
"description": "Unique redemption ID."
},
"date": {
"type": "string",
"example": "2021-12-22T10:13:06.487Z",
"description": "Timestamp representing the date and time when the object was created. The value is shown in the ISO 8601 format.",
"format": "date-time"
}
}
}
}
}
},
"failure_code": {
"type": "string",
"example": "customer_rules_violated",
"description": "If the result is `FAILURE`, this parameter will provide a generic reason as to why the redemption failed."
},
"failure_message": {
"type": "string",
"description": "If the result is `FAILURE`, this parameter will provide a more expanded reason as to why the redemption failed."
},
"order": {
"nullable": true,
"allOf": [
{
"$ref": "#/components/schemas/OrderCalculated"
},
{
"type": "object",
"properties": {
"items": {
"type": "array",
"description": "Array of items applied to the order. It can include up to 500 items.",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/OrderCalculatedItem"
},
{
"type": "object",
"properties": {
"application_details": {
"$ref": "#/components/schemas/ApplicationDetails"
}
}
}
]
}
}
}
}
]
},
"channel": {
"type": "object",
"description": "Defines the details of the channel through which the redemption was issued.",
"properties": {
"channel_id": {
"type": "string",
"example": "user_g24UoRO3Caxu7FCT4n5tpYEa3zUG0FrH",
"description": "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."
},
"channel_type": {
"type": "string",
"description": "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.",
"enum": [
"USER",
"API",
"AUTO_REDEEM"
]
}
}
},
"customer": {
"nullable": true,
"allOf": [
{
"$ref": "#/components/schemas/SimpleCustomer"
}
]
},
"related_object_type": {
"type": "string",
"description": "Defines the related object.",
"enum": [
"voucher",
"promotion_tier",
"redemption"
]
},
"related_object_id": {
"type": "string",
"description": "Unique related object ID assigned by Voucherify, i.e. v_lfZi4rcEGe0sN9gmnj40bzwK2FH6QUno for a voucher."
},
"promotion_tier": {
"description": "Contains details of the promotion tier and the parent campaign.",
"allOf": [
{
"$ref": "#/components/schemas/PromotionTier"
}
]
},
"reward": {
"$ref": "#/components/schemas/RedemptionRewardResult"
},
"gift": {
"type": "object",
"description": "Contains the amount subtracted from the gift card for the redemption.",
"properties": {
"amount": {
"type": "integer",
"description": "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": {
"type": "object",
"description": "Contains the number of points subtracted from the loyalty card for the redemption.",
"properties": {
"points": {
"type": "integer",
"description": "Number of points subtracted from the loyalty card as a result of the redemption."
}
}
}
},
"required": [
"id",
"object",
"date",
"customer_id",
"tracking_id",
"metadata",
"redemption",
"result",
"status",
"order",
"channel",
"customer",
"related_object_type",
"related_object_id"
]
},
"VoucherWithStackingRulesTypeCategories": {
"title": "Voucher with categories and validation rules assignments",
"description": "This is an object representing a voucher with categories and validation rules assignments for **POST** `v1/qualifications`, **POST** `v1/redemptions`, and **POST** `v1/validations`.",
"allOf": [
{
"$ref": "#/components/schemas/VoucherBase"
},
{
"type": "object",
"properties": {
"categories": {
"type": "array",
"description": "Contains details about the category.",
"items": {
"$ref": "#/components/schemas/CategoryWithStackingRulesType"
}
},
"validation_rules_assignments": {
"$ref": "#/components/schemas/ValidationRulesAssignmentsList"
}
}
}
]
},
"VoucherHolder": {
"title": "Voucher Holder",
"type": "object",
"description": "This is an object representing a voucher holder.",
"properties": {
"holder": {
"$ref": "#/components/schemas/SimpleCustomer"
}
}
},
"Bundle": {
"title": "Bundle Details",
"type": "object",
"description": "Determines how the bundle conditions are met by the customer's order items. The items in the order meet the bundle condition in the following way: SKU, then product, then collection.",
"properties": {
"quantity": {
"type": "integer",
"description": "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`.",
"minimum": 0,
"maximum": 100
},
"limit": {
"type": "integer",
"description": "Determines the maximum number of identified bundles. This also defines the maximum multiplier of the bundle discount.",
"minimum": 1,
"maximum": 100
},
"identified": {
"type": "array",
"description": "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.",
"items": {
"type": "object",
"description": "Determines a product from the customer's order items that meets bundle conditions.",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of the product or SKU that meets the bundle condition. This is an ID assigned by Voucherify."
},
"object": {
"type": "string",
"description": "Determines the type of the object that meets the bundle condition.",
"enum": [
"product",
"sku"
]
},
"item_index": {
"type": "integer",
"description": "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.",
"minimum": 0
},
"item_quantity": {
"type": "integer",
"description": "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`."
}
},
"required": [
"id",
"object",
"item_index",
"item_quantity"
]
}
},
"missing": {
"type": "array",
"description": "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.",
"items": {
"type": "object",
"description": "Determines a product, SKU, or collection that is in bundle conditions, but is missing in the customer's order items. Determines also the missing quantity.",
"properties": {
"id": {
"type": "string",
"description": "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": {
"type": "string",
"description": "Determines the type of the object that is missing in the customer's order items.",
"enum": [
"product",
"products_collection",
"sku"
]
},
"item_quantity": {
"type": "integer",
"description": "Quantity of items that are missing in the order items to meet the bundle conditions."
}
},
"required": [
"id",
"object",
"item_quantity"
]
}
}
},
"required": [
"quantity",
"limit"
]
},
"CategoryWithStackingRulesType": {
"type": "object",
"title": "Category with Stacking Rules Type",
"description": "Category object with `stacking_rules_type`",
"allOf": [
{
"$ref": "#/components/schemas/Category"
},
{
"type": "object",
"properties": {
"stacking_rules_type": {
"type": "string",
"description": "The type of the stacking rule eligibility.",
"enum": [
"JOINT",
"EXCLUSIVE"
]
}
}
}
]
},
"ValidationsRedeemableSkippedResultLimitExceeded": {
"title": "Validations Redeemable Skipped Result Limit Exceeded",
"type": "object",
"description": "Displayed when the `applicable_redeemables_limit` defined in the stacking rules is exceeded.",
"properties": {
"key": {
"type": "string",
"default": "applicable_redeemables_limit_exceeded",
"enum": [
"applicable_redeemables_limit_exceeded"
]
},
"message": {
"type": "string",
"example": "Applicable redeemables limit exceeded"
}
}
},
"ValidationsRedeemableSkippedResultCategoryLimitExceeded": {
"title": "Validations Redeemable Skipped Result Category Limit Exceeded",
"type": "object",
"description": "Displayed when `applicable_redeemables_per_category_limit` defined in the stacking rules is exceeded",
"properties": {
"key": {
"type": "string",
"default": "applicable_redeemables_per_category_limit_exceeded",
"enum": [
"applicable_redeemables_per_category_limit_exceeded"
]
},
"message": {
"type": "string",
"example": "Applicable redeemables limit per category exceeded"
}
}
},
"ValidationsRedeemableSkippedResultRedeemablesLimitExceeded": {
"title": "Validations Redeemable Skipped Result Redeemables Limit Exceeded",
"type": "object",
"description": "Displayed when `applicable_exclusive_redeemables_limit` defined in the stacking rules is exceeded.",
"properties": {
"key": {
"type": "string",
"default": "applicable_exclusive_redeemables_limit_exceeded",
"enum": [
"applicable_exclusive_redeemables_limit_exceeded"
]
},
"message": {
"type": "string",
"example": "Applicable exclusive redeemables limit exceeded"
}
}
},
"ValidationsRedeemableSkippedResultRedeemablesCategoryLimitExceeded": {
"title": "Validations Redeemable Skipped Result Redeemables Category Limit Exceeded",
"type": "object",
"description": "Displayed when `applicable_exclusive_redeemables_per_category_limit` defined in the stacking rules is exceeded.",
"properties": {
"key": {
"type": "string",
"default": "applicable_exclusive_redeemables_per_category_limit_exceeded",
"enum": [
"applicable_exclusive_redeemables_per_category_limit_exceeded"
]
},
"message": {
"type": "string",
"example": "Applicable exclusive redeemables limit per category exceeded"
}
}
},
"ValidationsRedeemableSkippedResultExclusionRulesNotMet": {
"title": "Validations Redeemable Skipped Result Exclusion Rules Not Met",
"type": "object",
"description": "Displayed when the redeemable cannot be applied because the exclusion rules are not fulfilled.",
"properties": {
"key": {
"type": "string",
"default": "exclusion_rules_not_met",
"enum": [
"exclusion_rules_not_met"
]
},
"message": {
"type": "string",
"example": "Redeemable cannot be applied due to exclusion rules"
}
}
},
"ValidationsRedeemableSkippedResultPrecedingValidationFailed": {
"title": "Validations Redeemable Skipped Result Preceding Validation Failed",
"type": "object",
"description": "Displayed in the ALL application rule when one of the preceding redeeambles is `INAPPLICABLE`, so the rest becomes `SKIPPED`",
"properties": {
"key": {
"type": "string",
"default": "preceding_validation_failed",
"enum": [
"preceding_validation_failed"
]
},
"message": {
"type": "string",
"example": "Redeemable cannot be applied due to preceding validation failure"
}
}
},
"ValidationsRedeemableSkippedResultNoEffect": {
"title": "Validations Redeemable Skipped Result No Effect",
"type": "object",
"description": "Displayed when the redeemable does not calculate any discount effect and the `redeemables_no_effect_rule` defined in the stacking rules is set to `SKIP` for the redeemable, either globally or through `no_effect_skip_categories`.",
"properties": {
"key": {
"type": "string",
"default": "no_effect",
"enum": [
"no_effect"
]
},
"message": {
"type": "string",
"example": "Redeemable cannot be applied due to no effect"
}
}
},
"ValidationsRedeemableApplicable": {
"type": "object",
"title": "Applicable Redeemable",
"properties": {
"status": {
"type": "string",
"default": "APPLICABLE",
"enum": [
"APPLICABLE"
],
"description": "Indicates whether the redeemable can be applied or not applied based on the validation rules."
},
"id": {
"type": "string",
"description": "Redeemable ID, i.e. the voucher code."
},
"object": {
"type": "string",
"description": "Redeemable's object type.",
"enum": [
"voucher",
"promotion_tier"
]
},
"order": {
"allOf": [
{
"$ref": "#/components/schemas/OrderCalculated"
},
{
"type": "object",
"properties": {
"items": {
"type": "array",
"description": "Array of items applied to the order. It can include up to 500 items.",
"items": {
"$ref": "#/components/schemas/OrderCalculatedItem"
}
}
}
}
]
},
"applicable_to": {
"$ref": "#/components/schemas/ApplicableToResultList"
},
"inapplicable_to": {
"$ref": "#/components/schemas/InapplicableToResultList"
},
"result": {
"description": "Specifies the redeemable's end effect on the order. This object is unique to each type of redeemable.",
"oneOf": [
{
"$ref": "#/components/schemas/RedeemableResultVoucherCode"
},
{
"$ref": "#/components/schemas/RedeemableResultGiftCard"
},
{
"$ref": "#/components/schemas/RedeemableResultLoyaltyCard"
},
{
"$ref": "#/components/schemas/RedeemableResultPromotionTier"
},
{
"$ref": "#/components/schemas/RedeemableResultPromotionStack"
}
]
},
"metadata": {
"type": "object",
"description": "The metadata object stores all custom attributes in the form of key/value pairs assigned to the redeemable."
},
"categories": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CategoryWithStackingRulesType"
}
},
"campaign_name": {
"type": "string",
"description": "Campaign name. Displayed only if the `options.expand` is passed with a `redeemable` value in the validation request body."
},
"campaign_id": {
"type": "string",
"description": "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": {
"type": "string",
"description": "Name of the promotion tier. Displayed only if the `options.expand` is passed with a `redeemable` value in the validation request body."
}
},
"required": [
"status",
"id",
"object",
"result"
]
},
"6_res_applicable_to_object": {
"title": "Included Items",
"type": "object",
"description": "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.",
"properties": {
"data": {
"type": "array",
"description": "Contains array of items to which the discount can apply.",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/6_res_product_collection"
},
{
"$ref": "#/components/schemas/6_res_product_collection_unit"
},
{
"$ref": "#/components/schemas/6_res_product_collection_fixed_amount"
},
{
"$ref": "#/components/schemas/6_res_product"
},
{
"$ref": "#/components/schemas/6_res_product_unit"
},
{
"$ref": "#/components/schemas/6_res_product_fixed_amount"
},
{
"$ref": "#/components/schemas/6_res_sku"
},
{
"$ref": "#/components/schemas/6_res_sku_unit"
},
{
"$ref": "#/components/schemas/6_res_sku_unit_fixed_amount"
}
]
}
},
"total": {
"type": "integer",
"description": "Total number of objects defining included products, SKUs, or product collections."
},
"data_ref": {
"type": "string",
"default": "data",
"description": "Identifies the name of the attribute that contains the array of included objects."
},
"object": {
"type": "string",
"default": "list",
"description": "The type of the object represented by JSON. This object stores information about included products, SKUs, or product collections in a dictionary."
}
}
},
"6_res_inapplicable_to_object": {
"title": "Excluded Items",
"type": "object",
"description": "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.",
"properties": {
"data": {
"description": "Contains array of items to which the discount cannot apply.",
"type": "array",
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/6_res_product_collection_excluded"
},
{
"$ref": "#/components/schemas/6_res_product_excluded"
},
{
"$ref": "#/components/schemas/6_res_sku_excluded"
}
]
}
},
"total": {
"type": "integer",
"description": "Total number of objects defining excluded products, SKUs, or product collections."
},
"data_ref": {
"type": "string",
"default": "data",
"description": "Identifies the name of the attribute that contains the array of excluded objects."
},
"object": {
"type": "string",
"default": "list",
"description": "The type of the object represented by JSON. This object stores information about excluded products, SKUs, or product collections in a dictionary."
}
}
},
"6_obj_order_object": {
"title": "Order object",
"description": "This is an object representing an order with calculated discounts applied using the voucher code.",
"oneOf": [
{
"$ref": "#/components/schemas/6_obj_order_object_apply_to_order"
},
{
"$ref": "#/components/schemas/6_obj_order_object_apply_to_items"
}
]
},
"6_res_validate_voucher_discount_amount": {
"title": "Amount Discount",
"type": "object",
"description": "This is an object representing the discount that the customer would receive in the context of the provided request body parameters. If the discount is calculated based on a formula, this object will return either the discount calculated based on the formula or the fallback value.",
"properties": {
"type": {
"type": "string",
"default": "AMOUNT",
"description": "Defines the type of the voucher."
},
"effect": {
"type": "string",
"description": "Defines how the discount is applied to the customer's order.",
"enum": [
"APPLY_TO_ORDER",
"APPLY_TO_ITEMS",
"APPLY_TO_ITEMS_PROPORTIONALLY",
"APPLY_TO_ITEMS_PROPORTIONALLY_BY_QUANTITY",
"APPLY_TO_ITEMS_BY_QUANTITY"
]
},
"amount_off": {
"type": "integer",
"description": "Amount taken off the subtotal of a price. Value is multiplied by 100 to precisely represent 2 decimal places. For example, a $10 discount is written as 1000. "
}
}
},
"6_res_validate_voucher_discount_percent": {
"title": "Percent Discount",
"type": "object",
"description": "This is an object representing the discount that the customer would receive in the context of the provided request body parameters. If the discount is calculated based on a formula, this object will return either the discount calculated based on the formula or the fallback value.",
"properties": {
"type": {
"type": "string",
"default": "PERCENT",
"description": "Defines the type of the voucher."
},
"effect": {
"type": "string",
"enum": [
"APPLY_TO_ORDER",
"APPLY_TO_ITEMS"
],
"description": "Defines how the discount is applied to the customer's order."
},
"percent_off": {
"type": "integer",
"description": "The percent discount that the customer will receive."
},
"amount_limit": {
"type": "integer",
"description": "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."
},
"is_dynamic": {
"type": "boolean",
"description": "Flag indicating whether the discount was calculated using a formula."
}
}
},
"6_res_validate_voucher_discount_fixed": {
"title": "Fixed Discount",
"type": "object",
"description": "This is an object representing the discount that the customer would receive in the context of the provided request body parameters. If the discount is calculated based on a formula, this object will return either the discount calculated based on the formula or the fallback value. A fixed discounts sets a fixed total on cart or item(s) and then calculates the discount to apply.",
"properties": {
"type": {
"type": "string",
"default": "FIXED",
"description": "Type of discount."
},
"effect": {
"type": "string",
"enum": [
"APPLY_TO_ORDER",
"APPLY_TO_ITEMS"
],
"description": "Defines how the discount is applied to the customer's order. \n \n| **Effect** | **Definition** |\n|---|---|\n| **APPLY_TO_ORDER** | Sets the order total amount to the value of the fixed amount. The discount value is calculated during the redemption as it's a difference between the total amount of the customer's order and the fixed amount. |\n| **APPLY_TO_ITEMS** | Sets a new price on items. The total discount amount is calculated during the redemption and it's a difference between the initial item price and the fixed amount. |"
},
"fixed_amount": {
"type": "integer",
"description": "Sets a fixed value for an order total or the item price. The value is multiplied by 100 to precisely represent 2 decimal places. For example, a $10 discount is written as 1000. If the fixed amount is calculated by the formula, i.e. the `fixed_amount_formula` parameter is present in the fixed amount definition, this value becomes the **fallback value**. As a result, if the formula cannot be calculated due to missing metadata, for example, this value will be used as the fixed value."
}
}
},
"6_res_validate_voucher_discount_unit": {
"title": "Unit Discount, single item",
"description": "This is an object representing the discount that the customer would receive in the context of the provided request body parameters. If the discount is calculated based on a formula, this object will return either the discount calculated based on the formula or the fallback value.",
"oneOf": [
{
"$ref": "#/components/schemas/6_res_validate_voucher_discount_unit_product"
},
{
"$ref": "#/components/schemas/6_res_validate_voucher_discount_unit_sku"
}
]
},
"6_res_validate_voucher_discount_unit_multiple": {
"title": "Unit Discount, multiple items",
"type": "object",
"description": "This is an object representing the discount that the customer would receive in the context of the provided request body parameters. If the discount is calculated based on a formula, this object will return either the discount calculated based on the formula or the fallback value.",
"properties": {
"type": {
"type": "string",
"default": "UNIT",
"description": "Discount type."
},
"effect": {
"type": "string",
"default": "ADD_MANY_ITEMS",
"description": "Defines how the discount is applied to the customer's order."
},
"units": {
"oneOf": [
{
"$ref": "#/components/schemas/6_res_validate_voucher_discount_unit_product_multiple"
},
{
"$ref": "#/components/schemas/6_res_validate_voucher_discount_unit_sku_multiple"
}
]
}
}
},
"6_res_validate_voucher_discount_shipping": {
"title": "Shipping Discount",
"type": "object",
"description": "This is an object representing the discount that the customer would receive in the context of the provided request body parameters. If the discount is calculated based on a formula, this object will return either the discount calculated based on the formula or the fallback value.",
"properties": {
"type": {
"type": "string",
"default": "UNIT",
"description": "Discount type."
},
"effect": {
"type": "string",
"description": "Defines how the unit is added to the customer's order.",
"default": "ADD_MISSING_ITEMS"
},
"unit_off": {
"type": "integer",
"description": "Number of units to be granted a full value discount.",
"default": 1
},
"unit_type": {
"type": "string",
"description": "The shipping \"product\" deemed as free.",
"default": "prod_5h1pp1ng"
},
"product": {
"type": "object",
"description": "Contains information about the shipping \"product\".",
"properties": {
"id": {
"type": "string",
"description": "Unique shipping \"product\" ID, assigned by Voucherify.",
"default": "prod_5h1pp1ng"
},
"source_id": {
"type": "string",
"description": "\"Product's\" source ID.",
"default": "5h1pp1ng"
},
"name": {
"type": "string",
"description": "\"Product\" name.",
"default": "Shipping"
}
}
}
}
},
"6_res_session_lock_discount_voucher": {
"title": "Session Lock",
"type": "object",
"description": "Schema model for `session` lock object. The session object contains information about the session key that was used to establish a session between multiple parallel validation and redemption requests.",
"properties": {
"type": {
"type": "string",
"description": "This session locks the redemption **quantity** by 1.",
"default": "LOCK"
},
"key": {
"type": "string",
"description": "The session unique ID assigned by Voucherify or your own unique session ID. ",
"example": "ssn_yQGMTeKBSw8OOuFPwlBEjzGy8d8VA9Ts"
},
"ttl_unit": {
"type": "string",
"description": "Defines the type of unit in which the session time is counted.",
"enum": [
"HOURS",
"DAYS",
"MINUTES",
"SECONDS",
"MILLISECONDS",
"MICROSECONDS",
"NANOSECONDS"
]
},
"ttl": {
"type": "integer",
"description": "Value for the period of time that the session is active. Units for this parameter are defined by the `session.ttl_unit` parameter."
}
}
},
"6_res_session_lock_gift_card": {
"title": "Session Lock",
"type": "object",
"description": "Schema model for `session` lock object. The session object contains information about the session key that was used to establish a session between multiple parallel validation and redemption requests.",
"properties": {
"type": {
"type": "string",
"description": "This session locks the redemption **quantity** by 1 and the redemption **gift credits** specified within the request.",
"default": "LOCK"
},
"key": {
"type": "string",
"description": "The session unique ID assigned by Voucherify or your own unique session ID. Sending an existing ID will result in overwriting an existing session. If no session key is provided, then a new ID will be generated.",
"example": "ssn_yQGMTeKBSw8OOuFPwlBEjzGy8d8VA9Ts"
},
"ttl_unit": {
"type": "string",
"description": "Defines the type of unit in which the session time is counted.",
"enum": [
"HOURS",
"DAYS",
"MINUTES",
"SECONDS",
"MILLISECONDS",
"MICROSECONDS",
"NANOSECONDS"
]
},
"ttl": {
"type": "integer",
"description": "Value for the period of time that the session is active. Units for this parameter are defined by the `session.ttl_unit` parameter."
}
}
},
"6_obj_order_object_apply_to_order": {
"type": "object",
"title": "Order object - Effect: Apply to order",
"description": "This is an object representing an order with calculated discounts applied using the voucher code.",
"properties": {
"id": {
"type": "string",
"example": "ord_OLWs41pBk7VFn6ZTyX9U6keh",
"description": "Unique order ID, assigned by Voucherify. This parameter is returned only if you use the order ID parameter of an already created and synced order in the Voucherify application, i.e by sending the `order.id` parameter in the request body."
},
"source_id": {
"type": "string",
"description": "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. This parameter is returned only if you use the order ID parameter of an already created and synced order in the Voucherify application, i.e by sending the `order.id` parameter in the request body."
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2022-10-06T11:40:48.705Z",
"description": "Timestamp representing the date and time when the order was created. The value is shown in the ISO 8601 format. This parameter is returned only if you use the order ID parameter of an already created and synced order in the Voucherify application, i.e by sending the `order.id` parameter in the request body."
},
"updated_at": {
"type": "string",
"format": "date-time",
"example": "2022-10-06T11:47:20.760Z",
"description": "Timestamp representing the date and time when the order was updated. The value is shown in the ISO 8601 format. This parameter is returned only if you use the order ID parameter of an already created and synced order in the Voucherify application, i.e by sending the `order.id` parameter in the request body."
},
"status": {
"type": "string",
"description": "Order status. This parameter is returned if you use the order ID parameter of an already created and synced order in the Voucherify application, i.e by sending the `order.id` parameter in the request body or if you send the request body parameter when defining an order in the request body. This parameter can be passed but it's not required for validation at all. It's used in the redemption process. Normally after the redemption is done, the order is automatically to a `PAID` status. To avoid such default behaviour, the user can pass any of the other status options and it will be set the order status after the redemption instead of the default `PAID`.",
"enum": [
"CREATED",
"PAID",
"CANCELED",
"FULFILLED"
]
},
"amount": {
"type": "integer",
"description": "Order amount before applying any discount."
},
"discount_amount": {
"type": "integer",
"description": "Sum of all order-level discounts applied to the order."
},
"total_discount_amount": {
"type": "integer",
"description": "Sum of all order-level discounts."
},
"total_amount": {
"type": "integer",
"description": "Order amount after applying all the discounts. \n`total_amount` = `amount` - `total_discount_amount`"
},
"applied_discount_amount": {
"type": "integer",
"description": "This field shows the order-level discount applied."
},
"total_applied_discount_amount": {
"type": "integer",
"description": "This field sums up all order-level discounts applied to the order."
},
"items": {
"type": "array",
"description": "Array of order items that have been applied to the order. Each order item can show the effects of particular discounts on the item-level.",
"items": {
"type": "object",
"properties": {
"object": {
"type": "string",
"default": "order_item",
"description": "The type of the object represented by JSON. This object stores information about the `order_item`."
},
"product_id": {
"type": "string",
"example": "prod_5h0wc453_1",
"description": "A unique identifier that represents the product and is assigned by Voucherify."
},
"sku_id": {
"type": "string",
"example": "sku_prod_5h0wc453_1_1",
"description": "A unique identifier that represents the SKU and is assigned by Voucherify."
},
"quantity": {
"type": "integer",
"description": "Quantity of the item in the cart."
},
"amount": {
"type": "integer",
"description": "Represents a total pre-discount amount of order item (`price` * `quantity`)."
},
"price": {
"type": "integer",
"description": "Unit price of an item. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `$100.00`."
},
"subtotal_amount": {
"type": "integer",
"description": "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`. \n`subtotal_amount`=`amount`-`discount_amount`"
},
"product": {
"type": "object",
"description": "This object stores more information about the related product.",
"properties": {
"id": {
"type": "string",
"example": "prod_5h0wc453_1",
"description": "A unique identifier that represents the product and is assigned by Voucherify."
},
"source_id": {
"type": "string",
"description": "A unique product identifier from your inventory system.",
"example": "illy-arabica"
},
"name": {
"type": "string",
"example": "Brewing System",
"description": "Product name."
},
"price": {
"type": "integer",
"description": "Unit price of a product. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `$100.00`."
}
}
},
"sku": {
"type": "object",
"description": "This object stores more information about the related SKU.",
"properties": {
"id": {
"type": "string",
"example": "sku_prod_5h0wc453_1_1",
"description": "A unique identifier that represents the SKU and is assigned by Voucherify."
},
"source_id": {
"type": "string",
"example": "illy-arabica-250g",
"description": "A unique SKU identifier from your inventory system."
},
"sku": {
"type": "string",
"description": "SKU name."
},
"price": {
"type": "integer",
"description": "Unit price of a SKU. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `$100.00`."
}
}
}
}
}
},
"metadata": {
"type": "object",
"description": "The metadata object stores all custom attributes assigned to the order. A set of key/value pairs that are att to an order object. Stores additional information about the order in a structured format."
},
"customer": {
"type": "object",
"description": "Object containing information about the customer that is making the purchase.",
"properties": {
"id": {
"type": "string",
"example": "cust_7iUa6ICKyU6gH40dBU25kQU1",
"description": "Unique customer identifier of the customer making the purchase. The ID is assigned by Voucherify."
},
"object": {
"type": "string",
"default": "customer",
"description": "Type of object represented by the `customer` object."
}
}
},
"referrer": {
"type": "object",
"description": "Object containing information about the referrer.",
"properties": {
"id": {
"type": "string",
"example": "cust_7iUa6ICKyU6gH40dBU25kQU1",
"description": "Unique referrer ID, who referred the customer making the purchase."
},
"object": {
"type": "string",
"default": "customer",
"description": "Type of object represented by the `referrer` object."
}
}
},
"customer_id": {
"type": "string",
"description": "Unique customer identifier of the customer making the purchase. The ID is assigned by Voucherify.",
"example": "cust_7iUa6ICKyU6gH40dBU25kQU1"
},
"referrer_id": {
"type": "string",
"example": "cust_nM4jqPiaXUvQdVSA6vTRUnix",
"description": "Unique referrer ID."
},
"object": {
"type": "string",
"default": "order",
"description": "The type of the object represented by JSON. This object stores information about the `order`."
}
}
},
"6_res_session_lock_loyalty_card": {
"title": "Session Lock",
"type": "object",
"description": "Schema model for `session` lock object. The session object contains information about the session key that was used to establish a session between multiple parallel validation and redemption requests.",
"properties": {
"type": {
"type": "string",
"description": "This session locks the redemption **quantity** by 1 and the redemption **loyalty points** specified within the request.",
"default": "LOCK"
},
"key": {
"type": "string",
"description": "The session unique ID assigned by Voucherify or your own unique session ID. Sending an existing ID will result in overwriting an existing session. If no session key is provided, then a new ID will be generated.",
"example": "ssn_yQGMTeKBSw8OOuFPwlBEjzGy8d8VA9Ts"
},
"ttl_unit": {
"type": "string",
"description": "Defines the type of unit in which the session time is counted.",
"enum": [
"HOURS",
"DAYS",
"MINUTES",
"SECONDS",
"MILLISECONDS",
"MICROSECONDS",
"NANOSECONDS"
]
},
"ttl": {
"type": "integer",
"description": "Value for the period of time that the session is active. Units for this parameter are defined by the `session.ttl_unit` parameter."
}
}
},
"6_req_session_lock_discount_code": {
"title": "Discount Code Session Lock",
"type": "object",
"description": "Schema model for `session` lock object. The session object is **required** to establish a session between multiple parallel validation and redemption requests. If you only send the `type` parameter in the request, then by default the session lock will be established for 7 days. Read more on establishing a [validation session](/guides/locking-validation-session).",
"properties": {
"type": {
"type": "string",
"description": "This parameter is **required** to establish a new session. The session locks the redemption **quantity** by 1.",
"default": "LOCK",
"enum": [
"LOCK"
]
},
"key": {
"type": "string",
"description": "The session unique ID assigned by Voucherify or your own unique session ID. Sending an existing ID will result in overwriting an existing session. If no session key is provided, then a new ID will be generated.",
"example": "ssn_yQGMTeKBSw8OOuFPwlBEjzGy8d8VA9Ts"
},
"ttl_unit": {
"type": "string",
"description": "Defines the type of unit in which the session time is counted.",
"enum": [
"HOURS",
"DAYS",
"MINUTES",
"SECONDS",
"MILLISECONDS",
"MICROSECONDS",
"NANOSECONDS"
]
},
"ttl": {
"type": "integer",
"description": "Value for the period of time that the session is active. Units for this parameter are defined by the `session.ttl_unit` parameter."
}
}
},
"6_req_validate_voucher_customer_id": {
"title": "Customer ID",
"description": "You can pass the unique customer ID that was assigned by Voucherify.",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The ID of an existing customer that will be linked to redemption in this request.",
"example": "cust_Vzck5i8U3OhcEUFY6MKhN9Rv"
}
}
},
"6_req_validate_voucher_customer_source_id": {
"title": "Customer Source ID",
"description": "You can send the source ID that you used to create the customer in Voucherify.",
"type": "object",
"properties": {
"source_id": {
"type": "string",
"description": "A unique identifier of the customer who validates a voucher. It can be a customer ID or email from a CRM system, database, or a third-party service. If you also pass a customer ID (unique ID assigned by Voucherify), the source ID will be ignored."
}
}
},
"9_req_create_customer": {
"type": "object",
"title": "Customer",
"description": "This is an object containing information about the customer.",
"properties": {
"source_id": {
"type": "string",
"description": "The merchant's customer ID if it is different from the Voucherify customer ID. It is really useful in case of an integration between multiple systems. It can be a customer ID from a CRM system, database or 3rd-party service. \n\nPlease note that if you would like your data to sync based on the `source_id` of the customer, you need to define the `source_id` upfront. You will not be able to change or update the `source_id` later on."
},
"name": {
"type": "string",
"description": "Customer's first and last name."
},
"description": {
"type": "string",
"description": "An arbitrary string that you can attach to a customer object."
},
"email": {
"type": "string",
"description": "Customer's email address."
},
"phone": {
"type": "string",
"description": "Customer's phone number. This parameter is mandatory when you try to send out codes to customers via an SMS channel."
},
"address": {
"type": "object",
"description": "Customer's address.",
"properties": {
"city": {
"type": "string",
"description": "City"
},
"state": {
"type": "string",
"description": "State"
},
"line_1": {
"type": "string",
"description": "First line of address."
},
"line_2": {
"type": "string",
"description": "Second line of address."
},
"country": {
"type": "string",
"description": "Country."
},
"postal_code": {
"type": "string",
"description": "Postal code."
}
}
},
"birthdate": {
"type": "string",
"description": "Customer's birthdate; format `YYYY-MM-DD`.",
"format": "date"
},
"birthday": {
"type": "string",
"description": "`Deprecated`. ~~Customer's birthdate; format `YYYY-MM-DD`~~.",
"format": "date"
},
"metadata": {
"type": "object",
"description": "A set of custom key/value pairs that you can attach to a customer. The metadata object stores all custom attributes assigned to the customer. It can be useful for storing additional information about the customer in a structured format. This metadata can be used for validating whether the customer qualifies for a discount or it can be used in building customer segments. "
}
}
},
"6_req_validate_voucher_order_id": {
"title": "Order ID",
"description": "You can pass the unique order ID that was assigned by Voucherify.",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique ID assigned by Voucherify of an existing order that will be linked to the redemption of this request."
}
}
},
"6_req_validate_voucher_order_source_id": {
"title": "Order Source ID",
"description": "You can send the source ID that you used to create the order in Voucherify.",
"type": "object",
"properties": {
"source_id": {
"type": "string",
"description": "Unique source ID of an existing order that will be linked to the redemption of this request."
}
}
},
"OrdersCreateRequestBody": {
"title": "Orders Create Request Body",
"type": "object",
"description": "Request body schema for **POST** `v1/orders`.",
"allOf": [
{
"$ref": "#/components/schemas/Order"
},
{
"title": "Order Customer And Referrer Ids Objects",
"type": "object",
"description": "Order information.",
"properties": {
"created_at": {
"type": "string",
"example": "2021-12-22T10:13:06.487Z",
"description": "Timestamp representing the date and time when the order was created. The value is shown in the ISO 8601 format.",
"format": "date-time"
},
"referrer_id": {
"type": "string",
"nullable": true,
"description": "Unique referrer ID.",
"example": "cust_nM4jqPiaXUvQdVSA6vTRUnix"
},
"customer": {
"allOf": [
{
"$ref": "#/components/schemas/Customer"
}
]
},
"referrer": {
"allOf": [
{
"$ref": "#/components/schemas/Referrer"
}
]
}
}
}
]
},
"6_req_session_lock_gift_card": {
"title": "Gift Card Session Lock",
"type": "object",
"description": "Schema model for `session` lock object. The session object is **required** to establish a session between multiple parallel validation and redemption requests. If you only send the `type` parameter in the request, then by default the session lock will be established for 7 days. Read more on establishing a [validation session](/guides/locking-validation-session).",
"properties": {
"type": {
"type": "string",
"description": "This parameter is **required** to establish a new session. The session locks the redemption **quantity** by 1 and the redemption **gift credits** specified within the request.",
"default": "LOCK",
"enum": [
"LOCK"
]
},
"key": {
"type": "string",
"description": "The session unique ID assigned by Voucherify or your own unique session ID. Sending an existing ID will result in overwriting an existing session. If no session key is provided, then a new ID will be generated.",
"example": "ssn_yQGMTeKBSw8OOuFPwlBEjzGy8d8VA9Ts"
},
"ttl_unit": {
"type": "string",
"description": "Defines the type of unit in which the session time is counted.",
"enum": [
"HOURS",
"DAYS",
"MINUTES",
"SECONDS",
"MILLISECONDS",
"MICROSECONDS",
"NANOSECONDS"
]
},
"ttl": {
"type": "integer",
"description": "Value for the period of time that the session is active. Units for this parameter are defined by the `session.ttl_unit` parameter."
}
}
},
"6_req_session_lock_loyalty_card": {
"title": "Loyalty Card Session Lock",
"type": "object",
"description": "Schema model for `session` lock object. The session object is **required** to establish a session between multiple parallel validation and redemption requests. If you only send the `type` parameter in the request, then by default the session lock will be established for 7 days. Read more on establishing a [validation session](/guides/locking-validation-session).",
"properties": {
"type": {
"type": "string",
"description": "This parameter is **required** to establish a new session. The session locks the redemption **quantity** by 1 and the redemption **loyalty points** specified within the request.",
"default": "LOCK",
"enum": [
"LOCK"
]
},
"key": {
"type": "string",
"description": "The session unique ID assigned by Voucherify or your own unique session ID. Sending an existing ID will result in overwriting an existing session. If no session key is provided, then a new ID will be generated.",
"example": "ssn_yQGMTeKBSw8OOuFPwlBEjzGy8d8VA9Ts"
},
"ttl_unit": {
"type": "string",
"description": "Defines the type of unit in which the session time is counted.",
"enum": [
"HOURS",
"DAYS",
"MINUTES",
"SECONDS",
"MILLISECONDS",
"MICROSECONDS",
"NANOSECONDS"
]
},
"ttl": {
"type": "integer",
"description": "Value for the period of time that the session is active. Units for this parameter are defined by the `session.ttl_unit` parameter."
}
}
},
"7_obj_redemption_object_discount_voucher_extended": {
"type": "object",
"title": "Discount Voucher",
"description": "This is an object representing a redemption. \n\nRedemption is the key operation in the voucher and promotion tier lifecycle. A customer can redeem a voucher or promotion tier once or multiple times depending on selected limit (`quantity`). Each redemption is recorded in voucher/promotion's history (`redemption_entries`). There is also an option to cancel a redemption. We call such operation a [redemption rollback](rollback-redemption).",
"properties": {
"id": {
"type": "string",
"example": "r_0bc92f81a6801f9bca",
"description": "Unique redemption ID."
},
"object": {
"type": "string",
"description": "The type of the object represented by the JSON. This object stores information about the `redemption`.",
"default": "redemption"
},
"date": {
"type": "string",
"format": "date-time",
"example": "2022-10-03T12:24:58.008Z",
"description": "Timestamp in ISO 8601 format indicating when the redemption occured."
},
"customer_id": {
"type": "string",
"example": "cust_i8t5Tt6eiKG5K79KQlJ0Vs64",
"description": "Unique customer ID of the redeeming customer."
},
"tracking_id": {
"type": "string",
"example": "track_fxEMFiLowFHg==",
"description": "Hashed customer source ID."
},
"metadata": {
"type": "object",
"description": "The metadata object stores all custom attributes in the form of key/value pairs assigned to the redemption."
},
"result": {
"type": "string",
"enum": [
"SUCCESS",
"FAILURE"
],
"description": "Redemption result."
},
"order": {
"description": "Defines the details of the order that is related to the redemption.",
"allOf": [
{
"$ref": "#/components/schemas/7_obj_order_object"
}
]
},
"channel": {
"type": "object",
"description": "Defines the details of the channel through which the redemption was issued.",
"properties": {
"channel_id": {
"type": "string",
"example": "user_g24UoRO3Caxu7FCT4n5tpYEa3zUG0FrH",
"description": "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."
},
"channel_type": {
"type": "string",
"description": "The source of the channel for the redemption. A `USER` corresponds to the Voucherify Dashboard and an `API` corresponds to the API.",
"enum": [
"USER",
"API"
]
}
}
},
"customer": {
"type": "object",
"description": "Defines the customer that is related to the redemption.",
"properties": {
"id": {
"type": "string",
"description": "The unique ID of a customer that is assigned by Voucherify.",
"example": "cust_eWgXlBBiY6THFRJwX45Iakv4"
},
"name": {
"type": "string",
"description": "Customer's first and last name."
},
"email": {
"type": "string",
"description": "Customer's email address."
},
"source_id": {
"type": "string",
"description": "The merchant's customer ID if it is different from the Voucherify customer ID. It is really useful in case of an integration between multiple systems. It can be a customer ID from a CRM system, database or 3rd-party service."
},
"metadata": {
"type": "object",
"description": "The metadata object stores all custom attributes assigned to the customer. A set of key/value pairs that you can attach to a customer object. It can be useful for storing additional information about the customer in a structured format."
},
"object": {
"type": "string",
"description": "Type of object represented is `customer`.",
"default": "customer"
}
}
},
"related_object_type": {
"type": "string",
"description": "Defines the related object.\n\n| **Related Object** | **Definition** |\n| :--- | :--- |\n| voucher | Either a discount voucher, gift card, or loyalty card. |",
"default": "voucher",
"enum": [
"voucher"
]
},
"related_object_id": {
"type": "string",
"description": "Unique related object ID assigned by Voucherify, i.e. v_lfZi4rcEGe0sN9gmnj40bzwK2FH6QUno for a voucher."
},
"voucher": {
"description": "Defines the details of the voucher being redeemed.",
"allOf": [
{
"$ref": "#/components/schemas/Voucher"
},
{
"$ref": "#/components/schemas/VoucherHolder"
}
]
}
}
},
"7_obj_redemption_object_loyalty_card_extended": {
"type": "object",
"title": "Loyalty Card Voucher",
"description": "This is an object representing a redemption. \n\nRedemption is the key operation in the voucher and promotion tier lifecycle. A customer can redeem a voucher or promotion tier once or multiple times depending on selected limit (`quantity`). Each redemption is recorded in voucher/promotion's history (`redemption_entries`). There is also an option to cancel a redemption. We call such operation a [redemption rollback](rollback-redemption).",
"properties": {
"id": {
"type": "string",
"example": "r_0bc92f81a6801f9bca",
"description": "Unique redemption ID."
},
"object": {
"type": "string",
"description": "The type of the object represented by the JSON. This object stores information about the redemption.",
"default": "redemption"
},
"date": {
"type": "string",
"format": "date-time",
"example": "2022-10-03T12:24:58.008Z",
"description": "Timestamp in ISO 8601 format indicating when the redemption occured."
},
"customer_id": {
"type": "string",
"example": "cust_i8t5Tt6eiKG5K79KQlJ0Vs64",
"description": "Unique customer ID of the redeeming customer."
},
"tracking_id": {
"type": "string",
"example": "track_fxEMFiLowFHg==",
"description": "Hashed customer source ID."
},
"metadata": {
"type": "object",
"description": "The metadata object stores all custom attributes in the form of key/value pairs assigned to the redemption."
},
"amount": {
"type": "integer",
"description": "Number of points being redeemed for a reward."
},
"result": {
"type": "string",
"enum": [
"SUCCESS",
"FAILURE"
],
"description": "Redemption result."
},
"order": {
"description": "Defines the details of the order that is related to the redemption.",
"allOf": [
{
"$ref": "#/components/schemas/7_obj_order_object"
}
]
},
"channel": {
"type": "object",
"description": "Defines the details of the channel through which the redemption was issued.",
"properties": {
"channel_id": {
"type": "string",
"example": "user_g24UoRO3Caxu7FCT4n5tpYEa3zUG0FrH",
"description": "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."
},
"channel_type": {
"type": "string",
"description": "The source of the channel for the redemption. A `USER` corresponds to the Voucherify Dashboard and an `API` corresponds to the API.",
"enum": [
"USER",
"API"
]
}
}
},
"customer": {
"type": "object",
"description": "Defines the customer redeeming the reward.",
"properties": {
"id": {
"type": "string",
"description": "The unique ID of a customer that is assigned by Voucherify.",
"example": "cust_eWgXlBBiY6THFRJwX45Iakv4"
},
"name": {
"type": "string",
"description": "Customer's first and last name."
},
"email": {
"type": "string",
"description": "Customer's email address."
},
"source_id": {
"type": "string",
"description": "The merchant's customer ID if it is different from the Voucherify customer ID. It is really useful in case of an integration between multiple systems. It can be a customer ID from a CRM system, database or 3rd-party service."
},
"metadata": {
"type": "object",
"description": "The metadata object stores all custom attributes assigned to the customer. A set of key/value pairs that you can attach to a customer object. It can be useful for storing additional information about the customer in a structured format."
},
"object": {
"type": "string",
"description": "Type of object represented is `customer`.",
"default": "customer"
}
}
},
"related_object_type": {
"type": "string",
"description": "Defines the related object, i.e. `voucher`.",
"default": "voucher",
"enum": [
"voucher"
]
},
"related_object_id": {
"type": "string",
"description": "Unique related object ID assigned by Voucherify, i.e. `v_lfZi4rcEGe0sN9gmnj40bzwK2FH6QUno` for a voucher."
},
"voucher": {
"description": "Defines the details of the voucher being redeemed.",
"allOf": [
{
"$ref": "#/components/schemas/Voucher"
}
]
},
"reward": {
"description": "Defines the reward being redeemed.",
"oneOf": [
{
"$ref": "#/components/schemas/7_obj_redemption_object_loyalty_card_pay_with_points"
},
{
"$ref": "#/components/schemas/7_obj_redemption_object_loyalty_card_material_product"
},
{
"$ref": "#/components/schemas/7_obj_redemption_object_loyalty_card_material_sku"
},
{
"$ref": "#/components/schemas/7_obj_redemption_object_loyalty_card_digital"
}
]
},
"loyalty_card": {
"type": "object",
"description": "Stores the number of points being subtracted from the loyalty card for the reward redemption.",
"properties": {
"points": {
"type": "integer",
"description": "Number of points being subtracted from the loyalty card for the reward redemption."
}
}
}
}
},
"7_obj_redemption_object_gift_card_extended": {
"type": "object",
"title": "Gift Card",
"description": "This is an object representing a gift card redemption.",
"properties": {
"id": {
"type": "string",
"example": "r_0bc92f81a6801f9bca",
"description": "Unique redemption ID."
},
"object": {
"type": "string",
"description": "The type of the object represented by the JSON. This object stores information about the `redemption`.",
"default": "redemption"
},
"date": {
"type": "string",
"format": "date-time",
"example": "2022-10-03T12:24:58.008Z",
"description": "Timestamp in ISO 8601 format indicating when the redemption occured."
},
"customer_id": {
"type": "string",
"example": "cust_i8t5Tt6eiKG5K79KQlJ0Vs64",
"description": "Unique customer ID of the redeeming customer."
},
"tracking_id": {
"type": "string",
"example": "track_fxEMFiLowFHg==",
"description": "Hashed customer source ID."
},
"metadata": {
"type": "object",
"description": "The metadata object stores all custom attributes in the form of key/value pairs assigned to the redemption."
},
"amount": {
"type": "integer",
"description": "The amount subtracted from the gift card expressed as the smallest currency unit (e.g. 100 cents for $1.00)."
},
"result": {
"type": "string",
"enum": [
"SUCCESS",
"FAILURE"
],
"description": "Redemption result."
},
"order": {
"description": "Defines the details of the order that is related to the redemption.",
"allOf": [
{
"$ref": "#/components/schemas/7_obj_order_object"
}
]
},
"channel": {
"type": "object",
"description": "Defines the details of the channel through which the redemption was issued.",
"properties": {
"channel_id": {
"type": "string",
"example": "user_g24UoRO3Caxu7FCT4n5tpYEa3zUG0FrH",
"description": "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."
},
"channel_type": {
"type": "string",
"description": "The source of the channel for the redemption. A `USER` corresponds to the Voucherify Dashboard and an `API` corresponds to the API.",
"enum": [
"USER",
"API"
]
}
}
},
"customer": {
"type": "object",
"description": "Defines the customer redeeming the gift card.",
"properties": {
"id": {
"type": "string",
"description": "The unique ID of a customer that is assigned by Voucherify.",
"example": "cust_eWgXlBBiY6THFRJwX45Iakv4"
},
"name": {
"type": "string",
"description": "Customer's first and last name."
},
"email": {
"type": "string",
"description": "Customer's email address."
},
"source_id": {
"type": "string",
"description": "The merchant's customer ID if it is different from the Voucherify customer ID. It is really useful in case of an integration between multiple systems. It can be a customer ID from a CRM system, database or 3rd-party service."
},
"metadata": {
"type": "object",
"description": "The metadata object stores all custom attributes assigned to the customer. A set of key/value pairs that you can attach to a customer object. It can be useful for storing additional information about the customer in a structured format."
},
"object": {
"type": "string",
"description": "Type of object represented is `customer`.",
"default": "customer"
}
}
},
"related_object_type": {
"type": "string",
"description": "Defines the related object.\n\n| **Related Object** | **Definition** |\n| :--- | :--- |\n| voucher | Either a discount voucher, gift card, or loyalty card. |",
"default": "voucher",
"enum": [
"voucher"
]
},
"related_object_id": {
"type": "string",
"description": "Unique related object ID assigned by Voucherify, i.e. v_lfZi4rcEGe0sN9gmnj40bzwK2FH6QUno for a voucher."
},
"voucher": {
"description": "Defines the details of the voucher being redeemed.",
"allOf": [
{
"$ref": "#/components/schemas/Voucher"
}
]
},
"gift": {
"type": "object",
"description": "Contains the amount being subtracted from the gift card for the redemption.",
"properties": {
"amount": {
"type": "integer",
"description": "The amount subtracted from the gift card expressed as the smallest currency unit (e.g. 100 cents for $1.00)."
}
}
}
}
},
"CreatePublicationBase": {
"title": "Create Publication Base",
"type": "object",
"description": "Create publication",
"properties": {
"source_id": {
"type": "string",
"description": "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.\nIf `source_id` is provided only 1 voucher can be published per request."
},
"customer": {
"description": "Contains information about the customer to whom the publication was directed. Use `customer.id`, `customer.source_id`, or both to identify the customer; at least one of them is required.",
"allOf": [
{
"$ref": "#/components/schemas/Customer"
}
]
},
"metadata": {
"type": "object",
"description": "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": {
"type": "string",
"description": "Specify the distribution channel."
}
},
"required": [
"customer"
]
},
"CreatePublicationCampaign": {
"title": "Create Publication Campaign",
"type": "object",
"description": "Create publication with campaign.",
"properties": {
"name": {
"type": "string",
"description": "Name of voucher's parent campaign or unique campaign ID that was assigned by Voucherify.",
"example": "camp_dphuwqH7BOVkgh4JmpDtS32l"
},
"count": {
"type": "integer",
"description": "Number of vouchers to be published to customer.",
"minimum": 1,
"maximum": 50
}
},
"required": [
"name"
]
},
"PublicationsCreateBaseResponseBody": {
"title": "Publications Create Base Response Body",
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "pub_BbjAXnmm8e0SIm3zG8qvvFCP0KuLywtp",
"description": "Unique publication ID, assigned by Voucherify."
},
"object": {
"type": "string",
"default": "publication",
"enum": [
"publication"
],
"description": "The type of the object represented by the JSON. This object stores information about the `publication`."
},
"created_at": {
"type": "string",
"example": "2022-09-23T09:57:00.434Z",
"description": "Timestamp representing the date and time when the publication was created. The value is shown in the ISO 8601 format.",
"format": "date-time"
},
"customer_id": {
"type": "string",
"example": "cust_eWgXlBBiY6THFRJwX45Iakv4",
"description": "Unique customer ID of the customer receiving the publication."
},
"tracking_id": {
"type": "string",
"description": "Customer's `source_id`."
},
"metadata": {
"type": "object",
"description": "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": {
"type": "string",
"description": "How the publication was originated. It can be your own custom channel or an example value provided here.",
"default": "API",
"enum": [
"API"
]
},
"source_id": {
"type": "string",
"nullable": true,
"description": "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": {
"type": "string",
"default": "SUCCESS",
"enum": [
"SUCCESS"
],
"description": "Status of the publication attempt."
},
"customer": {
"$ref": "#/components/schemas/CustomerWithSummaryLoyaltyReferrals"
},
"vouchers_id": {
"type": "array",
"description": "Contains the unique internal voucher ID that was assigned by Voucherify.",
"items": {
"type": "string",
"example": "v_Bw3qWZWv47yb1Onra8F2LlFI1enLakfA"
}
}
},
"required": [
"id",
"object",
"created_at",
"customer_id",
"metadata",
"channel",
"source_id",
"result",
"customer",
"vouchers_id"
]
},
"Voucher": {
"title": "Voucher",
"description": "This is an object representing a voucher with categories and validation rules assignments.",
"allOf": [
{
"$ref": "#/components/schemas/VoucherBase"
},
{
"type": "object",
"properties": {
"categories": {
"type": "array",
"description": "Contains details about the category.",
"items": {
"$ref": "#/components/schemas/Category"
}
},
"validation_rules_assignments": {
"$ref": "#/components/schemas/ValidationRulesAssignmentsList"
}
}
}
]
},
"OrderItem": {
"type": "object",
"title": "Order Item",
"properties": {
"sku_id": {
"type": "string",
"description": "Unique identifier of the SKU. It is assigned by Voucherify."
},
"product_id": {
"type": "string",
"description": "Unique identifier of the product. It is assigned by Voucherify."
},
"related_object": {
"type": "string",
"enum": [
"product",
"sku"
],
"description": "Used along with the source_id property, can be set to either sku or product."
},
"source_id": {
"type": "string",
"description": "The merchant's product/SKU ID (if it is different from the Voucherify product/SKU ID). It is useful in the integration between multiple systems. It can be an ID from an eCommerce site, a database, or a third-party service."
},
"quantity": {
"type": "integer",
"description": "The quantity of the particular item in the cart."
},
"discount_quantity": {
"type": "integer",
"description": "Number of dicounted items."
},
"initial_quantity": {
"type": "integer",
"description": "A positive integer in the smallest unit quantity representing the total amount of the order; this is the sum of the order items' quantity."
},
"amount": {
"type": "integer",
"description": "The total amount of the order item (price * quantity)."
},
"discount_amount": {
"type": "integer",
"description": "Sum of all order-item-level discounts applied to the order."
},
"initial_amount": {
"type": "integer",
"description": "A positive integer in the smallest currency unit (e.g. 100 cents for $1.00) representing the total amount of the order. This is the sum of the order items' amounts."
},
"price": {
"type": "integer",
"description": "Unit price of an item. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `$100.00`."
},
"product": {
"type": "object",
"description": "An object containing details of the related product.",
"properties": {
"id": {
"type": "string",
"description": "A unique identifier that represents the product and is assigned by Voucherify."
},
"source_id": {
"type": "string",
"description": "The merchant's product ID (if it is different than Voucherify's product ID). It is really useful in case of integration between multiple systems. It can be an ID from an eCommerce site, a database or a 3rd party service."
},
"override": {
"type": "boolean",
"description": "The override set to `true` is used to store the product information in the system. If the product does not exist, it will be created with a source_id; if it does exist, the provided values for the name, price, and metadata will replace those already stored in the system. Override works only for endpoints that create an order in the database."
},
"name": {
"type": "string",
"description": "Product name."
},
"metadata": {
"type": "object",
"description": "A set of custom key/value pairs that you can attach to a product. It can be useful for storing additional information about the product in a structured format. It can be used to create product collections."
},
"price": {
"type": "number",
"description": "Product price. A positive integer in the smallest currency unit (e.g. 100 cents for $1.00)."
}
}
},
"sku": {
"type": "object",
"description": "An object containing details of the related SKU.",
"properties": {
"id": {
"type": "string",
"description": "A unique identifier that represents the SKU and is assigned by Voucherify."
},
"source_id": {
"type": "string",
"description": "The merchant's SKU ID (if it is different than Voucherify's SKU ID). It is really useful in case of integration between multiple systems. It can be an ID from an eCommerce site, a database or a 3rd party service."
},
"override": {
"type": "boolean",
"description": "The override set to `true` is used to store the product information in the system. If the product does not exist, it will be created with a source_id; if it does exist, the provided values for the name, price, and metadata will replace those already stored in the system."
},
"sku": {
"type": "string",
"description": "The SKU name."
},
"price": {
"type": "number",
"description": "SKU price. A positive integer in the smallest currency unit (e.g. 100 cents for $1.00)."
},
"metadata": {
"type": "object",
"description": "A set of custom key/value pairs that you can attach to an order item. It can be useful for storing additional information about the order item in a structured format. It can be used to create product collections."
}
}
},
"metadata": {
"type": "object",
"description": "A set of custom key/value pairs that you can attach to an order item. It can be useful for storing additional information about the order item in a structured format. It can be used to define business validation rules."
}
},
"required": [
"object"
]
},
"QualificationsFiltersCondition": {
"title": "Qualifications Filters Condition",
"type": "object",
"properties": {
"$is": {
"type": "array",
"items": {
"type": "string"
}
},
"$is_not": {
"type": "array",
"items": {
"type": "string"
}
},
"$has_value": {
"$ref": "#/components/schemas/Any"
},
"$is_unknown": {
"$ref": "#/components/schemas/Any"
},
"$in": {
"type": "array",
"items": {
"type": "string"
}
},
"$not_in": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"QualificationsRedeemableBase": {
"title": "Single redeemable",
"description": "Data of single redeemable which was properly qualified.",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "ID of the redeemable. For a voucher, it's its `code` value."
},
"object": {
"type": "string",
"description": "Object type of the redeemable.",
"enum": [
"campaign",
"promotion_tier",
"promotion_stack",
"voucher"
]
},
"created_at": {
"type": "string",
"description": "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",
"format": "date-time"
},
"result": {
"$ref": "#/components/schemas/RedeemableResult"
},
"order": {
"allOf": [
{
"$ref": "#/components/schemas/OrderCalculated"
},
{
"type": "object",
"properties": {
"items": {
"type": "array",
"description": "Array of items applied to the order. It can include up to 500 items.",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/OrderCalculatedItem"
},
{
"type": "object",
"properties": {
"application_details": {
"$ref": "#/components/schemas/ApplicationDetails"
}
}
}
]
}
}
}
}
]
},
"validation_rule_id": {
"type": "string",
"description": "A unique validation rule identifier assigned by the Voucherify API. The validation rule is verified before points are added to the balance."
},
"applicable_to": {
"description": "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.",
"allOf": [
{
"$ref": "#/components/schemas/ApplicableToResultList"
}
]
},
"inapplicable_to": {
"description": "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.",
"allOf": [
{
"$ref": "#/components/schemas/InapplicableToResultList"
}
]
},
"metadata": {
"type": "object",
"description": "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": {
"type": "array",
"description": "List of category information.",
"items": {
"$ref": "#/components/schemas/CategoryWithStackingRulesType"
}
},
"banner": {
"type": "string",
"example": "Order Paid - You will get 100 points",
"description": "Name of the earning rule. This is displayed as a header for the earning rule in the Dashboard."
},
"name": {
"type": "string",
"example": "promotion_tier_get_points",
"description": "Name of the redeemable."
},
"campaign_name": {
"type": "string",
"example": "PromotionCampaign",
"description": "Name of the campaign associated to the redeemable. This field is available only if object is not `campaign`"
},
"campaign_id": {
"type": "string",
"example": "camp_Mow7u4gSxagLlZ2oDQ01ZS5N",
"description": "Id of the campaign associated to the redeemable. This field is available only if object is not `campaign`"
},
"validation_rules_assignments": {
"$ref": "#/components/schemas/ValidationRulesAssignmentsList"
}
}
},
"Discount": {
"title": "Discount",
"type": "object",
"description": "Contains information about discount.",
"oneOf": [
{
"$ref": "#/components/schemas/DiscountAmount"
},
{
"$ref": "#/components/schemas/DiscountUnit"
},
{
"$ref": "#/components/schemas/DiscountUnitMultiple"
},
{
"$ref": "#/components/schemas/DiscountPercent"
},
{
"$ref": "#/components/schemas/DiscountFixed"
}
]
},
"ValidityTimeframe": {
"title": "Validity Timeframe",
"type": "object",
"description": "Set recurrent time periods when the earning rule is valid. For example, valid for 1 hour every other day.`start_date` **required** when including the `validity_timeframe`.",
"properties": {
"duration": {
"type": "string",
"description": "Defines the amount of time an earning rule will be active in ISO 8601 format. For example, an earning rule with a `duration` of `PT1H` will be valid for a duration of one hour.",
"example": "PT1H"
},
"interval": {
"type": "string",
"description": "Defines the intervening time between two time points in ISO 8601 format, expressed as a duration. For example, an earning rule with an `interval` of `P2D` will be valid every other day.",
"example": "P2D"
}
}
},
"ValidityDayOfWeek": {
"title": "Validity Day Of Week",
"type": "array",
"description": "Integer array corresponding to the particular days of the week in which the voucher is valid.\n\n- `0` Sunday\n- `1` Monday\n- `2` Tuesday\n- `3` Wednesday\n- `4` Thursday\n- `5` Friday\n- `6` Saturday",
"items": {
"type": "integer",
"enum": [
0,
1,
2,
3,
4,
5,
6
]
}
},
"ValidityHours": {
"title": "Validity Hours",
"type": "object",
"description": "Determines the hours of validity, e.g. to create a happy hours scenario.",
"properties": {
"daily": {
"type": "array",
"description": "Defines the recurring period(s) when the resource is active. The periods should not overlap.",
"items": {
"type": "object",
"description": "Defines the recurring period(s) when the resource will be active.",
"properties": {
"start_time": {
"type": "string",
"format": "time",
"description": "Defines the starting hour of validity in the HH:mm format. The resource is *inactive before* this time.",
"example": "12:00"
},
"days_of_week": {
"type": "array",
"description": "Integer array corresponding to the particular days of the week in which the resource is valid.\n\n- `0` Sunday\n- `1` Monday\n- `2` Tuesday\n- `3` Wednesday\n- `4` Thursday\n- `5` Friday\n- `6` Saturday",
"items": {
"type": "integer",
"enum": [
0,
1,
2,
3,
4,
5,
6
]
}
},
"expiration_time": {
"type": "string",
"format": "time",
"description": "Defines the ending hour of validity in the HH:mm format. The resource is *inactive after* this time.",
"example": "14:00"
}
}
}
}
}
},
"ValidationRuleAssignmentsList": {
"type": "object",
"description": "Validation Rule Assignments List",
"title": "Validation Rule Assignments List",
"properties": {
"object": {
"type": "string",
"description": "The type of the object represented by JSON. This object stores information about validation rule assignments.",
"default": "list"
},
"data_ref": {
"type": "string",
"description": "Identifies the name of the JSON property that contains the array of validation rule assignments.",
"default": "data"
},
"data": {
"type": "array",
"description": "A dictionary that contains an array of validation rule assignments.",
"items": {
"$ref": "#/components/schemas/ValidationRuleAssignment"
}
},
"total": {
"type": "integer",
"description": "Total number of validation rule assignments."
}
},
"required": [
"object",
"data_ref",
"data",
"total"
]
},
"Category": {
"title": "Category",
"description": "This is an object representing a category.",
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique category ID assigned by Voucherify."
},
"name": {
"type": "string",
"description": "Category name."
},
"hierarchy": {
"type": "integer",
"description": "Category hierarchy. Categories with lower hierarchy are processed before categories with higher hierarchy value.",
"minimum": 0
},
"object": {
"type": "string",
"default": "category",
"enum": [
"category"
],
"description": "The type of the object represented by the JSON. This object stores information about the category."
},
"created_at": {
"type": "string",
"description": "Timestamp representing the date and time when the category was created. The value is shown in the ISO 8601 format.",
"example": "2022-07-14T10:45:13.156Z",
"format": "date-time"
},
"updated_at": {
"type": "string",
"example": "2022-08-16T10:52:08.094Z",
"description": "Timestamp representing the date and time when the category was updated. The value is shown in the ISO 8601 format.",
"format": "date-time"
}
},
"required": [
"id",
"name",
"hierarchy",
"created_at",
"object"
]
},
"SimpleCustomer": {
"title": "Simple Customer",
"type": "object",
"description": "Simplified customer data.",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier of an existing customer. It is assigned by Voucherify."
},
"name": {
"type": "string",
"description": "Customer's first and last name."
},
"email": {
"type": "string",
"description": "Customer's email address."
},
"source_id": {
"type": "string",
"description": "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": {
"type": "object",
"description": "A set of custom key/value pairs that are attached to the customer. It stores all custom attributes assigned to the customer."
},
"object": {
"type": "string",
"description": "The type of the object represented by JSON.",
"enum": [
"customer"
]
}
}
},
"RedemptionRewardResult": {
"title": "Redemption Reward Result",
"type": "object",
"properties": {
"customer": {
"nullable": true,
"allOf": [
{
"$ref": "#/components/schemas/SimpleCustomer"
}
]
},
"assignment_id": {
"type": "string",
"nullable": true,
"description": "Unique reward assignment ID assigned by Voucherify."
},
"voucher": {
"nullable": true,
"allOf": [
{
"$ref": "#/components/schemas/Voucher"
}
]
},
"product": {
"nullable": true,
"allOf": [
{
"$ref": "#/components/schemas/Product"
}
]
},
"sku": {
"nullable": true,
"allOf": [
{
"$ref": "#/components/schemas/Sku"
}
]
},
"loyalty_tier_id": {
"type": "string",
"nullable": true,
"description": "Unique loyalty tier ID assigned by Voucherify."
},
"id": {
"type": "string",
"example": "rew_0bc92f81a6801f9bca",
"description": "Unique reward ID."
},
"name": {
"type": "string",
"example": "Reward Name",
"description": "Name of the reward."
},
"object": {
"type": "string",
"description": "The type of the object represented by the JSON",
"default": "reward",
"enum": [
"reward"
]
},
"created_at": {
"type": "string",
"example": "2021-12-22T10:13:06.487Z",
"description": "Timestamp representing the date and time when the redemption was created. The value is shown in the ISO 8601 format.",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time",
"example": "2022-10-03T12:24:58.008Z",
"description": "Timestamp in ISO 8601 format indicating when the reward was updated."
},
"parameters": {
"type": "object",
"description": "These are parameters representing a material reward.",
"properties": {
"campaign": {
"type": "object",
"description": "Defines the product redeemed as a reward.",
"properties": {
"id": {
"type": "string",
"description": "Campaign unique ID.",
"example": "camp_13BbZ0kQsNinhqsX3wUts2UP"
},
"balance": {
"type": "integer",
"description": "Points available for reward redemption. This is calculated as follows: `balance` = `points` - `expired_points` - `subtracted_points` - `redemption.redeemed_points`."
},
"type": {
"type": "string",
"description": "Defines the type of the campaign."
}
}
},
"product": {
"type": "object",
"description": "Defines the product redeemed as a reward.",
"properties": {
"id": {
"type": "string",
"example": "prod_0b7d7dfb05cbe5c616",
"description": "Unique product ID, assigned by Voucherify. "
},
"sku_id": {
"type": "string",
"description": "Unique identifier of the SKU. It is assigned by Voucherify.",
"example": "sku_0a41e31c7b41c28358"
}
}
},
"coin": {
"type": "object",
"description": "Defines the ratio by mapping the number of loyalty points in `points_ratio` to a predefined cash amount in `exchange_ratio`.",
"properties": {
"exchange_ratio": {
"type": "number",
"description": "The cash equivalent of the points defined in the `points_ratio` property."
},
"points_ratio": {
"type": "integer",
"description": "The number of loyalty points that will map to the predefined cash amount defined by the `exchange_ratio` property."
}
}
}
}
},
"metadata": {
"type": "object",
"description": "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": {
"type": "string",
"enum": [
"CAMPAIGN",
"COIN",
"MATERIAL"
],
"description": "Reward type."
}
},
"required": [
"reward",
"customer",
"assignment_id",
"voucher",
"product",
"sku",
"loyalty_tier_id"
]
},
"VoucherBase": {
"title": "Voucher Base",
"description": "This is an object representing a voucher.",
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "v_mkZN9v7vjYUadXnHrMza8W5c34fE5KiV",
"description": "Assigned by the Voucherify API, identifies the voucher."
},
"code": {
"type": "string",
"example": "WVPblOYX",
"description": "A code that identifies a voucher. Pattern can use all letters of the English alphabet, Arabic numerals, and special characters."
},
"campaign": {
"type": "string",
"example": "Gift Card Campaign",
"description": "A unique campaign name, identifies the voucher's parent campaign."
},
"campaign_id": {
"type": "string",
"example": "camp_FNYR4jhqZBM9xTptxDGgeNBV",
"description": "Assigned by the Voucherify API, identifies the voucher's parent campaign."
},
"category": {
"type": "string",
"description": "Tag defining the category that this voucher belongs to. Useful when listing vouchers using the List Vouchers endpoint."
},
"category_id": {
"type": "string",
"description": "Unique category ID assigned by Voucherify.",
"example": "cat_0bb343dee3cdb5ec0c"
},
"type": {
"type": "string",
"enum": [
"GIFT_VOUCHER",
"DISCOUNT_VOUCHER",
"LOYALTY_CARD"
],
"description": "Defines the type of the voucher. "
},
"discount": {
"$ref": "#/components/schemas/Discount"
},
"gift": {
"type": "object",
"description": "Object representing gift parameters. Child attributes are present only if `type` is `GIFT_VOUCHER`. Defaults to `null`.",
"properties": {
"amount": {
"type": "integer",
"example": 10000,
"description": "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": {
"type": "integer",
"description": "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": {
"type": "integer",
"example": 500,
"description": "Available funds. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `$100.00`."
},
"effect": {
"type": "string",
"enum": [
"APPLY_TO_ORDER",
"APPLY_TO_ITEMS"
],
"description": "Defines how the credits are applied to the customer's order."
}
}
},
"loyalty_card": {
"type": "object",
"description": "Object representing loyalty card parameters. Child attributes are present only if `type` is `LOYALTY_CARD`. Defaults to `null`.",
"properties": {
"points": {
"type": "integer",
"example": 7000,
"description": "Total number of points added to the loyalty card over its lifespan."
},
"balance": {
"type": "integer",
"example": 6970,
"description": "Points available for reward redemption. This is calculated as follows: `balance` = `points` - `expired_points` - `subtracted_points` - `redemption.redeemed_points`."
},
"next_expiration_date": {
"type": "string",
"format": "date",
"example": "2023-05-30",
"description": "The next closest date when the next set of points are due to expire."
},
"next_expiration_points": {
"type": "integer",
"description": "The amount of points that are set to expire next."
},
"pending_points": {
"type": "integer",
"description": "Shows the number of pending points that will be added to the loyalty card when they are activated automatically or manually."
},
"expired_points": {
"type": "integer",
"description": "Shows the total number of expired points over the lifetime of the loyalty card."
},
"subtracted_points": {
"type": "integer",
"description": "Shows the total number of subtracted points over the lifetime of the loyalty card."
}
}
},
"start_date": {
"type": "string",
"example": "2021-12-01T00:00:00.000Z",
"format": "date-time",
"description": "Activation timestamp defines when the code starts to be active in ISO 8601 format. Voucher is *inactive before* this date. "
},
"expiration_date": {
"type": "string",
"example": "2021-12-31T00:00:00.000Z",
"format": "date-time",
"description": "Expiration timestamp defines when the code expires in ISO 8601 format. Voucher is *inactive after* this date."
},
"validity_timeframe": {
"$ref": "#/components/schemas/ValidityTimeframe"
},
"validity_day_of_week": {
"$ref": "#/components/schemas/ValidityDayOfWeek"
},
"validity_hours": {
"$ref": "#/components/schemas/ValidityHours"
},
"active": {
"type": "boolean",
"nullable": true,
"description": "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`. \n\n- `true` indicates an *active* voucher\n- `false` indicates an *inactive* voucher"
},
"additional_info": {
"type": "string",
"description": "An optional field to keep any extra textual information about the code such as a code description and details."
},
"metadata": {
"type": "object",
"description": "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": {
"$ref": "#/components/schemas/VoucherAssets"
},
"is_referral_code": {
"type": "boolean",
"nullable": true,
"description": "Flag indicating whether this voucher is a referral code; `true` for campaign type `REFERRAL_PROGRAM`."
},
"created_at": {
"type": "string",
"example": "2021-12-22T10:13:06.487Z",
"description": "Timestamp representing the date and time when the voucher was created. The value is shown in the ISO 8601 format.",
"format": "date-time"
},
"updated_at": {
"type": "string",
"example": "2021-12-22T10:14:45.316Z",
"format": "date-time",
"description": "Timestamp representing the date and time when the voucher was last updated in ISO 8601 format."
},
"holder_id": {
"type": "string",
"example": "cust_eWgXlBBiY6THFRJwX45Iakv4",
"description": "Unique customer identifier of the redeemable holder. It equals to the customer ID assigned by Voucherify."
},
"referrer_id": {
"type": "string",
"description": "Unique identifier of the referring person.",
"example": "cust_Vzck5i8U3OhcEUFY6MKhN9Rv"
},
"object": {
"type": "string",
"description": "The type of the object represented by JSON. Default is `voucher`.",
"default": "voucher"
},
"publish": {
"type": "object",
"description": "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.",
"properties": {
"object": {
"type": "string",
"default": "list",
"description": "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": {
"type": "integer",
"example": 0,
"description": "Publication events counter."
},
"url": {
"type": "string",
"example": "/v1/vouchers/WVPblOYX/publications?page=1&limit=10",
"description": "The endpoint where this list of publications can be accessed using a **GET** method. `/v1/vouchers/{voucher_code}/publications`"
}
}
},
"redemption": {
"type": "object",
"description": "Stores a summary of redemptions that have been applied to the voucher.",
"properties": {
"quantity": {
"type": "integer",
"description": "How many times a voucher can be redeemed. A `null` value means unlimited."
},
"redeemed_quantity": {
"type": "integer",
"example": 1,
"description": "How many times a voucher has already been redeemed."
},
"redeemed_points": {
"type": "integer",
"example": 100000,
"description": "Total loyalty points redeemed."
},
"object": {
"type": "string",
"default": "list",
"description": "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": {
"type": "string",
"example": "/v1/vouchers/WVPblOYX/redemptions?page=1&limit=10",
"description": "The endpoint where this list of redemptions can be accessed using a **GET** method. `/v1/vouchers/{voucher_code}/redemptions`"
}
}
}
}
},
"ValidationRulesAssignmentsList": {
"title": "Validation Rules Assignments List",
"description": "List of Validation Rules Assignments",
"type": "object",
"properties": {
"object": {
"type": "string",
"default": "list",
"enum": [
"list"
],
"description": "The type of the object represented by JSON. This object stores information about validation rules assignments."
},
"data_ref": {
"type": "string",
"default": "data",
"enum": [
"data"
],
"description": "Identifies the name of the attribute that contains the array of validation rules assignments."
},
"data": {
"type": "array",
"description": "Contains array of validation rules assignments.",
"items": {
"$ref": "#/components/schemas/BusValRuleAssignment"
}
},
"total": {
"type": "integer",
"minimum": 0,
"description": "Total number of validation rules assignments."
}
},
"required": [
"object",
"data_ref",
"data",
"total"
]
},
"ApplicableToResultList": {
"title": "Applicable To Result List",
"type": "object",
"properties": {
"data": {
"type": "array",
"description": "Contains array of items to which the discount can apply.",
"items": {
"$ref": "#/components/schemas/ApplicableTo"
}
},
"total": {
"type": "integer",
"minimum": 0,
"description": "Total number of objects defining included products, SKUs, or product collections."
},
"object": {
"type": "string",
"default": "list",
"enum": [
"list"
],
"description": "The type of the object represented by JSON."
},
"data_ref": {
"type": "string",
"description": "The type of the object represented by JSON.",
"default": "data",
"enum": [
"data"
]
}
},
"required": [
"data",
"total",
"object",
"data_ref"
]
},
"InapplicableToResultList": {
"title": "Inapplicable To Result List",
"type": "object",
"properties": {
"data": {
"type": "array",
"description": "Contains array of items to which the discount cannot apply.",
"items": {
"$ref": "#/components/schemas/InapplicableTo"
}
},
"total": {
"type": "integer",
"minimum": 0,
"description": "Total number of objects defining included products, SKUs, or product collections."
},
"object": {
"type": "string",
"default": "list",
"enum": [
"list"
],
"description": "The type of the object represented by JSON."
},
"data_ref": {
"type": "string",
"description": "The type of the object represented by JSON.",
"default": "data",
"enum": [
"data"
]
}
},
"required": [
"data",
"total",
"object",
"data_ref"
]
},
"RedeemableResultVoucherCode": {
"type": "object",
"title": "Coupon Code",
"description": "This is a `result` object representing the results for a coupon code.",
"properties": {
"discount": {
"description": "Discount details about the type of discount to be applied for the redeemable.",
"oneOf": [
{
"$ref": "#/components/schemas/DiscountAmount"
},
{
"$ref": "#/components/schemas/DiscountUnit"
},
{
"$ref": "#/components/schemas/DiscountUnitMultiple"
},
{
"$ref": "#/components/schemas/DiscountPercent"
},
{
"$ref": "#/components/schemas/DiscountFixed"
}
]
},
"bundle": {
"$ref": "#/components/schemas/Bundle"
}
}
},
"RedeemableResultGiftCard": {
"type": "object",
"title": "Gift Card",
"description": "This is a `result` object representing the results for a gift card.",
"properties": {
"gift": {
"description": "Stores the amount of gift card credits to be applied.",
"type": "object",
"properties": {
"balance": {
"type": "integer",
"description": "Available funds at the moment of validation. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `$100.00`."
},
"credits": {
"type": "integer",
"description": "Total number of gift card credits to be applied. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `$100.00`."
}
}
}
}
},
"RedeemableResultLoyaltyCard": {
"type": "object",
"title": "Loyalty Card",
"description": "This is a `result` object representing the results for a loyalty card.",
"properties": {
"loyalty_card": {
"description": "Stores the amount of loyalty card points to be applied in the redemption.",
"type": "object",
"properties": {
"points": {
"type": "integer",
"description": "Total number of loyalty points to be applied in the redemption."
}
}
}
}
},
"RedeemableResultPromotionTier": {
"type": "object",
"title": "Promotion Tier",
"description": "This is a `result` object representing the results for a promotion tier.",
"properties": {
"discount": {
"description": "Discount details about the type of discount to be applied for the redeemable.",
"oneOf": [
{
"$ref": "#/components/schemas/DiscountAmount"
},
{
"$ref": "#/components/schemas/DiscountUnit"
},
{
"$ref": "#/components/schemas/DiscountUnitMultiple"
},
{
"$ref": "#/components/schemas/DiscountPercent"
},
{
"$ref": "#/components/schemas/DiscountFixed"
}
]
},
"bundle": {
"$ref": "#/components/schemas/Bundle"
}
}
},
"RedeemableResultPromotionStack": {
"type": "object",
"title": "Promotion Stack",
"description": "This is a `result` object representing the results for a promotion stack.",
"properties": {
"discount": {
"description": "Discount details about the type of discount to be applied for the redeemable.",
"oneOf": [
{
"$ref": "#/components/schemas/DiscountAmount"
},
{
"$ref": "#/components/schemas/DiscountUnit"
},
{
"$ref": "#/components/schemas/DiscountUnitMultiple"
},
{
"$ref": "#/components/schemas/DiscountPercent"
},
{
"$ref": "#/components/schemas/DiscountFixed"
}
]
},
"bundle": {
"$ref": "#/components/schemas/Bundle"
}
}
},
"6_res_product_collection": {
"title": "Product Collection",
"type": "object",
"description": "Contains definition for a product collection.",
"properties": {
"object": {
"type": "string",
"default": "products_collection",
"description": "This object stores information about the product collection."
},
"id": {
"type": "string",
"example": "pc_4ndRXAsTOzwSdHcQcxf489uU",
"description": "Unique product collection ID assigned by Voucherify."
},
"effect": {
"type": "string",
"enum": [
"APPLY_TO_EVERY",
"APPLY_TO_CHEAPEST",
"APPLY_TO_MOST_EXPENSIVE"
],
"description": "Defines how the discount is applied to the customer's order."
}
}
},
"6_res_product_collection_unit": {
"title": "Product Collection for Unit Discount",
"type": "object",
"description": "Contains definition for a product collection.",
"properties": {
"object": {
"type": "string",
"default": "products_collection",
"description": "This object stores information about the product collection."
},
"id": {
"type": "string",
"example": "pc_4ndRXAsTOzwSdHcQcxf489uU",
"description": "Unique product collection ID assigned by Voucherify."
},
"effect": {
"type": "string",
"enum": [
"APPLY_TO_EVERY",
"APPLY_TO_CHEAPEST",
"APPLY_TO_MOST_EXPENSIVE"
],
"description": "Defines how the discount is applied to the customer's order."
},
"quantity_limit": {
"type": "integer",
"description": "The maximum number of units allowed to be discounted per order line item."
},
"aggregated_quantity_limit": {
"type": "integer",
"description": "The maximum number of units allowed to be discounted combined across all matched order line items."
}
}
},
"6_res_product_collection_fixed_amount": {
"title": "Product Collection for Fixed Amount Discount",
"type": "object",
"description": "Contains definition for a product collection.",
"properties": {
"object": {
"type": "string",
"default": "products_collection",
"description": "This object stores information about the product collection."
},
"id": {
"type": "string",
"example": "pc_4ndRXAsTOzwSdHcQcxf489uU",
"description": "Unique product collection ID assigned by Voucherify."
},
"price": {
"type": "integer",
"description": "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": {
"type": "string",
"description": "Formula used to dynamically calculate the discounted price of an item.",
"example": "\"IF(ORDER_AMOUNT > 300;ORDER_ITEM_PRICE * 0.8;ORDER_ITEM_PRICE)"
},
"effect": {
"type": "string",
"enum": [
"APPLY_TO_EVERY",
"APPLY_TO_CHEAPEST",
"APPLY_TO_MOST_EXPENSIVE"
],
"description": "Defines how the discount is applied to the customer's order."
}
}
},
"6_res_product": {
"title": "Product",
"type": "object",
"description": "Contains definition for a product.",
"properties": {
"object": {
"type": "string",
"default": "product",
"description": "This object stores information about the product."
},
"id": {
"type": "string",
"description": "Unique product ID assigned by Voucherify.",
"example": "prod_0bae2dc5a090fd0184"
},
"source_id": {
"type": "string",
"description": "The product ID from your inventory system."
},
"effect": {
"type": "string",
"enum": [
"APPLY_TO_EVERY",
"APPLY_TO_CHEAPEST",
"APPLY_TO_MOST_EXPENSIVE"
],
"description": "Defines how the discount is applied to the customer's order."
}
}
},
"6_res_product_unit": {
"title": "Product for Unit Discount",
"type": "object",
"description": "Contains definition for a product.",
"properties": {
"object": {
"type": "string",
"default": "product",
"description": "This object stores information about the product."
},
"id": {
"type": "string",
"description": "Unique product ID assigned by Voucherify.",
"example": "prod_0bae2dc5a090fd0184"
},
"source_id": {
"type": "string",
"description": "The product ID from your inventory system."
},
"effect": {
"type": "string",
"enum": [
"APPLY_TO_EVERY",
"APPLY_TO_CHEAPEST",
"APPLY_TO_MOST_EXPENSIVE"
],
"description": "Defines how the discount is applied to the customer's order."
},
"quantity_limit": {
"type": "integer",
"description": "The maximum number of units allowed to be discounted per order line item."
},
"aggregated_quantity_limit": {
"type": "integer",
"description": "The maximum number of units allowed to be discounted combined across all matched order line items."
}
}
},
"6_res_product_fixed_amount": {
"title": "Product for Fixed Amount Discount",
"type": "object",
"description": "Contains definition for a product.",
"properties": {
"object": {
"type": "string",
"default": "product",
"description": "This object stores information about the product."
},
"id": {
"type": "string",
"description": "Unique product ID assigned by Voucherify.",
"example": "prod_0bae2dc5a090fd0184"
},
"source_id": {
"type": "string",
"description": "The product ID from your inventory system."
},
"price": {
"type": "integer",
"description": "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": {
"type": "string",
"description": "Formula used to dynamically calculate the discounted price of an item.",
"example": "IF(ORDER_AMOUNT > 300;ORDER_ITEM_PRICE * 0.8;ORDER_ITEM_PRICE)"
},
"effect": {
"type": "string",
"enum": [
"APPLY_TO_EVERY",
"APPLY_TO_CHEAPEST",
"APPLY_TO_MOST_EXPENSIVE"
],
"description": "Defines how the discount is applied to the customer's order."
}
}
},
"6_res_sku": {
"title": "SKU",
"type": "object",
"description": "Contains definition for a product variant.",
"properties": {
"object": {
"type": "string",
"default": "sku",
"description": "This object stores information about the product variant."
},
"id": {
"type": "string",
"description": "Unique SKU ID assigned by Voucherify.",
"example": "sku_0b7d7dfb090be5c619"
},
"source_id": {
"type": "string",
"description": "The source ID from your inventory system."
},
"product_id": {
"type": "string",
"description": "Parent product's unique ID assigned by Voucherify."
},
"product_source_id": {
"type": "string",
"description": "Parent product's source ID from your inventory system."
},
"effect": {
"type": "string",
"enum": [
"APPLY_TO_EVERY",
"APPLY_TO_CHEAPEST",
"APPLY_TO_MOST_EXPENSIVE"
],
"description": "Defines how the discount is applied to the customer's order."
}
}
},
"6_res_sku_unit": {
"title": "SKU for Unit Discount",
"type": "object",
"description": "Contains definition for a product variant.",
"properties": {
"object": {
"type": "string",
"default": "sku",
"description": "This object stores information about the product variant."
},
"id": {
"type": "string",
"description": "Unique SKU ID assigned by Voucherify.",
"example": "sku_0b7d7dfb090be5c619"
},
"source_id": {
"type": "string",
"description": "The source ID from your inventory system."
},
"product_id": {
"type": "string",
"description": "Parent product's unique ID assigned by Voucherify."
},
"product_source_id": {
"type": "string",
"description": "Parent product's source ID from your inventory system."
},
"effect": {
"type": "string",
"enum": [
"APPLY_TO_EVERY",
"APPLY_TO_CHEAPEST",
"APPLY_TO_MOST_EXPENSIVE"
],
"description": "Defines how the discount is applied to the customer's order."
},
"quantity_limit": {
"type": "integer",
"description": "The maximum number of units allowed to be discounted per order line item."
},
"aggregated_quantity_limit": {
"type": "integer",
"description": "The maximum number of units allowed to be discounted combined across all matched order line items."
}
}
},
"6_res_sku_unit_fixed_amount": {
"title": "SKU for Amount Discount",
"type": "object",
"description": "Contains definition for a product variant.",
"properties": {
"object": {
"type": "string",
"default": "sku",
"description": "This object stores information about the product variant."
},
"id": {
"type": "string",
"description": "Unique SKU ID assigned by Voucherify.",
"example": "sku_0b7d7dfb090be5c619"
},
"source_id": {
"type": "string",
"description": "The source ID from your inventory system."
},
"product_id": {
"type": "string",
"description": "Parent product's unique ID assigned by Voucherify."
},
"product_source_id": {
"type": "string",
"description": "Parent product's source ID from your inventory system."
},
"price": {
"type": "integer",
"description": "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": {
"type": "string",
"description": "Formula used to dynamically calculate the discounted price of an item.",
"example": "IF(ORDER_AMOUNT > 200;ORDER_ITEM_PRICE * 0.2;6)"
},
"effect": {
"type": "string",
"enum": [
"APPLY_TO_EVERY",
"APPLY_TO_CHEAPEST",
"APPLY_TO_MOST_EXPENSIVE"
],
"description": "Defines how the discount is applied to the customer's order."
}
}
},
"6_res_product_collection_excluded": {
"title": "Product Collection",
"type": "object",
"description": "Contains definition for a product collection.",
"properties": {
"object": {
"type": "string",
"default": "products_collection",
"description": "This object stores information about the product collection."
},
"id": {
"type": "string",
"example": "pc_4ndRXAsTOzwSdHcQcxf489uU",
"description": "Unique product collection ID assigned by Voucherify."
},
"effect": {
"type": "string",
"default": "APPLY_TO_EVERY",
"enum": [
"APPLY_TO_EVERY"
],
"description": "Defines how the discount is applied to the customer's order."
}
}
},
"6_res_product_excluded": {
"title": "Product",
"type": "object",
"description": "Contains definition for a product.",
"properties": {
"object": {
"type": "string",
"default": "product",
"description": "This product stores information about the product."
},
"id": {
"type": "string",
"description": "Unique product ID assigned by Voucherify.",
"example": "prod_0bae2dc5a090fd0184"
},
"source_id": {
"type": "string",
"description": "The product ID from your inventory system."
},
"effect": {
"type": "string",
"default": "APPLY_TO_EVERY",
"enum": [
"APPLY_TO_EVERY"
],
"description": "Defines how the discount is applied to the customer's order."
}
}
},
"6_res_sku_excluded": {
"title": "SKU",
"type": "object",
"description": "Contains definition for a product variant.",
"properties": {
"object": {
"type": "string",
"default": "sku",
"description": "This object stores information about the product variant."
},
"id": {
"type": "string",
"description": "Unique SKU ID assigned by Voucherify.",
"example": "sku_0b7d7dfb090be5c619"
},
"source_id": {
"type": "string",
"description": "The source ID from your inventory system."
},
"effect": {
"type": "string",
"default": "APPLY_TO_EVERY",
"enum": [
"APPLY_TO_EVERY"
],
"description": "Defines how the discount is applied to the customer's order."
}
}
},
"6_obj_order_object_apply_to_items": {
"type": "object",
"title": "Order object - Effect: Apply to items",
"description": "This is an object representing an order with calculated discounts applied using the voucher code.",
"properties": {
"id": {
"type": "string",
"example": "ord_OLWs41pBk7VFn6ZTyX9U6keh",
"description": "Unique order ID, assigned by Voucherify. This parameter is returned only if you use the order ID parameter of an already created and synced order in the Voucherify application, i.e by sending the `order.id` parameter in the request body."
},
"source_id": {
"type": "string",
"description": "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. This parameter is returned only if you use the order ID parameter of an already created and synced order in the Voucherify application, i.e by sending the `order.id` parameter in the request body."
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2022-10-06T11:40:48.705Z",
"description": "Timestamp representing the date and time when the order was created. The value is shown in the ISO 8601 format. This parameter is returned only if you use the order ID parameter of an already created and synced order in the Voucherify application, i.e by sending the `order.id` parameter in the request body."
},
"updated_at": {
"type": "string",
"format": "date-time",
"example": "2022-10-06T11:47:20.760Z",
"description": "Timestamp representing the date and time when the order was updated. The value is shown in the ISO 8601 format. This parameter is returned only if you use the order ID parameter of an already created and synced order in the Voucherify application, i.e by sending the `order.id` parameter in the request body."
},
"status": {
"type": "string",
"description": "Order status. This parameter is returned if you use the order ID parameter of an already created and synced order in the Voucherify application, i.e by sending the `order.id` parameter in the request body or if you send the request body parameter when defining an order in the request body. This parameter can be passed but it's not required for validation at all. It's used in the redemption process. Normally after the redemption is done, the order is automatically to a `PAID` status. To avoid such default behaviour, the user can pass any of the other status options and it will be set the order status after the redemption instead of the default `PAID`.",
"enum": [
"CREATED",
"PAID",
"CANCELED",
"FULFILLED"
]
},
"amount": {
"type": "integer",
"description": "Order amount before applying any discount."
},
"items_discount_amount": {
"type": "integer",
"description": "Sum of all product-specific discounts applied. \n`sum(items, i => i.discount_amount)`"
},
"total_discount_amount": {
"type": "integer",
"description": "Sum of all product-specific discounts applied."
},
"total_amount": {
"type": "integer",
"description": "Order amount after applying all the discounts. \n`total_amount` = `amount` - `total_discount_amount`"
},
"items_applied_discount_amount": {
"type": "integer",
"description": "Product-specifc discounts applied to all the items."
},
"total_applied_discount_amount": {
"type": "integer",
"description": "Product-specific discounts applied in the order."
},
"items": {
"type": "array",
"description": "Array of order items that have been applied to the order. Each order item can show the effects of particular discounts on the item-level.",
"items": {
"type": "object",
"properties": {
"object": {
"type": "string",
"default": "order_item",
"description": "The type of the object represented by JSON. This object stores information about the `order_item`."
},
"product_id": {
"type": "string",
"example": "prod_5h0wc453_1",
"description": "A unique identifier that represents the product and is assigned by Voucherify."
},
"sku_id": {
"type": "string",
"example": "sku_prod_5h0wc453_1_1",
"description": "A unique identifier that represents the SKU and is assigned by Voucherify."
},
"quantity": {
"type": "integer",
"description": "Quantity of the item in the cart."
},
"amount": {
"type": "integer",
"description": "Represents a total pre-discount amount of order item (`price` * `quantity`)."
},
"discount_amount": {
"type": "integer",
"description": "The item-level discount applied to the item."
},
"applied_discount_amount": {
"type": "integer",
"description": "The item-level discount applied to the item."
},
"price": {
"type": "integer",
"description": "Unit price of an item. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `$100.00`."
},
"subtotal_amount": {
"type": "integer",
"description": "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`. \n`subtotal_amount`=`amount`-`discount_amount`"
},
"product": {
"type": "object",
"description": "This object stores more information about the related product.",
"properties": {
"id": {
"type": "string",
"example": "prod_5h0wc453_1",
"description": "A unique identifier that represents the product and is assigned by Voucherify."
},
"source_id": {
"type": "string",
"description": "A unique product identifier from your inventory system.",
"example": "illy-arabica"
},
"name": {
"type": "string",
"example": "Brewing System",
"description": "Product name."
},
"price": {
"type": "integer",
"description": "Unit price of a product. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `$100.00`."
}
}
},
"sku": {
"type": "object",
"description": "This object stores more information about the related SKU.",
"properties": {
"id": {
"type": "string",
"example": "sku_prod_5h0wc453_1_1",
"description": "A unique identifier that represents the SKU and is assigned by Voucherify."
},
"source_id": {
"type": "string",
"example": "illy-arabica-250g",
"description": "A unique SKU identifier from your inventory system."
},
"sku": {
"type": "string",
"description": "SKU name."
},
"price": {
"type": "integer",
"description": "Unit price of a SKU. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `$100.00`."
}
}
}
}
}
},
"metadata": {
"type": "object",
"description": "The metadata object stores all custom attributes assigned to the order. A set of key/value pairs that are att to an order object. Stores additional information about the order in a structured format."
},
"customer": {
"type": "object",
"description": "Object containing information about the customer that is making the purchase.",
"properties": {
"id": {
"type": "string",
"example": "cust_7iUa6ICKyU6gH40dBU25kQU1",
"description": "Unique customer identifier of the customer making the purchase. The ID is assigned by Voucherify."
},
"object": {
"type": "string",
"default": "customer",
"description": "Type of object represented by the `customer` object."
}
}
},
"referrer": {
"type": "object",
"description": "Object containing information about the referrer.",
"properties": {
"id": {
"type": "string",
"example": "cust_7iUa6ICKyU6gH40dBU25kQU1",
"description": "Unique referrer ID, who referred the customer making the purchase."
},
"object": {
"type": "string",
"default": "customer",
"description": "Type of object represented by the `referrer` object."
}
}
},
"customer_id": {
"type": "string",
"description": "Unique customer identifier of the customer making the purchase. The ID is assigned by Voucherify.",
"example": "cust_7iUa6ICKyU6gH40dBU25kQU1"
},
"referrer_id": {
"type": "string",
"example": "cust_nM4jqPiaXUvQdVSA6vTRUnix",
"description": "Unique referrer ID."
},
"object": {
"type": "string",
"default": "order",
"description": "The type of the object represented by JSON. This object stores information about the `order`."
}
}
},
"6_res_validate_voucher_discount_unit_product": {
"title": "Unit Discount, Product",
"type": "object",
"description": "This is an object representing the discount that the customer would receive in the context of the provided request body parameters. If the discount is calculated based on a formula, this object will return either the discount calculated based on the formula or the fallback value.",
"properties": {
"type": {
"type": "string",
"default": "UNIT",
"description": "Discount type."
},
"effect": {
"type": "string",
"enum": [
"ADD_MISSING_ITEMS",
"ADD_NEW_ITEMS"
],
"description": "Defines how the unit is added to the customer's order."
},
"unit_off": {
"type": "integer",
"description": "Number of units to be granted a full value discount."
},
"unit_type": {
"type": "string",
"example": "prod_0a9f9ab4ab019a42d5",
"description": "The product deemed as free, chosen from product inventory (e.g. time, items)."
},
"product": {
"type": "object",
"description": "Contains information about the product.",
"properties": {
"id": {
"type": "string",
"description": "Unique product ID, assigned by Voucherify."
},
"source_id": {
"type": "string",
"description": "Product's source ID."
},
"name": {
"type": "string",
"description": "Product name."
}
}
}
}
},
"6_res_validate_voucher_discount_unit_sku": {
"title": "Unit Discount, SKU",
"type": "object",
"description": "This is an object representing the discount that the customer would receive in the context of the provided request body parameters. If the discount is calculated based on a formula, this object will return either the discount calculated based on the formula or the fallback value.",
"properties": {
"type": {
"type": "string",
"default": "UNIT",
"description": "Discount type."
},
"effect": {
"type": "string",
"enum": [
"ADD_MISSING_ITEMS",
"ADD_NEW_ITEMS"
],
"description": "Defines how the unit is added to the customer's order."
},
"unit_off": {
"type": "integer",
"description": "Number of units to be granted a full value discount."
},
"unit_type": {
"type": "string",
"example": "sku_0bae3b28f610fd0da1",
"description": "The product variant deemed as free, chosen from product inventory (e.g. time, items)."
},
"sku": {
"type": "object",
"description": "Contains information about the SKU.",
"properties": {
"id": {
"type": "string",
"example": "sku_0bae3b28f610fd0da1",
"description": "Unique SKU ID, assigned by Voucherify."
},
"source_id": {
"type": "string",
"description": "Product variant's source ID."
},
"sku": {
"type": "string",
"description": "Product varient's name."
}
}
},
"product": {
"type": "object",
"description": "Contains information about the parent product.",
"properties": {
"id": {
"type": "string",
"description": "Unique parent product ID, assigned by Voucherify.",
"example": "prod_0bae2dc5a090fd0184"
},
"source_id": {
"type": "string",
"description": "Source ID of parent product."
},
"name": {
"type": "string",
"description": "Name of parent product."
}
}
}
}
},
"6_res_validate_voucher_discount_unit_product_multiple": {
"title": "Product Item",
"type": "object",
"description": "This is an object representing the discount that the customer would receive in the context of the provided request body parameters. If the discount is calculated based on a formula, this object will return either the discount calculated based on the formula or the fallback value.",
"properties": {
"effect": {
"type": "string",
"enum": [
"ADD_MISSING_ITEMS",
"ADD_NEW_ITEMS"
],
"description": "Defines how the unit is added to the customer's order."
},
"unit_off": {
"type": "integer",
"description": "Number of units to be granted a full value discount."
},
"unit_type": {
"type": "string",
"example": "prod_0a9f9ab4ab019a42d5",
"description": "The product deemed as free, chosen from product inventory (e.g. time, items)."
},
"product": {
"type": "object",
"description": "Contains information about the product.",
"properties": {
"id": {
"type": "string",
"description": "Unique product ID, assigned by Voucherify.",
"example": "prod_0a9f9ab4ab019a42d5"
},
"source_id": {
"type": "string",
"description": "Product's source ID."
},
"name": {
"type": "string",
"description": "Product name."
}
}
}
}
},
"6_res_validate_voucher_discount_unit_sku_multiple": {
"title": "SKU Item",
"type": "object",
"description": "This is an object representing the discount that the customer would receive in the context of the provided request body parameters. If the discount is calculated based on a formula, this object will return either the discount calculated based on the formula or the fallback value.",
"properties": {
"effect": {
"type": "string",
"enum": [
"ADD_MISSING_ITEMS",
"ADD_NEW_ITEMS"
],
"description": "Defines how the unit is added to the customer's order."
},
"unit_off": {
"type": "integer",
"description": "Number of units to be granted a full value discount."
},
"unit_type": {
"type": "string",
"example": "sku_0bae3b28f610fd0da1",
"description": "The product variant deemed as free, chosen from product inventory (e.g. time, items)."
},
"sku": {
"type": "object",
"description": "Contains information about the SKU.",
"properties": {
"id": {
"type": "string",
"example": "sku_0bae3b28f610fd0da1",
"description": "Unique SKU ID, assigned by Voucherify."
},
"source_id": {
"type": "string",
"description": "Product variant's source ID."
},
"sku": {
"type": "string",
"description": "Product varient's name."
}
}
},
"product": {
"type": "object",
"description": "Contains information about the parent product.",
"properties": {
"id": {
"type": "string",
"description": "Unique parent product ID, assigned by Voucherify.",
"example": "prod_0b7d7dfb05cbe5c616"
},
"source_id": {
"type": "string",
"description": "Source ID of parent product."
},
"name": {
"type": "string",
"description": "Name of parent product."
}
}
}
}
},
"Referrer": {
"title": "Referrer",
"allOf": [
{
"$ref": "#/components/schemas/Customer"
}
]
},
"7_obj_order_object": {
"title": "Order object",
"description": "This is an object representing an order with calculated discounts applied using the voucher code.",
"oneOf": [
{
"$ref": "#/components/schemas/7_obj_order_object_apply_to_order"
},
{
"$ref": "#/components/schemas/7_obj_order_object_apply_to_items"
}
]
},
"7_obj_redemption_object_loyalty_card_pay_with_points": {
"type": "object",
"description": "Defines the pay with points reward redeemed for the particular loyalty card.",
"properties": {
"customer": {
"type": "object",
"description": "Defines the customer redeeming the reward.",
"properties": {
"id": {
"type": "string",
"description": "The unique ID of a customer that is assigned by Voucherify.",
"example": "cust_eWgXlBBiY6THFRJwX45Iakv4"
},
"name": {
"type": "string",
"description": "Customer's first and last name."
},
"email": {
"type": "string",
"description": "Customer's email address."
},
"source_id": {
"type": "string",
"description": "The merchant's customer ID if it is different from the Voucherify customer ID. It is really useful in case of an integration between multiple systems. It can be a customer ID from a CRM system, database or 3rd-party service."
},
"metadata": {
"type": "object",
"description": "The metadata object stores all custom attributes assigned to the customer. A set of key/value pairs that you can attach to a customer object. It can be useful for storing additional information about the customer in a structured format."
},
"object": {
"type": "string",
"description": "Type of object represented is `customer`.",
"default": "customer"
}
}
},
"assignment_id": {
"type": "string",
"example": "rewa_YAIuU7AY6LNJVlUbRxSbNgiD",
"description": "Unique reward assginment ID assigned by Voucherify."
},
"id": {
"type": "string",
"example": "rew_INt3fGH3n7xIr3ZQcq4kkUZ1",
"description": "Unique reward ID assigned by Voucherify."
},
"object": {
"type": "string",
"default": "reward",
"description": "Type of object represented is `reward`."
},
"name": {
"type": "string",
"description": "Reward name."
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2022-10-03T12:24:58.008Z",
"description": "Timestamp in ISO 8601 format indicating when the reward was created."
},
"updated_at": {
"type": "string",
"format": "date-time",
"example": "2022-10-03T12:24:58.008Z",
"description": "Timestamp in ISO 8601 format indicating when the reward was updated."
},
"parameters": {
"type": "object",
"description": "These are parameters representing a Pay with Points (COIN) reward.",
"properties": {
"coin": {
"type": "object",
"description": "Defines the ratio by mapping the number of loyalty points in `points_ratio` to a predefined cash amount in `exchange_ratio`.",
"properties": {
"exchange_ratio": {
"type": "integer",
"description": "The cash equivalent of the points defined in the `points_ratio` property."
},
"points_ratio": {
"type": "integer",
"description": "The number of loyalty points that will map to the predefined cash amount defined by the `exchange_ratio` property."
}
}
}
}
},
"type": {
"type": "string",
"description": "Reward type",
"default": "COIN",
"enum": [
"COIN"
]
}
},
"title": "Pay with Points Reward"
},
"7_obj_redemption_object_loyalty_card_material_product": {
"type": "object",
"description": "Defines the product material reward redeemed for the particular loyalty card.",
"properties": {
"customer": {
"type": "object",
"description": "Defines the customer redeeming the reward.",
"properties": {
"id": {
"type": "string",
"description": "The unique ID of a customer that is assigned by Voucherify.",
"example": "cust_eWgXlBBiY6THFRJwX45Iakv4"
},
"name": {
"type": "string",
"description": "Customer's first and last name."
},
"email": {
"type": "string",
"description": "Customer's email address."
},
"source_id": {
"type": "string",
"description": "The merchant's customer ID if it is different from the Voucherify customer ID. It is really useful in case of an integration between multiple systems. It can be a customer ID from a CRM system, database or 3rd-party service."
},
"metadata": {
"type": "object",
"description": "The metadata object stores all custom attributes assigned to the customer. A set of key/value pairs that you can attach to a customer object. It can be useful for storing additional information about the customer in a structured format."
},
"object": {
"type": "string",
"description": "Type of object represented is `customer`.",
"default": "customer"
}
}
},
"assignment_id": {
"type": "string",
"example": "rewa_YAIuU7AY6LNJVlUbRxSbNgiD",
"description": "Unique reward assginment ID assigned by Voucherify."
},
"product": {
"description": "Details of the product redeemed as a reward.",
"allOf": [
{
"$ref": "#/components/schemas/Product"
}
]
},
"id": {
"type": "string",
"example": "rew_INt3fGH3n7xIr3ZQcq4kkUZ1",
"description": "Unique reward ID assigned by Voucherify."
},
"object": {
"type": "string",
"default": "reward",
"description": "Type of object represented is `reward`."
},
"name": {
"type": "string",
"description": "Reward name."
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2022-10-03T12:24:58.008Z",
"description": "Timestamp in ISO 8601 format indicating when the reward was created."
},
"updated_at": {
"type": "string",
"format": "date-time",
"example": "2022-10-03T12:24:58.008Z",
"description": "Timestamp in ISO 8601 format indicating when the reward was updated."
},
"parameters": {
"type": "object",
"description": "These are parameters representing a material reward.",
"properties": {
"product": {
"type": "object",
"description": "Defines the product redeemed as a reward.",
"properties": {
"id": {
"type": "string",
"description": "Unique product ID assignedy by Voucherify of the product.",
"example": "prod_0b2c2ddf35150b83bb"
},
"sku_id": {
"type": "string",
"nullable": true
}
}
}
}
},
"type": {
"type": "string",
"description": "Reward type",
"default": "MATERIAL",
"enum": [
"MATERIAL"
]
}
},
"title": "Product Material Reward"
},
"7_obj_redemption_object_loyalty_card_material_sku": {
"type": "object",
"description": "Defines the SKU material reward redeemed for the particular loyalty card.",
"properties": {
"customer": {
"type": "object",
"description": "Defines the customer redeeming the reward.",
"properties": {
"id": {
"type": "string",
"description": "The unique ID of a customer that is assigned by Voucherify.",
"example": "cust_eWgXlBBiY6THFRJwX45Iakv4"
},
"name": {
"type": "string",
"description": "Customer's first and last name."
},
"email": {
"type": "string",
"description": "Customer's email address."
},
"source_id": {
"type": "string",
"description": "The merchant's customer ID if it is different from the Voucherify customer ID. It is really useful in case of an integration between multiple systems. It can be a customer ID from a CRM system, database or 3rd-party service."
},
"metadata": {
"type": "object",
"description": "The metadata object stores all custom attributes assigned to the customer. A set of key/value pairs that you can attach to a customer object. It can be useful for storing additional information about the customer in a structured format."
},
"object": {
"type": "string",
"description": "Type of object represented is `customer`.",
"default": "customer"
}
}
},
"assignment_id": {
"type": "string",
"example": "rewa_YAIuU7AY6LNJVlUbRxSbNgiD",
"description": "Unique reward assginment ID assigned by Voucherify."
},
"product": {
"description": "Details of the SKU's parent product redeemed as a reward.",
"allOf": [
{
"$ref": "#/components/schemas/Product"
}
]
},
"sku": {
"description": "Details of the SKU redeemed as a reward.",
"allOf": [
{
"$ref": "#/components/schemas/Sku"
}
]
},
"id": {
"type": "string",
"example": "rew_INt3fGH3n7xIr3ZQcq4kkUZ1",
"description": "Unique reward ID assigned by Voucherify."
},
"object": {
"type": "string",
"default": "reward",
"description": "Type of object represented is `reward`."
},
"name": {
"type": "string",
"description": "Reward name."
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2022-10-03T12:24:58.008Z",
"description": "Timestamp in ISO 8601 format indicating when the reward was created."
},
"updated_at": {
"type": "string",
"format": "date-time",
"example": "2022-10-03T12:24:58.008Z",
"description": "Timestamp in ISO 8601 format indicating when the reward was updated."
},
"parameters": {
"type": "object",
"description": "These are parameters representing a material reward.",
"properties": {
"product": {
"type": "object",
"description": "Defines the SKU redeemed as a reward.",
"properties": {
"id": {
"type": "string",
"description": "Unique product ID assignedy by Voucherify of the SKU's parent."
},
"sku_id": {
"type": "string",
"description": "Unique SKU ID assigned by Voucherify of the SKU redeemed as a reward."
}
}
}
}
},
"type": {
"type": "string",
"description": "Reward type",
"default": "MATERIAL",
"enum": [
"MATERIAL"
]
}
},
"title": "SKU Material Reward"
},
"7_obj_redemption_object_loyalty_card_digital": {
"type": "object",
"description": "Defines the digital reward redeemed for the particular loyalty card.",
"properties": {
"customer": {
"type": "object",
"description": "Defines the customer redeeming the reward.",
"properties": {
"id": {
"type": "string",
"description": "The unique ID of a customer that is assigned by Voucherify.",
"example": "cust_eWgXlBBiY6THFRJwX45Iakv4"
},
"name": {
"type": "string",
"description": "Customer's first and last name."
},
"email": {
"type": "string",
"description": "Customer's email address."
},
"source_id": {
"type": "string",
"description": "The merchant's customer ID if it is different from the Voucherify customer ID. It is really useful in case of an integration between multiple systems. It can be a customer ID from a CRM system, database or 3rd-party service."
},
"metadata": {
"type": "object",
"description": "The metadata object stores all custom attributes assigned to the customer. A set of key/value pairs that you can attach to a customer object. It can be useful for storing additional information about the customer in a structured format."
},
"object": {
"type": "string",
"description": "Type of object represented is `customer`.",
"default": "customer"
}
}
},
"assignment_id": {
"type": "string",
"example": "rewa_YAIuU7AY6LNJVlUbRxSbNgiD",
"description": "Unique reward assginment ID assigned by Voucherify."
},
"voucher": {
"description": "Voucher object.",
"allOf": [
{
"$ref": "#/components/schemas/Voucher"
}
]
},
"id": {
"type": "string",
"example": "rew_INt3fGH3n7xIr3ZQcq4kkUZ1",
"description": "Unique reward ID assigned by Voucherify."
},
"object": {
"type": "string",
"default": "reward",
"description": "Type of object represented is `reward`."
},
"name": {
"type": "string",
"description": "Reward name."
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2022-10-03T12:24:58.008Z",
"description": "Timestamp in ISO 8601 format indicating when the reward was created."
},
"updated_at": {
"type": "string",
"format": "date-time",
"example": "2022-10-03T12:24:58.008Z",
"description": "Timestamp in ISO 8601 format indicating when the reward was updated."
},
"parameters": {
"type": "object",
"description": "These are parameters representing a digital reward. These can be in the form of discount coupons, gift card credits, or loyalty point credits.",
"properties": {
"campaign": {
"description": "Defines the source of the digital reward.",
"oneOf": [
{
"$ref": "#/components/schemas/7_obj_redemption_object_loyalty_card_digital_discount_voucher"
},
{
"$ref": "#/components/schemas/7_obj_redemption_object_loyalty_card_digital_gift_card_credits"
},
{
"$ref": "#/components/schemas/7_obj_redemption_object_loyalty_card_digital_loyalty_card_points"
}
]
}
}
},
"type": {
"type": "string",
"description": "Reward type",
"default": "CAMPAIGN",
"enum": [
"CAMPAIGN"
]
}
},
"title": "Digital Reward"
},
"CustomerWithSummaryLoyaltyReferrals": {
"title": "Customer With Summary Loyalty Referrals",
"allOf": [
{
"type": "object",
"title": "Customer Response Data",
"properties": {
"id": {
"type": "string",
"description": "The ID of an existing customer that will be linked to redemption in this request."
},
"source_id": {
"type": "string",
"description": "A unique identifier of the customer who validates a voucher. It can be a customer ID or email from a CRM system, database, or a third-party service. If you also pass a customer ID (unique ID assigned by Voucherify), the source ID will be ignored."
},
"summary": {
"nullable": true,
"allOf": [
{
"$ref": "#/components/schemas/CustomerSummary"
}
]
},
"loyalty": {
"nullable": true,
"allOf": [
{
"$ref": "#/components/schemas/CustomerLoyalty"
}
]
},
"referrals": {
"nullable": true,
"allOf": [
{
"$ref": "#/components/schemas/CustomerReferrals"
}
]
},
"system_metadata": {
"type": "object",
"description": "Object used to store system metadata information."
},
"created_at": {
"type": "string",
"description": "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",
"format": "date-time"
},
"updated_at": {
"type": "string",
"description": "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",
"format": "date-time"
},
"assets": {
"type": "object",
"description": "Contains information about the customer's cockpit.\n\n⚠️ Warning: Customer cockpits were removed. The customer cockpit URLs redirect to customer preference center.",
"properties": {
"cockpit_url": {
"type": "string",
"description": "URL address to customer preference center. Previously, a customer's cockpit URL address."
},
"cockpit_preference_center_url": {
"type": "string",
"description": "URL address to customer preference center."
}
}
},
"object": {
"type": "string",
"description": "The type of the object represented by JSON.",
"default": "customer",
"enum": [
"customer"
]
}
},
"required": [
"summary",
"loyalty",
"referrals",
"object"
]
},
{
"$ref": "#/components/schemas/CustomerBase"
}
]
},
"Any": {
"title": "Any",
"type": "array",
"items": {
"oneOf": [
{
"title": "string",
"type": "string"
},
{
"title": "string - date",
"type": "string",
"format": "date"
},
{
"title": "string - date-time",
"type": "string",
"format": "date-time"
},
{
"title": "number",
"type": "number"
},
{
"title": "object",
"type": "object"
}
]
}
},
"RedeemableResult": {
"title": "Redeemable Result",
"description": "Information about redeemable result.",
"properties": {
"discount": {
"$ref": "#/components/schemas/Discount"
},
"bundle": {
"$ref": "#/components/schemas/Bundle"
},
"gift": {
"$ref": "#/components/schemas/RedeemableGift"
},
"loyalty_card": {
"description": "Loyalty Card object response",
"allOf": [
{
"$ref": "#/components/schemas/RedeemableLoyaltyCard"
}
]
},
"error": {
"description": "Error in result",
"allOf": [
{
"$ref": "#/components/schemas/Error"
}
]
}
}
},
"DiscountAmount": {
"type": "object",
"title": "Amount",
"properties": {
"type": {
"type": "string",
"default": "AMOUNT",
"enum": [
"AMOUNT"
],
"description": "Defines the type of the voucher."
},
"amount_off": {
"type": "number",
"description": "Amount taken off the subtotal of a price. Value is multiplied by 100 to precisely represent 2 decimal places. For example, a $10 discount is written as 1000."
},
"amount_off_formula": {
"type": "string",
"description": "Formula used to dynamically calculate the discount."
},
"aggregated_amount_limit": {
"type": "integer",
"description": "Maximum discount amount per order."
},
"effect": {
"description": "Defines how the discount is applied to the customer's order.",
"allOf": [
{
"$ref": "#/components/schemas/DiscountAmountVouchersEffectTypes"
}
]
},
"is_dynamic": {
"type": "boolean",
"description": "Flag indicating whether the discount was calculated using a formula."
}
},
"required": [
"type",
"amount_off"
]
},
"DiscountUnit": {
"type": "object",
"title": "Unit",
"properties": {
"type": {
"type": "string",
"default": "UNIT",
"enum": [
"UNIT"
],
"description": "Discount type."
},
"unit_off": {
"type": "integer",
"description": "Number of units to be granted a full value discount."
},
"unit_off_formula": {
"type": "string",
"description": "Formula used to dynamically calculate the number of units."
},
"effect": {
"description": "Defines how the unit is added to the customer's order.",
"allOf": [
{
"$ref": "#/components/schemas/DiscountUnitVouchersEffectTypes"
}
]
},
"unit_type": {
"type": "string",
"description": "The product deemed as free, chosen from product inventory (e.g. time, items)."
},
"product": {
"description": "Contains information about the product.",
"allOf": [
{
"$ref": "#/components/schemas/SimpleProductDiscountUnit"
}
]
},
"sku": {
"$ref": "#/components/schemas/SimpleSkuDiscountUnit"
},
"is_dynamic": {
"type": "boolean",
"description": "Flag indicating whether the discount was calculated using a formula."
}
},
"required": [
"type",
"unit_type"
]
},
"DiscountUnitMultiple": {
"type": "object",
"title": "Unit Multiple",
"properties": {
"type": {
"type": "string",
"default": "UNIT",
"enum": [
"UNIT"
],
"description": "Discount type."
},
"effect": {
"type": "string",
"default": "ADD_MANY_ITEMS",
"enum": [
"ADD_MANY_ITEMS"
],
"description": "Defines how the discount is applied to the customer's order."
},
"units": {
"type": "array",
"items": {
"$ref": "#/components/schemas/DiscountUnitMultipleOneUnit"
}
}
},
"required": [
"type",
"units"
]
},
"DiscountPercent": {
"type": "object",
"title": "Percent",
"properties": {
"type": {
"type": "string",
"default": "PERCENT",
"enum": [
"PERCENT"
],
"description": "Defines the type of the voucher."
},
"percent_off": {
"type": "number",
"description": "The percent discount that the customer will receive."
},
"percent_off_formula": {
"type": "string",
"description": "Formula used to dynamically calculate the discount."
},
"amount_limit": {
"type": "number",
"description": "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": {
"type": "integer",
"description": "Maximum discount amount per order."
},
"effect": {
"description": "Defines how the discount is applied to the customer's order.",
"allOf": [
{
"$ref": "#/components/schemas/DiscountPercentVouchersEffectTypes"
}
]
},
"is_dynamic": {
"type": "boolean",
"description": "Flag indicating whether the discount was calculated using a formula."
}
},
"required": [
"type",
"percent_off"
]
},
"DiscountFixed": {
"title": "Fixed",
"type": "object",
"properties": {
"type": {
"type": "string",
"default": "FIXED",
"enum": [
"FIXED"
],
"description": "Defines the type of the voucher."
},
"fixed_amount": {
"type": "number",
"description": "Sets a fixed value for an order total or the item price. The value is multiplied by 100 to precisely represent 2 decimal places. For example, a $10 discount is written as 1000. If the fixed amount is calculated by the formula, i.e. the `fixed_amount_formula` parameter is present in the fixed amount definition, this value becomes the **fallback value**. As a result, if the formula cannot be calculated due to missing metadata, for example, this value will be used as the fixed value."
},
"fixed_amount_formula": {
"type": "string",
"description": "Formula used to dynamically calculate the discount."
},
"effect": {
"description": "Defines how the discount is applied to the customer's order.",
"allOf": [
{
"$ref": "#/components/schemas/DiscountFixedVouchersEffectTypes"
}
]
},
"is_dynamic": {
"type": "boolean",
"description": "Flag indicating whether the discount was calculated using a formula."
}
},
"required": [
"type",
"fixed_amount"
]
},
"ValidationRuleAssignment": {
"title": "Validation Rule Assignment",
"type": "object",
"description": "This is an object representing a validation rule assignment.",
"properties": {
"id": {
"type": "string",
"example": "asgm_74F7QZoYbUoljwQO",
"description": "Validation rule assignment ID."
},
"rule_id": {
"type": "string",
"example": "val_4j7DCRm2IS59",
"description": "Validation rule ID."
},
"related_object_id": {
"type": "string",
"example": "v_JtWunK6jUo7X2qOFj0SyRHq4p9tgENlT",
"description": "The resource ID to which the validation rule was assigned."
},
"related_object_type": {
"type": "string",
"description": "The type of resource to which the validation rule was assigned.",
"enum": [
"voucher",
"campaign",
"earning_rule",
"reward_assignment",
"promotion_tier",
"distribution"
]
},
"created_at": {
"type": "string",
"example": "2022-02-17T08:18:15.085Z",
"description": "Timestamp representing the date and time when the validation rule assignment was created. The value is shown in the ISO 8601 format.",
"format": "date-time"
},
"object": {
"type": "string",
"default": "validation_rules_assignment",
"description": "The type of the object represented by the ID.",
"enum": [
"validation_rules_assignment"
]
}
},
"required": [
"id",
"rule_id",
"related_object_id",
"related_object_type",
"created_at",
"object"
]
},
"Product": {
"type": "object",
"description": "This is an object representing a product. \n\nThis 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.",
"title": "Product",
"allOf": [
{
"$ref": "#/components/schemas/ProductWithoutSkus"
},
{
"type": "object",
"properties": {
"skus": {
"$ref": "#/components/schemas/SkusListForProduct"
}
}
}
]
},
"Sku": {
"title": "SKU Object",
"type": "object",
"description": "This is an object representing a product SKU.",
"properties": {
"id": {
"type": "string",
"example": "sku_0b1621b319d248b79f",
"description": "A unique identifier that represents the SKU and is assigned by Voucherify."
},
"source_id": {
"type": "string",
"nullable": true,
"example": "sku_source_id_4",
"description": "A unique SKU identifier from your inventory system."
},
"product_id": {
"type": "string",
"example": "prod_0b15f6b9f650c16990",
"description": "The parent product's unique ID."
},
"sku": {
"type": "string",
"nullable": true,
"example": "Large Pink Shirt",
"description": "Unique user-defined SKU name."
},
"price": {
"type": "integer",
"nullable": true,
"description": "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": {
"type": "string",
"nullable": true,
"description": "SKU price currency.",
"example": "USD"
},
"attributes": {
"type": "object",
"description": "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": {
"type": "string",
"nullable": true,
"description": "The HTTPS URL pointing to the .png or .jpg file that will be used to render the SKU image."
},
"metadata": {
"type": "object",
"description": "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": {
"type": "string",
"example": "2022-05-17T10:36:30.187Z",
"description": "Timestamp representing the date and time when the SKU was created. The value is shown in the ISO 8601 format.",
"format": "date-time"
},
"updated_at": {
"type": "string",
"nullable": true,
"example": "2022-05-17T10:55:09.137Z",
"description": "Timestamp representing the date and time when the SKU was updated. The value is shown in the ISO 8601 format.",
"format": "date-time"
},
"object": {
"type": "string",
"default": "sku",
"description": "The type of the object represented by JSON. This object stores information about the `SKU`.",
"enum": [
"sku"
]
}
},
"required": [
"id",
"source_id",
"product_id",
"sku",
"price",
"attributes",
"metadata",
"image_url",
"created_at",
"updated_at",
"object"
]
},
"VoucherAssets": {
"title": "Voucher Assets",
"type": "object",
"description": "Stores links to images of QR and barcode that correspond to an encrypted voucher code.",
"properties": {
"qr": {
"type": "object",
"description": "Stores Quick Response (QR) representation of encrypted code.",
"properties": {
"id": {
"type": "string",
"example": "U2FsdGVkX19ucFhvVmBVpVYG5KoswTsjSIaqoKg5L9ie4BK+t4pp7U7oFzjGJzj9q/bmuMOj9mEFiVKDMIkSaruKedMvHbKoPX5Sg+BaZk5QwXMf8k/OzSlOEVybpwSq+AiqPoNtjeuqtIgkDyvT6Q==",
"description": "Encrypted voucher code ID."
},
"url": {
"type": "string",
"example": "https://dev.dl.voucherify.io/api/v1/assets/qr/U2FsdGVkX19ucFhvVmBVpVYG5KoswTsjSIaqoKg5L9ie4BK%2Bt4pp7U7oFzjGJzj9q%2FbmuMOj9mEFiVKDMIkSaruKedMvHbKoPX5Sg%2BBaZk5QwXMf8k%2FOzSlOEVybpwSq%2BAiqPoNtjeuqtIgkDyvT6Q%3D%3D",
"description": "URL to QR code \n\n*Optional:* Attach query parameters to base URL to customize the image of the encrypted voucher code. \n\n- `size`: integer value from `1` to `100` \n- `format`: string, either `png` (default) or `svg`"
}
}
},
"barcode": {
"type": "object",
"description": "Stores barcode representation of encrypted code.",
"properties": {
"id": {
"type": "string",
"example": "U2FsdGVkX19eJhGfWwUrH9+tulBkON+AnMktic+N6CVWzZ9+fHVxuVx22WakrzxiWXy0skuvvEHSeZIw9HlgyIJ+kJ1iPdUKpyENuNYJKzoZlO0mmTf6WQM6/pFs61apEn9SJx32ttCF6d3oxKISQQ==",
"description": "Encrypted voucher code ID."
},
"url": {
"type": "string",
"example": "https://dev.dl.voucherify.io/api/v1/assets/barcode/U2FsdGVkX19eJhGfWwUrH9%2BtulBkON%2BAnMktic%2BN6CVWzZ9%2BfHVxuVx22WakrzxiWXy0skuvvEHSeZIw9HlgyIJ%2BkJ1iPdUKpyENuNYJKzoZlO0mmTf6WQM6%2FpFs61apEn9SJx32ttCF6d3oxKISQQ%3D%3D",
"description": "URL to barcode \n\n*Optional:* Attach query parameters to base URL to customize the image of the encrypted voucher code. \n\n- `size`: integer value from `1` to `100` \n- `format`: string, either `png` (default) or `svg`"
}
}
}
}
},
"BusValRuleAssignment": {
"title": "Business Validation Rule Assignment",
"description": "Assignments of business validation rule",
"example": {
"id": "asgm_LnY1g7UNFA9KyDrD",
"rule_id": "val_3gPNA6SnH4ae",
"related_object_id": "camp_CZOnEGiZfwIKWmSjhIoIT7Ol",
"related_object_type": "campaign",
"object": "validation_rules_assignment",
"validation_status": "PARTIALLY_VALID",
"validation_omitted_rules": [
"1"
]
},
"properties": {
"id": {
"type": "string",
"description": "The unique identifier for a assignment"
},
"rule_id": {
"type": "string",
"description": "The unique identifier for a rule"
},
"related_object_id": {
"type": "string",
"description": "The unique identifier for a related object"
},
"related_object_type": {
"type": "string",
"description": "The type of related object"
},
"created_at": {
"type": "string",
"description": "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",
"format": "date-time"
},
"updated_at": {
"type": "string",
"description": "Timestamp representing the date and time when the object was last updated in ISO 8601 format.",
"example": "2022-03-09T11:19:04.819Z",
"format": "date-time"
},
"object": {
"type": "string",
"description": "The type of the object represented by JSON.",
"default": "validation_rules_assignment",
"enum": [
"validation_rules_assignment"
]
},
"validation_status": {
"type": "string",
"description": "The validation status of the assignment",
"enum": [
"VALID",
"PARTIALLY_VALID",
"INVALID"
]
},
"validation_omitted_rules": {
"type": "array",
"description": "The list of omitted rules",
"items": {
"type": "string"
}
}
},
"required": [
"id",
"rule_id",
"related_object_id",
"related_object_type",
"object"
]
},
"ApplicableTo": {
"title": "Applicable To",
"type": "object",
"properties": {
"object": {
"type": "string",
"enum": [
"product",
"sku",
"products_collection"
],
"description": "This object stores information about the resource to which the discount is applicable."
},
"id": {
"type": "string",
"description": "Unique product collection, product, or SKU identifier assigned by Voucherify."
},
"source_id": {
"type": "string",
"description": "The source identifier from your inventory system."
},
"product_id": {
"type": "string",
"description": "Parent product's unique ID assigned by Voucherify."
},
"product_source_id": {
"type": "string",
"description": "Parent product's source ID from your inventory system."
},
"price": {
"type": "number",
"description": "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": {
"type": "number",
"description": "Formula used to dynamically calculate the discounted price of an item."
},
"effect": {
"description": "Defines how the discount is applied to the customer's order.",
"allOf": [
{
"$ref": "#/components/schemas/ApplicableToEffect"
}
]
},
"quantity_limit": {
"type": "integer",
"description": "The maximum number of units allowed to be discounted per order line item."
},
"aggregated_quantity_limit": {
"type": "integer",
"description": "The maximum number of units allowed to be discounted combined across all matched order line items."
},
"amount_limit": {
"type": "integer",
"description": "Upper limit allowed to be applied as a discount per order line item. Value is multiplied by 100 to precisely represent 2 decimal places. For example, a $6 maximum discount is written as 600."
},
"aggregated_amount_limit": {
"type": "integer",
"description": "Maximum discount amount per order. 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:\n- `APPLY_TO_ITEMS` (each item subtotal is discounted equally)\n- `APPLY_TO_ITEMS_BY_QUANTITY` (each unit of matched products has the same discount value)"
},
"product_campaign_quantity_limit": {
"type": "integer",
"description": "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.\n\nThis limit is available on demand as part of campaign budget limits. Contact [Voucherify support](https://www.voucherify.io/contact-support) or your account manager to learn more."
},
"product_campaign_quantity_limit_formula": {
"type": "string",
"description": "Formula used to dynamically calculate the maximum units per campaign.\n\nThis limit is available on demand as part of campaign budget limits. Contact [Voucherify support](https://www.voucherify.io/contact-support) or your account manager to learn more."
},
"product_customer_campaign_quantity_limit": {
"type": "integer",
"description": "Limits the number of discounted item units (product, SKU, collection) that one customer can receive in a given campaign.\n\nThis limit is available on demand as part of campaign budget limits. Contact [Voucherify support](https://www.voucherify.io/contact-support) or your account manager to learn more."
},
"product_customer_campaign_quantity_limit_formula": {
"type": "string",
"description": "Formula used to dynamically calculate the maximum units per customer in a campaign.\n\nThis limit is available on demand as part of campaign budget limits. Contact [Voucherify support](https://www.voucherify.io/contact-support) or your account manager to learn more."
},
"product_in_collection_campaign_quantity_limit": {
"type": "integer",
"description": "Limits the number of discounted item units of a given product in a collection that all customers can receive in a given campaign.\n\nThis limit is available on demand as part of campaign budget limits. Contact [Voucherify support](https://www.voucherify.io/contact-support) or your account manager to learn more."
},
"product_in_collection_campaign_quantity_limit_formula": {
"type": "string",
"description": "Formula used to dynamically calculate the maximum units per campaign for a product in a collection.\n\nThis limit is available on demand as part of campaign budget limits. Contact [Voucherify support](https://www.voucherify.io/contact-support) or your account manager to learn more."
},
"product_in_collection_customer_campaign_quantity_limit": {
"type": "integer",
"description": "Limits the number of discounted item units of a given product in a collection that one customer can receive in a campaign.\n\nThis limit is available on demand as part of campaign budget limits. Contact [Voucherify support](https://www.voucherify.io/contact-support) or your account manager to learn more."
},
"product_in_collection_customer_campaign_quantity_limit_formula": {
"type": "string",
"description": "Formula used to dynamically calculate the maximum units per customer for a product in a collection.\n\nThis limit is available on demand as part of campaign budget limits. Contact [Voucherify support](https://www.voucherify.io/contact-support) or your account manager to learn more."
},
"product_promotion_tier_quantity_limit": {
"type": "integer",
"description": "Limits the number of discounted item units that all customers can receive in a promotion tier.\n\nThis limit is available on demand as part of campaign budget limits. Contact [Voucherify support](https://www.voucherify.io/contact-support) or your account manager to learn more."
},
"product_promotion_tier_quantity_limit_formula": {
"type": "string",
"description": "Formula used to dynamically calculate the maximum units per promotion tier.\n\nThis limit is available on demand as part of campaign budget limits. Contact [Voucherify support](https://www.voucherify.io/contact-support) or your account manager to learn more."
},
"product_customer_promotion_tier_quantity_limit": {
"type": "integer",
"description": "Limits the number of discounted item units that one customer can receive in a given promotion tier.\n\nThis limit is available on demand as part of campaign budget limits. Contact [Voucherify support](https://www.voucherify.io/contact-support) or your account manager to learn more."
},
"product_customer_promotion_tier_quantity_limit_formula": {
"type": "string",
"description": "Formula used to dynamically calculate the maximum units per customer in a promotion tier.\n\nThis limit is available on demand as part of campaign budget limits. Contact [Voucherify support](https://www.voucherify.io/contact-support) or your account manager to learn more."
},
"product_in_collection_promotion_tier_quantity_limit": {
"type": "integer",
"description": "Limits the number of discounted item units of a given product in a collection that all customers can receive in a given promotion tier.\n\nThis limit is available on demand as part of campaign budget limits. Contact [Voucherify support](https://www.voucherify.io/contact-support) or your account manager to learn more."
},
"product_in_collection_promotion_tier_quantity_limit_formula": {
"type": "string",
"description": "Formula used to dynamically calculate the maximum units per promotion tier for a product in a collection.\n\nThis limit is available on demand as part of campaign budget limits. Contact [Voucherify support](https://www.voucherify.io/contact-support) or your account manager to learn more."
},
"product_in_collection_customer_promotion_tier_quantity_limit": {
"type": "integer",
"description": "Limits the number of discounted item units of a given product in a collection that one customer can receive in a promotion tier.\n\nThis limit is available on demand as part of campaign budget limits. Contact [Voucherify support](https://www.voucherify.io/contact-support) or your account manager to learn more."
},
"product_in_collection_customer_promotion_tier_quantity_limit_formula": {
"type": "string",
"description": "Formula used to dynamically calculate the maximum units per customer in a promotion tier for a product in a collection.\n\nThis limit is available on demand as part of campaign budget limits. Contact [Voucherify support](https://www.voucherify.io/contact-support) or your account manager to learn more."
},
"order_item_indices": {
"type": "array",
"description": "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.",
"items": {
"type": "integer"
}
},
"order_item_units": {
"type": "array",
"description": "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.",
"items": {
"type": "object",
"properties": {
"index": {
"type": "integer",
"description": "Number assigned to the order line item in accordance with the order sent in the request.",
"minimum": 0
},
"units": {
"type": "array",
"description": "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.",
"items": {
"type": "integer"
}
},
"units_limit_exceeded": {
"type": "boolean",
"description": "Returned as `true` only when the sum total of `quantity` of all order items exceeds 1000."
}
}
}
},
"repeat": {
"type": "integer",
"description": "Determines the recurrence of the discount, e.g. `\"repeat\": 3` means that the discount is applied to every third item."
},
"skip_initially": {
"type": "integer",
"description": "Determines how many items are skipped before the discount is applied."
},
"target": {
"type": "string",
"description": "Determines to which kinds of objects the discount is applicable. `ITEM` includes products and SKUs. `UNIT` means particular units within an order line.",
"enum": [
"ITEM",
"UNIT"
]
}
},
"required": [
"object",
"id",
"effect"
]
},
"InapplicableTo": {
"title": "Inapplicable To",
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/ApplicableTo"
}
]
},
"7_obj_order_object_apply_to_order": {
"type": "object",
"title": "Order object - Effect: Apply to order",
"description": "This is an object representing an order with calculated discounts applied using the voucher code.",
"properties": {
"id": {
"type": "string",
"example": "ord_OLWs41pBk7VFn6ZTyX9U6keh",
"description": "Unique order ID, assigned by Voucherify."
},
"source_id": {
"type": "string",
"description": "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."
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2022-10-06T11:40:48.705Z",
"description": "Timestamp representing the date and time when the order was created. The value is shown in the ISO 8601 format."
},
"updated_at": {
"type": "string",
"format": "date-time",
"example": "2022-10-06T11:47:20.760Z",
"description": "Timestamp representing the date and time when the order was updated. The value is shown in the ISO 8601 format."
},
"status": {
"type": "string",
"description": "Order status.",
"enum": [
"CREATED",
"PAID",
"CANCELED",
"FULFILLED"
]
},
"amount": {
"type": "integer",
"description": "Order amount before applying any discount."
},
"discount_amount": {
"type": "integer",
"description": "Sum of all order-level discounts applied to the order."
},
"total_discount_amount": {
"type": "integer",
"description": "Sum of all order-level AND all product-specific discounts applied to the order. \n`total_discount_amount` = `discount_amount` + `items_discount_amount`"
},
"total_amount": {
"type": "integer",
"description": "Order amount after applying all the discounts. \n`total_amount` = `amount` - `total_discount_amount`"
},
"applied_discount_amount": {
"type": "integer",
"description": "This field shows the order-level discount applied."
},
"total_applied_discount_amount": {
"type": "integer",
"description": "This field sums up all order-level and all product-specific discounts applied in a particular request."
},
"items": {
"type": "array",
"description": "Array of order items that have been applied to the order. Each order item can show the effects of particular discounts on the item-level.",
"items": {
"type": "object",
"properties": {
"object": {
"type": "string",
"default": "order_item",
"description": "The type of the object represented by JSON. This object stores information about the `order_item`."
},
"product_id": {
"type": "string",
"example": "prod_5h0wc453_1",
"description": "A unique identifier that represents the product and is assigned by Voucherify."
},
"sku_id": {
"type": "string",
"example": "sku_prod_5h0wc453_1_1",
"description": "A unique identifier that represents the SKU and is assigned by Voucherify."
},
"quantity": {
"type": "integer",
"description": "Quantity of the item in the cart."
},
"amount": {
"type": "integer",
"description": "Represents a total pre-discount amount of order item (`price` * `quantity`)."
},
"price": {
"type": "integer",
"description": "Unit price of an item. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `$100.00`."
},
"subtotal_amount": {
"type": "integer",
"description": "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`. \n`subtotal_amount`=`amount`-`discount_amount`"
},
"product": {
"type": "object",
"description": "This object stores more information about the related product.",
"properties": {
"id": {
"type": "string",
"example": "prod_5h0wc453_1",
"description": "A unique identifier that represents the product and is assigned by Voucherify."
},
"source_id": {
"type": "string",
"description": "A unique product identifier from your inventory system.",
"example": "illy-arabica"
},
"name": {
"type": "string",
"example": "Brewing System",
"description": "Product name."
},
"price": {
"type": "integer",
"description": "Unit price of a product. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `$100.00`."
}
}
},
"sku": {
"type": "object",
"description": "This object stores more information about the related SKU.",
"properties": {
"id": {
"type": "string",
"example": "sku_prod_5h0wc453_1_1",
"description": "A unique identifier that represents the SKU and is assigned by Voucherify."
},
"source_id": {
"type": "string",
"example": "illy-arabica-250g",
"description": "A unique SKU identifier from your inventory system."
},
"sku": {
"type": "string",
"description": "SKU name."
},
"price": {
"type": "integer",
"description": "Unit price of a SKU. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `$100.00`."
}
}
}
}
}
},
"metadata": {
"type": "object",
"description": "The metadata object stores all custom attributes assigned to the order. A set of key/value pairs that are att to an order object. Stores additional information about the order in a structured format."
},
"customer": {
"type": "object",
"description": "Object containing information about the customer that is making the purchase.",
"properties": {
"id": {
"type": "string",
"example": "cust_7iUa6ICKyU6gH40dBU25kQU1",
"description": "Unique customer identifier of the customer making the purchase. The ID is assigned by Voucherify."
},
"object": {
"type": "string",
"default": "customer",
"description": "Type of object represented by the `customer` object."
}
}
},
"referrer": {
"type": "object",
"description": "Object containing information about the referrer.",
"properties": {
"id": {
"type": "string",
"example": "cust_7iUa6ICKyU6gH40dBU25kQU1",
"description": "Unique referrer ID, who referred the customer making the purchase."
},
"object": {
"type": "string",
"default": "customer",
"description": "Type of object represented by the `referrer` object."
}
}
},
"customer_id": {
"type": "string",
"description": "Unique customer identifier of the customer making the purchase. The ID is assigned by Voucherify.",
"example": "cust_7iUa6ICKyU6gH40dBU25kQU1"
},
"referrer_id": {
"type": "string",
"example": "cust_nM4jqPiaXUvQdVSA6vTRUnix",
"description": "Unique referrer ID."
},
"object": {
"type": "string",
"default": "order",
"description": "The type of the object represented by JSON. This object stores information about the `order`."
},
"redemptions": {
"description": "Lists details related to the redemption.",
"allOf": [
{
"$ref": "#/components/schemas/10_obj_order_object_unstacked_redemptions"
}
]
}
}
},
"7_obj_order_object_apply_to_items": {
"type": "object",
"title": "Order object - Effect: Apply to items",
"description": "This is an object representing an order with calculated discounts applied using the voucher code.",
"properties": {
"id": {
"type": "string",
"example": "ord_OLWs41pBk7VFn6ZTyX9U6keh",
"description": "Unique order ID, assigned by Voucherify. "
},
"source_id": {
"type": "string",
"description": "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."
},
"created_at": {
"type": "string",
"format": "date-time",
"example": "2022-10-06T11:40:48.705Z",
"description": "Timestamp representing the date and time when the order was created. The value is shown in the ISO 8601 format."
},
"updated_at": {
"type": "string",
"format": "date-time",
"example": "2022-10-06T11:47:20.760Z",
"description": "Timestamp representing the date and time when the order was updated. The value is shown in the ISO 8601 format."
},
"status": {
"type": "string",
"description": "Order status.",
"enum": [
"CREATED",
"PAID",
"CANCELED",
"FULFILLED"
]
},
"amount": {
"type": "integer",
"description": "Order amount before applying any discount."
},
"items_discount_amount": {
"type": "integer",
"description": "Sum of all product-specific discounts applied to the order. \n`sum(items, i => i.discount_amount)`"
},
"total_discount_amount": {
"type": "integer",
"description": "Sum of all order-level AND all product-specific discounts applied to the order."
},
"total_amount": {
"type": "integer",
"description": "Order amount after applying all the discounts. \n`total_amount` = `amount` - `total_discount_amount`"
},
"items_applied_discount_amount": {
"type": "integer",
"description": "Sum of all product-specific discounts applied."
},
"total_applied_discount_amount": {
"type": "integer",
"description": "Sum of all order-level AND all product-specific discounts applied to the order."
},
"items": {
"type": "array",
"description": "Array of order items that have been applied to the order. Each order item can show the effects of particular discounts on the item-level.",
"items": {
"type": "object",
"properties": {
"object": {
"type": "string",
"default": "order_item",
"description": "The type of the object represented by JSON. This object stores information about the `order_item`."
},
"product_id": {
"type": "string",
"example": "prod_5h0wc453_1",
"description": "A unique identifier that represents the product and is assigned by Voucherify."
},
"sku_id": {
"type": "string",
"example": "sku_prod_5h0wc453_1_1",
"description": "A unique identifier that represents the SKU and is assigned by Voucherify."
},
"quantity": {
"type": "integer",
"description": "Quantity of the item in the cart."
},
"amount": {
"type": "integer",
"description": "Represents a total pre-discount amount of order item (`price` * `quantity`)."
},
"discount_amount": {
"type": "integer",
"description": "The item-level discount applied to the item."
},
"applied_discount_amount": {
"type": "integer",
"description": "The item-level discount applied to the item."
},
"price": {
"type": "integer",
"description": "Unit price of an item. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `$100.00`."
},
"subtotal_amount": {
"type": "integer",
"description": "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`. \n`subtotal_amount`=`amount`-`discount_amount`"
},
"product": {
"type": "object",
"description": "This object stores more information about the related product.",
"properties": {
"id": {
"type": "string",
"example": "prod_5h0wc453_1",
"description": "A unique identifier that represents the product and is assigned by Voucherify."
},
"source_id": {
"type": "string",
"description": "A unique product identifier from your inventory system.",
"example": "illy-arabica"
},
"name": {
"type": "string",
"example": "Brewing System",
"description": "Product name."
},
"price": {
"type": "integer",
"description": "Unit price of a product. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `$100.00`."
}
}
},
"sku": {
"type": "object",
"description": "This object stores more information about the related SKU.",
"properties": {
"id": {
"type": "string",
"example": "sku_prod_5h0wc453_1_1",
"description": "A unique identifier that represents the SKU and is assigned by Voucherify."
},
"source_id": {
"type": "string",
"example": "illy-arabica-250g",
"description": "A unique SKU identifier from your inventory system."
},
"sku": {
"type": "string",
"description": "SKU name."
},
"price": {
"type": "integer",
"description": "Unit price of a SKU. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `$100.00`."
}
}
}
}
}
},
"metadata": {
"type": "object",
"description": "The metadata object stores all custom attributes assigned to the order. A set of key/value pairs that are att to an order object. Stores additional information about the order in a structured format."
},
"customer": {
"type": "object",
"description": "Object containing information about the customer that is making the purchase.",
"properties": {
"id": {
"type": "string",
"example": "cust_7iUa6ICKyU6gH40dBU25kQU1",
"description": "Unique customer identifier of the customer making the purchase. The ID is assigned by Voucherify."
},
"object": {
"type": "string",
"default": "customer",
"description": "Type of object represented by the `customer` object."
}
}
},
"referrer": {
"type": "object",
"description": "Object containing information about the referrer.",
"properties": {
"id": {
"type": "string",
"example": "cust_7iUa6ICKyU6gH40dBU25kQU1",
"description": "Unique referrer ID, who referred the customer making the purchase."
},
"object": {
"type": "string",
"default": "customer",
"description": "Type of object represented by the `referrer` object."
}
}
},
"customer_id": {
"type": "string",
"description": "Unique customer identifier of the customer making the purchase. The ID is assigned by Voucherify.",
"example": "cust_7iUa6ICKyU6gH40dBU25kQU1"
},
"referrer_id": {
"type": "string",
"example": "cust_nM4jqPiaXUvQdVSA6vTRUnix",
"description": "Unique referrer ID."
},
"object": {
"type": "string",
"default": "order",
"description": "The type of the object represented by JSON. This object stores information about the `order`."
},
"redemptions": {
"description": "Lists details related to the redemption.",
"allOf": [
{
"$ref": "#/components/schemas/10_obj_order_object_unstacked_redemptions"
}
]
}
}
},
"7_obj_redemption_object_loyalty_card_digital_discount_voucher": {
"type": "object",
"title": "Discount Voucher",
"description": "Contains information about the source of the digital reward.",
"properties": {
"id": {
"type": "string",
"example": "camp_0dJG7cCAjquzcxWmZ634bA0C",
"description": "Unique parent campaign ID of reward."
},
"type": {
"type": "string",
"description": "Campaign type.",
"default": "DISCOUNT_COUPONS",
"enum": [
"DISCOUNT_COUPONS"
]
}
}
},
"7_obj_redemption_object_loyalty_card_digital_gift_card_credits": {
"type": "object",
"title": "Gift Card",
"description": "Contains information about the source of the digital reward.",
"properties": {
"id": {
"type": "string",
"example": "camp_0dJG7cCAjquzcxWmZ634bA0C",
"description": "Unique parent campaign ID of reward."
},
"balance": {
"type": "integer",
"description": "The amount credited to the gift card as a reward expressed as the smallest currency unit (e.g. 100 cents for $1.00)."
},
"type": {
"type": "string",
"description": "Campaign type.",
"default": "GIFT_VOUCHERS",
"enum": [
"GIFT_VOUCHERS"
]
}
}
},
"7_obj_redemption_object_loyalty_card_digital_loyalty_card_points": {
"type": "object",
"title": "Loyalty Card",
"description": "Contains information about the source of the digital reward.",
"properties": {
"id": {
"type": "string",
"example": "camp_0dJG7cCAjquzcxWmZ634bA0C",
"description": "Unique parent campaign ID of reward."
},
"balance": {
"type": "integer",
"description": "The number of loyalty points that is added to the loyalty card as a reward."
},
"type": {
"type": "string",
"description": "Campaign type.",
"default": "LOYALTY_PROGRAM",
"enum": [
"LOYALTY_PROGRAM"
]
}
}
},
"CustomerSummary": {
"title": "Customer Summary",
"type": "object",
"properties": {
"redemptions": {
"$ref": "#/components/schemas/CustomerSummaryRedemptions"
},
"orders": {
"$ref": "#/components/schemas/CustomerSummaryOrders"
}
},
"required": [
"redemptions",
"orders"
]
},
"CustomerLoyalty": {
"title": "Customer Loyalty",
"type": "object",
"properties": {
"points": {
"type": "integer",
"description": "Customer's loyalty points minus expired for all loyalty cards which the customer has."
},
"referred_customers": {
"type": "integer",
"description": "Total number of customers referred by the customer."
},
"campaigns": {
"type": "object",
"description": "Contains campaigns with details about point balances and how many customers were referred by the customer.",
"additionalProperties": {
"type": "object",
"description": "Contains details about the point balances left on loyalty cards and the number of referred customers in each campaign.",
"properties": {
"points": {
"type": "integer",
"description": "Remaining point balance in campaign."
},
"loyalty_tier": {
"type": "string",
"example": "ltr_UJ5Q54Q0OvEhua87Qfv2Ki5x",
"description": "Customer's loyalty tier within the campaign."
},
"referred_customers": {
"type": "integer",
"description": "Number of customers referred by the customer in campaign."
}
}
}
}
},
"required": [
"points",
"referred_customers",
"campaigns"
]
},
"CustomerReferrals": {
"title": "Customer Referrals",
"type": "object",
"description": "Summary of customer's referrals, in this case, the customer being the referee, i.e. information about the source of referrals and number of times the customer was referred by other customers.",
"properties": {
"total": {
"type": "integer",
"description": "Total number of times this customer received a referral, i.e. was referred by another customer."
},
"campaigns": {
"type": "array",
"description": "Contains an array of campaigns that served as the source of a referral for the customer.",
"items": {
"title": "Customer Referrals Campaigns Item",
"type": "object",
"description": "Contains information about the source of the referral.",
"properties": {
"campaign_id": {
"type": "string",
"description": "Unique campaign ID, assigned by Voucherify.",
"example": "camp_rRsfatlwN7unSeUIJDCYedal"
},
"referrer_id": {
"type": "string",
"example": "cust_sehkNIi8Uq2qQuRqSr7xn4Zi",
"description": "Unique referrer ID, assigned by Voucherify. This is the customer ID of a customer that is referring this customer."
},
"related_object_id": {
"type": "string",
"description": "Related object id",
"example": "r_0b9d4cc4aa164dd073"
},
"related_object_type": {
"type": "string",
"description": "Related object type, i.e. `redemption`."
},
"date": {
"type": "string",
"format": "date-time",
"example": "2022-08-30T10:19:39.196Z",
"description": "Timestamp representing the date and time when the customer was referred in ISO 8601 format."
}
},
"required": [
"campaign_id",
"referrer_id",
"related_object_id",
"related_object_type",
"date"
]
}
}
},
"required": [
"total",
"campaigns"
]
},
"RedeemableGift": {
"title": "Redeemable Gift",
"type": "object",
"description": "Contains current gift card balance information.",
"properties": {
"balance": {
"type": "number",
"description": "Available funds. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `$100.00`."
},
"credits": {
"type": "number",
"description": "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": {
"type": "number",
"description": "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."
}
}
},
"RedeemableLoyaltyCard": {
"type": "object",
"title": "Redeemable Loyalty Card",
"description": "Redeemable loyalty card object response",
"properties": {
"points": {
"type": "integer",
"example": 7000,
"description": "Total number of points added to the loyalty card over its lifespan."
},
"balance": {
"type": "integer",
"example": 6970,
"description": "Points available for reward redemption. This is calculated as follows: `balance` = `points` - `expired_points` - `subtracted_points` - `redemption.redeemed_points`."
},
"exchange_ratio": {
"type": "number",
"description": "The cash equivalent of the points defined in the points_ratio property."
},
"points_ratio": {
"type": "integer",
"description": "The number of loyalty points that will map to the predefined cash amount defined by the exchange_ratio property."
},
"transfers": {
"title": "Loyalties Transfer",
"type": "array",
"items": {
"$ref": "#/components/schemas/LoyaltiesTransferPoints"
}
}
}
},
"DiscountAmountVouchersEffectTypes": {
"title": "Discount Amount Vouchers Effect Types",
"enum": [
"APPLY_TO_ORDER",
"APPLY_TO_ITEMS",
"APPLY_TO_ITEMS_PROPORTIONALLY",
"APPLY_TO_ITEMS_PROPORTIONALLY_BY_QUANTITY",
"APPLY_TO_ITEMS_BY_QUANTITY"
],
"type": "string"
},
"DiscountUnitVouchersEffectTypes": {
"title": "Discount Unit Vouchers Effect Types",
"enum": [
"ADD_MISSING_ITEMS",
"ADD_NEW_ITEMS",
"ADD_MANY_ITEMS",
"ADD_SAME_ITEMS"
],
"type": "string"
},
"SimpleProductDiscountUnit": {
"type": "object",
"title": "Simple Product Discount Unit",
"properties": {
"id": {
"type": "string",
"description": "Unique product ID, assigned by Voucherify."
},
"source_id": {
"type": "string",
"description": "Product's source ID."
},
"name": {
"type": "string",
"description": "Product name."
}
},
"required": [
"id",
"name"
]
},
"SimpleSkuDiscountUnit": {
"type": "object",
"title": "Simple Sku Discount Unit",
"properties": {
"id": {
"type": "string",
"description": "Unique SKU ID, assigned by Voucherify."
},
"source_id": {
"type": "string",
"description": "Product variant's source ID."
},
"name": {
"type": "string",
"description": "Sku name"
}
},
"required": [
"id",
"name"
]
},
"DiscountUnitMultipleOneUnit": {
"type": "object",
"title": "One Unit",
"properties": {
"unit_off": {
"type": "number",
"description": "Number of units to be granted a full value discount."
},
"unit_off_formula": {
"type": "string",
"description": "Formula used to dynamically calculate the number of units."
},
"effect": {
"type": "string",
"enum": [
"ADD_NEW_ITEMS",
"ADD_MISSING_ITEMS"
],
"description": "Defines how the unit is added to the customer's order.\n\n"
},
"unit_type": {
"type": "string",
"description": "The product deemed as free, chosen from product inventory (e.g. time, items)."
},
"product": {
"description": "Contains information about the product.",
"allOf": [
{
"$ref": "#/components/schemas/SimpleProductDiscountUnit"
}
]
},
"sku": {
"description": "Contains information about the sku.",
"allOf": [
{
"$ref": "#/components/schemas/SimpleSkuDiscountUnit"
}
]
}
},
"required": [
"effect",
"unit_type"
]
},
"DiscountPercentVouchersEffectTypes": {
"title": "Discount Percent Vouchers Effect Types",
"enum": [
"APPLY_TO_ORDER",
"APPLY_TO_ITEMS"
],
"type": "string"
},
"DiscountFixedVouchersEffectTypes": {
"title": "Discount Fixed Vouchers Effect Types",
"enum": [
"APPLY_TO_ORDER",
"APPLY_TO_ITEMS"
],
"type": "string"
},
"ProductWithoutSkus": {
"title": "Product without Skus Object",
"properties": {
"id": {
"type": "string",
"description": "Unique product ID assigned by Voucherify.",
"example": "prod_0b1da8105693710357"
},
"source_id": {
"type": "string",
"nullable": true,
"example": "productSourceID16",
"description": "Unique product source ID."
},
"name": {
"type": "string",
"nullable": true,
"description": "Unique user-defined product name.",
"example": "T-shirt"
},
"price": {
"type": "integer",
"nullable": true,
"description": "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": {
"type": "array",
"description": "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.",
"items": {
"type": "string"
}
},
"metadata": {
"type": "object",
"description": "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": {
"type": "string",
"nullable": true,
"description": "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"
},
"created_at": {
"type": "string",
"description": "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",
"format": "date-time"
},
"updated_at": {
"type": "string",
"nullable": true,
"description": "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",
"format": "date-time"
},
"object": {
"type": "string",
"description": "The type of the object represented by JSON. This object stores information about the product.",
"default": "product",
"enum": [
"product"
]
}
},
"required": [
"id",
"source_id",
"name",
"attributes",
"metadata",
"object",
"price"
]
},
"SkusListForProduct": {
"type": "object",
"description": "Contains information about child SKUs.",
"title": "Skus List For Product",
"properties": {
"object": {
"type": "string",
"description": "The type of the object represented by JSON. This object stores information about SKUs.",
"default": "list"
},
"data_ref": {
"type": "string",
"description": "Identifies the name of the JSON property that contains the array of SKUs.",
"default": "data"
},
"data": {
"type": "array",
"description": "A dictionary that contains an array of SKUs.",
"items": {
"$ref": "#/components/schemas/Sku"
}
},
"total": {
"type": "integer",
"description": "Total number of SKUs in the product."
}
},
"required": [
"object",
"data_ref",
"data",
"total"
]
},
"ApplicableToEffect": {
"title": "Applicable To Effect",
"type": "string",
"enum": [
"APPLY_TO_EVERY",
"APPLY_TO_CHEAPEST",
"APPLY_FROM_CHEAPEST",
"APPLY_TO_MOST_EXPENSIVE",
"APPLY_FROM_MOST_EXPENSIVE"
]
},
"10_obj_order_object_unstacked_redemptions": {
"type": "object",
"title": "Unstacked Redemption",
"description": "Redemption object representing a single redemption.",
"properties": {
"redemption_ID": {
"type": "object",
"description": "The property name is the unique redemption ID; i.e. `r_0ba186c4824e4881e1`. This object contains information about the redemption of an incentive.",
"properties": {
"date": {
"type": "string",
"description": "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",
"format": "date-time"
},
"related_object_type": {
"type": "string",
"description": "The source of the incentive.",
"enum": [
"voucher",
"promotion_tier"
]
},
"related_object_id": {
"type": "string",
"description": "Unique ID of the related object that defines the incentive."
},
"related_object_parent_id": {
"type": "string",
"description": "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."
}
}
}
}
},
"CustomerSummaryRedemptions": {
"title": "Customer Summary Redemptions",
"type": "object",
"properties": {
"total_redeemed": {
"type": "integer",
"description": "Total number of redemptions made by the customer."
},
"total_failed": {
"type": "integer",
"description": "Total number of redemptions that failed."
},
"total_succeeded": {
"type": "integer",
"description": "Total number of redemptions that succeeded."
},
"total_rolled_back": {
"type": "integer",
"description": "Total number of redemptions that were rolled back for the customer."
},
"total_rollback_failed": {
"type": "integer",
"description": "Total number of redemption rollbacks that failed."
},
"total_rollback_succeeded": {
"type": "integer",
"description": "Total number of redemption rollbacks that succeeded."
},
"gift": {
"type": "object",
"description": "Summary of gift card credits.",
"required": [
"redeemed_amount",
"amount_to_go"
],
"properties": {
"redeemed_amount": {
"type": "integer",
"description": "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`.",
"default": 0
},
"amount_to_go": {
"type": "integer",
"description": "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`.",
"default": 0
}
}
},
"loyalty_card": {
"type": "object",
"description": "Summary of loyalty points.",
"required": [
"redeemed_points",
"points_to_go"
],
"properties": {
"redeemed_points": {
"type": "integer",
"description": "Total number of loyalty points redeemed by the customer."
},
"points_to_go": {
"type": "integer",
"description": "Sum of remaining available point balance across all loyalty cards."
}
}
}
},
"required": [
"total_redeemed",
"total_failed",
"total_succeeded",
"total_rolled_back",
"total_rollback_failed",
"total_rollback_succeeded",
"gift",
"loyalty_card"
]
},
"CustomerSummaryOrders": {
"title": "Customer Summary Orders",
"description": "Lists details about orders related to the customer. Lists only data for orders with the `PAID` or `FULFILLED` status. Data from orders with a `CREATED` or `CANCELED` status are not included. The data is updated also when an order changes status.",
"type": "object",
"properties": {
"total_amount": {
"type": "integer",
"description": "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": {
"type": "integer",
"description": "Total number of orders made by the customer."
},
"average_amount": {
"type": "integer",
"description": "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": {
"type": "integer",
"description": "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": {
"type": "string",
"format": "date-time",
"example": "2022-08-30T11:51:08.029Z",
"description": "Timestamp representing the date and time of the customer's last order in ISO 8601 format."
}
},
"required": [
"total_amount",
"total_count",
"average_amount",
"last_order_amount"
]
},
"LoyaltiesTransferPoints": {
"title": "Loyalties Transfer Points",
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Unique loyalty card code from which the user wants to transfer loyalty points (source)."
},
"points": {
"type": "integer",
"description": "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": {
"type": "string",
"description": "Reason for the transfer."
},
"source_id": {
"type": "string",
"description": "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."
}
},
"required": [
"code",
"points",
"source_id"
]
}
},
"parameters": {
"origin": {
"name": "origin",
"in": "header",
"required": true,
"schema": {
"$ref": "#/components/schemas/ParameterOrigin"
},
"description": "Indicates the origin (scheme, hostname, and port)."
},
"metadata": {
"name": "metadata",
"in": "query",
"required": false,
"schema": {
"$ref": "#/components/schemas/ParameterObject"
},
"style": "deepObject",
"explode": true,
"description": "Metadata key value pairs."
},
"item": {
"name": "item",
"in": "query",
"required": false,
"schema": {
"$ref": "#/components/schemas/6_query_validate_voucher_client_side_orders_order_item"
},
"description": "Array of order items.",
"style": "deepObject",
"explode": true
}
},
"securitySchemes": {
"X-Client-Application-Id": {
"type": "apiKey",
"name": "X-Client-Application-Id",
"in": "header"
},
"X-Client-Token": {
"type": "apiKey",
"name": "X-Client-Token",
"in": "header"
},
"X-Voucherify-OAuth": {
"type": "oauth2",
"flows": {
"implicit": {
"authorizationUrl": "https://api.voucherify.io/v1/oauth/token",
"scopes": {
"api": "Gives access to whole server-side API.",
"vouchers": "Gives access to all endpoints and methods starting with `v1/vouchers`.",
"client_api": "Gives access to whole client-side API.",
"client_vouchers": "Gives access to all endpoints and methods starting with `/client/v1/vouchers`.",
"promotions": "Gives access to all endpoints and methods starting with `/v1/promotions`.",
"client_promotions": "Gives access to all endpoints and methods starting with `/client/v1/promotions`",
"campaigns": "Gives access to all endpoints and methods starting with `v1/campaigns`.",
"client_publish": "Gives access to all endpoints and methods starting with `/client/v1/publish`.",
"exports": "Gives access to all endpoints and methods starting with `/v1/exports`.",
"publications": "Gives access to all endpoints and methods starting with `/v1/publications`.",
"client_validate": "Gives access to all endpoints and methods starting with `/client/v1/validate`.",
"validations": "Gives access to all endpoints and methods starting with `/v1/validations`.",
"client_validations": "Gives access to all endpoints and methods starting with `/client/v1/validations`.",
"qualifications": "Gives access to all endpoints and methods starting with `/v1/qualifications`.",
"client_qualifications": "Gives access to all endpoints and methods starting with `/client/v1/qualifications`.",
"client_redeem": "Gives access to all endpoints and methods starting with `/client/v1/redeem",
"redemptions": "Gives access to all endpoints and methods starting with `/v1/redemptions`.",
"client_redemptions": "Gives access to all endpoints and methods starting with `/client/v1/redemptions`",
"customers": "Gives access to all endpoints and methods starting with `/v1/customers`.",
"client_customers": "Gives access to all endpoints and methods starting with `/client/v1/customers`.",
"orders": "Gives access to all endpoints and methods starting with `/v1/orders`.",
"products": "Gives access to all endpoints and methods starting with `/v1/products`.",
"skus": "Gives access to all endpoints and methods starting with `/v1/SKUs`.",
"validation-rules": "Gives access to all endpoints and methods starting with `/v1/validation-rules`.",
"validation-rules-assignments": "Gives access to all endpoints and methods starting with `/v1/validation-rules-assignments",
"segments": "Gives access to all endpoints and methods starting with `/v1/segments`.",
"events": "Gives access to all endpoints and methods starting with `/v1/events`.",
"client_events": "Gives access to all endpoints and methods starting with `client/v1/events`.",
"rewards": "Gives access to all endpoints and methods starting with `/v1/rewards`.",
"assets": "Gives access to all endpoints and methods starting with `/v1/assets`.",
"task-results": "Gives access to all endpoints and methods starting with `/v1/task-results`.",
"loyalties": "Gives access to all endpoints and methods starting with `/v1/loyalties`.",
"client_consents": "Gives access to all endpoints and methods starting with `client/v1/consents`.",
"consents": "Gives access to all endpoints and methods starting with `/v1/consents`.",
"async-actions": "Gives access to all endpoints and methods starting with `/v1/async-actions`.",
"product-collections": "Gives access to all endpoints and methods starting with `/v1/product-collections`.",
"categories": "Gives access to all endpoints and methods starting with `/v1/categories`.",
"metadata-schemas": "Gives access to all endpoints and methods starting with `/v1/metadata-schemas`.",
"locations": "Gives access to all endpoints and methods starting with `/v1/locations`.",
"referrals": "Gives access to all endpoints and methods starting with `/v1/referrals`.",
"trash-bin": "Gives access to all endpoints and methods starting with `/v1/trash-bin`.",
"templates": "Gives access to all endpoints and methods starting with `/v1/templates`."
}
}
}
},
"X-App-Id": {
"type": "apiKey",
"name": "X-App-Id",
"in": "header"
},
"X-App-Token": {
"type": "apiKey",
"name": "X-App-Token",
"in": "header"
}
}
}
}