--- title: "List Customer's Redeemables" method: GET path: "/v1/customers/{customerId}/redeemables" tags: ["Customers"] --- # List Customer's Redeemables `GET /v1/customers/{customerId}/redeemables` Retrieves all the redeemables that have been assigned to the customer. To use this endpoint, you must have the following permissions: - Read Customers (`customers.details.read`) ## Query parameters - `limit` integer - `order` 'id' | '-id' - `starting_after_id` string - `filters` ParameterFiltersListCustomerRedeemables - `id` object — Unique redeemable holder ID, i.e. `rh_0e77502f84f0f4a6a8`. - `conditions` FilterConditionsString — Data filters used to narrow down the data records to be returned in the result. - `$in` string[] — Array of resource values that should be included in the results (multiple values). - `$not_in` string[] — Array of resource values that should be included in the results (multiple values). - `$is` string — Value is exactly this value (single value). - `$is_not` string — Results omit this value (single value). - `$has_value` string — Value is NOT null. The value for this parameter is an empty string. - `$is_unknown` string — Value is null. The value for this parameter is an empty string. - `$starts_with` string — Value starts with the specified string. - `$ends_with` string — Value ends with the specified string. - `$contains` string — Value includes the specified string. - `$not_contain` string — Value does NOT include the specified string. - `created_at` object — Timestamp representing the date and time when the customer redeemable was created. The value is shown in the ISO 8601 format. - `conditions` FilterConditionsDateTime — Data filters used to narrow down the data records to be returned in the result. - `$after` string, date-time — Value is after this date. The value for this parameter is shown in the ISO 8601 format. - `$before` string, date-time — Value is before this date. The value for this parameter is shown in the ISO 8601 format. - `$has_value` string — Value is NOT null. The value for this parameter is an empty string. - `$is_unknown` string — Value is null. The value for this parameter is an empty string. - `$more_than` integer — Value is more days ago before the current date and time, e.g. more than `10` days ago. - `$less_than` integer — Value is less days before the current date and time, e.g. less than `10` days ago. - `redeemable_id` object — Unique redeemable ID, e.g. `v_hS8JFl8S6lNcd1L69wLIoXgTio7eWEgk`. - `conditions` FilterConditionsString — Data filters used to narrow down the data records to be returned in the result. - `$in` string[] — Array of resource values that should be included in the results (multiple values). - `$not_in` string[] — Array of resource values that should be included in the results (multiple values). - `$is` string — Value is exactly this value (single value). - `$is_not` string — Results omit this value (single value). - `$has_value` string — Value is NOT null. The value for this parameter is an empty string. - `$is_unknown` string — Value is null. The value for this parameter is an empty string. - `$starts_with` string — Value starts with the specified string. - `$ends_with` string — Value ends with the specified string. - `$contains` string — Value includes the specified string. - `$not_contain` string — Value does NOT include the specified string. - `redeemable_object` object — Unique related object, i.e. `voucher`. - `conditions` object - `$in` string[] — Array of resource values that should be included in the results (multiple values). - `$not_in` string[] — Array of resource values that should be included in the results (multiple values). - `$is` 'voucher' — Value is exactly this value (single value). - `$is_not` 'voucher' — Results omit this value (single value). - `$has_value` string — Value is NOT null. The value for this parameter is an empty string. - `$is_unknown` string — Value is null. The value for this parameter is an empty string. - `$starts_with` string — Value starts with the specified string. - `$ends_with` string — Value ends with the specified string. - `holder_role` object — Holder role of the redeemable. Allowed values: `OWNER`, `REFEREE`, `REFERRER`. - `conditions` object - `$in` string[] — Array of resource values that should be included in the results (multiple values). - `$not_in` string[] — Array of resource values that should be included in the results (multiple values). - `$is` 'OWNER' | 'REFEREE' | 'REFERRER' — Value is exactly this value (single value). - `$is_not` 'OWNER' | 'REFEREE' | 'REFERRER' — Results omit this value (single value). - `$has_value` string — Value is NOT null. The value for this parameter is an empty string. - `$is_unknown` string — Value is null. The value for this parameter is an empty string. - `$starts_with` string — Value starts with the specified string. - `$ends_with` string — Value ends with the specified string. - `campaign_id` object — Unique campaign identifer, e.g. `camp_bfrwAVsP6Q1EM1ZjgHwheKYr`. - `conditions` FilterConditionsString — Data filters used to narrow down the data records to be returned in the result. - `$in` string[] — Array of resource values that should be included in the results (multiple values). - `$not_in` string[] — Array of resource values that should be included in the results (multiple values). - `$is` string — Value is exactly this value (single value). - `$is_not` string — Results omit this value (single value). - `$has_value` string — Value is NOT null. The value for this parameter is an empty string. - `$is_unknown` string — Value is null. The value for this parameter is an empty string. - `$starts_with` string — Value starts with the specified string. - `$ends_with` string — Value ends with the specified string. - `$contains` string — Value includes the specified string. - `$not_contain` string — Value does NOT include the specified string. - `campaign_type` object — Type of the campaign. Allowed values: `DISCOUNT_COUPONS`, `REFERRAL_PROGRAM`, `GIFT_VOUCHERS`, `LOYALTY_PROGRAM` - `conditions` object - `$in` string[] — Array of resource values that should be included in the results (multiple values). - `$not_in` string[] — Array of resource values that should be included in the results (multiple values). - `$is` 'LOYALTY_PROGRAM' | 'GIFT_VOUCHERS' | 'DISCOUNT_COUPONS' | 'REFERRAL_PROGRAM' — Value is exactly this value (single value). - `$is_not` 'LOYALTY_PROGRAM' | 'GIFT_VOUCHERS' | 'DISCOUNT_COUPONS' | 'REFERRAL_PROGRAM' — Results omit this value (single value). - `$has_value` string — Value is NOT null. The value for this parameter is an empty string. - `$is_unknown` string — Value is null. The value for this parameter is an empty string. - `$starts_with` string — Value starts with the specified string. - `$ends_with` string — Value ends with the specified string. - `voucher_type` object — Type of the voucher. Allowed values: `DISCOUNT_VOUCHER`, `GIFT_VOUCHER`, `LOYALTY_CARD`. - `conditions` object - `$in` string[] — Array of resource values that should be included in the results (multiple values). - `$not_in` string[] — Array of resource values that should be included in the results (multiple values). - `$is` 'GIFT_VOUCHER' | 'DISCOUNT_VOUCHER' | 'LOYALTY_CARD' — Value is exactly this value (single value). - `$is_not` 'GIFT_VOUCHER' | 'DISCOUNT_VOUCHER' | 'LOYALTY_CARD' — Results omit this value (single value). - `$has_value` string — Value is NOT null. The value for this parameter is an empty string. - `$is_unknown` string — Value is null. The value for this parameter is an empty string. - `$starts_with` string — Value starts with the specified string. - `$ends_with` string — Value ends with the specified string. - `junction` 'and' | 'or' — Logical Operator Between Filters. Filter by conditions set on the `junction` parameter indicating how the `conditions` should be accounted for in the query. An `AND` is an all-inclusive logical operator, meaning the `AND` operator displays a record if **ALL** the conditions separated by AND are TRUE, while an `OR` operator displays a record if **ANY** of the conditions separated by OR is TRUE. ## Response `200` The method returns redeemable(s) to which the given customer is assigned. - CustomersRedeemablesListResponseBody — List of customer's redeemables - `object` string, required — The type of the object represented by JSON. This object stores information about customer redeemables. - `data_ref` string, required — Identifies the name of the JSON property that contains the array of redeemables. - `data` CustomerRedeemable[], required — A dictionary that contains an array of redeemables. - `id` string, required — Unique redeemable holder identifier. - `created_at` string, date-time, required — Timestamp representing the date and time when the redeemable was assigned. The value is shown in the ISO 8601 format. - `redeemable_id` string, required — Identifier of the redeemable item. - `redeemable_object` string, required — Type of the redeemable. - `customer_id` string, required — Identifier of the customer. - `holder_role` 'OWNER' | 'REFERRER' | 'REFEREE', required — Role of the holder. - `campaign_id` string, nullable, required — Unique campaign identifier, assigned by Voucherify. - `campaign_type` 'LOYALTY_PROGRAM' | 'GIFT_VOUCHERS' | 'DISCOUNT_COUPONS' | 'PROMOTION' | 'REFERRAL_PROGRAM', nullable, required — Defines the type of the campaign. - `voucher_type` 'GIFT_VOUCHER' | 'DISCOUNT_VOUCHER' | 'LOYALTY_CARD', required — Defines the type of the voucher. - `redeemable` object, required — Detailed information about the customer's redeemable item - `type` string, required — Type of the redeemable. - `voucher` RedeemableVoucher, required — This is an object representing a voucher. - `id` string — Assigned by the Voucherify API, identifies the voucher. - `code` string — A code that identifies a voucher. Pattern can use all letters of the English alphabet, Arabic numerals, and special characters. - `campaign` string — A unique campaign name, identifies the voucher's parent campaign. - `campaign_id` string — Assigned by the Voucherify API, identifies the voucher's parent campaign. - `category` string, nullable — The value is null. - `category_id` string — Unique category ID assigned by Voucherify. - `categories` object[] — Contains an empty array. - `type` 'GIFT_VOUCHER' | 'DISCOUNT_VOUCHER' | 'LOYALTY_CARD' — Defines the type of the voucher. - `discount` union — Contains information about discount. - object - `type` 'AMOUNT', required — Defines the type of the voucher. - `amount_off` number, required — Amount taken off the subtotal of a price. Value is multiplied by 100 to precisely represent 2 decimal places. For example, a $10 discount is written as 1000. - `amount_off_formula` string — Formula used to dynamically calculate the discount. - `aggregated_amount_limit` integer — Maximum discount amount per order. - `effect` 'APPLY_TO_ORDER' | 'APPLY_TO_ITEMS' | 'APPLY_TO_ITEMS_PROPORTIONALLY' | 'APPLY_TO_ITEMS_PROPORTIONALLY_BY_QUANTITY' | 'APPLY_TO_ITEMS_BY_QUANTITY' - `is_dynamic` boolean — Flag indicating whether the discount was calculated using a formula. - object - `type` 'UNIT', required — Discount type. - `unit_off` integer — Number of units to be granted a full value discount. - `unit_off_formula` string — Formula used to dynamically calculate the number of units. - `effect` 'ADD_MISSING_ITEMS' | 'ADD_NEW_ITEMS' | 'ADD_MANY_ITEMS' | 'ADD_SAME_ITEMS' - `unit_type` string, required — The product deemed as free, chosen from product inventory (e.g. time, items). - `product` SimpleProductDiscountUnit - … - `sku` SimpleSkuDiscountUnit - … - `is_dynamic` boolean — Flag indicating whether the discount was calculated using a formula. - object - `type` 'UNIT', required — Discount type. - `effect` 'ADD_MANY_ITEMS' — Defines how the discount is applied to the customer's order. - `units` DiscountUnitMultipleOneUnit[], required - … - object - `type` 'PERCENT', required — Defines the type of the voucher. - `percent_off` number, required — The percent discount that the customer will receive. - `percent_off_formula` string — Formula used to dynamically calculate the discount. - `amount_limit` number — Upper limit allowed to be applied as a discount. Value is multiplied by 100 to precisely represent 2 decimal places. For example, a $6 maximum discount is written as 600. - `aggregated_amount_limit` integer — Maximum discount amount per order. - `effect` 'APPLY_TO_ORDER' | 'APPLY_TO_ITEMS' - `is_dynamic` boolean — Flag indicating whether the discount was calculated using a formula. - object - `type` 'FIXED', required — Defines the type of the voucher. - `fixed_amount` number, required — Sets a fixed value for an order total or the item price. The value is multiplied by 100 to precisely represent 2 decimal places. For example, a $10 discount is written as 1000. If the fixed amount is calculated by the formula, i.e. the `fixed_amount_formula` parameter is present in the fixed amount definition, this value becomes the **fallback value**. As a result, if the formula cannot be calculated due to missing metadata, for example, this value will be used as the fixed value. - `fixed_amount_formula` string — Formula used to dynamically calculate the discount. - `effect` 'APPLY_TO_ORDER' | 'APPLY_TO_ITEMS' - `is_dynamic` boolean — Flag indicating whether the discount was calculated using a formula. - `gift` object — Object representing gift parameters. Child attributes are present only if `type` is `GIFT_VOUCHER`. Defaults to `null`. - `amount` integer — Total gift card income over the lifetime of the card. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `$100.00`. - `subtracted_amount` integer — Total amount of subtracted credits over the gift card lifetime. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `$100.00`. - `balance` integer — Available funds. The value is multiplied by 100 to represent 2 decimal places. For example `10000 cents` for `$100.00`. `balance` = `amount` - `subtracted_amount` - `redemption.redeemed_amount`. - `effect` 'APPLY_TO_ORDER' | 'APPLY_TO_ITEMS' — Defines how the credits are applied to the customer's order. - `loyalty_card` object — Object representing loyalty card parameters. Child attributes are present only if `type` is `LOYALTY_CARD`. Defaults to `null`. - `points` integer — Total number of points added to the loyalty card over its lifespan. - `balance` integer — Points available for reward redemption. This is calculated as follows: `balance` = `points` - `expired_points` - `subtracted_points` - `redemption.redeemed_points`. - `next_expiration_date` string, date — The next closest date when the next set of points are due to expire. - `next_expiration_points` integer — The amount of points that are set to expire next. - `pending_points` integer — Shows the number of pending points that will be added to the loyalty card when they are activated automatically or manually. - `expired_points` integer — Shows the total number of expired points over the lifetime of the loyalty card. - `subtracted_points` integer — Shows the total number of subtracted points over the lifetime of the loyalty card. - `start_date` string, date-time — Activation timestamp defines when the code starts to be active in ISO 8601 format. Voucher is *inactive before* this date. - `expiration_date` string, date-time — Expiration timestamp defines when the code expires in ISO 8601 format. Voucher is *inactive after* this date. - `validity_timeframe` ValidityTimeframe — Set recurrent time periods when the earning rule is valid. For example, valid for 1 hour every other day.`start_date` **required** when including the `validity_timeframe`. - `duration` string — Defines the amount of time an earning rule will be active in ISO 8601 format. For example, an earning rule with a `duration` of `PT1H` will be valid for a duration of one hour. - `interval` string — Defines the intervening time between two time points in ISO 8601 format, expressed as a duration. For example, an earning rule with an `interval` of `P2D` will be valid every other day. - `validity_day_of_week` integer[] — Integer array corresponding to the particular days of the week in which the voucher is valid. - `0` Sunday - `1` Monday - `2` Tuesday - `3` Wednesday - `4` Thursday - `5` Friday - `6` Saturday - `validity_hours` ValidityHours — Determines the hours of validity, e.g. to create a happy hours scenario. - `daily` object[] — Defines the recurring period(s) when the resource is active. The periods should not overlap. - `start_time` string, time — Defines the starting hour of validity in the HH:mm format. The resource is *inactive before* this time. - `days_of_week` integer[] — Integer array corresponding to the particular days of the week in which the resource is valid. - `0` Sunday - `1` Monday - `2` Tuesday - `3` Wednesday - `4` Thursday - `5` Friday - `6` Saturday - `expiration_time` string, time — Defines the ending hour of validity in the HH:mm format. The resource is *inactive after* this time. - `active` boolean, nullable — A flag to toggle the voucher on or off. You can disable a voucher even though it's within the active period defined by the `start_date` and `expiration_date`. - `true` indicates an *active* voucher - `false` indicates an *inactive* voucher - `additional_info` string — An optional field to keep any extra textual information about the code such as a code description and details. - `metadata` object — The metadata object stores all custom attributes assigned to the code. A set of key/value pairs that you can attach to a voucher object. It can be useful for storing additional information about the voucher in a structured format. - `assets` VoucherAssets — Stores links to images of QR and barcode that correspond to an encrypted voucher code. - `qr` object — Stores Quick Response (QR) representation of encrypted code. - `id` string — Encrypted voucher code ID. - `url` string — URL to QR code *Optional:* Attach query parameters to base URL to customize the image of the encrypted voucher code. - `size`: integer value from `1` to `100` - `format`: string, either `png` (default) or `svg` - `barcode` object — Stores barcode representation of encrypted code. - `id` string — Encrypted voucher code ID. - `url` string — URL to barcode *Optional:* Attach query parameters to base URL to customize the image of the encrypted voucher code. - `size`: integer value from `1` to `100` - `format`: string, either `png` (default) or `svg` - `is_referral_code` boolean, nullable — Flag indicating whether this voucher is a referral code; `true` for campaign type `REFERRAL_PROGRAM`. - `created_at` string, date-time — Timestamp representing the date and time when the voucher was created. The value is shown in the ISO 8601 format. - `updated_at` string, date-time — Timestamp representing the date and time when the voucher was last updated in ISO 8601 format. - `referrer_id` string — Unique identifier of the referring person. - `holder_id` string — Unique customer identifier of the redeemable holder. It equals to the customer ID assigned by Voucherify. - `object` string — The type of the object represented by JSON. Default is `voucher`. - `publish` object — This object stores a summary of publish events: an events counter and an endpoint which can be called to return details of each event. A publication is required for loyalty cards and referral codes. This object gets updated whenever a voucher has been published. Publication means assigning a code to a particular customer. Typically, a publication is made by distributing your codes to your customers, e.g. through Export to MailChimp or | Required | Optional | | -------- | :------: | | `type`:`LOYALTY_CARD` | `type`:`DISCOUNT_VOUCHER` | | `is_referral_code`:`true` | `type`:`GIFT_VOUCHER` | - `object` string — The type of the object represented is by default `list`. To get this list, you need to make a call to the endpoint returned in the `url` attribute. - `count` integer — Publication events counter. - `url` string — The endpoint where this list of publications can be accessed using a **GET** method. `/v1/vouchers/{voucher_code}/publications` - `redemption` object — Stores a summary of redemptions that have been applied to the voucher. - `quantity` integer — How many times a voucher can be redeemed. A `null` value means unlimited. - `redeemed_quantity` integer — How many times a voucher has already been redeemed. - `redeemed_points` integer — Total loyalty points redeemed. - `object` string — The type of the object represented is by default `list`. To get this list, you need to make a call to the endpoint returned in the url attribute. - `url` string — The endpoint where this list of redemptions can be accessed using a **GET** method. `/v1/vouchers/{voucher_code}/redemptions` - `status` 'ACTIVE' | 'USED' | 'DISABLED' | 'NOT_ACTIVE_YET' | 'EXPIRED' | 'NO_BALANCE', required — Status of the redeemable. - `total` integer, required — Total number of results returned. - `has_more` boolean, required — As query results are always limited (by the limit parameter), the `has_more` flag indicates if there are more records for given filter parameters. This lets you know if you can run another request with a `starting_after_id` query or a different limit to get more records returned in the results. - `more_starting_after` string — Returns an ID that can be used to return another page of results. Use the ID in the `starting_after_id` query parameter to display another page of the results occuring after the field with that ID. ## Other responses - `404` — Returns an error if a resource is not found. --- [API](https://skmtc.net/voucherifyio/apis/voucherify-api-async-actions.md) · [All operations](https://skmtc.net/voucherifyio/apis/voucherify-api-async-actions/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/voucherifyio/voucherify-api-async-actions/revisions/4982266e0494/schema)