--- title: "Add Voucher with Specific Code to Campaign" method: POST path: "/v1/campaigns/{campaignId}/vouchers/{code}" tags: ["Campaigns"] --- # Add Voucher with Specific Code to Campaign `POST /v1/campaigns/{campaignId}/vouchers/{code}` ## Request - Base URL: `https://api.voucherify.io` - URL: `https://api.voucherify.io/v1/campaigns/{campaignId}/vouchers/{code}` - Auth: one of: - API key in header `X-App-Id` and API key in header `X-App-Token` - OAuth 2 - Implicit: `https://api.voucherify.io/v1/oauth/token` - Scopes: `api`, `campaigns` This method gives a possibility to add a new voucher to an existing campaign. The voucher definition will be inherited from the definition kept in the campaign profile. However, you are able to overwrite a few properties inherited from the campaign. ## Request body - CampaignsVouchersCreateRequestBody - `category` string: The category assigned to the campaign. Either pass this parameter OR the `category_id`. - `metadata` object: The metadata object stores all custom attributes assigned to the voucher. 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. - `redemption` object: Stores the quantity of redemptions that can be applied to the voucher. - `quantity` integer: How many times a voucher can be redeemed. A `null` value means unlimited. - `additional_info` string: An optional field to keep any extra textual information about the code such as a code description and details. - `start_date` string, date-time: Activation timestamp defines when the voucher starts to be active in ISO 8601 format. Voucher is *inactive before* this date. - `expiration_date` string, date-time: Expiration timestamp defines when the voucher expires in ISO 8601 format. Voucher is *inactive after* this date. ## Response `200` Returns a voucher object if the call succeeded. - CampaignsVouchersCreateResponseBody: This is an object representing a voucher. - `id` string: Assigned by the Voucherify API, identifies the voucher. - `code` string: A code that identifies a voucher. Pattern can use all letters of the English alphabet, Arabic numerals, and special characters. - `campaign` string: A unique campaign name, identifies the voucher's parent campaign. - `campaign_id` string: Assigned by the Voucherify API, identifies the voucher's parent campaign. - `category` string: Tag defining the category that this voucher belongs to. Useful when listing vouchers using the List Vouchers endpoint. - `category_id` string: Unique category ID assigned by Voucherify. - `type` 'GIFT_VOUCHER' | 'DISCOUNT_VOUCHER' | 'LOYALTY_CARD': Defines the type of the voucher. - `discount` union: Contains information about discount. - object - `type` 'AMOUNT', required: Defines the type of the voucher. - `amount_off` number, required: Amount taken off the subtotal of a price. Value is multiplied by 100 to precisely represent 2 decimal places. For example, a $10 discount is written as 1000. - `amount_off_formula` string: Formula used to dynamically calculate the discount. - `aggregated_amount_limit` integer: Maximum discount amount per order. - `effect` 'APPLY_TO_ORDER' | 'APPLY_TO_ITEMS' | 'APPLY_TO_ITEMS_PROPORTIONALLY' | 'APPLY_TO_ITEMS_PROPORTIONALLY_BY_QUANTITY' | 'APPLY_TO_ITEMS_BY_QUANTITY' - `is_dynamic` boolean: Flag indicating whether the discount was calculated using a formula. - object - `type` 'UNIT', required: Discount type. - `unit_off` integer: Number of units to be granted a full value discount. - `unit_off_formula` string: Formula used to dynamically calculate the number of units. - `effect` 'ADD_MISSING_ITEMS' | 'ADD_NEW_ITEMS' | 'ADD_MANY_ITEMS' | 'ADD_SAME_ITEMS' - `unit_type` string, required: The product deemed as free, chosen from product inventory (e.g. time, items). - `product` SimpleProductDiscountUnit - `id` string, required: Unique product ID, assigned by Voucherify. - `source_id` string: Product's source ID. - `name` string, required: Product name. - `sku` SimpleSkuDiscountUnit - `id` string, required: Unique SKU ID, assigned by Voucherify. - `source_id` string: Product variant's source ID. - `name` string, required: Sku name - `is_dynamic` boolean: Flag indicating whether the discount was calculated using a formula. - object - `type` 'UNIT', required: Discount type. - `effect` 'ADD_MANY_ITEMS': Defines how the discount is applied to the customer's order. - `units` DiscountUnitMultipleOneUnit[], required - `unit_off` number: Number of units to be granted a full value discount. - `unit_off_formula` string: Formula used to dynamically calculate the number of units. - `effect` 'ADD_NEW_ITEMS' | 'ADD_MISSING_ITEMS', required: Defines how the unit is added to the customer's order. - `unit_type` string, required: The product deemed as free, chosen from product inventory (e.g. time, items). - `product` SimpleProductDiscountUnit - `id` string, required: Unique product ID, assigned by Voucherify. - `source_id` string: Product's source ID. - `name` string, required: Product name. - `sku` SimpleSkuDiscountUnit - `id` string, required: Unique SKU ID, assigned by Voucherify. - `source_id` string: Product variant's source ID. - `name` string, required: Sku name - object - `type` 'PERCENT', required: Defines the type of the voucher. - `percent_off` number, required: The percent discount that the customer will receive. - `percent_off_formula` string: Formula used to dynamically calculate the discount. - `amount_limit` number: Upper limit allowed to be applied as a discount. Value is multiplied by 100 to precisely represent 2 decimal places. For example, a $6 maximum discount is written as 600. - `aggregated_amount_limit` integer: Maximum discount amount per order. - `effect` 'APPLY_TO_ORDER' | 'APPLY_TO_ITEMS' - `is_dynamic` boolean: Flag indicating whether the discount was calculated using a formula. - object - `type` 'FIXED', required: Defines the type of the voucher. - `fixed_amount` number, required: Sets a fixed value for an order total or the item price. The value is multiplied by 100 to precisely represent 2 decimal places. For example, a $10 discount is written as 1000. If the fixed amount is calculated by the formula, i.e. the `fixed_amount_formula` parameter is present in the fixed amount definition, this value becomes the **fallback value**. As a result, if the formula cannot be calculated due to missing metadata, for example, this value will be used as the fixed value. - `fixed_amount_formula` string: Formula used to dynamically calculate the discount. - `effect` 'APPLY_TO_ORDER' | 'APPLY_TO_ITEMS' - `is_dynamic` boolean: Flag indicating whether the discount was calculated using a formula. - `gift` object: Object representing gift parameters. Child attributes are present only if `type` is `GIFT_VOUCHER`. Defaults to `null`. - `amount` integer: Total gift card income over the lifetime of the card. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `$100.00`. - `subtracted_amount` integer: Total amount of subtracted credits over the gift card lifetime. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `$100.00`. - `balance` integer: Available funds. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `$100.00`. - `effect` 'APPLY_TO_ORDER' | 'APPLY_TO_ITEMS': Defines how the credits are applied to the customer's order. - `loyalty_card` object: Object representing loyalty card parameters. Child attributes are present only if `type` is `LOYALTY_CARD`. Defaults to `null`. - `points` integer: Total number of points added to the loyalty card over its lifespan. - `balance` integer: Points available for reward redemption. This is calculated as follows: `balance` = `points` - `expired_points` - `subtracted_points` - `redemption.redeemed_points`. - `next_expiration_date` string, date: The next closest date when the next set of points are due to expire. - `next_expiration_points` integer: The amount of points that are set to expire next. - `pending_points` integer: Shows the number of pending points that will be added to the loyalty card when they are activated automatically or manually. - `expired_points` integer: Shows the total number of expired points over the lifetime of the loyalty card. - `subtracted_points` integer: Shows the total number of subtracted points over the lifetime of the loyalty card. - `start_date` string, date-time: Activation timestamp defines when the code starts to be active in ISO 8601 format. Voucher is *inactive before* this date. - `expiration_date` string, date-time: Expiration timestamp defines when the code expires in ISO 8601 format. Voucher is *inactive after* this date. - `validity_timeframe` ValidityTimeframe: 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`. - `duration` string: Defines the amount of time an earning rule will be active in ISO 8601 format. For example, an earning rule with a `duration` of `PT1H` will be valid for a duration of one hour. - `interval` string: Defines the intervening time between two time points in ISO 8601 format, expressed as a duration. For example, an earning rule with an `interval` of `P2D` will be valid every other day. - `validity_day_of_week` integer[]: Integer array corresponding to the particular days of the week in which the voucher is valid. - `0` Sunday - `1` Monday - `2` Tuesday - `3` Wednesday - `4` Thursday - `5` Friday - `6` Saturday - `validity_hours` ValidityHours: Determines the hours of validity, e.g. to create a happy hours scenario. - `daily` object[]: Defines the recurring period(s) when the resource is active. The periods should not overlap. - `start_time` string, time: Defines the starting hour of validity in the HH:mm format. The resource is *inactive before* this time. - `days_of_week` integer[]: Integer array corresponding to the particular days of the week in which the resource is valid. - `0` Sunday - `1` Monday - `2` Tuesday - `3` Wednesday - `4` Thursday - `5` Friday - `6` Saturday - `expiration_time` string, time: Defines the ending hour of validity in the HH:mm format. The resource is *inactive after* this time. - `active` boolean, nullable: A flag to toggle the voucher on or off. You can disable a voucher even though it's within the active period defined by the `start_date` and `expiration_date`. - `true` indicates an *active* voucher - `false` indicates an *inactive* voucher - `additional_info` string: An optional field to keep any extra textual information about the code such as a code description and details. - `metadata` object: The metadata object stores all custom attributes assigned to the code. A set of key/value pairs that you can attach to a voucher object. It can be useful for storing additional information about the voucher in a structured format. - `assets` VoucherAssets: Stores links to images of QR and barcode that correspond to an encrypted voucher code. - `qr` object: Stores Quick Response (QR) representation of encrypted code. - `id` string: Encrypted voucher code ID. - `url` string: URL to QR code *Optional:* Attach query parameters to base URL to customize the image of the encrypted voucher code. - `size`: integer value from `1` to `100` - `format`: string, either `png` (default) or `svg` - `barcode` object: Stores barcode representation of encrypted code. - `id` string: Encrypted voucher code ID. - `url` string: URL to barcode *Optional:* Attach query parameters to base URL to customize the image of the encrypted voucher code. - `size`: integer value from `1` to `100` - `format`: string, either `png` (default) or `svg` - `is_referral_code` boolean, nullable: Flag indicating whether this voucher is a referral code; `true` for campaign type `REFERRAL_PROGRAM`. - `created_at` string, date-time: Timestamp representing the date and time when the voucher was created. The value is shown in the ISO 8601 format. - `updated_at` string, date-time: Timestamp representing the date and time when the voucher was last updated in ISO 8601 format. - `holder_id` string: Unique customer identifier of the redeemable holder. It equals to the customer ID assigned by Voucherify. - `referrer_id` string: Unique identifier of the referring person. - `object` string: The type of the object represented by JSON. Default is `voucher`. - `publish` object: Stores a summary of publication events: an event counter and endpoint to return details of each event. Publication is an assignment of a code to a customer, e.g. through a distribution. - `object` string: The type of the object represented is by default `list`. To get this list, you need to make a call to the endpoint returned in the `url` attribute. - `count` integer: Publication events counter. - `url` string: The endpoint where this list of publications can be accessed using a **GET** method. `/v1/vouchers/{voucher_code}/publications` - `redemption` object: Stores a summary of redemptions that have been applied to the voucher. - `quantity` integer: How many times a voucher can be redeemed. A `null` value means unlimited. - `redeemed_quantity` integer: How many times a voucher has already been redeemed. - `redeemed_points` integer: Total loyalty points redeemed. - `object` string: The type of the object represented is by default `list`. To get this list, you need to make a call to the endpoint returned in the url attribute. - `url` string: The endpoint where this list of redemptions can be accessed using a **GET** method. `/v1/vouchers/{voucher_code}/redemptions` - `categories` Category[]: Contains details about the category. - `id` string, required: Unique category ID assigned by Voucherify. - `name` string, required: Category name. - `hierarchy` integer, required: Category hierarchy. Categories with lower hierarchy are processed before categories with higher hierarchy value. - `object` 'category', required: The type of the object represented by the JSON. This object stores information about the category. - `created_at` string, date-time, required: Timestamp representing the date and time when the category was created. The value is shown in the ISO 8601 format. - `updated_at` string, date-time: Timestamp representing the date and time when the category was updated. The value is shown in the ISO 8601 format. - `validation_rules_assignments` ValidationRulesAssignmentsList: List of Validation Rules Assignments - `object` 'list', required: The type of the object represented by JSON. This object stores information about validation rules assignments. - `data_ref` 'data', required: Identifies the name of the attribute that contains the array of validation rules assignments. - `data` BusValRuleAssignment[], required: Contains array of validation rules assignments. - `id` string, required: The unique identifier for a assignment - `rule_id` string, required: The unique identifier for a rule - `related_object_id` string, required: The unique identifier for a related object - `related_object_type` string, required: The type of related object - `created_at` string, date-time: Timestamp representing the date and time when the object was created. The value is shown in the ISO 8601 format. - `updated_at` string, date-time: Timestamp representing the date and time when the object was last updated in ISO 8601 format. - `object` 'validation_rules_assignment', required: The type of the object represented by JSON. - `validation_status` 'VALID' | 'PARTIALLY_VALID' | 'INVALID': The validation status of the assignment - `validation_omitted_rules` string[]: The list of omitted rules - `total` integer, required: Total number of validation rules assignments. ## Other responses - `409`: Returns an error if a voucher with the same code already exists. --- [API](https://skmtc.dev/voucherifyio/apis/voucherify-api-async-actions.md) - [All operations](https://skmtc.dev/voucherifyio/apis/voucherify-api-async-actions/llms.txt) - [OpenAPI document](https://skmtc.dev/voucherifyio/apis/voucherify-api-async-actions/revisions/4982266e0494?raw)