v4.2.0: Loyalty Programs pending points & statistics, Introducing Loyalty customer inventory, customer profiles v2 integration dry runs

⚠️⚠️ Breaking Changes and Future Plans

We are using the OpenAPI Generator of the OpenAPITools project in order to generate all of our SDKs, including this one.

Unfortunately, the current status of the project implementation for JAVA client is not of the same philosophy as ours, with regard to amending optional query parameters (adding / removing / reordering):
We believe (and assume) that such amendments should not break the API consumers' operation calls, and are relying on that assumption while developing and implementing our APIs.

We are evaluating how to address the situation, and find a more robust and seamless approach to generate our Java SDK in the future.

While we are doing so, we wish to allow our SDK's consumers access to latest API changes and features, and therefore we will continue to publish versions to our SDK, including the current paradigm, which is breaking change on such changes to query parameters.

We are apologizing for the temporary inconvenience and will do our best to minimize such changes and take it into account while introducing those.
As well will we curate a list of those changes when they take place in the release notes, starting this release.
Please try to get yourself informed with those changes before updating your SDK version in your code base and make sure that the new version doesn't introduce breaking changes to your implementation.

Management API

getApplicationCustomers

ManagementApi apiInstance = new ManagementApi(defaultClient);
Integer applicationId = 56; // Integer | 
+ String integrationId = "integrationId_example"; // String | Filter results performing an exact matching against the profile integration identifier.
+ Integer pageSize = 56; // Integer | The number of items to include in this response. When omitted, the maximum value of 1000 will be used.
+ Integer skip = 56; // Integer | Skips the given number of items when paging through large result sets.
+ Boolean withTotalResultSize = true; // Boolean | When this flag is set, the result will include the total size of the result, across all pages. This might decrease performance on large data sets. With this flag set to true, hasMore will be be true whenever there is a next page. totalResultSize will always be zero. With this flag set to false, hasMore will always be set to false. totalResultSize will contain the total number of results for this query. 

- InlineResponse20012 result = apiInstance.getApplicationCustomers(applicationId);
+ InlineResponse20012 result = apiInstance.getApplicationCustomers(applicationId, integrationId, pageSize, skip, withTotalResultSize);
// ...

getApplicationSessions

ManagementApi apiInstance = new ManagementApi(defaultClient);
Integer applicationId = 56; // Integer | 
// ...
+ OffsetDateTime createdBefore = new OffsetDateTime(); // OffsetDateTime | Only return events created before this date
+ OffsetDateTime createdAfter = new OffsetDateTime(); // OffsetDateTime | Only return events created after this date
// ...

- InlineResponse20016 result = apiInstance.getApplicationSessions(applicationId, pageSize, skip, sort, profile, state, coupon, referral, integrationId, customerId);
+ InlineResponse20016 result = apiInstance.getApplicationSessions(applicationId, pageSize, skip, sort, profile, state, createdBefore, createdAfter, coupon, referral, integrationId);
// ...

getCampaigns

ManagementApi apiInstance = new ManagementApi(defaultClient);
Integer applicationId = 56; // Integer | 
// ...
+ Integer campaignGroupId = 56; // Integer | Filter results to campaigns owned by the specified campaign group ID.

- InlineResponse2002 result = apiInstance.getCampaigns(applicationId, pageSize, skip, sort, campaignState, name, tags, createdBefore, createdAfter);
+ InlineResponse2002 result = apiInstance.getCampaigns(applicationId, pageSize, skip, sort, campaignState, name, tags, createdBefore, createdAfter, campaignGroupId);
// ...

getCustomerProfile

ManagementApi apiInstance = new ManagementApi(defaultClient);
- Integer applicationId = 56; // Integer | 
Integer customerId = 56; // Integer | 

- ApplicationCustomer result = apiInstance.getCustomerProfile(applicationId, customerId);
+ ApplicationCustomer result = apiInstance.getCustomerProfile(customerId);
// ...

Integration API

getCustomerInventory

IntegrationApi apiInstance = new IntegrationApi(defaultClient);
String integrationId = "integrationId_example"; // String | The custom identifier for this profile, must be unique within the account.
Boolean profile = true; // Boolean | optional flag to decide if you would like customer profile information in the response
Boolean referrals = true; // Boolean | optional flag to decide if you would like referral information in the response
Boolean coupons = true; // Boolean | optional flag to decide if you would like coupon information in the response
+ Boolean loyalty = true; // Boolean | optional flag to decide if you would like loyalty information in the response

- CustomerInventory result = apiInstance.getCustomerInventory(integrationId, profile, referrals, coupons);
+ CustomerInventory result = apiInstance.getCustomerInventory(integrationId, profile, referrals, coupons, loyalty);
// ...

updateCustomerProfileV2

IntegrationApi apiInstance = new IntegrationApi(defaultClient);
- String customerProfileId = "customerProfileId_example"; // String | The custom identifier for this profile, must be unique within the account.
- NewCustomerProfile body = new NewCustomerProfile(); // NewCustomerProfile | 
+ String integrationId = "integrationId_example"; // String | The custom identifier for this profile, must be unique within the account.
+ CustomerProfileIntegrationRequestV2 body = new CustomerProfileIntegrationRequestV2(); // CustomerProfileIntegrationRequestV2 | 
+ Boolean runRuleEngine = true; // Boolean | Flag to indicate whether to run the rule engine (Defaults to false).
+ Boolean dry = true; // Boolean | Flag to indicate whether to skip persisting the changes or not (Will not persist if set to 'true'. Only used when 'runRuleEngine' is set to 'true').

- CustomerProfileUpdate result = apiInstance.updateCustomerProfileV2(customerProfileId, body);
+ IntegrationStateV2 result = apiInstance.updateCustomerProfileV2(integrationId, body, runRuleEngine, dry);
// ...

❗ Please Notice: All those additional optional parameters could be simply sent with null to represent the lack of them (instead of "" for String parameters or false for Boolean parameters)

Summary

Integration API

• Introduce loyalty flag in getCustomerInventory endpoint to retrieve also profile's loyalty programs subscription and stats upon querying the endpoint
• Introduce flags to control whether a customer profile update request v2 should be a "dry run" or force it to "run rule engine"

⚠️ Deprecation Notice: Integration API@v1 endpoints

This version also introduced the deprecation notices for Integration API@v1 endpoints:

• Update a Customer Session (V1)
• Update a Customer Profile (V1)

These endpoints will be flagged deprecated on 15.07.2021, meaning support for requests to these endpoints will end on that date. We will not remove the endpoints, and they will still be accessible for you to use.

We do encourage migrating to the correspondent v2 endpoints for easier and more granular integration, as well as new features support (See our developer docs section about API V2.0).

Loyalty Programs

Introduce Loyalty Program pending points, points that belong to the program's balance but will become active in the future:

• Introduce Loyalty Program setting to control default points' pending duration
• Introduce a couple of new attributes to communicate better a ledger's points status (pending, active, expired and spent)
• Introduce Loyalty Programs statistics endpoint to get a loyalty program stats snapshot

⚠️⚠️ Breaking Change: Loyalty Program points addition payload

This version also introduced the ability to set both loyalty points pending and validity durations.
In order to communicate these more clear, we have renamed the former expiryDuration attribute of LoyaltyPoints entity to validityDuration:

String programID = "1";
String integrationID = "Example_Profile";
LoyaltyPoints body = new LoyaltyPoints()
    .name("Some points with validity limitation")
    .points(new java.math.BigDecimal("42.42"))
-    .expiryDuration("48h"); // 2 days expiration limit
+    .validityDuration("48h"); // 2 days expiration limit

api.addLoyaltyPoints(programID, integrationID, body);

⚠️ Deprecation Notice: Loyalty Program Ledger's total property

Please note that we are deprecating the total property of the LoyaltySubLedger entity. In order to be more transparent and express better distinction between a customer's balance in a program (active, pending, and expired points).

We will remove this property in the next version of the SDK, please use the new totalActivePoints property instead.

Sandbox/Live Applications & Account Analytics

Applications now can be flagged as live or sandbox (available only via the web application):

• This can be seen via the sandbox attribute of the Application entity
• Account analytics now respect this separation and reports new data points: liveApplications, sandboxApplications and liveActiveCampaigns

Misc: OpenAPI Generator version upgrade

We have upgraded the OpenAPI Generator used to release this SDK from v4.2.3 to v4.3.1 which includes a few subtle improvements in the generated code, for full list of changes, please consult the release logs' under the JAVA section.

Considering the disadvantages mentioned above, we are contemplating the future of our usage of the generator. So far it was serving most of our purposes well, and we will try to find a solution that will help us keep using it.

We will keep updating about the topic in this Repository as well as in our Developer Docs website.