Vendor Redemption API enables a brand to interact with third-party vendor systems for redeeming rewards. For example a brand wants to issue a gift card through a third-party vendor, ABC. This API provides the necessary details to the ABC vendor to process the reward redemption.

Example request

curl --location 'https://eu.api.capillarytech.com/api_gateway/rewards/core/v1/vendor/redemption/create' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Basic bWFkaHMjU2YQ==' \
--header 'Cookie: _cfuvid=n5.Z39H9xIs0DR219d1iOxrl73PaXk1ymkn3rClOfZ4-1764151707509-0.0.1.1-604800000' \
--data '{
    
    "brandId": 61,
    "vendorId": 430,
    "name": "UAT Vendor Redemption 6",
    "redemptionType": "INTOUCH_REWARD",
    
    "actions": [
        {
            "name": "add good will points",
            "execOrder": 1,
            "apiUrl": "https://crm-nightly-new.cc.capillarytech.com/v1.1/request/add?program_id=2851",
            "apiType": "POST",
            "apiHeaders": {
                "accept": "application/json",
                "Content-Type": "application/json",
                "Authorization": "Basic bHVjaWF1dG9fdGlsbF8xMDoyMDJjYjk2MmFjNTkwNzViOTY0YjA3MTUyZDIzNGI3MA=="
            },
             "apiBody" : "{\"transactionId_property\": \"${rewardTransactionId}\",\"customFields_property\": {\"customField_1_property\": \"${customfield_CF1}\"}, \"fulfillmentStatus_property\": \"${fulfillmentStatus}\"}",
            "contextKeys": {
                "voucher": "response.requests.request.get(0).id"
            }
        } 
    ],
    "responseKeys": [
        "voucher"
    ] 
}'

Pre-requisites

Authentication: Basic or OAuth authentication.
Default access group

Rate limit

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

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

Body parameters

Field	Type	Required	Description
brandId	Integer	Yes	The unique ID of the brand.
vendorId	String	Yes	The unique ID of the vendor.
name	String	Yes	The name defined by the brand for the vendor reward.
redemptionType	Enum	Yes	Defines the method by which a customer can redeem rewards.
actions	Array of Objects	Yes	An array containing action objects to be executed.
.name	String	Yes	The name of the action to be executed.
.execOrder	Integer	Yes	The execution order of the action.
.apiUrl	String	Yes	The URL to which the API request is made.
.apiType	String	Yes	The HTTP method to be used for the API request.
.apiHeaders	Object	Yes	An object containing the headers to be sent with the API request.
..accept	String	Optional	Indicates the expected response format.
..Content-Type	String	Optional	Indicates the format of the request body.
..Authorization	String	Optional	Defines the authentication credentials.
.apiBody	String	Optional	Defines the API body for the external API endpoint, allowing you to include additional data like custom fields, fulfillment status, and the reward transaction ID.
.contextKeys	Object	Yes	An object containing context keys for extracting values from the response.
..voucher	String	Optional	Defines a temporary variable to hold data from an API's response for use in subsequent API calls. Example: An API returns the discount code "SAVE20". You store this as "voucher" to pass into the next API to activate the code, and then another API to send it via SMS.
responseKeys	Array of Strings	Optional	An array of keys to be extracted from the API response for subsequent use.
.voucher	String	Optional	Defines what data is returned in the final response to the client. Example: After collecting "voucher", "status", and "transactionId", setting responseKeys to show just the voucher ensures the customer only sees "Your code SAVE20 is active," ensuring internal details are secure.

Example response

{
  "status": {
    "success": true,
    "code": 5012,
    "message": "Vendor redemption created successfully"
  },
  "redemption": {
    "id": 36987,
    "name": "UAT Vendor Redemption 6",
    "redemptionType": "INTOUCH_REWARD",
    "enabled": true,
    "lastUpdatedOn": 1764153001000,
    "lastUpdatedOnDateTime": "2025-11-26T10:30:01Z",
    "actionCount": 1,
    "createdBy": 75197372,
    "lastUpdatedBy": 75197372,
    "createdOn": 1764153001000,
    "createdOnDateTime": "2025-11-26T10:30:01Z"
  }
}

Response parameters

Field	Type	Description
success	Boolean	Indicates whether the API call was successful or not.
code	Integer	The code associated with the response.
message	String	A message providing details about the response.
id	Integer	The unique identifier for the redemption object.
name	String	The name associated with the redemption object.
redemptionType	Enum	The type of redemption.
enabled	Boolean	Indicates whether the redemption is currently enabled.
lastUpdatedOn	Date	Indicates the timestamp when the vendor redemption was updated. The timestamp is in Epoch time format.
actionCount	Integer	The count of the number of redemptions.
lastUpdatedBy	Long	The unique identifier of the user who last updated the vendor redemption record.
createdBy	String	The unique identifier of the user who created the vendor redemption.
createdOn	String	Indicates the timestamp when the vendor redemption was created. The timestamp is in Epoch time format.

Error codes

Code	Description
400	Invalid Request. Check the required parameters.
500	Unexpected error. An internal server error occurred. Retry the request after a short delay. If the issue persists, contact support with the request details.
5013	Unable to create vendor redemption.There was an issue during the creation process. Review your request payload for any errors or conflicts, and try again.