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
- 8, 9, 10
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();
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();
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) {
}
});
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.
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
voucherify.vouchers().create(CreateVoucher createVoucher);
Check voucher object.
voucherify.vouchers().get(String code);
voucherify.vouchers().update(String code, VoucherUpdate update)
voucherify.vouchers().delete(String code, boolean force)
voucherify.vouchers().list(VouchersFilter filter);
voucherify.vouchers().enable(String code);
voucherify.vouchers().disable(String code);
voucherify.vouchers().addBalance(String code, AddBalance addBalance);
voucherify.vouchers().importVouchers(ImportVouchers importVouchers);
voucherify.vouchers().getQualified(QualificationContext context, QualifiedResourceFilter filter);
voucherify.vouchers().releaseSession(String code, String sessionKey);
Methods are provided within voucherify.campaigns().*
namespace.
voucherify.campaigns().create(CreateCampaign campaign);
voucherify.campaigns().addVoucher(String campaignName, AddVoucherToCampaign addVoucherToCampaing);
voucherify.campaigns().addVoucherWithCode(String campaignName, String code, AddVoucherToCampaign addVoucherToCampaing);
voucherify.campaigns().delete(String campaignName, DeleteCampaignParams params);
voucherify.campaigns().update(String name, UpdateCampaign updateCampaign);
voucherify.campaigns().importVouchers(String campaignName, String campaignName, CampaignImportVouchers importVouchers);
voucherify.campaigns().getQualified(QualificationContext context, QualifiedResourceFilter filter);
Methods are provided within voucherify.distributions().*
namespace.
voucherify.distributions().publish(PublishVoucher publishVoucher);
voucherify.distributions().createExport(CreateExport createExport);
voucherify.distributions().getExport(String id);
voucherify.distributions().deleteExport(String id);
voucherify.distributions.list()
voucherify.distributions.list(ListPublicationsFilter filter)
Methods are provided within voucherify.validations().*
namespace.
voucherify.validations().validate(String code, VoucherValidation voucherValidation);
voucherify.validations().validate(PromotionValidation promotionValidation);
Methods are provided within voucherify.redemptions.()*
namespace.
- Redeem Voucher
- Redeem Promotion
- List Redemptions
- Get Voucher's Redemptions
- Get Redemption
- Rollback Redemption
voucherify.redemptions().redeem(String code, RedeemVoucher redeemVoucher);
voucherify.redemptions().redeem(String id, RedeemPromotion redeemPromotion);
voucherify.redemptions().list(RedemptionsFilter filter);
voucherify.redemptions().getForVoucher(String code);
voucherify.redemptions().get(String id);
voucherify.redemptions().rollback(String id, String reason, RollbackRedemption rollbackRedemption);
Check redemption rollback object.
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
voucherify.customers().create(Customer customer);
Check customer object.
voucherify.customers().get(String id);
voucherify.customers().update(Customer customer);
voucherify.customers().update(List<Customer> customers);
voucherify.customers().delete(String id);
voucherify.customers.list()
voucherify.customers.list(CustomersFilter filter)
voucherify.customers().updateCustomerConsents(String customerId, Map<String, Boolean> consents);
Methods are provided within voucherify.orders.*
namespace.
voucherify.orders().create(CreateOrder order)
Check the order object.
voucherify.orders().get(String orderId)
voucherify.orders().update(UpdateOrder order)
voucherify.orders().list()
voucherify.orders().list(OrdersFilter filter)
voucherify.rewards().create(reward);
voucherify.rewards().get(id);
voucherify.rewards().update(id, reward);
voucherify.rewards().list(params);
voucherify.rewards().delete(id);
voucherify.rewards().listAssignments(reward_id, query);
voucherify.rewards().createAssignment(reward_id, assignment);
voucherify.rewards().updateAssignment(reward_id, assignment_id, assignment);
voucherify.rewards().deleteAssignment(reward_id, assignment_id);
voucherify.loyalties().list(filter);
voucherify.loyalties().create(loyalty);
voucherify.loyalties().get(id);
voucherify.loyalties().update(id, loyalty);
voucherify.loyalties().delete(id, params);
voucherify.loyalties().listRewardAssignments(loyalty_id, query);
voucherify.loyalties().createRewardAssignment(loyalty_id, assignment);
voucherify.loyalties().updateRewardAssignment(loyalty_id, assignment_id, assignment);
voucherify.loyalties().deleteRewardAssignment(loyalty_id, assignment_id);
voucherify.loyalties().listEarningRules(loyalty_id, query);
voucherify.loyalties().createEarningRules(loyalty_id, earning_rule);
voucherify.loyalties().updateEarningRule(loyalty_id, earning_rule_id, earning_rule);
voucherify.loyalties().deleteEarningRule(loyalty_id, earning_rule_id);
voucherify.loyalties().listMembers(loyalty_id, query);
voucherify.loyalties().addMember(loyalty_id, member);
voucherify.loyalties().getMember(loyalty_id, member_id);
voucherify.loyalties().getMember(member_id);
voucherify.loyalties().redeemReward(loyalty_id, member_id, add_balance);
voucherify.loyalties().addLoyaltyCardBalance(loyalty_id, member_id, redeem_reward);
voucherify.loyalties().addLoyaltyCardBalance(member_id, redeem_reward);
voucherify.loyalties().getMembersLoyaltyTier(member_id);
voucherify.loyalties().getMemberActivities(String loyalty_id, String member_id);
voucherify.loyalties().getMemberActivities(String member_id);
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
voucherify.products().create(Product product);
Check product object.
voucherify.products().get(String id);
voucherify.products().update(Product product);
voucherify.products().update(List<Product> products);
voucherify.products().delete(String id, DeleteProductParams params);
voucherify.products().list(ProductsFilter filter);
voucherify.products().createSKU(String productId, SKU sku);
Check SKU object.
voucherify.products().getSKU(String productId, String skuId);
voucherify.products().updateSKU(String product_id, SKU sku);
voucherify.products().deleteSKU(String productId, String skuId, DeleteSKUParams params);
voucherify.products().listSKU(String productId)
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
voucherify.validationRules().create(CreateBusinessValidationRule rules);
voucherify.validationRules().get(String id);
voucherify.validationRules().update(UpdateBusinessValidationRule rule);
voucherify.validationRules().list(BusinessValidationRuleFilter filer);
voucherify.validationRules().delete(String id);
voucherify.validationRules().createAssignment(String ruleId, CreateBusinessValidationRuleAssignment assignment);
voucherify.validationRules().listAssignments(String ruleId, BusinessValidationRuleAssignmentFilter filer);
voucherify.validationRules().delete(String ruleId, String assignmentId);
Methods are provided within voucherify.segments().*
namespace.
voucherify.segments().create(Segment segment);
voucherify.segments().get(String id);
voucherify.segments().delete(String id);
Methods are provided within voucherify.promotions().*
namespace.
- Create Promotion Campaign
- List Promotion Tiers
- Add Promotion Tier
- Update Promotion Tier
- Delete Promotion Tier
voucherify.promotions().create(CreatePromotionCampaign campaign);
voucherify.promotions().list(String campaignId);
voucherify.promotions().addPromotionTier(String tierId, Tier tier);
voucherify.promotions().updatePromotionTier(String tierId, Tier tier);
voucherify.promotions().deletePromotionTier(String tierId);
Methods are provided within voucherify.events.*
namespace.
Check customer object.
voucherify.events.track(CustomEvent customEvent)
Methods are provided within voucherify.asyncActions().*
namespace.
voucherify.asyncActions().get(String id);
voucherify.asyncActions().list(AsyncActionsFilter filter);
Methods are provided within voucherify.consents().*
namespace.
voucherify.consents().list();
Methods are provided within voucherify.stackables().*
namespace.
voucherify.stackables().redeem(RedeemStackableDiscount redeemStackableDiscount);
voucherify.stackables().validate(ValidateStackableDiscount validateStackableDiscount);
voucherify.stackables().rollbackRedemption(String parentRedemptionId);
Methods are provided within voucherify.qualifications.*
namespace.
voucherify.qualifications().checkEligibility(CheckEligibility checkEligibility)
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.
-
RollbackRedemptionResponse
class usesVoucherResponse
class as type forvoucher
field instead ofPublishVoucherResponse
-
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, thePublishVoucherResponse
object returned fromdistributions().publish
call will use older structure and new fields will be set to null. Developers using API version2017-04-05
can still safely access returned fields as before.
When API version2017-04-20
is used, thePublisherVoucherResponse
object returned fromdistributions().publish
call will use new structure and new fields will be set to proper values.
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.
-
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()
pl.rspective.voucherify.client
->io.voucherify.client
Most of the classes were moved under the model/moduleName
package. For example:
model/customer
andmodel/customer/response
(which contains only response classes)
In most cases invoking builders has changed in the following way:
new Customer.Builder()
->Customer.builder()
VoucherifyUtils.calculatePrice(BigDecimal basePrice, Voucher voucher, BigDecimal unitPrice)
VoucherifyUtils.calculateDiscount(BigDecimal basePrice, Voucher voucher, BigDecimal unitPrice)
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
try {
voucherify.vouchers().create(createVoucher);
} catch(VoucherifyError e) {
// Error handling
}
voucherify.vouchers().rx().create(createVoucher)
.doOnError(new Action1<VoucherifyError>() {
@Override
public void call(VoucherifyError error) {
// Error handling
}
});
voucherify.vouchers().async().create(createVoucher, new VoucherifyCallback<VoucherResponse>() {
@Override
public void onFailure(VoucherifyError error) {
// Error handling
}
});
Bug reports and pull requests are welcome on GitHub at https://github.com/rspective/voucherify-java-sdk.
- 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.
- Added
- 2023-09-21 - 11.1.6 - Added
VoucherValidationErrorResponse
toVoucherValidationResponse
. Thanks to tcalvoarroyo for issue request! - 2023-08-30 - 11.1.5 - Added mapping for
status
toresult
inRollbackRedemptionResponse
to correctly catch data returned by api in the new version wherestatus
property was added. - 2023-03-21 - 11.1.4 - Added
holder_id
to VoucherResponse. Addedstatus
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 toCreateOrder
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
toresult
inRollbackRedemptionResponse
to correctly catch data returned by api in the new version wherestatus
property was added. - 2021-10-25 - 11.0.0 - Dropped
VoucherifyUtils
. ChangedInteger
toLong
for amount/quantity/total alike fields. Added missingFIXED
discount type. Added discount/gift effects. ChangedCampaignType
->CampaignExtenstionType
,CampaginType
now contains actual campaign types likeREFERRAL_PROGRAM
. Aligned OkHttp3 version. - 2023-08-30 - 10.2.1 - Added mapping for
status
toresult
inRollbackRedemptionResponse
to correctly catch data returned by api in the new version wherestatus
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
toresult
inRollbackRedemptionResponse
to correctly catch data returned by api in the new version wherestatus
property was added. - 2021-07-16 - 10.1.0 - Add support for Async Actions
- 2023-08-30 - 10.0.1 - Added mapping for
status
toresult
inRollbackRedemptionResponse
to correctly catch data returned by api in the new version wherestatus
property was added. - 2020-10-14 - 10.0.0 - Drop old versions usage. Changed properties type from
Integer
toLong
in some classes. Addcampaign
andcampaign_id
in Voucher validation response. - 2023-08-30 - 9.1.2 - Added mapping for
status
toresult
inRollbackRedemptionResponse
to correctly catch data returned by api in the new version wherestatus
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
The SDK is available as open source under the terms of the MIT License.