Java SDK for Voucherify - coupons, vouchers, promo codes
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
gradle/wrapper
src Filter vouchers by client Sep 9, 2018
.gitignore
.travis.yml
CHANGELOG.md
README.md
build.gradle
gradlew
gradlew.bat
settings.gradle
voucherify-java-sdk.png

README.md

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 | Products | Validation Rules | Segments | Promotions | Events | Utils


Setup

Grab via Maven:

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

or via Gradle

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

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

You can also specify which API version you want to use. Simply specify it when creating client:

VoucherifyClient.Builder()
            .apiVersion(ApiVersion.V_2017_04_05)
            .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

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

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

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

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.

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 Rules

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

Get Validation Rules

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

Update Validation Rules

voucherify.validationRules().update(ValidationRules rules);

Delete Validation Rules

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

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

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:

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

  • 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.