Deduct Points and Alternate Currencies from user group

Time	Status	User Agent
Retrieving recent requests…

This API deducts reward currencies (points or alternate currencies) from a user group or fleet ledger. Identify the group using any of the supported query parameters.

📘
Notes

For detailed information about our APIs and for hands-on testing, see API overview and Make your first API call.

You can enable ALLOW_NEGATIVE_BALANCE_ON_RETURN to allow the group points balance to go negative. For example, if the group has zero points, you can still deduct 100 points from it. To enable, raise a JIRA ticket to the Capillary product support team.

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

To deduct points from an individual customer instead of a group, see Deduct points and alternate currencies from user.

Example request

curl --location 'https://eu.api.capillarytech.com/v2/userGroup2/negativePointsAdjustment?externalId=fleet_group_123' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Basic <base64-encoded-credentials>' \
--data '{
    "pointsToBeAdjusted": "100.00",
    "programId": 3500,
    "reasonOfReturn": "store redemption"
}'

Prerequisites

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

Query parameters

Pass at least one of id, externalId, primaryUserId, or primaryUserIdentifierType + primaryUserIdentifierValue to identify the group.

Field	Type	Required	Description
`id`	Integer	Conditional	Identifier for the user group.
`externalId`	String	Conditional	External ID of the user group.
`primaryUserId`	Integer	Conditional	User ID of the primary member. The group associated with this member is resolved.
`primaryUserIdentifierType`	Enum	Conditional	Identifier type for looking up the primary member. Supported values: `mobile`, `email`, `externalId`, `userId`, `cardnumber`. Provide `primaryUserIdentifierValue` along with this parameter.
`primaryUserIdentifierValue`	String	Conditional	Value of the primary member identifier. Provide `primaryUserIdentifierType` along with this parameter.
`primaryUserSource`	Enum	Conditional	Source in which the primary member identifier is registered. Supported values: `INSTORE`, `WEB_ENGAGE`, `WECHAT`.
`primaryUserAccountId`	String	Conditional	Account ID for the primary member.

Body parameters

Field	Type	Required	Description
`pointsToBeAdjusted`	String	Required	Points to deduct from the group. Provide a value greater than 0. Applicable for points.
`reasonOfReturn`	String	Required	Reason for the points deduction.
`programId`	Integer	Optional	Unique ID of the loyalty program.
`valueToBeAdjusted`	String	Optional	Alternate currencies to deduct from the group. Provide a value greater than 0. Applicable for alternate currencies. Provide `alternateCurrencyName` along with this parameter.
`alternateCurrencyName`	String	Optional	Unique name of the alternate currency. See viewing alternate currencies.
`pointCategoryTypes`	Enum	Optional	Points category to deduct. Supported values: `REGULAR`, `PROMISED`, `EXTERNAL_TRIGGER_BASED`. Defaults to `REGULAR`. See points categories.
`pointsAwardedId`	Integer	Optional	Unique ID of the awarded points entry. Provide `pointsAwardedRefType` along with this parameter. This ID cannot be retrieved through an API — contact the Capillary support team to obtain it.
`pointsAwardedRefType`	Enum	Optional	Reference type for the awarded points entry. Supported values: `bill_regular`, `bill_promotions`, `line_item_regular`, `line_item_promotions`, `customer_promotions`.
`promotionId`	Integer	Optional	Unique identifier of the promotion. Provide either `promotionId` or `promotionIdentifier`, not both.
`promotionIdentifier`	String	Optional	External identifier of the promotion. Provide `programId` along with this parameter.

Example response

{
    "status": "success",
    "pointsAvailable": "490.000",
    "message": "points deducted successfully for the user ",
    "warnings": []
}

Response parameters

Field	Type	Description
`status`	String	Status of the deduction. Possible value: `success`.
`pointsAvailable`	String	Group points balance after the deduction.
`message`	String	Note for the deduction operation.
`warnings`	Array	Array of warning objects returned for non-fatal conditions. Empty on a successful deduction.

Error & warning codes

Code	Type	Description
1635	Error	No group identifier passed. Provide at least one of: `id`, `externalId`, `primaryUserId`, or `primaryUserIdentifierType`.
1632	Error	Group identifier doesn't resolve to a valid group.
8888	Error	Points to be adjusted can't be zero. Provide a value greater than 0.
8882	Error	Reason for adjustment can't be null.
8907	Error	Points to deduct exceed the available group points balance and `ALLOW_NEGATIVE_BALANCE_ON_RETURN` is disabled for the org.
8887	Error	`programId` not provided along with `promotionIdentifier`.
8874	Error	`promotionId` is invalid or incorrect.
8877	Error	`pointsAwardedId` is invalid or incorrect.
9975	Error	`pointsAwardedRefType` is invalid or incorrect.
8911	Error	`alternateCurrencyName` not found for the program in this org.
1218	Error	Group not enrolled in the loyalty program, or `programId` is invalid or incorrect.

Notes