Replace Redemption Rule

1 min

PUT

https://api.b.preview.loyaltyservices.io/api/v3/redemption-rules/{code}

Fully replaces an unreleased redemption rule. All fields are overwritten with the values provided. Only rules in WORKING or READY workflow status may be replaced.

Path Parameters

codestringrequired

Body Parameters

bodyRedemptionRulerequired
- codestringrequired
  Example
  GOLD_REWARD_2026
  Description
  Unique code for the redemption rule. Cannot be changed after creation. The code of a deleted rule can be reused. Use findRedemptionRules to check whether a code already exists.
  Min Length
  1
  Max Length
  30
- groupCodestring
  Example
  GOLD_REWARD
  Description
  Groups rules that offer the same reward at different prices (personalized pricing). Choose any code up to 30 characters; use findRedemptionRules with this groupCode to see the rules already in a group. When a member redeems, the highest ranked rule in the group that the member qualifies for is the one presented, and the lowest ranked rule is shown as the reference (strike-through) price. Each rule in a group needs a unique rank.
  Min Length
  1
  Max Length
  30
- descriptionstringrequired
  Example
  Gold Member Exclusive Reward
  Description
  Display name for the redemption rule
  Min Length
  1
  Max Length
  100
- statusCodestring
  Description
  Rule status code. Valid values: use getCodesByType with codeType=RedemptionRuleStatus (A = Active, I = Inactive).
  Default
  A
- startDatestring<date>required
  Example
  2025-01-01
  Description
  First day the rule can be redeemed (YYYY-MM-DD). Required.
  Format
  date
- endDatestring<date>
  Example
  2050-12-31
  Description
  Last day the rule can be redeemed (YYYY-MM-DD). Leave empty for a rule with no end date.
  Format
  date
- redemptionTypeCodestringrequired
  Example
  I
  Description
  Type of redemption. Valid values: use getCodesByType with codeType=RedemptionType and read the notes on each code to see what each type is for. Cannot be changed after creation.
- rankinteger<int32>
  Example
  10
  Description
  Order of rules within a groupCode. Of the rules a member qualifies for, the highest rank is the one that applies, so give the best discount the highest rank and the base (full price) rule the lowest. Must be unique within the same groupCode; use findRedemptionRules with the groupCode to see ranks already used.
  Default
  1
  Format
  int32
- redeemableboolean
  Example
  true
  Description
  Whether members can redeem this rule
  Default
  true
- workflowStatusstring
  Description
  Authoring state. Valid values: use getCodesByType with codeType=RuleWorkflowStatus. WORKING is a draft that is still being edited; READY marks it ready to be released. A rule takes effect only after it is added to a data release and approved in Release Management in the Tally UI; this field does not release it.
  Default
  WORKING
- rawExpressionstring
  Description
  Expression defining which members qualify for the rule. If not set, every member qualifies. Use findExpressionBuilderConfig to see the fields and operators available for building expressions.
- faceValuenumber
  Example
  500
  Description
  Value of the item in USD, for gift cards and certificates. Leave empty for other types.
- dataReleaseinteger<int64>
  Description
  Managed by Release Management in the Tally UI. Leave unset when creating or editing a rule through the API.
  Format
  int64
- dataReleaseNamestring
  Example
  Rules Release 2025
  Description
  Managed by Release Management in the Tally UI. Leave unset when creating or editing a rule through the API.
  Max Length
  250
- dataReleaseItemStatusstring
  Example
  LIVE
  Description
  Managed by Release Management in the Tally UI. Leave unset when creating or editing a rule through the API. Valid values, if ever needed, use getCodesByType with codeType=DataReleaseItemStatus.
  Max Length
  50
- partnerCodestring
  Description
  Partner that fulfills the redemption, for partner-based redemptions. Valid values: use getManagedEntityOptions with entityType=Partner.
- minimumRoleRequiredinteger<int64>
  Description
  Id of the minimum user role allowed to redeem this rule. Valid values: use getUserRoles and pass the id of the chosen role. Leave empty for no role restriction.
  Format
  int64
- quantitiesRedemptionRuleQuantitiesrequired
  - pointCategoryCodestringrequired
    Example
    Points
    Description
    Point category (currency) deducted for the redemption. Valid values: use getCodesByType with codeType=PointCategory and pass the exact code returned, which may differ from the example. Supports custom currencies and DMX (data migration currency).
    Default
    POINTS
  - amountProvidedbooleanrequired
    Description
    Whether the amount of points is chosen at redemption (true, conversion rate rule) or fixed per item (false, uses pointsRequired)
    Default
    false
  - pointsRequirednumber
    Example
    5000
    Description
    Points required per item (required if amountProvided = false)
  - providedAmountRatenumber
    Example
    100
    Description
    Conversion rate used to work out the points deducted from the amount entered at redemption (required if amountProvided = true)
  - minimumQuantityinteger<int32>required
    Example
    1
    Description
    Minimum number of items per redemption
    Default
    1
    Format
    int32
  - maximumQuantityinteger<int32>
    Description
    Maximum redemption quantity per transaction
    Format
    int32
  - redeemIncrementinteger<int32>
    Example
    1
    Description
    Step size for quantity selection
    Format
    int32
- fulfillmentRedemptionRuleFulfillment
  - fulfillmentPathCodestringrequired
    Example
    COUPON
    Description
    How the redemption is delivered. Required. Valid values: use getCodesByType with codeType=FulfillmentPath and read the notes on each code. NOFULFILLMENT means nothing is delivered automatically; COUPON issues the coupon award in couponAward.
  - communicationTypeCodestring
    Example
    RedemptionConfirmationEmail
    Description
    Communication sent to the member when the redemption completes. Valid values: use findCommunicationTypes and pass the communication code.
  - couponAwardstring
    Description
    Coupon award to issue when fulfillmentPathCode is COUPON. There is no service yet to list valid coupon awards (TPB-41682); the value must be known.
  - redemptionRuleBonusCodestring
    Description
    Bonus rule awarded when the redemption completes. Valid values: use findBonusRules and pass the bonus rule code.
  - merchantstring
    Description
    Merchant identifier for partner-based fulfillment
    Max Length
    50
- contentstring
  Description
  ContentKey of the content item (GenericItem) shown with this rule. Content is created with createContent; there is no search or list service yet, so the key must be known (TPB-41715).
  Max Length
  50
- displayOnlineboolean
  Description
  Whether the rule is displayed in online channels (website, app)
  Default
  true
- providerDetailsmap<string, string>
  Example
```
{
  "catalogId": "CAT123",
  "sku": "SKU123-D-001"
}
```
  Description
  Provider-specific attributes for this rule. Present only when the rule's fulfillmentPathCode has a registered encoder and provider details have been set. Absent from the response when no provider details exist. Null values are not returned; the absence of this field indicates no provider details are stored.
- tagsstring[]
  Example
```
[
  "SUMMER_SALE",
  "VIP"
]
```
  Description
  Tag codes associated with this redemption rule

Responses

200Success

RedemptionRule
- idinteger<int64>
  Description
  System-generated ID for the redemption rule
  Format
  int64
- codestringrequired
  Example
  GOLD_REWARD_2026
  Description
  Unique code for the redemption rule. Cannot be changed after creation. The code of a deleted rule can be reused. Use findRedemptionRules to check whether a code already exists.
  Min Length
  1
  Max Length
  30
- groupCodestring
  Example
  GOLD_REWARD
  Description
  Groups rules that offer the same reward at different prices (personalized pricing). Choose any code up to 30 characters; use findRedemptionRules with this groupCode to see the rules already in a group. When a member redeems, the highest ranked rule in the group that the member qualifies for is the one presented, and the lowest ranked rule is shown as the reference (strike-through) price. Each rule in a group needs a unique rank.
  Min Length
  1
  Max Length
  30
- descriptionstringrequired
  Example
  Gold Member Exclusive Reward
  Description
  Display name for the redemption rule
  Min Length
  1
  Max Length
  100
- statusCodestring
  Description
  Rule status code. Valid values: use getCodesByType with codeType=RedemptionRuleStatus (A = Active, I = Inactive).
  Default
  A
- startDatestring<date>required
  Example
  2025-01-01
  Description
  First day the rule can be redeemed (YYYY-MM-DD). Required.
  Format
  date
- endDatestring<date>
  Example
  2050-12-31
  Description
  Last day the rule can be redeemed (YYYY-MM-DD). Leave empty for a rule with no end date.
  Format
  date
- redemptionTypeCodestringrequired
  Example
  I
  Description
  Type of redemption. Valid values: use getCodesByType with codeType=RedemptionType and read the notes on each code to see what each type is for. Cannot be changed after creation.
- rankinteger<int32>
  Example
  10
  Description
  Order of rules within a groupCode. Of the rules a member qualifies for, the highest rank is the one that applies, so give the best discount the highest rank and the base (full price) rule the lowest. Must be unique within the same groupCode; use findRedemptionRules with the groupCode to see ranks already used.
  Default
  1
  Format
  int32
- redeemableboolean
  Example
  true
  Description
  Whether members can redeem this rule
  Default
  true
- workflowStatusstring
  Description
  Authoring state. Valid values: use getCodesByType with codeType=RuleWorkflowStatus. WORKING is a draft that is still being edited; READY marks it ready to be released. A rule takes effect only after it is added to a data release and approved in Release Management in the Tally UI; this field does not release it.
  Default
  WORKING
- rawExpressionstring
  Description
  Expression defining which members qualify for the rule. If not set, every member qualifies. Use findExpressionBuilderConfig to see the fields and operators available for building expressions.
- faceValuenumber
  Example
  500
  Description
  Value of the item in USD, for gift cards and certificates. Leave empty for other types.
- dataReleaseinteger<int64>
  Description
  Managed by Release Management in the Tally UI. Leave unset when creating or editing a rule through the API.
  Format
  int64
- dataReleaseNamestring
  Example
  Rules Release 2025
  Description
  Managed by Release Management in the Tally UI. Leave unset when creating or editing a rule through the API.
  Max Length
  250
- dataReleaseItemStatusstring
  Example
  LIVE
  Description
  Managed by Release Management in the Tally UI. Leave unset when creating or editing a rule through the API. Valid values, if ever needed, use getCodesByType with codeType=DataReleaseItemStatus.
  Max Length
  50
- partnerCodestring
  Description
  Partner that fulfills the redemption, for partner-based redemptions. Valid values: use getManagedEntityOptions with entityType=Partner.
- minimumRoleRequiredinteger<int64>
  Description
  Id of the minimum user role allowed to redeem this rule. Valid values: use getUserRoles and pass the id of the chosen role. Leave empty for no role restriction.
  Format
  int64
- quantitiesRedemptionRuleQuantitiesrequired
  - pointCategoryCodestringrequired
    Example
    Points
    Description
    Point category (currency) deducted for the redemption. Valid values: use getCodesByType with codeType=PointCategory and pass the exact code returned, which may differ from the example. Supports custom currencies and DMX (data migration currency).
    Default
    POINTS
  - amountProvidedbooleanrequired
    Description
    Whether the amount of points is chosen at redemption (true, conversion rate rule) or fixed per item (false, uses pointsRequired)
    Default
    false
  - pointsRequirednumber
    Example
    5000
    Description
    Points required per item (required if amountProvided = false)
  - providedAmountRatenumber
    Example
    100
    Description
    Conversion rate used to work out the points deducted from the amount entered at redemption (required if amountProvided = true)
  - minimumQuantityinteger<int32>required
    Example
    1
    Description
    Minimum number of items per redemption
    Default
    1
    Format
    int32
  - maximumQuantityinteger<int32>
    Description
    Maximum redemption quantity per transaction
    Format
    int32
  - redeemIncrementinteger<int32>
    Example
    1
    Description
    Step size for quantity selection
    Format
    int32
- fulfillmentRedemptionRuleFulfillment
  - fulfillmentPathCodestringrequired
    Example
    COUPON
    Description
    How the redemption is delivered. Required. Valid values: use getCodesByType with codeType=FulfillmentPath and read the notes on each code. NOFULFILLMENT means nothing is delivered automatically; COUPON issues the coupon award in couponAward.
  - communicationTypeCodestring
    Example
    RedemptionConfirmationEmail
    Description
    Communication sent to the member when the redemption completes. Valid values: use findCommunicationTypes and pass the communication code.
  - couponAwardstring
    Description
    Coupon award to issue when fulfillmentPathCode is COUPON. There is no service yet to list valid coupon awards (TPB-41682); the value must be known.
  - redemptionRuleBonusCodestring
    Description
    Bonus rule awarded when the redemption completes. Valid values: use findBonusRules and pass the bonus rule code.
  - merchantstring
    Description
    Merchant identifier for partner-based fulfillment
    Max Length
    50
- contentstring
  Description
  ContentKey of the content item (GenericItem) shown with this rule. Content is created with createContent; there is no search or list service yet, so the key must be known (TPB-41715).
  Max Length
  50
- displayOnlineboolean
  Description
  Whether the rule is displayed in online channels (website, app)
  Default
  true
- providerDetailsmap<string, string>
  Example
```
{
  "catalogId": "CAT123",
  "sku": "SKU123-D-001"
}
```
  Description
  Provider-specific attributes for this rule. Present only when the rule's fulfillmentPathCode has a registered encoder and provider details have been set. Absent from the response when no provider details exist. Null values are not returned; the absence of this field indicates no provider details are stored.
- tagsstring[]
  Example
```
[
  "SUMMER_SALE",
  "VIP"
]
```
  Description
  Tag codes associated with this redemption rule
- allowedActionsRuleAllowedActions
  Description
  Write actions permitted on this rule in its current status, computed by the backend from the rule's workflow status. Caller entitlements are not considered; the corresponding operations still enforce their OAuth scopes. Clients should render an action only when its flag is true.
  - modifyboolean
    Description
    The rule may be fully edited (Working, Ready, or Approved status).
  - manageboolean
    Description
    The rule may receive limited edits such as dates and status (Approved, Published, or Live status).
  - adminboolean
    Description
    An administrator may edit the rule (Working, Ready, Approved, Published, Live, or Ended status).
  - deleteboolean
    Description
    The rule may be deleted (Working or Ready status).

400Bad request

ErrorResponse
- errorsValidationError[]
  Description
  List of errors
  - codestring
    Description
    Error code assigned to this violation
  - fieldNamestring
    Description
    Name of field that violated validation constraint (optional)
  - messagestring
    Description
    Internal message describing the error
  - messageParametersobject[]
    Description
    Error message parameters

401Unauthorized

403Forbidden

404Redemption Rule not found

500Internal error

curl

curl --request PUT \
     --url https://api.b.preview.loyaltyservices.io/api/v3/redemption-rules/{code} \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
     "code": "GOLD_REWARD_2026",
     "description": "Gold Member Exclusive Reward",
     "statusCode": "A",
     "startDate": "2025-01-01",
     "redemptionTypeCode": "I",
     "rank": 1,
     "redeemable": true,
     "workflowStatus": "WORKING",
     "quantities": {
     "pointCategoryCode": "POINTS",
     "amountProvided": false,
     "minimumQuantity": 1
     },
     "fulfillment": {
     "fulfillmentPathCode": "COUPON"
     },
     "displayOnline": true
     }'

ruby

require "uri"
require "json"
require "net/http"

url = URI("https://api.b.preview.loyaltyservices.io/api/v3/redemption-rules/{code}")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Put.new(url)
request["accept"] = "application/json"
request["content-type"] = "application/json"
request.body = JSON.dump({
   "code": "GOLD_REWARD_2026",
   "description": "Gold Member Exclusive Reward",
   "statusCode": "A",
   "startDate": "2025-01-01",
   "redemptionTypeCode": "I",
   "rank": 1,
   "redeemable": true,
   "workflowStatus": "WORKING",
   "quantities": {
      "pointCategoryCode": "POINTS",
      "amountProvided": false,
      "minimumQuantity": 1
   },
   "fulfillment": {
      "fulfillmentPathCode": "COUPON"
   },
   "displayOnline": true
})

response = https.request(request)
puts response.read_body

python

import requests
import json

url = "https://api.b.preview.loyaltyservices.io/api/v3/redemption-rules/{code}"

payload = json.dumps({
   "code": "GOLD_REWARD_2026",
   "description": "Gold Member Exclusive Reward",
   "statusCode": "A",
   "startDate": "2025-01-01",
   "redemptionTypeCode": "I",
   "rank": 1,
   "redeemable": True,
   "workflowStatus": "WORKING",
   "quantities": {
      "pointCategoryCode": "POINTS",
      "amountProvided": False,
      "minimumQuantity": 1
   },
   "fulfillment": {
      "fulfillmentPathCode": "COUPON"
   },
   "displayOnline": True
})
headers = {
   'accept': 'application/json',
   'content-type': 'application/json'
}

response = requests.request("PUT", url, headers=headers, data=payload)

print(response.text)

java

OkHttpClient client = new OkHttpClient().newBuilder()
   .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n  \"code\": \"GOLD_REWARD_2026\",\n  \"description\": \"Gold Member Exclusive Reward\",\n  \"statusCode\": \"A\",\n  \"startDate\": \"2025-01-01\",\n  \"redemptionTypeCode\": \"I\",\n  \"rank\": 1,\n  \"redeemable\": true,\n  \"workflowStatus\": \"WORKING\",\n  \"quantities\": {\n    \"pointCategoryCode\": \"POINTS\",\n    \"amountProvided\": false,\n    \"minimumQuantity\": 1\n  },\n  \"fulfillment\": {\n    \"fulfillmentPathCode\": \"COUPON\"\n  },\n  \"displayOnline\": true\n}");
Request request = new Request.Builder()
   .url("https://api.b.preview.loyaltyservices.io/api/v3/redemption-rules/{code}")
   .method("PUT", body)
   .addHeader("accept", "application/json")
   .addHeader("content-type", "application/json")
   .build();
Response response = client.newCall(request).execute();

200

// Success
{
  "id": "",
  "code": "GOLD_REWARD_2026",
  "groupCode": "GOLD_REWARD",
  "description": "Gold Member Exclusive Reward",
  "statusCode": "",
  "startDate": "2025-01-01",
  "endDate": "2050-12-31",
  "redemptionTypeCode": "I",
  "rank": 10,
  "redeemable": true,
  "workflowStatus": "",
  "rawExpression": "",
  "faceValue": 500,
  "dataRelease": "",
  "dataReleaseName": "Rules Release 2025",
  "dataReleaseItemStatus": "LIVE",
  "partnerCode": "",
  "minimumRoleRequired": "",
  "quantities": {
    "pointCategoryCode": "Points",
    "amountProvided": false,
    "pointsRequired": 5000,
    "providedAmountRate": 100,
    "minimumQuantity": 1,
    "maximumQuantity": "",
    "redeemIncrement": 1
  },
  "fulfillment": {
    "fulfillmentPathCode": "COUPON",
    "communicationTypeCode": "RedemptionConfirmationEmail",
    "couponAward": "",
    "redemptionRuleBonusCode": "",
    "merchant": ""
  },
  "content": "",
  "displayOnline": false,
  "providerDetails": "{\"catalogId\":\"CAT123\",\"sku\":\"SKU123-D-001\"}",
  "tags": [
    ""
  ],
  "allowedActions": {
    "modify": false,
    "manage": false,
    "admin": false,
    "delete": false
  }
}

400

// Bad request
{
  "errors": [
    {
      "code": "",
      "fieldName": "",
      "message": "",
      "messageParameters": [
        {}
      ]
    }
  ]
}

401

// Unauthorized

403

// Forbidden

404

// Redemption Rule not found

500

// Internal error