IomarSantos/voucherify-java-sdk

Java SDK for Voucherify - coupons, vouchers, promo codes

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>9.0.0</version>
</dependency>

or via Gradle

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

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

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
• 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
• Delete Customer
• List Customers

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()
voucherify.customers.list(CustomersFilter filter)

---

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

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
• Get Product
• Update Product
• 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);

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)

---

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

• 2019-09-30 - 9.0.0 - Updated retrofit and rxjava to version >= 2.x. Dropped support for JDK 1.6 and 1.7
• 2019-09-30 - 8.1.0 - Extended QualifiedResourceFilter to support order query param.
• 2019-08-22 - 8.0.1 - Added missing id to VoucherResponse.
• 2019-06-19 - 8.0.0 - Hide API versioning in setEndpoint method.
• 2019-05-27 - 7.4.1 - Restore discount_amount for OrderResponse.
• 2019-05-16 - 7.4.0 - API for getting qualified Vouchers and Campaigns.
• 2019-04-23 - 7.3.0 - Loyalties API, Rewards API.
• 2019-03-21 - 7.2.0 - Added ValidationRules assignments property to Voucher and Campaign responses, added Referral to CustomEvent, updated OrderResponse object with new properties.
• 2019-02-01 - 7.1.3 - Fixed deserialisation of CampaignResponse for newest API version.
• 2019-02-01 - 7.1.2 - Fixed deserialisation of VoucherResponse for newest API version.
• 2019-01-28 - 7.1.1 - Fixed release.
• 2019-01-25 - 7.1.0 - Extended OrderItem and OrderItemResponse with OrderItemProduct and OrderItemSKU.
• 2018-12-20 - 7.0.0 - Replaced Validation Rules with Business Validation Rules. Added API Verion v2018-08-01.
• 2018-12-04 - 6.2.0 - Added support for Order when listing vouchers.
• 2018-11-08 - 6.1.0 - Added support for advanced filters for Vouchers.
• 2018-11-08 - 6.0.9 - Fix Segment metadata entry builder.
• 2018-10-24 - 6.0.8 - Add discountAmount to OrderItemResponse.
• 2018-10-19 - 6.0.7 - Add amount to OrderItem.
• 2018-10-17 - 6.0.6 - Added ApplicableTo object to response of redeem/validate methods for vouchers and promotions.
• 2018-10-10 - 6.0.5 - Added ValidationRules in VoucherResponse object.
• 2018-09-09 - 6.0.4 - Added filtering vouchers by customer.
• 2018-05-21 - 6.0.3 - Added support for price when creating Price model.
• 2018-04-05 - 6.0.2 - Added support for unitType when creating Discount Voucher, removed obsolete VoucherType from validation response. Added class PromotionTierValidationResponse for proper promotion tier response mapping for promotion validation returned from voucherify.validations().validate(PromotionValidation) method.
• 2018-04-05 - 6.0.1 - Fix response class accessibility from package to public. OrderItem and OrderItemResponse classes now supports price field.
• 2018-04-04 - 6.0.0 - Response from Publish Voucher method now includes additional fields and structure introduced when using ApiVersion.V_2017_04_20. RollbackRedemptionResponse object uses VoucherResponse as voucher field instead of PublishVoucherResponse.
• 2018-04-03 - 5.3.2 - Add missing fields in Validation and Redeem responses, provide more examples related to percent discount voucher.
• 2018-04-03 - 5.3.1 - Add Order to Validation response.
• 2018-01-14 - 5.3.0 - API Version set in header by default, Events API, Orders API, added missing methods to Customers, Distributions and Campaigns modules.
• 2017-09-28 - 5.2.0 - Support for additional ValidationRules properties, additional examples, license info update.
• 2017-09-19 - 5.1.2 - Fix creating VoucherifyError from Retrofit errors, fix typo in RedeemVoucherBuilder.
• 2017-08-21 - 5.1.1 - Added metadata to VoucherValidationResponse.
• 2017-08-21 - 5.1.0 - Added metadata to VoucherValidation.
• 2017-08-18 - 5.0.1 - Fix for retrofit response body mapping.
• 2017-05-10 - 5.0.0 - Separate modules, general refactoring, updated models.
• 2017-04-21 - 4.2.0 - Moved validation to a separate module.
• 2017-04-20 - 4.1.0 - Added method to validate voucher.
• 2017-04-11 - 4.0.0 - Fixed redemptions list filter and response format.
• 2016-12-02 - 3.6.1 - Added gift balance. Enhanced utils to support gift vouchers.
• 2016-10-07 - 3.6.0 - Added a method to publish voucher.

See more in Changelog

License

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