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

---

Setup

Grab via Maven:

<dependency>
  <groupId>io.voucherify.client</groupId>
  <artifactId>voucherify-java-sdk</artifactId>
  <version>11.2.1</version>
</dependency>

or via Gradle

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

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

VoucherifyClient voucherify = new VoucherifyClient.Builder()
            .setAppId("YOUR-APPLICATION-ID")
            .setClientSecretKey("YOUR-CLIENT-SECRET-KEY")
            .build();

API Endpoint

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

VoucherifyClient.Builder()
            .apiVersion(ApiVersion.V_2018_08_01)
            .setEndpoint("api.voucherify.io")
            .build();

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>() {
    @Override
    public void onSuccess(VoucherResponse result) {
    }

    @Override
    public void onFailure(VoucherifyError error) {
    // error
  }
});

or using RxJava:

client.vouchers()
        .rx()
        .create(createVoucher)
        .subscribe(new Action1<VoucherResponse>() {
            @Override
            public void call(VoucherResponse voucher) {

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

API

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
• Get Voucher
• Update Voucher
• Delete Voucher
• List Vouchers
• Enable Voucher
• Disable Voucher
• Add Gift Voucher Balance
• Import Vouchers
• Get Qualified Vouchers
• Release Session

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);

Release Session

voucherify.vouchers().releaseSession(String code, String sessionKey);

---

Campaigns API

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

• Create Campaign
• Add Voucher to Campaign
• Delete Campaign
• Update Campaign
• Import Vouchers to Campaign

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
• Create Export
• Get Export
• Delete Export
• List publications

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()
voucherify.distributions.list(ListPublicationsFilter filter)

---

Validations API

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

• Validate Voucher
• Validate Promotion Campaign

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
• Redeem Promotion
• List Redemptions
• Get Voucher's Redemptions
• Get Redemption
• Rollback Redemption

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
• Get Customer
• Update Customer
• Update Customers in bulk
• Delete Customer
• List Customers
• Update Customer's Consents

Create Customer

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

Check customer object.

Get Customer

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

Update Customer

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

Update Customers in bulk

voucherify.customers().update(List<Customer> customers);

Delete Customer

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

List Customers

voucherify.customers.list()
voucherify.customers.list(CustomersFilter filter)

Update Customer's Consents

voucherify.customers().updateCustomerConsents(String customerId, Map<String, Boolean> consents);

---

Orders API

Methods are provided within voucherify.orders.* namespace.

• Create Order
• Get Order
• Update Order
• List Orders

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()
voucherify.orders().list(OrdersFilter filter)

---

Rewards API

Create Rewards

voucherify.rewards().create(reward);

Get Reward

voucherify.rewards().get(id);

Update Reward

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

List Rewards

voucherify.rewards().list(params);

Delete Reward

voucherify.rewards().delete(id);

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

voucherify.loyalties().list(filter);

Create Loyalty

voucherify.loyalties().create(loyalty);

Get Loyalty

voucherify.loyalties().get(id);

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);

Get Loyalty Member By Id

voucherify.loyalties().getMember(member_id);

Redeem Loyalty Reward

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

Add Loyalty Card Balance

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

Add or Remove Loyalty Card Balance

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

Get Members Loyalty Tier

voucherify.loyalties().getMembersLoyaltyTier(member_id);

Get Member Activities For Loyalty

voucherify.loyalties().getMemberActivities(String loyalty_id, String member_id);

Get Member Activities

voucherify.loyalties().getMemberActivities(String member_id);

---

Products API

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

• Create Product
• Get Product
• Update Product
• Update Products in bulk
• Delete Product
• List Products
• Create SKU
• Get SKU
• Update SKU
• Delete SKU
• List all product SKUs

Create Product

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

Check product object.

Get Product

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

Update Product

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

Update Products in bulk

voucherify.products().update(List<Product> products);

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.

Get SKU

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
• Get Validation Rule
• Update Validation Rule
• List Validation Rules
• Delete Validation Rule
• Create Validation Rule Assignment
• List Validation Rule Assignments
• Delete Validation Assignment

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
• Get Segment
• Delete Validation Rules

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
• List Promotion Tiers
• Add Promotion Tier
• Update Promotion Tier
• Delete Promotion Tier

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 voucherify.events.* namespace.

• Create Events

Create event

Check customer object.

voucherify.events.track(CustomEvent customEvent)

Async Actions API

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

• Get Async Action
• List Async Actions

Get Async Action

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

List Async Actions

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

---

Consents API

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

• List Consents

List Consents

voucherify.consents().list();

---

Stackable Discounts API

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

• Redeem Stackable Discounts
• Validate Stackable Discounts
• Rollback Stackable Redemptions

Redeem Stackable Discounts

voucherify.stackables().redeem(RedeemStackableDiscount redeemStackableDiscount);

Validate Stackable Discounts

voucherify.stackables().validate(ValidateStackableDiscount validateStackableDiscount);

Rollback Stackable Redemptions

voucherify.stackables().rollbackRedemption(String parentRedemptionId);

---

Qualifications API

Methods are provided within voucherify.qualifications.* namespace.

• Check Eligibility

Check Eligibility

voucherify.qualifications().checkEligibility(CheckEligibility checkEligibility) 

---

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:

• voucherify.customers().getCustomer(String customerId) - voucherify.customers().get()

• voucherify.customers().createCustomer(Customer customer) - voucherify.customers().create()

• voucherify.customers().updateCustomer(Customer customer) - voucherify.customers().update()

• voucherify.customers().deleteCustomer(String customerId) - voucherify.customers().delete()

• voucherify.validations().validateVoucher(String code, VoucherValidationContext validityContext) - voucherify.validations().validate()

• voucherify.vouchers().listVouchers(VouchersFilter filter) - voucherify.vouchers().list()

• voucherify.vouchers().fetchVoucher(String identifier) - voucherify.vouchers().list()

• voucherify.vouchers().createVoucher(Voucher voucher) - voucherify.vouchers().create()

• voucherify.vouchers().updateVoucher(String code, VoucherUpdate voucherUpdate) - voucherify.vouchers().update()

• voucherify.vouchers().publishVoucher(String code) - voucherify.distributions().publish()

• voucherify.vouchers().disableVoucher(String code) - voucherify.vouchers().disable()

• voucherify.vouchers().enableVoucher(String code) - voucherify.vouchers().enable()

• voucherify.vouchers().redeem(String identifier, String trackingId) - voucherify.redemptions().redeem()

• voucherify.vouchers().redeem(String identifier, VoucherRedemptionContext redemptionContext) - - voucherify.redemptions().redeem()

• voucherify.vouchers().redemption(String identifier) - voucherify.redemptions().get()

• voucherify.vouchers().listRedemptions(RedemptionsFilter filter) - voucherify.redemptions().list()

• voucherify.vouchers().rollbackRedemption(String redemptionId, String trackingId, String reason) - voucherify.redemptions().rollback()

• voucherify.vouchers().validate(String code, VoucherValidationContext validityContext) - voucherify.validations().validate()

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)

Builders

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

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

---

Utils

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.

###Examples

Synchronous

try {
    voucherify.vouchers().create(createVoucher);
  } catch(VoucherifyError e) {
    // Error handling
  }

RX java

voucherify.vouchers().rx().create(createVoucher)
  .doOnError(new Action1<VoucherifyError>() {
    
    @Override
    public void call(VoucherifyError error) {
     // Error handling
    }
  });

Async

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

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/rspective/voucherify-java-sdk.

Changelog

• 2024-03-12 - 11.2.1 - Added all supported fields to DiscountResponse. Thanks to mariaivanova-git for issue request
• 2023-10-26 - 11.2.0 -
  • Added APPLY_TO_ITEMS_BY_QUANTITY discount type. Added Update Products in bulk method. Thanks to @viglu for contribution!
  • Added missing properties to OrderResponse and OrderItemResponse models. Thanks to @petro-dutchak-infopulse for issue request!
  • Added support for Stackable Discounts API. Thanks to prenner-voucherify for issue request.
  • Added basic implementation for GetMemberActivities.
  • Added support for consents API.
  • Added support for Qualifications API.
• 2023-09-21 - 11.1.6 - Added VoucherValidationErrorResponse to VoucherValidationResponse. Thanks to tcalvoarroyo for issue request!
• 2023-08-30 - 11.1.5 - Added mapping for status to result in RollbackRedemptionResponse to correctly catch data returned by api in the new version where status property was added.
• 2023-03-21 - 11.1.4 - Added holder_id to VoucherResponse. Added status to CreateOrder. Thanks to @viglu for contribution and @markonieczny for issue request!
• 2023-01-23 - 11.1.3 - Added functions Get Loyalty Member By Id and Get Members Loyalty Tier. Thanks to @viglu for Your contribution!
• 2022-09-16 - 11.1.2 - Customer bulk update. Added function Add or Remove Loyalty Card Balance. Added information about Loyalty Card potins expiration. Thanks to @mabdullah12 for Your contribution!
• 2022-09-07 - 11.1.1 - Add source_id field to CreateOrder model
• 2021-12-21 - 11.1.0 - Add support for Session on Voucher validation & redemption as well as session release
• 2023-08-30 - 11.0.1 - Added mapping for status to result in RollbackRedemptionResponse to correctly catch data returned by api in the new version where status property was added.
• 2021-10-25 - 11.0.0 - Dropped VoucherifyUtils. Changed Integer to Long for amount/quantity/total alike fields. Added missing FIXED discount type. Added discount/gift effects. Changed CampaignType -> CampaignExtenstionType, CampaginType now contains actual campaign types like REFERRAL_PROGRAM. Aligned OkHttp3 version.
• 2023-08-30 - 10.2.1 - Added mapping for status to result in RollbackRedemptionResponse to correctly catch data returned by api in the new version where status property was added.
• 2021-07-27 - 10.2.0 - Add support for Async Actions in vouchers import.
• 2023-08-30 - 10.1.1 - Added mapping for status to result in RollbackRedemptionResponse to correctly catch data returned by api in the new version where status property was added.
• 2021-07-16 - 10.1.0 - Add support for Async Actions
• 2023-08-30 - 10.0.1 - Added mapping for status to result in RollbackRedemptionResponse to correctly catch data returned by api in the new version where status property was added.
• 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.
• 2023-08-30 - 9.1.2 - Added mapping for status to result in RollbackRedemptionResponse to correctly catch data returned by api in the new version where status property was added.
• 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

License

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