Issue points or alternate currencies to customers

This API allows you to manually issue reward currency to a customer or user group.

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

This API is similar to the issue goodwill points request API, but with more features and is recommended to use this API when issuing additional points to users.

FeatureGoodwill PointsManual Issue API
Transaction LinkNo direct link to a specific transaction.Directly linked to a specific transaction or target completion using an eventSourceId.
Revocation on ReturnPoints are not revoked when the bill is returned.Points are automatically revoked when the bill is returned.
ReportingAttribution against the transaction is not possible.Allows for accurate report attribution against the specific transaction.
👍

Note

Example request

curl --location 'https://eu.api.capillarytech.com/v2/customers/bulk/manualCurrencyAllocate' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Basic ****************************' \
--data '[
  {
    "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"
  }
]'
curl --location 'https://eu.api.capillarytech.com/v2/customers/bulk/manualCurrencyAllocate' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Basic ****************************' \
--data '[
  {
    "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"
  }
]'
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": 100737,
    "programId": 973,
    "awardStrategyId": 12311,
    "expiryStrategyId": 11833,
    "sourceValue": -1,
    "eventName": "TransactionAdd",
    "eventSourceId": "888812915",
    "currencyType": "PROMISED",
    "lookupParams": {
      "identifierType": "id",
      "identifierValue": "{{customerId}}",
      "source": "INSTORE",
      "entityType": "CUSTOMER"
    }
  }
]'
curl --location 'https://eu.api.capillarytech.com/v2/customers/bulk/manualCurrencyAllocate' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Basic ****************************' \
--data '[
  {
    "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"
  }
]'
curl --location 'https://eu.api.capillarytech.com/v2/customers/bulk/manualCurrencyAllocate' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Basic ****************************' \
--data '[
  {
    "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"
    }
  }
]'
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": 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
        }
    }
]'

Prerequisites

Make sure you have the right authentication and appropriate access control configured.

  • Access group resource: Write access to the points group resource. For more information on access control, see the access group documentation.
  • Authentication: Basic authentication details. For more information on authentication, see the Authentication documentation.

Rate limit

  • Demo and Testing Clusters: 1,000 requests per minute per API key
  • Other Organisations: The rate limit is brand-specific.

To modify the limit, create a ticket with the Capillary Product support team.

Header information

You can define certain attributes in the API header section.

Header NameDescription
Authentication/Authorisation TypeBasic Auth
Request / Content Typeapplication/json
Response Typeapplication/json

Body parameters

Parameter

Type

Description

Required

orgId

Integer

Unique identifier of the organisation. To retrieve the orgId, use the

Get Org Details

API.

Yes

lookupParams

Object

Object containing the identifier details of the user.

Yes

. entityType

String

Type of entity to issue the reward currency. Supported values: CUSTOMER, USERGROUP2.

Optional

. identifierType

String

Type of identifier for the customer. Required if entityType is "CUSTOMER". Supported values: mobile, email, id, externalId

Optional

. 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

Optional

. accountId

String

ID of source. Provide this ID if the source is not INSTORE

Optional

. groupId

String

Unique ID of the user group, required if entityType is USERGROUP2.

Optional

. identifierValue

String

Value of the customer identifier. Required if entityType is CUSTOMER.

Optional

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.

Optional

currencyType

String

Type of currency to be issued. Supported values: REGULAR, PROMISED.

Optional

alternateCurrencyIdentifier

String

Unique ID of the alternate currency that is generated when created.

Optional

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.

Optional

sourceValueRoundingStrategy

String

Strategy for rounding the source value. Supported values: FLOOR, ACTUAL, ROUND

Optional

pointsRoundingStrategy

String

Strategy for rounding the calculated points. Supported values: FLOOR, ACTUAL, ROUND

Optional

Example response

{
    "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": []
}

Response parameters

ParameterTypeDescription
totalIntegerTotal number of requests processed in the batch.
successIntegerNumber of successfully processed requests.
failuresIntegerNumber of failed requests.
dataObjectAn object containing detailed results for each processed request.
.statusStringStatus of the individual request. Possible values: SUCCESS or FAILED.
.entityIdIntegerID of the customer/entity for which points were allocated.
. sideEffectsObjectDetails of the currency issual.
.. entityTypeStringType of entity the points are issued.
.. rawAwardedPointsDoublePoints awarded before rounding.
.. awardedPointsIntegerFinal points awarded after rounding is applied.
.. rawAwardedValueDoublePoints awarded before rounding is applied.
.. awardedValueIntegerAlternate currency awarded after rounding is applied.
.. alternateCurrencyIdentifierStringUnique identifier of the alternate currency.
.. alternateCurrencyNameStringUnique name of the alternate currency.
.. typeStringType of reward currency issued. Possible values: points, alternate_currency
warningsObjectWarnings encountered when processing, if any.

Error codes

CodeDescriptionReason
8136Program with id not foundprogramId provided is invalid
8136Award Strategy not found with id : <id number>awardStrategyId provided is invalid
8136Expiry strategy not found with id : : <id number>expiryStrategyId provided is invalid
8136Event not supported for Manual currency allocation, Supported events are [TransactionAdd, TargetCompleted, Behavioural events]eventName provided is invalid or unsupported.
8139Bill not found with id <id number>eventSourceId provided is invalid.
8136Alternate currency not found with provided identifier : <alternate currency id>alternateCurrencyIdentifier provided is invalid
Language
Credentials
Basic
base64
:
URL
Click Try It! to start a request and see the response here!