Deduct points and alternate currencies from user

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

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

👍
Notes

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 .

You can enable 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 are 0, you can still deduct 100 points from a customer. To enable, create a JIRA ticket to the Capillary Product Support team.

This API overrides the CONF_POINTS_RETURN_ENABLED configuration that prevents the reversal of earned points when a transaction is returned. Points are reversed even if the configuration is disabled.

Prerequisites

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

Resource information


URI	v2/customers/lookup/negativePointsAdjustment
HTTP method	POST
Pagination	NA
Rate limit	NA
Batch support	NA

API endpoint example

https://eu.api.capillarytech.com/v2/customers/lookup/negativePointsAdjustment?identifierName=mobile&identifierValue=9876543210&source=INSTORE

Request query parameters

Field name	Data type	Description
identifierName*	Enum	Identifier of the user. Supported values: `externalId`, `mobile`, `email`
identifierValue*	String	Value of the identifier.
source*	Enum	Source 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

Parameter	Data type	Description
pointsAwardedId	Integer	Unique 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 Capillary product support team to obtain the `pointsAwardedId`.
pointsAwardedRefType	Enum	Reference type for points awarded. Supported values: `bill_regular`, `bill_promotions`, `line_item_regular`, `line_item_promotions`, `customer_promotions`
promotionId	Integer	Unique identifier for the promotion NOTE: Provide either `promotionId` or `promotionIdentifier`.
promotionIdentifier	string	Identifier for the promotion. NOTE: Provide the `programId` along with the `promotionIdentifier`.
programId	Integer	Unique ID of the loyalty program associated with the promotion.
alternateCurrencyName	String	Unique name of the alternate currency. Refer to the documentation on viewing alternate currencies to identify the alternate currency name.
pointCategoryTypes	Enum	Points 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*	Integer	Points to be deducted for the user. Provide a value greater than 0. This is applicable for points.
valueToBeAdjusted*	Integer	Alternate currencies to be deducted for the user. Provide a value greater than 0. This is applicable for alternate currencies. Provide the `alternateCurrencyName` when using this parameter.
reasonOfReturn*	String	Reason 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"
}

Response parameters

Field name	Description
status	Status of the operation. Possible values: `success`: The operation was successful. `false`: The operation was unsuccessful.
pointsAvailable	Points available for the customer after the deduction.
valueAvailable	Alternate currencies available for the customer after the deduction.
message	Note for the point deduction operation.
warnings	Warnings (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

Code	Description	Reason
8906	decimal places passed: 3 is greater than the configured round decimals: 2 for programId: 973	Decimal places are higher than configured decimals for the program.
8003	Invalid source	Source is invalid or incorrect.
8015	Customer not found for the given identifiers	Identifier value is invalid or incorrect.
8013	Lookup,Invalid identifier passed	Type of identifier is invalid or incorrect.
8907	points 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.
8888	Points to be adjusted cannot be zero	Points to deduct is zero.
8887	Provide Program Id with Promotion Identifier	`programId` is not provided along with the `promotionIdentifier`
8874	promotion id passed is invalid	`promotionId` provided is invalid or incorrect.
8877	points awarded Id passed is invalid	`pointsAwardedId`provided is invalid or incorrect.
9975	Points awarded ref type is invalid	`pointsAwardedRefType`provided is invalid or incorrect.
8911	No alternate currency with name coins found for programId in org	`alternateCurrencyName`provided is invalid or incorrect.
8882	Reason for adjustment cannot be null	Reason for return is not provided.
1218	Customer not enrolled in loyalty program : customer not found for `programId` 97	Customer 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!