Skip to content

Add token unit to redemption

Request

Add a new token unit to an existing redemption. Available to Admin and Business accounts.

Security
authJWT
Path
redemptionIdstringrequired
Bodyapplication/jsonrequired
tokenEntityIdstringrequired

Token entity id

tokenMetadataIncrementalIdnumber

Token metadata template ID. For ERC1155: becomes on-chain tokenId. For ERC721: lookup key for template to generate unique metadata.

amountnumberrequired

Amount of tokens to mint/transfer. For ERC721 this is typically 1, for ERC1155/ERC20 can be any quantity.

maxAmountnumber

Token unit max amount. Applies to MINT/EARN contexts only (e.g. campaign reward capping). Ignored for spend/transfer contexts such as redemption priceTokenUnits.

tokenIdnumberrequireddeprecated

Use Token entity id instead

curl -i -X POST \
  'https://docs.pers.ninja/_mock/swagger/redemptions/{redemptionId}/tokens' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "tokenId": 0,
    "tokenEntityId": "string",
    "tokenMetadataIncrementalId": 0,
    "amount": 0,
    "maxAmount": 0
  }'

Responses

Token unit added to redemption

Bodyapplication/json
idstringrequired

Redemption id

ownerBusinessIdstring or nullrequired

Optional owner business ID. If set, this redemption belongs to a specific business. If null, the redemption is tenant-owned (system-level).

descriptionstring or nullrequired

Description of the redemption

namestring or nullrequired

Name of the redemption

imageUrlstring or nullrequired

Image url of the redemption

logoUrlstring or nullrequired

Logo URL for the redemption

termsstring or nullrequired

Terms and conditions for the redemption. Plain text or HTML. Multi-language handling at app level.

startDatestring or null, (date-time)required

Redemption start date

endDatestring or null, (date-time)required

Redemption end date

isActivebooleanrequired

Redemption is active

approvalobject(ApprovalDTO)required

Approval metadata for this redemption.

creditTokenAmountnumberrequired

The amount of credit tokens needed to redeem the redemption tokens

typeobject or null(RedemptionTypeDTO)required

The redemption type

priceTokenUnitsArray of objects(PriceTokenUnitSpec)required

Optional token units the user must transfer/burn as payment (ERC20, ERC1155, or ERC721). When set, these are transferred from user → business in addition to (or instead of) creditTokenAmount.

Default:[]
mechanismstring(RedemptionMechanism)required

Computed payment mechanism. Use this for rendering decisions (FREE = no payment, CREDIT = platform credit tokens, TOKEN_PAY = ERC20 transfer, TOKEN_BURN = ERC1155/ERC721 stamp/NFT, MIXED = credit + token). Never stored — derived from creditTokenAmount and priceTokenUnits.

Enum:"FREE""CREDIT""TOKEN_PAY""TOKEN_BURN""MIXED"
tokenUnitsArray of objects(TokenUnitDTO)required

The redemption tokens to be redeemed

ordernumber or nullrequired

The order of the redemption

supplyobject or null(ItemSupply)

The available supply of the redemption

maxPerUsernumberrequired

The maximum redemption per user

minUserStatusTypeobject or null(UserStatusTypeDTO)required

The minimum user status type to redeem the redemption

countryCodeRestrictionsobject

Country code restrictions as an array of strings (e.g., ["NOT_ES", "FR"])

Example:
[
  "NOT_ES",
  "FR"
]
tagsArray of stringsrequired

Redemption tags

Default:[]
contextobject

ERC721 only - Admin-defined dynamic context for AI prompts and trigger-based validity. Always applied to tokens minted from this redemption. Special keys: validityDate, validityEndDate, validityDuration for token expiry.

Example:
{
  "eventName": "Summer Sale",
  "validityDuration": 30
}
specificRequiredUserFieldsArray of stringsrequired

Required user fields specific to this redemption (beyond type defaults). Can include built-in field keys (email, firstName) or custom field UUIDs.

Default:[]
requiredUserFieldsArray of stringsrequired

All required fields for this redemption (type baseline + extras, deduplicated). Use this for validation.

Default:[]
specificBookingRequirementobject or null(BookingRequirementConfigDTO)

Redemption-specific booking requirement override. Set to override type default. Omit or null = use type default.

bookingRequirementobject or null(BookingRequirementConfigDTO)

Effective booking requirement (specific override ?? type default). Use this for validation. Null = no booking required.

includedobject or null

Optional data requested via include parameter. All include-based data lives here for consistency.

Response
{
  "id": "string",
  "ownerBusinessId": "string",
  "description": "string",
  "name": "string",
  "imageUrl": "string",
  "logoUrl": "string",
  "terms": "string",
  "startDate": "2019-08-24T14:15:22Z",
  "endDate": "2019-08-24T14:15:22Z",
  "isActive": true,
  "approval": {
    "status": "pending_approval",
    "approvedAt": "2019-08-24T14:15:22Z",
    "approvedBy": "string",
    "rejectionReason": "string"
  },
  "creditTokenAmount": 0,
  "type": {
    "name": "string",
    "description": "string",
    "imageUrl": "string",
    "baseRequiredUserFields": [],
    "bookingRequirement": { … },
    "id": 0
  },
  "priceTokenUnits": [],
  "mechanism": "FREE",
  "tokenUnits": [
    { … }
  ],
  "order": 0,
  "supply": {
    "available": 0,
    "total": 0
  },
  "maxPerUser": 0,
  "minUserStatusType": {
    "name": "string",
    "description": "string",
    "minTokenBalance": "string",
    "discountPercentage": 0,
    "imageUrl": "string",
    "eligibleTokenAddresses": [ … ],
    "tags": [ … ],
    "order": 100,
    "id": 0
  },
  "countryCodeRestrictions": [
    "NOT_ES",
    "FR"
  ],
  "tags": [],
  "context": {
    "eventName": "Summer Sale",
    "validityDuration": 30
  },
  "specificRequiredUserFields": [],
  "requiredUserFields": [],
  "specificBookingRequirement": {
    "type": "active",
    "eligibleBusinessIds": [ … ],
    "eligibleBusinessTypeIds": [ … ]
  },
  "bookingRequirement": {
    "type": "active",
    "eligibleBusinessIds": [ … ],
    "eligibleBusinessTypeIds": [ … ]
  },
  "included": {
    "redeemCount": 0,
    "ownerBusiness": { … },
    "requiredUserInfo": { … },
    "booking": { … }
  }
}