Issue reward currency

This API allows you to manually issue points or alternate currencies to a customer or user group. You can issue reward currency for up to 10 users in bulk.

👍
Notes

For detailed information about our APIs and for hands-on testing, refer to the documentation on API Overview and a step-by-step guide in Make Your First API Call.

This API adheres to reward currency limits for points and alternate currencies. If a limit is set, the system will not issue points beyond that limit to the customer.

If a user returns the entire bill, the system revokes the reward currency (Loyalty program issued and manually issued) earned by the customer.

If a user returns a partial bill, the system automatically revokes the entire manually issued currency. It then re-evaluates the points earned from the Loyalty program based on the updated bill amount.

Prerequisites

Authentication: Basic Authentication
Access group resource: N/A

Resource information

Field	Value
URI	`/v2/customers/bulk/manualCurrencyAllocate`
HTTP Method	`POST`
Pagination	N/A
Batch support	Yes. Supports processing up to 10 reward currency issue requests in a single call.
Rate limit information	N/A

cURL example

curl --location 'https://eu.api.capillarytech.com/v2/customers/bulk/manualCurrencyAllocate' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Basic ****************************' \
--data '[
    {
        "orgId": 51135,
        "programId": 2568,
        "awardStrategyId": 108865,
        "expiryStrategyId": 109345,
        "promotionId": -1,
        "sourceValue": 1000,
        "eventName": "TransactionAdd",
        "eventSourceId": "2152328861",
        "currencyType": "PROMISED",
        "identifierType": "mobile",
        "identifierValue": "971249123481",
        "source":"INSTORE",
        "entityType":"CUSTOMER"
    }
]'

Request body parameters

Parameter	Data type	Description	Required
`orgId`	`Integer`	Unique identifier of the organisation. To retrieve the orgId, use the Get Org Details API.	Yes
`entityType`	`String`	Type of entity to issue the reward currency. Supported values: `CUSTOMER`, USERGROUP2`.	No
`identifierType`	`String`	Type of identifier for the customer. Required if `entityType` is "CUSTOMER". Supported values: `mobile`, `email`, `id`, `externalId`	No
`source`	`String`	Source of the user's account. Supported values: `FACEBOOK`, `WEB_ENGAGE`, `WECHAT`, `INSTORE`, `MARTJACK`, `TMALL`, `TAOBAO`, `JD`, `ECOMMERCE`, `WEBSITE`, `LINE`, `MOBILE_APP`, `ALL`, `MAPP_SDK`	No
`accountId`	`String`	ID of source. Provide this ID if the source is not `INSTORE`	No
`groupId`	`String`	Unique ID of the user group, required if `entityType` is `USERGROUP2`.	No
`identifierValue`	`String`	Value of the customer identifier. Required if `entityType` is `CUSTOMER`.	No
`programId`	`Integer`	Unique identifier of the program for which points are issued.	Yes
`awardStrategyId`	`Integer`	Unique identifier of the award strategy to be used, which defines how the issued reward currency is calculated. To get the `awardStrategyId`, also known as earn code, refer to the Viewing conditions configured for points section in the Points documentation.	Yes
`expiryStrategyId`	`Integer`	Unique identifier of the expiry strategy to be used, which defines when the issued reward currency expires. To get the `expiryStrategyId`, also known as expire code, refer to the Viewing conditions configured for points section in the Points documentation.	Yes
`sourceValue`	`Double`	Transaction amount on which points are calculated. Provide the value as `-1` if a fixed number of points is issued.	Yes
`eventName`	`String`	Type of event triggering the issual. Supported values: `TransactionAdd`, `TargetCompleted` `GenericEvent` (provide the specific event name instead of "GenericEvent")	Yes
`promotionId`	`Long`	Unique ID of a loyalty promotion. To associate the reward currency issual with a promotion, provide the `promotionId`, To retrieve the `promotionId`, use the Get Details of All Promotions API.	No
`currencyType`	`String`	Type of currency to be issued. Supported values: `REGULAR`, `PROMISED`.	No
`alternateCurrencyIdentifier`	`String`	Unique ID of the alternate currency that is generated when created.	No
`eventSourceId`	`String`	Identifier for the event source. Provide the identifier based on the `eventName` value: For `TransactionAdd`, this is the bill ID. For TargetCompleted`, this can be a streak, a target, or a unified target achieved ID.	Yes
`billLineItemId`	`Long`	Identifier for the specific bill line item, if applicable. Provide this value when `eventName` is `TransactionAdd`.	No
`sourceValueRoundingStrategy`	`String`	Strategy for rounding the source value. Supported values: `FLOOR`, `ACTUAL`, `ROUND`	No
`pointsRoundingStrategy`	`String`	Strategy for rounding the calculated points. Supported values: `FLOOR`, `ACTUAL`, `ROUND`	No

Request body

[
  {
    "eventName": "TransactionAdd",
    "currencyType": "REGULAR",
    "sourceValueRoundingStrategy": "FLOOR",
    "pointsRoundingStrategy": "FLOOR",
    "lookupParams": {
      "identifierType": "id",
      "entityType": "CUSTOMER",
      "source": "INSTORE",
      "identifierValue": "{{customerId}}"
    },
    "orgId": 100737,
    "programId": 973,
    "awardStrategyId": 13167,
    "expiryStrategyId": 11833,
    "sourceValue": -1,
    "eventSourceId": "888812915"
  }
]

[
  {
    "eventName": "TransactionAdd",
    "currencyType": "REGULAR",
    "sourceValueRoundingStrategy": "FLOOR",
    "pointsRoundingStrategy": "FLOOR",
    "lookupParams": {
      "identifierType": "id",
      "entityType": "CUSTOMER",
      "source": "INSTORE",
      "identifierValue": "{{customerId}}"
    },
    "orgId": 100737,
    "programId": 973,
    "awardStrategyId": 13167,
    "expiryStrategyId": 11833,
    "sourceValue": -1,
    "eventSourceId": "888812915",
    "alternateCurrencyIdentifier": "9DxGBP"
  }
]

[
  {
    "orgId": 100737,
    "programId": 973,
    "awardStrategyId": 12311,
    "expiryStrategyId": 11833,
    "sourceValue": -1,
    "eventName": "TransactionAdd",
    "eventSourceId": "888812915",
    "currencyType": "PROMISED",
    "lookupParams": {
      "identifierType": "id",
      "identifierValue": "{{customerId}}",
      "source": "INSTORE",
      "entityType": "CUSTOMER"
    }
  }
]

[
  {
    "eventName": "TransactionAdd",
    "currencyType": "PROMISED",
    "sourceValueRoundingStrategy": "FLOOR",
    "pointsRoundingStrategy": "FLOOR",
    "lookupParams": {
      "identifierType": "id",
      "entityType": "CUSTOMER",
      "source": "INSTORE",
      "identifierValue": "{{customerId}}"
    },
    "orgId": 100737,
    "programId": 973,
    "awardStrategyId": 12311,
    "expiryStrategyId": 11833,
    "sourceValue": -1,
    "eventSourceId": "888812915",
    "alternateCurrencyIdentifier": "9DxGBP"
  }
]

[
  {
    "eventName": "TransactionAdd",
    "currencyType": "REGULAR",
    "sourceValueRoundingStrategy": "FLOOR",
    "pointsRoundingStrategy": "FLOOR",
    "lookupParams": {
      "identifierType": "id",
      "entityType": "CUSTOMER",
      "source": "INSTORE",
      "identifierValue": "{{customerId}}"
    },
    "orgId": 100737,
    "programId": 973,
    "awardStrategyId": 11879,
    "expiryStrategyId": 11833,
    "sourceValue": 100,
    "eventSourceId": "888812915",
    "alternateCurrencyIdentifier": "9DxGBP"
  },
  {
    "orgId": 100737,
    "programId": 973,
    "awardStrategyId": 11879,
    "expiryStrategyId": 11833,
    "sourceValue": 100,
    "eventName": "TransactionAdd",
    "eventSourceId": "888853513",
    "currencyType": "REGULAR",
    "alternateCurrencyIdentifier": "9DxGBP",
    "lookupParams": {
      "identifierType": "id",
      "identifierValue": "564671435",
      "source": "INSTORE",
      "entityType": "CUSTOMER"
    }
  }
]

[
    {
        "orgId": 51186,
        "programId": 2649,
        "awardStrategyId": 111523,
        "expiryStrategyId": 111581,
        "promotionId": -1,
        "sourceValue": 5000,
        "eventName": "TransactionAdd",
        "eventSourceId": "2152312071",
        "currencyType": "REGULAR",
        "lookupParams": {  
            "identifierType": "mobile",
            "identifierValue": "919300000019",
            "entityType":"USERGROUP2",
            "groupId":61450
        }
    }
]

Response body parameters

Parameter	Datatype	Description
`total`	`Integer`	Total number of requests processed in the batch.
`success`	`Integer`	Number of successfully processed requests.
`failures`	`Integer`	Number of failed requests.
`data`	`Object`	An object containing detailed results for each processed request.
-`status`	`String`	Status of the individual request. Possible values: `SUCCESS` or `FAILED`.
-`entityId`	`Integer`	ID of the customer/entity for which points were allocated.
-`sideEffects`	`Object`	Details of the currency issual.
-- `entityType`	`String`	Type of entity the points are issued.
-- `rawAwardedPoints`	`Double`	Points awarded before rounding.
-- `awardedPoints`	`Integer`	Final points awarded after rounding.
-- `rawAwardedValue`
-- `awardedValue`
-- `alternateCurrencyIdentifier`
-- `alternateCurrencyName`
-- `type`	`String`	Type of reward currency issued. Possible values: `points`, `alternate_currency`
`warnings`	`Object`	Warnings encountered when processing, if any.

Response body

{
    "total": 1,
    "success": 1,
    "failures": 0,
    "data": [
        {
            "status": "SUCCESS",
            "entityId": 387979573,
            "sideEffects": [
                {
                    "entityType": "USER",
                    "rawAwardedPoints": 500.000,
                    "awardedPoints": 500,
                    "type": "points"
                }
            ]
        }
    ],
    "warnings": []
}

{
    "total": 1,
    "success": 1,
    "failures": 0,
    "data": [
        {
            "status": "SUCCESS",
            "eventLogId": 634634563,
            "entityId": 566135941,
            "sideEffects": [
                {
                    "entityType": "USER",
                    "rawAwardedValue": 200.000,
                    "alternateCurrencyIdentifier": "9DxGBP",
                    "alternateCurrencyName": "DocCoin",
                    "awardedValue": 200,
                    "type": "alternate_currency"
                }
            ]
        }
    ],
    "warnings": []
}

API Specific Error Codes

Code	Description	Reason
8136	Program with id not found	`programId` provided is invalid
8136	Award Strategy not found with id : <id number>	`awardStrategyId` provided is invalid
8136	Expiry strategy not found with id : : <id number>	`expiryStrategyId` provided is invalid
8136	Event not supported for Manual currency allocation, Supported events are [TransactionAdd, TargetCompleted, Behavioural events]	`eventName` provided is invalid or unsupported.
8139	Bill not found with id <id number>	`eventSourceId` provided is invalid.
8136	Alternate currency not found with provided identifier : <alternate currency id>	`alternateCurrencyIdentifier` provided is invalid