Developer Documentation

Deduct points and alternate currencies from user using userId

post https://{host}/v2/customers//negativePointsAdjustment

This API allows you to deduct reward currencies (points or alternate currencies) from a user using the userId . It is also referred to as the Manual Points Adjustment API.

Additionally, you can raise a request to enable configuration ALLOW_NEGATIVE_BALANCE_ON_RETURN that support negative points. For example, if the negative points configuration is enabled and the currently available points for a customer is 0, you can still deduct 100 points from a customer.

👍

Note

For detailed information about our APIs and for hands-on testing, refer documentation in API overview and step-by-step guide on making your first API call in Make your first API call .

Prerequisites

  • Authentication: Basic or OAuth authentication
  • Access to Points access group resource. For more information, see access group documentation.

Resource information

URIv2/customers/{userid}/negativePointsAdjustment
HTTP methodPOST
PaginationNA
Rate limitNA
Batch supportNA

API endpoint example

https://eu.api.capillarytech.com/v2/customers/{userid}/negativePointsAdjustment?source=INSTORE

Request path parameters

Field NameData TypeDescription
userId*IntegerUnique ID of the customer (customerId).
Note: When using userId as an identifier, request it within the path parameter.

Request query parameters

Field nameData typeDescription
sourceEnumSource in which the identifier is available. Supported values: INSTORE, MARTJACK, WECHAT, FACEBOOK , WEB_ENGAGE, INSTORE, TMALL, TAOBAO, JD, ECOMMERCE, WEBSITE, LINE, ALL.

Request body parameters

ParameterData typeDescription
pointsAwardedIdIntegerUnique ID of the awarded points.
NOTES:

- Provide the pointsAwardedRefType along with the pointsAwardedId.
- pointsAwardedId is an internally generated identifier assigned when points are awarded. This identifier cannot be retrieved through an API. Raise a ticket to the support team to obtain the pointsAwardedId.
pointsAwardedRefTypeEnumReference type for points awarded. Supported values: bill_regular, bill_promotions, line_item_regular, line_item_promotions, customer_promotions
promotionIdIntegerUnique identifier for the promotion
NOTE: Provide either promotionId or promotionIdentifier.
promotionIdentifierstringIdentifier for the promotion.
NOTE: Provide the programId along with the promotionIdentifier.
programIdIntegerUnique ID of the loyalty program associated with the promotion.
alternateCurrencyNameStringUnique name of the alternate currency.
Refer to the documentation on viewing alternate currencies to identify the alternate currency name.
pointCategoryTypesEnumPoints category to deduct for the user. Supported values:
REGULAR PROMISED and EXTERNAL_TRIGGER_BASED.

Note: Default value is REGULAR if the pointCategoryTypes is not provided.
Refer to the documentation for more information on points categories.
pointsToBeAdjusted*IntegerPoints to be deducted for the user. Provide a value greater than 0.
valueToBeAdjusted*IntegerAlternate currencies to be deducted for the user. Provide a value greater than 0.
reasonOfReturn*StringReason for the return of points.

Deducting points

{
    "pointCategoryTypes": "REGULAR",
    "pointsToBeAdjusted": "100.00",
    "reasonOfReturn": "Extra points were issued"
}

{
    "pointsAwardedId": 38768508,
    "pointsAwardedRefType": "bill_regular",
    "pointCategoryTypes": "REGULAR",
    "pointsToBeAdjusted": "10",
    "reasonOfReturn": "Extra points were issued"
}

{
    "promotionId": 79555,
    "pointsToBeAdjusted": "10",
    "pointCategoryTypes": "REGULAR",
    "reasonOfReturn": "Extra points were issued"
}

{
    "promotionIdentifier": "b86ca53f-4c5e-46d3-8d33-b61c4f49392c",
    "programId": 973,
    "pointCategoryTypes": "REGULAR",
    "pointsToBeAdjusted": "10",
    "reasonOfReturn": "Extra points were issued"
}

{
    "programId": 973,
    "pointCategoryTypes": "REGULAR",
    "pointsToBeAdjusted": "10",
    "reasonOfReturn": "Extra points were issued"
}

Deducting alternate currencies

{
    "pointsAwardedId": 38768508,
    "pointsAwardedRefType": "bill_regular",
    "alternateCurrencyName": "coins",
    "pointCategoryTypes": "REGULAR",
    "valueToBeAdjusted": "10",
    "reasonOfReturn": "Extra points were issued"
}

{
    "promotionId": 79555,
    "alternateCurrencyName": "coins",
    "pointCategoryTypes": "REGULAR",
    "valueToBeAdjusted": "10",
    "reasonOfReturn": "Extra points were issued"
}

{
    "promotionIdentifier": "b86ca53f-4c5e-46d3-8d33-b61c4f49392c",
    "programId": 973,
    "alternateCurrencyName": "coins",
    "pointCategoryTypes": "REGULAR",
    "valueToBeAdjusted": "10",
    "reasonOfReturn": "Extra points were issued"
}

{
    "programId": 973,
    "alternateCurrencyName": "coins",
    "pointCategoryTypes": "REGULAR",
    "valueToBeAdjusted": "10",
    "reasonOfReturn": "Extra points were issued"
}


{
    "pointsAwardedId": 38768508,
    "pointsAwardedRefType": "bill_regular",
  	"alternateCurrencyName": "coins",
  	"pointCategoryTypes": "REGULAR",
    "valueToBeAdjusted": "10",
    "reasonOfReturn": "Extra points were issued"
}

{
    "promotionId": 79555,
  	"alternateCurrencyName": "coins",
  	"pointCategoryTypes": "REGULAR",
    "valueToBeAdjusted": "10",
  	"reasonOfReturn": "Extra points were issued"
}

{
    "promotionIdentifier":"b86ca53f-4c5e-46d3-8d33-b61c4f49392c" ,
    "programId": 973,
  	"alternateCurrencyName": "coins",
  	"pointCategoryTypes": "REGULAR",
    "valueToBeAdjusted": "10",
  	"reasonOfReturn": "Extra points were issued"
}

{
    "programId": 973,
  	"alternateCurrencyName": "coins",
  	"pointCategoryTypes": "REGULAR",
    "valueToBeAdjusted": "10",
  	"reasonOfReturn": "Extra points were issued"
}

Response parameters

Field nameDescription
statusStatus of the operation. Possible values:
success: The operation was successful.
false: The operation was unsuccessful.
pointsAvailablePoints available for the customer after the deduction.
valueAvailableAlternate currencies available for the customer after the deduction.
messageNote for the point deduction operation.
warningsWarnings (if any).
{
    "status": "success",
    "pointsAvailable": "670.000",
    "message": "points deducted successfully for the user ",
    "warnings": []
}

{
    "status": "success",
    "valueAvailable": "80145.500",
    "message": "DocCoin deducted successfully for the user ",
    "warnings": []
}

API Error Codes

CodeDescriptionReason
8906decimal places passed: 3 is greater than the configured round decimals: 2 for programId: 973Decimal places are higher than configured decimals for the program.
8003Invalid sourceSource is invalid or incorrect.
8015Customer not found for the given identifiersIdentifier value is invalid or incorrect.
8013Lookup,Invalid identifier passedType of identifier is invalid or incorrect.
8907points to be deducted 101.54 is greater than available points for program and NegativeBalanceOnReturn config is disabled for org.Points to deduct is higher than the available points balance.
8888Points to be adjusted cannot be zeroPoints to deduct is zero.
8887Provide Program Id with Promotion IdentifierprogramId is not provided along with the promotionIdentifier
8874promotion id passed is invalidpromotionId provided is invalid or incorrect.
8877points awarded Id passed is invalidpointsAwardedIdprovided is invalid or incorrect.
9975Points awarded ref type is invalidpointsAwardedRefTypeprovided is invalid or incorrect.
8911No alternate currency with name coins found for programId in orgalternateCurrencyNameprovided is invalid or incorrect.
8882Reason for adjustment cannot be nullReason for return is not provided.
1218Customer not enrolled in loyalty program : customer not found for programId 97Customer is not enrolled in the loyalty program or the programId is invalid or incorrect.
Language
Credentials
Basic
base64
:
URL
Click Try It! to start a request and see the response here!