v2.4.0: Customer Inventory Enhancements, Referral Updates and Import Endpoints

Summary

• Management API
  • Expose Import Endpoints
  • Introduce updateReferral Endpoint
• Integration API
  • Extended Customer Inventory Endpoint
  • A reminder of The Deprecation Notice: Integration API@v1 endpoints

Management API

Expose import endpoints as integral part of the SDK

All of our CSV import endpoints are accessible via the Web Application from the corresponding entity pages (refer to our Help Center for an example regarding Coupons).

Now these are also available endpoints as part of the SDK (links to our developer docs):

• Coupons Import
• Referrals Import
• Loyalty Points Import
• Giveaway Codes Import

Example code snippet demonstrating import coupons using a CSV file:

// ...preparing api client...
// An example could be seen at the repository's README file: https://github.com/talon-one/talon_go#management-api

referralsCSVFileContents, err := ioutil.ReadFile("/path/to/import-referrals.csv")
if err != nil {
	fmt.Printf("Error occurred while reading referrals csv: %s", err)
	// handle error / return / panic
	return
}

applicationId := 1
campaignId := 2

importSummary, _, err := managementClient.ManagementApi.
		ImportReferrals(managerAuthContext, applicationId, campaignId).
		UpFile(string(referralsFile)).
		Execute()

☝️ Back to Table of Contents

Introduce updateReferral Endpoint

We introduced an endpoint to update referrals in order to allow updating their scheduling, usage limits and custom attributes attached to them.

Please consult the endpoint reference in our developer docs for more details.

☝️ Back to Table of Contents

Integration API

Extended Customer Inventory Endpoint

We have added a couple of useful data points to our customer inventory to make integration even simpler.

The customer inventory endpoint now has the ability to return giveaway codes that belong to the profile in query.
In order to learn more about setting up such campaigns refer to this help center article and this developer docs tutorial.

We have also extended the coupons objects that are returned as part of the inventory and attached these two useful data-points to each returned coupon:

• profileRedemptionCount - holds the number of times the coupon was redeemed by the profile
• state - holds the state of the coupon and can be one of the below values:
  • active: reserved coupons that are neither pending nor used nor expired, and have a non-exhausted limit counter
  • used: coupons that are not pending, and have reached their redemption limit or were redeemed by the profile before expiration
  • expired: all non-pending, non-active, non-used coupons that were not redeemed by the profile
  • pending: coupons that have a start date in the future

☝️ Back to Table of Contents

⚠️ A reminder of The Deprecation Notice: Integration API@v1 endpoints

The deprecation was introduced already in the last release of the SDK, here is a kind reminder of 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 highly 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).

☝️ Back to Table of Contents

v2.3.1: fix go pkg cahce

Summary

We have noticed that our package version at https://pkg.go.dev is stuck behind on v1.4.0

• Run go modules tidying command
• Include vendor folder in the release
• Add a LICENSE file

v2.3.0: Multiple personal coupons creation endpoint, Loyalty and Referrals counters and Export Endpoints

Summary

• Management API
  • Introduce createCouponsForMultipleRecipients Endpoint
  • Expose Export Endpoints
  • Expose destroySession Endpoint
  • Introduce loyalty effects related and referrals creation counters
  • Breaking Change: Fix Campaign's DiscountCount type from int32 to float32
• Integration API
  • Improve Responses Transparency
  • Attach Loyalty Program ID in responses
  • A reminder of The Deprecation Notice: Integration API@v1 endpoints

Management API

Introduce createCouponsForMultipleRecipients Endpoint

An endpoint to allow creation of multiple coupons of the same configuration for up to 1,000 recipients at once.

☝️ Back to Table of Contents

Expose export endpoints as integral part of the SDK

All of our CSV export endpoints are accessible via the Web Application from the corresponding entity pages (refer to our Help Center for an example regarding Coupons).

Now these are also available endpoints as part of the SDK (links to our developer docs):

• Coupons Export
• Customer Sessions Export
• Effects Export
• Customer Loyalty Balance Export
• Customer Loyalty Ledgers Log Export

Example code snippet demonstrating consuming and printing the lines of a Customer Loyalty Balance Export using the encoding/csv package:

import (
	"context"
	"encoding/csv"
	"fmt"
	"strings"

	talon "github.com/talon-one/talon_go"
)

// ...preparing api client...
// An example could be seen at the repository's README file: https://github.com/talon-one/talon_go#management-api

export, _, err := managementClient.ManagementApi.
	ExportLoyaltyBalance(managerAuthContext, "1").
	Execute()

if err != nil {
	fmt.Printf("Error occurred while requesting ExportLoyaltyBalance: %s", err)
	// handle error / return / panic
	return
}

exportCSVReader := csv.NewReader(strings.NewReader(export))
records, err := exportCSVReader.ReadAll()
if err != nil {
	fmt.Printf("Error occurred while processing export CSV: %s", err)
	// handle error / return / panic
	return
}

fmt.Printf(">>`ExportLoyaltyBalance` records:\n%v", records)
// processing data using records ...

☝️ Back to Table of Contents

Expose destroySession Endpoint

Expose an existing endpoint to allow destroying a bearer token used in the context of the management-api.
This endpoint imitates a "logout" function and will make the attached token invalid for consequent requests.

☝️ Back to Table of Contents

Introduce loyalty effects related and referrals creation counters on Campaign entities

As part of the newly added budgets to campaigns (see relevant Help Center Section), we have added new counters on campaigns with regard to loyalty and referrals:

• CreatedLoyaltyPointsCount : Total number of loyalty points created by rules in this campaign
• CreatedLoyaltyPointsEffectCount : Total number of loyalty point creation effects triggered by rules in this campaign
• RedeemedLoyaltyPointsCount : Total number of loyalty points redeemed by rules in this campaign
• RedeemedLoyaltyPointsEffectCount : Total number of loyalty point redemption effects triggered by rules in this campaign
• ReferralCreationCount : Total number of referrals created by rules in this campaign

☝️ Back to Table of Contents

⚠️⚠️ Breaking Change: Fix Campaign's DiscountCount type from int32 to float32

Campaign's DiscountCount counter property was all along calculated as a floating decimal number by our system.

From this release on the returned values will be floating decimals and not cut-off integers:

- **DiscountCount** | Pointer to **int32** | Total amount of discounts redeemed in the campaign. | [optional]
+ **DiscountCount** | Pointer to **float32** | Total amount of discounts redeemed in the campaign. | [optional]

☝️ Back to Table of Contents

Integration API

Improve Responses Transparency

We are constantly extending and improving our integration API to provide our consumers with the best transparency regarding what exactly has happened within their requests.

We have added new data points to our v2 endpoints effects in order to improve the transparency we aspire for:

• If an effect was triggered because of a specific coupon the effect will now include this coupon ID, see Effect.md
• When a coupon is rejected we attach more details regarding the origin of the failure in RejectCouponEffectProps:
  • ConditionIndex - The index of the condition that caused the rejection of the coupon
  • EffectIndex - The index of the effect that caused the rejection of the coupon
  • Details - More details about the failure (if available)
• The same applies for referrals, when a referral is rejected we attach more details regarding the origin of the failure in RejectReferralEffectProps:
  • ConditionIndex - The index of the condition that caused the rejection of the referral
  • EffectIndex - The index of the effect that caused the rejection of the referral
  • Details - More details about the failure (if available)

Moreover, we have introduced a new response content, ruleFailureReasons, which when requested will attach to the response a collection containing all failed rules, with details (see the RuleFailureReason model) to help narrowing down failures and further debugging efforts to a specific single condition or effect that caused the failure.

One "gotcha" to keep in mind: in order to maximize transparency, and due to the fact that we do not know in advance which campaign in the application the request targets, the list contains a collection of all failure reasons.

Meaning that, it might have "white noise" with data about failures that could be considered as "obvious" to the consumer. Therefore, we suggest always filtering the list by the campaign id that was expected to trigger and did not.

☝️ Back to Table of Contents

Attach Loyalty Program ID in responses

When the consumer requires that the response will contain the details of loyalty programs involved in processing the requests, we now attach the identifier of the loyalty program to the returned LoyaltyProgramLedgers models.

The idea behind attaching the identifier is to help streamline further potential requests to our Management API with regard to details about a Loyalty Program, for example getLoyaltyStatistics or getLoyaltyPoints, that require the program identifier as part of the URI of the endpoint.

☝️ Back to Table of Contents

⚠️ A reminder of The Deprecation Notice: Integration API@v1 endpoints

The deprecation was introduced already in the last release of the SDK, here is a kind reminder of 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 highly encourage migrating to the correspondent v2 endpoints for easier and more granular integration...

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

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:

loyaltyProgramID := "1"
profileIntegrationID := "Customer_Profile_ID"

body := talon.LoyaltyPoints{}
body.SetPoints(42.42)
body.SetName("Points that expire after 3 days")
- body.SetExpiryDuration("72h")
+ body.SetValidityDuration("72h")

res, err = managementClient.ManagementApi.
	AddLoyaltyPoints(managerAuthContext, loyaltyProgramID, profileIntegrationID).
	Body(body).
	Execute()

⚠️ 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

v2.1.1: Fix `LoyaltyLedgerEntry` parsing from API

• Fix LoyaltyLedgerEntry's type property values, failing to parse when retrieving values from the API
• Flag API operations that return total count in their name for better visibility

v2.1.0: Dry Runs & Coupons discount limits

• Introduce "dry runs" for Integration API endpoints (See more details below)
• Add support to retrieve coupons as part of requesting customer profile inventories
• Add support for setting the discountLimit when creating or editing coupons

You can read more about the concept and where this feature could apply in your integration and workflow in our developers documentation center: https://developers.talon.one/Integration-API/dry-requests

v2.0.0: Integration API V2

• Replace code generator to OpenAPITools [email protected]
• Add our new v2 integration api endpoint for customer sessions. Read more here: https://developers.talon.one/Getting-Started/APIV2
• Add v2-related management endpoints for managing AdditionalCosts

⚠️ Migration to v2.0.0 from prior versions

As part of migrating our code generation to a new, and more modernized one, a few minor changes needed to take place in the provided API of the library.

Please refer to the Migration Guide for the migration process.

v1.4.0

• Expose new profile inventory endpoint. Consult our developer docs for more information: https://developers.talon.one/Integration-API/API-Reference#getCustomerInventory
• Expose more attributes handling endpoints (create, update, get all)
• copyCampaignToApplications endpoint extended and now allows to override original campaign's description scheduling details and tags as part of the copy functionality. See parameters here: https://developers.talon.one/Management-API/API-Reference#copyCampaignToApplications

v1.3.0

• More filtering parameters when querying changes endpoint
• The full Coupon object is now returned as part of an integration response
• Support for new limit configuration of amount of give discount effects

v1.2.0

• Add ReferralRejectionReason object and integration response properties
• Add users emails notifications subscriptions
• Remove stale usedAt and locked properties from Webhooks and Attributes