Skip to content
Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Official Voucherify SDK for Java

Migration to 5.x | Setup | Synchronous, Rx or Async? | Error handling | Contributing | Changelog

API: Vouchers | Campaigns | Distributions | Validations | Redemptions | Customers | Orders | Loyalties | Rewards | Products | Validation Rules | Segments | Promotions | Events | Utils

Supported JRE versions

  • 8, 9, 10


Grab via Maven:


or via Gradle

compile 'io.voucherify.client:voucherify-java-sdk:10.1.0'

Log-in to Voucherify web interface and obtain your Application Keys from Configuration:

VoucherifyClient voucherify = new VoucherifyClient.Builder()

API Endpoint

You can also specify additional client options - like API version or a different endpoint:


Synchronous, Rx or Async?

All the methods in SDK are provided directly or in asynchronous or rx version:

Every method has a corresponding asynchronous extension which can be accessed through the async() or rx() method of the vouchers module.

try {
    VoucherResponse voucher = client.vouchers.create(createVoucher);
} catch (VoucherifyError e) {
    // error

or asynchronously:

client.vouchers().async().create(createVoucher, new VoucherifyCallback<VoucherResponse>() {
    public void onSuccess(VoucherResponse result) {

    public void onFailure(VoucherifyError error) {
    // error

or using RxJava:

        .subscribe(new Action1<VoucherResponse>() {
            public void call(VoucherResponse voucher) {

        }, new Action1<Throwable>() {
            public void call(Throwable throwable) {


This SDK is fully consistent with restful API Voucherify provides. Detailed descriptions and example responses you will find at official docs. Method headers point to more detailed params description you can use.

Each namespace provides method equivalents for RxJava and Async/callback style API calls.

Vouchers API

Methods are provided within voucherify.vouchers().* namespace.

Create Voucher

voucherify.vouchers().create(CreateVoucher createVoucher);

Check voucher object.

Get Voucher

voucherify.vouchers().get(String code);

Update Voucher

voucherify.vouchers().update(String code, VoucherUpdate update)

Delete Voucher

voucherify.vouchers().delete(String code, boolean force)

List Vouchers

voucherify.vouchers().list(VouchersFilter filter);

Enable Voucher

voucherify.vouchers().enable(String code);

Disable Voucher

voucherify.vouchers().disable(String code);

Add Gift Voucher Balance

voucherify.vouchers().addBalance(String code, AddBalance addBalance);

Import Vouchers

voucherify.vouchers().importVouchers(ImportVouchers importVouchers);

[Get Qualified Vouchers]

voucherify.vouchers().getQualified(QualificationContext context, QualifiedResourceFilter filter);

Campaigns API

Methods are provided within voucherify.campaigns().* namespace.

Create Campaign

voucherify.campaigns().create(CreateCampaign campaign);

Add Voucher to Campaign

voucherify.campaigns().addVoucher(String campaignName, AddVoucherToCampaign addVoucherToCampaing);
voucherify.campaigns().addVoucherWithCode(String campaignName, String code, AddVoucherToCampaign addVoucherToCampaing);

Delete Campaign

voucherify.campaigns().delete(String campaignName, DeleteCampaignParams params);

Update Campaign

voucherify.campaigns().update(String name, UpdateCampaign updateCampaign);

Import Vouchers to Campaign

voucherify.campaigns().importVouchers(String campaignName, String campaignName, CampaignImportVouchers importVouchers);

[Get Qualified Campaigns]

voucherify.campaigns().getQualified(QualificationContext context, QualifiedResourceFilter filter);

Distributions API

Methods are provided within voucherify.distributions().* namespace.

Publish Vouchers

voucherify.distributions().publish(PublishVoucher publishVoucher);

Create Export

voucherify.distributions().createExport(CreateExport createExport);

Get Export

voucherify.distributions().getExport(String id);

Delete Export

voucherify.distributions().deleteExport(String id);

List publications

voucherify.distributions.list(ListPublicationsFilter filter)

Validations API

Methods are provided within voucherify.validations().* namespace.

Validate Voucher

voucherify.validations().validate(String code, VoucherValidation voucherValidation);

Validate Promotion Campaign

voucherify.validations().validate(PromotionValidation promotionValidation);

Redemptions API

Methods are provided within voucherify.redemptions.()* namespace.

Redeem Voucher

voucherify.redemptions().redeem(String code, RedeemVoucher redeemVoucher);

Redeem Promotion

voucherify.redemptions().redeem(String id, RedeemPromotion redeemPromotion);

List Redemptions

voucherify.redemptions().list(RedemptionsFilter filter);

Get Voucher's Redemptions

voucherify.redemptions().getForVoucher(String code);

Get Redemption

voucherify.redemptions().get(String id);

Rollback Redemption

voucherify.redemptions().rollback(String id, String reason, RollbackRedemption rollbackRedemption);

Check redemption rollback object.

Customers API

Methods are provided within voucherify.customers().* namespace.

Create Customer

voucherify.customers().create(Customer customer);

Check customer object.

Get Customer

voucherify.customers().get(String id);

Update Customer

voucherify.customers().update(Customer customer);

Delete Customer

voucherify.customers().delete(String id);

List Customers

voucherify.customers.list(CustomersFilter filter)

Orders API

Methods are provided within voucherify.orders.* namespace.

Create Order

voucherify.orders().create(CreateOrder order)

Check the order object.

Get Order

voucherify.orders().get(String orderId)

Update Order

voucherify.orders().update(UpdateOrder order)

List Orders

voucherify.orders().list(OrdersFilter filter)

Rewards API

Create Rewards


Get Reward


Update Reward

voucherify.rewards().update(id, reward);

List Rewards


Delete Reward


List Reward Assignments

voucherify.rewards().listAssignments(reward_id, query);

Create Reward Assignment

voucherify.rewards().createAssignment(reward_id, assignment);

Update Reward Assignment

voucherify.rewards().updateAssignment(reward_id, assignment_id, assignment);

Delete Reward Assignment

voucherify.rewards().deleteAssignment(reward_id, assignment_id);

Loyalties API

List Loyalties


Create Loyalty


Get Loyalty


Update Loyalty

voucherify.loyalties().update(id, loyalty);

Delete Loyalty

voucherify.loyalties().delete(id, params);

List Loyalty Reward Assignments

voucherify.loyalties().listRewardAssignments(loyalty_id, query);

Create Loyalty Reward Assignment

voucherify.loyalties().createRewardAssignment(loyalty_id, assignment);

Update Loyalty Reward Assignment

voucherify.loyalties().updateRewardAssignment(loyalty_id, assignment_id, assignment);

Delete Loyalty Reward Assignment

voucherify.loyalties().deleteRewardAssignment(loyalty_id, assignment_id);

List Loyalty Earning Rules

voucherify.loyalties().listEarningRules(loyalty_id, query);

Create Loyalty Earning Rule

voucherify.loyalties().createEarningRules(loyalty_id, earning_rule);

Update Loyalty Earning Rule

voucherify.loyalties().updateEarningRule(loyalty_id, earning_rule_id, earning_rule);

Delete Loyalty Earning Rule

voucherify.loyalties().deleteEarningRule(loyalty_id, earning_rule_id);

List Loyalty Members

voucherify.loyalties().listMembers(loyalty_id, query);

Add Loyalty Member

voucherify.loyalties().addMember(loyalty_id, member);

Get Loyalty Member

voucherify.loyalties().getMember(loyalty_id, member_id);

Add Loyalty Card Balance

voucherify.loyalties().redeemReward(loyalty_id, member_id, add_balance);

Redeem Loyalty Reward

voucherify.loyalties().addLoyaltyCardBalance(loyalty_id, member_id, redeem_reward);

Products API

Methods are provided within voucherify.products().* namespace.

Create Product

voucherify.products().create(Product product);

Check product object.

Get Product

voucherify.products().get(String id);

Update Product

voucherify.products().update(Product product);

Delete Product

voucherify.products().delete(String id, DeleteProductParams params);

List Products

voucherify.products().list(ProductsFilter filter);

Create SKU

voucherify.products().createSKU(String productId, SKU sku);

Check SKU object.


voucherify.products().getSKU(String productId, String skuId);

Update SKU

voucherify.products().updateSKU(String product_id, SKU sku);

Delete SKU

voucherify.products().deleteSKU(String productId, String skuId, DeleteSKUParams params);

List all product SKUs

voucherify.products().listSKU(String productId)

Validation Rules API

Methods are provided within voucherify.validationRules().* namespace.

Create Validation Rule

voucherify.validationRules().create(CreateBusinessValidationRule rules);

Get Validation Rule

voucherify.validationRules().get(String id);

Update Validation Rule

voucherify.validationRules().update(UpdateBusinessValidationRule rule);

[List Validation Rules]

voucherify.validationRules().list(BusinessValidationRuleFilter filer);

Delete Validation Rule

voucherify.validationRules().delete(String id);

[Create Validation Rule Assignment]

voucherify.validationRules().createAssignment(String ruleId, CreateBusinessValidationRuleAssignment assignment);

[List Validation Rule Assignments]

voucherify.validationRules().listAssignments(String ruleId, BusinessValidationRuleAssignmentFilter filer);

[Delete Validation Rule Assignment]

voucherify.validationRules().delete(String ruleId, String assignmentId);

Segments API

Methods are provided within voucherify.segments().* namespace.

Create Segment

voucherify.segments().create(Segment segment);

Get Segment

voucherify.segments().get(String id);

Delete Segment

voucherify.segments().delete(String id);

Promotions API

Methods are provided within voucherify.promotions().* namespace.

Create Promotion Campaign

voucherify.promotions().create(CreatePromotionCampaign campaign);

List Promotion Tiers

voucherify.promotions().list(String campaignId);

Add Promotion Tier

voucherify.promotions().addPromotionTier(String tierId, Tier tier);

Update Promotion Tier

voucherify.promotions().updatePromotionTier(String tierId, Tier tier);

Delete Promotion Tier

voucherify.promotions().deletePromotionTier(String tierId);

Events API

Methods are provided within* namespace.

Create event

Check customer object. customEvent)

Async Actions API

Methods are provided within voucherify.asyncActions().* namespace.

Get Async Action

voucherify.asyncActions().get(String id);

List Async Actions

voucherify.asyncActions().list(AsyncActionsFilter filter);

Migration to 6.0

Version 6.0 of the SDK is not backwards compatible with previous version Changes made in version 6.0 relate to PublishVoucherResponse class and RollbackRedemptionResponse class.

Classes changes

  • RollbackRedemptionResponse class uses VoucherResponse class as type for voucher field instead of PublishVoucherResponse

  • PublishVoucherResponse class has additional fields to be compatible with API version - 2017-04-20:

    • id
    • object
    • createdAt
    • customerId
    • trackingId
    • voucher

    When API version 2017-04-05 is used, the PublishVoucherResponse object returned from distributions().publish call will use older structure and new fields will be set to null. Developers using API version 2017-04-05 can still safely access returned fields as before.
    When API version 2017-04-20 is used, the PublisherVoucherResponse object returned from distributions().publish call will use new structure and new fields will be set to proper values.

Migration to 5.0

Version 5.x of the SDK is not backwards compatible with previous version Changes made in version 5.x mostly relate to grouping methods within namespaces.

Methods changes:

Package changes:

  • pl.rspective.voucherify.client -> io.voucherify.client

Classes changes

Most of the classes were moved under the model/moduleName package. For example:

  • model/customer and model/customer/response (which contains only response classes)


In most cases invoking builders has changed in the following way:

  • new Customer.Builder() -> Customer.builder()


Available methods

  • VoucherifyUtils.calculatePrice(BigDecimal basePrice, Voucher voucher, BigDecimal unitPrice)
  • VoucherifyUtils.calculateDiscount(BigDecimal basePrice, Voucher voucher, BigDecimal unitPrice)

Error handling

When an abnormal situation (http calls return 4xx or 5xx, network issues, )a VoucherifyError. It contains following properties:

  • code - HTTP status code.
  • message - a human-readable message providing short description about the error.
  • details - a human-readable message providing more details about the error, usually includes a hint on how to fix the error.
  • key - a short string describing the kind of error that occurred.



try {
  } catch(VoucherifyError e) {
    // Error handling

RX java

  .doOnError(new Action1<VoucherifyError>() {
    public void call(VoucherifyError error) {
     // Error handling


voucherify.vouchers().async().create(createVoucher, new VoucherifyCallback<VoucherResponse>() {
  public void onFailure(VoucherifyError error) {
     // Error handling


Bug reports and pull requests are welcome on GitHub at


  • 2021-07-16 - 10.1.0 - Add support for Async Actions
  • 2020-10-14 - 10.0.0 - Drop old versions usage. Changed properties type from Integer to Long in some classes. Add campaign and campaign_id in Voucher validation response.
  • 2020-07-22 - 9.1.1 - Fixed previous release version and improved publishing artifacts
  • 2020-07-14 - 9.1.0 - Added possibility to specify points as reward when redeeming loyalty card, fixed UpdateOrder status field
  • 2019-09-30 - 9.0.0 - Updated retrofit and rxjava to version >= 2.x. Dropped support for JDK 1.6 and 1.7

See more in Changelog


The SDK is available as open source under the terms of the MIT License.


Java SDK for Voucherify - coupons, vouchers, promo codes




No releases published


No packages published