Developer Documentation

Issue bulk reward

post https://{host}/api_gateway/rewards/core/v1/user/rewards/issue?username=&skip_validation=true

This API is used to issue multiple rewards to the user based on mobile number/ email Id.

While issuing bulk rewards,

  1. The intouch points required to purchase the rewards are summed up and isRedeemable call checks if the customer has enough points or not.

    1. If the customer has enough points, then all the rewards in the issue bulk call are issued in a single shot
    2. If the customer doesn't have enough points, then the issue bulk call is failed and no reward is issued.

  2. If the isRedeemable call is successful, then the system will issue the rewards to the user.

    1. Let's say, one reward is coupon, another is cart promotion in the request payload. Coupon is issued but cart promotion issual failed, this can happen and the coupon will be issued. Here in this case, partial issual will be successful.

❗️

Issuing reward that was created for a customer segment

If you want to issue a reward created for a specific customer segment, the user receiving the reward must belong to the segment or partition to which the reward is attached.

👍

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 .

If either of the user_group2_primary_user_id or user_group2_id or user_group2_external_id is not null, the transaction will be treated as group loyalty redemption and GROUP_LOYALTY_REDEMPTION will be set to true for transaction

Prerequisites

  • Authentication: Basic or OAuth authentication
  • Default access group

Resource information

URI/api_gateway/rewards/core/v1/user/rewards/issue?username={store}&skip_validation=true
HTTP MethodPOST
PaginationNo
Batch supportNo
Rate limit informationNone

API endpoint example

https://eucrm.cc.capillarytech.com/api_gateway/rewards/core/v1/user/rewards/issue?username=swati&skip_validation=true

Request query parameters

ParameterData TypeDescription
Username*StringUsername name of the store.
skip_validationBooleanA validation code is used to redeem points for the transaction. skip_validation is set to true as brands configured in Marvel bypass validation code.

Request body parameters

ParameterData TypeDescription
mobile\StringMobile phone number of the customer. Any of the identifiers is mandatory.
Email IDStringEmail ID of the customer. Any of the identifiers is mandatory.
External IDStringExternal ID of the customer. Any of the identifiers is mandatory.
brandStringBrand associated with the transaction.
transactionNumberStringUnique identifier for the transaction.
programIdIntegerThe ID of the program associated with the promotion.
notesStringA string used to store or represent additional information.
quantity*IntegerQuantity of the specified reward. This is applicable for rewards with payment config CONV_RATIO only and should have a value greater than one. For more information and various examples, refer to the documentation here.
Note: If the quantity is entered with decimals, the system will not consider the decimal part. For example, if you enter the value 1.56, the system will disregard the .56, and the value will be treated as 1.
rewardsArrayArray of rewards associated with the transaction.
rewardIdIntegerUnique identifier for a reward.
paramsStringParams acts as a key that holds additional information or configuration details as a JSON object.
paymentConfigObjectPayment configuration details for the reward.
Note: The payment config ID is mandatory if rewards are created with a payment configuration block. This applies when multiple payment configurations are defined for a single reward.. It is not recommended to use Payment Config for single payment config as it will break the flow when rewards need to be issued from loyalty workflows/ loyalty promotions/ journeys/ campaigns.
idIntegerUnique identifier for the payment configuration. (id can be obtained from this API)
customFieldsObjectThe list of custom fields associated with the reward issued to the customer. A custom field allows you to add extra information related to the reward.
You can add the custom field in the issue reward call once the custom field is created using the create custom field API .
fulfillmentDetailsObjectThe list of fulfillment details associated with the reward. There can be multiple stages that the reward undergoes, such as BOOKED, ON THE WAY, DELIVERED.
For example, A brand can have a fulfillment status as the Reward is SHIPPED before delivering the reward to the customer.
You can create a fulfillment status using the Create fulfillment status API and use it in the issue reward call.
user_group2_primary_user_idStringUnique user ID of the primary member of the group associated with the rewards to be issued. Customer ID (user_group2_id) or User ID (user_group2_primary_user_id) or External ID (user_group2_external_id) ,any one of these three can be used. If any one of these is null, the transaction won't be considered a Group Loyalty Redemption.
{
    "mobile": "11223569865",
    "brand": "BUKL",
    "transactionNumber": 107,
    "programId": "626",
    "notes": "This is notes",
    "rewards": [
        {
            "rewardId": 239433,
            "quantity": 1,
            "customFields": {
                "issue-reward-1": "issue-reward-values"
            },
            "paymentConfig": {
                "id": 700
            },
            "fulfillmentDetails": {
                "status": "Order confirmed"
            }
        },
        {
            "rewardId": 239434,
            "quantity": 1,
            "paymentConfig": {
                "id": 701
            },
            "fulfillmentDetails": {
                "status": "Order confirmed"
            }
        }
    ],
    "userGroup2PrimaryUserId": 890
}

{
  "mobile": "919886022338",
  "brand": "marvel_automation",
  "transactionNumber": "Transaction-1716621508000",
  "rewards": [
    {
      "rewardId": 13649,
      "quantity": 40,
      "paymentConfig": {
            "id": 307,
            "points": 500
     }
    }
  ]
}

{
    "brand": "lekhanaBrand",
    "transactionNumber": "123456789",
    "rewards": [
        {
            "rewardId": 9252,
            "quantity": 1,
            "customFields": {
                "issue-reward-1": "issue-reward-values"
            },
            "fulfillmentDetails": {
                "status": "SHIPPED"
            }
        }
    ],
    "mobile": "916677777777"
}

{
    "mobile": "11223569865",
    "brand": "BUKL",
    "transactionNumber": "107",
    "rewards": [
        {
            "rewardId": 221441,
            "quantity": 2,
            "paymentConfig": {
                "id": 456
            }
        }
    ],
    "user_group2_primary_user_id":"11223569865"
}

{
    "mobile": "162651476021",
    "brand": "BUKL",
    "transactionNumber": 1719466915,
    "rewards": [
        {
            "rewardId": 153873,
            "quantity": 1,
            "paymentConfig": {
                "id": 34
            },
            "params": {
                "test": "test"
            }
        },
        {
            "rewardId": 225087,
            "quantity": 1
        }
    ]
}

{
    "mobile": "9988776655",
    "brand": "BUKL",
    "transactionNumber": "NeeTesttr11",
    "params": {
        "denomination": 100,
        "quantity": 1
    },
    "rewards": [
        {
            "rewardId": 225086,
            "quantity": 1
        },
        {
            "rewardId": 225087,
            "quantity": 1
        }
    ]
}

Response parameters

ParameterData TypeDescription
statusObjectGeneral status of the response.
successBooleanIndicates success status.
codeIntegerStatus code of the API call.
messageStringMessage describing the status.
rewardsArrayArray of rewards details.
statusObjectStatus of each individual reward.
successBooleanIndicates success status of the reward.
codeIntegerStatus code for the reward.
messageStringMessage describing the status of the reward.
rewardIdIntegerUnique identifier for the reward.
requestedQuantityIntegerQuantity of the reward requested.
pointsReferenceIdStringReference ID for points used.
intouchArrayArray of intouch details.
pointsRedeemedStringNumber of points redeemed.
couponCodeStringCoupon code provided.
codeExpiryStringExpiry date and time for the coupon code.
promotionsArrayArray of associated promotions.
vendorArrayArray of associated vendors.
paramsObjectThis is a set of parameters assigned to a reward.
{
    "status": {
        "success": true,
        "code": 200,
        "message": "Reward issued successfully"
    },
    "rewards": [
        {
            "status": {
                "success": true,
                "code": 200,
                "message": "Reward issued successfully"
            },
            "transactionId": 257735,
            "rewardId": 239433,
            "requestedQuantity": 1,
            "pointsReferenceId": null,
            "intouch": null,
            "promotions": [],
            "vendor": [
                {}
            ],
            "restrictions": null,
            "paymentConfig": {
                "paymentMode": "FREE",
                "id": 700
            },
            "fulfillmentDetails": {
                "status": "Order confirmed"
            },
            "customFields": null
        },
        {
            "status": {
                "success": true,
                "code": 200,
                "message": "Reward issued successfully"
            },
            "transactionId": 257736,
            "rewardId": 239434,
            "requestedQuantity": 1,
            "pointsReferenceId": null,
            "intouch": null,
            "promotions": [],
            "vendor": [
                {}
            ],
            "restrictions": null,
            "paymentConfig": {
                "paymentMode": "FREE",
                "id": 701
            },
            "fulfillmentDetails": {
                "status": "Order confirmed"
            },
            "customFields": null
        }
    ]
}

{
    "status": {
        "success": false,
        "code": 8010,
        "message": "Reward issued partially"
    },
    "rewards": [
        {
            "status": {
                "success": true,
                "code": 200,
                "message": "Reward issued successfully"
            },
            "rewardId": 13649,
            "requestedQuantity": 1,
            "pointsReferenceId": "jDgoKj",
            "intouch": null,
            "promotions": [],
            "vendor": [
                {
                    "voucher": "1510791",
                    "pointsRedeemed": "114"
                }
            ],
            "restrictions": null,
            "paymentConfig": {
                "paymentMode": "CONV_RATIO",
                "id": 307,
                "conversionRatio": 0.3500
            },
            "fulfillmentDetails": null,
            "customFields": null
        },
        {
            "status": {
                "success": false,
                "code": 12035,
                "message": "Payment Mode needs to be passed when multiple payment Payment Config Exists"
            },
            "rewardId": 14746,
            "requestedQuantity": 1,
            "pointsReferenceId": null,
            "intouch": null,
            "promotions": null,
            "vendor": null,
            "restrictions": null,
            "paymentConfig": null,
            "fulfillmentDetails": null,
            "customFields": null
        }
    ]
}

{
    "status": {
        "success": false,
        "code": 12016,
        "message": "Invalid payment mode passed."
    },
    "intouch": null,
    "promotion": null,
    "vendor": null,
    "paymentConfig": null,
    "fulfillmentDetails": null,
    "customFields": null
}

{
    "status": {
        "success": false,
        "code": 400,
        "message": "Invalid payment mode passed.,Payment configuration id is mandatory"
    }
}

{
    "status": {
        "success": false,
        "code": 8004,
        "message": "fail to issue reward as user 373971337 does not belong to group 124",
        "partnerError": {
            "codes": [
                "1620"
            ],
            "messages": [
                "user 373971337 does not belong to group 124"
            ]
        }
    },
    "rewards":null
    
}

{
    "status": {
        "success": false,
        "code": 8004,
        "message": "fail to issue reward as  points are not redeemable",
        "partnerError": {
            "codes": [
                "828"
            ],
            "messages": [
                "points redemption rules/configuration not allowing redemption"
            ]
        }
    },
    "intouch": null,
    "promotion": null,
    "vendor": null
}

{
    "status": {
        "success": false,
        "code": 8004,
        "message": "fail to issue reward as  points are not redeemable",
        "partnerError": {
            "codes": [
                "1632"
            ],
            "messages": [
                "group id/externalId/primary userId 381751178 passed is not valid"
            ]
        }
    },
    "intouch": null,
    "promotion": null,
    "vendor": null
}

Example: Issuing reward created for customer segment

Consider the following scenario:

RewardSegments and Partitions
r1{s1, p1}, {s2, p2}
r2{s1, p2}, {s2, p1}
r3{s1, p1}, {s3, p1}
r4No segments or partitions

User Segments and Partitions:

UserBelongs to Segments and PartitionsReward details
user1{s2, p1}, {s3, p2}Does not contain r1, r3; contains r2, r4
user2{s1, p1}Contains r1, r3, r4; does not contain r2
user3No segments or partitionsContains r4

Bulk Issuance Results:

UserBulk Issuance (r1, r2, r3, r4)Success/Failure
user1r1, r2, r3, r4r1 and r3 fail; r2 and r4 are issued
user2r1, r2, r3, r4r2 fails; r1, r3, and r4 pass
user3r1, r2, r3, r4r1, r2, and r3 fail; r4 passes

API-specific error codes

Error codeDescription
400Invalid payment mode passed. Payment configuration ID is mandatory. Invalid payment mode passed. Payment configuration ID is mandatory. if the paymentConfig block is defined in the body, then paymentId is mandatory.
3004Brand not found
8003fail to issue reward as Reward is disabled or not started yet or expired
8004fail to issue reward as points are not redeemable
8010Reward issued partially. This occurs when one of the rewards has multiple payment configurations mapped to it. For more information, refer to the documentation here.
12005Reward constraint evaluation failed. Request failed. Max limit for the DAYS is reached. Allowed limit is 15 For Level CUSTOMER
12016Invalid payment mode passed. Invalid payment mode passed. Whatever paymentId is passed in this API, the same should be mapped for the reward created.
12034User Doesn't Belong To Segment Partition Defined For Reward Segment
Language
Credentials
Basic
base64
:
URL
Click Try It! to start a request and see the response here!