> ## Documentation Index
> Fetch the complete documentation index at: https://voucherify-rc-lv2-guides.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Expire points bucket
>
Documentation in progress
This documentation is in progress. The parameters, fields, request and response bodies, and other data may be subject to change. If you need more information or you want to share feedback, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager.
Manually expires a points bucket before its scheduled expiration date, creating an
`ADMIN_POINTS_EXPIRATION` card transaction (status `PENDING`, processed
asynchronously). No request body.
The program and member must be in `ACTIVE` status, the card definition must have
points expiration enabled, the bucket must be in `ACTIVE` status, and the bucket's
expiration date must not be in the past (423 otherwise). Returns 404 when the
program, member, card or bucket does not exist.
## OpenAPI
````yaml /openapi/loyalties-v2.json post /v2/loyalties/programs/{programId}/members/{memberId}/cards/{cardId}/expiring-points/{bucketId}/expire
openapi: 3.1.0
info:
title: Voucherify Loyalty v2 API
version: 2.0.0
description: >-
Complete OpenAPI specification for the Voucherify Loyalty v2 API.
All endpoints require the LOYALTY_V2 feature flag.
Combined from per-domain specs: programs.yaml, members.yaml,
program-operations.yaml, card-definitions.yaml, earning-rules.yaml,
tier-structures.yaml, benefits.yaml, rewards.yaml, examine.yaml
servers:
- url: '{protocol}://{host}'
variables:
protocol:
default: https
enum:
- https
- http
host:
default: api.voucherify.io
security:
- X-App-Id: []
X-App-Token: []
- bearerAuth: []
tags:
- name: Programs
description: >-
Loyalty program CRUD, lifecycle management, program-scoped resource
assignments (card definitions, earning rules, rewards, tier structures),
member management (create, list, get, update, activate, deactivate,
delete), membership retrieval (member + program + cards with tier
progress, by customer ID, customer source ID, or member ID), card
operations (points adjustment, pending points, expiring points,
transactions), reward purchases, and activity history.
- name: Card Definitions
description: >-
CRUD operations, lifecycle management, and activity history for card
definitions. Card definitions describe the configuration for loyalty
cards, including code generation, points expiration, earning/spending
limits, pending points, refunds, and balance settings.
- name: Earning Rules
description: >-
Manage earning rules that define how customers earn points or receive
incentives based on triggers (events, segments, custom events). Includes
CRUD, lifecycle, and activity history.
- name: Tier Structures
description: >-
CRUD operations, lifecycle management, and activity history for tier
structures. Includes nested tier definitions (create, list, update,
delete) within tier structures. Tier structures define the tiering model
for loyalty programs — how members qualify for and move between tiers.
- name: Benefits
description: >-
Manage benefit definitions (fixed points, proportional points, material,
digital). Includes CRUD, lifecycle transitions, and activity history.
- name: Rewards
description: >-
CRUD, lifecycle operations, and activity history for reward definitions.
Rewards can be material (product/SKU) or digital (discount coupons, gift
vouchers).
- name: Examine
description: >-
Evaluation endpoints that estimate earning opportunities and reward
availability for a customer across their loyalty program memberships,
without side effects.
paths:
/v2/loyalties/programs/{programId}/members/{memberId}/cards/{cardId}/expiring-points/{bucketId}/expire:
post:
tags:
- Programs
summary: Expire points bucket
description: >-
Documentation in progress
This documentation is in progress. The parameters, fields, request and
response bodies, and other data may be subject to change. If you need
more information or you want to share feedback, contact [Voucherify
support](https://www.voucherify.io/contact-support) or your Technical
Account Manager.
Manually expires a points bucket before its scheduled expiration date,
creating an
`ADMIN_POINTS_EXPIRATION` card transaction (status `PENDING`, processed
asynchronously). No request body.
The program and member must be in `ACTIVE` status, the card definition
must have
points expiration enabled, the bucket must be in `ACTIVE` status, and
the bucket's
expiration date must not be in the past (423 otherwise). Returns 404
when the
program, member, card or bucket does not exist.
operationId: expireCardPointsBucket
parameters:
- name: programId
in: path
required: true
description: Unique loyalty program ID (format `lprg_[a-f0-9]+`).
schema:
type: string
pattern: ^lprg_[a-f0-9]+$
- name: memberId
in: path
required: true
description: Program member ID (format `lmbr_[a-f0-9]+`), assigned by Voucherify.
schema:
type: string
pattern: ^lmbr_[a-f0-9]+$
- name: cardId
in: path
required: true
description: Loyalty card ID (format `lcrd_[a-f0-9]+`), assigned by Voucherify.
schema:
type: string
pattern: ^lcrd_[a-f0-9]+$
- name: bucketId
in: path
required: true
description: Points expiration bucket ID (format `lcpeb_[a-f0-9]+`).
schema:
type: string
pattern: ^lcpeb_[a-f0-9]+$
responses:
'200':
description: Result of the points expiration.
content:
application/json:
schema:
$ref: '#/components/schemas/CardPointsExpirationResult'
'400':
description: >-
Validation error - request body or query parameters failed
validation, or the operation is not allowed in the current resource
state.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Resource not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'409':
description: Conflict - e.g. duplicate resource or invalid state transition.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'423':
description: >-
Resource locked - a related resource is in a state that prevents
this operation.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
schemas:
CardPointsExpirationResult:
type: object
description: >-
Result of a manual points bucket expiration. This endpoint always
returns status
`TRANSACTION_CREATED` on success.
properties:
transaction:
description: The created `ADMIN_POINTS_EXPIRATION` card transaction, or `null`.
oneOf:
- $ref: '#/components/schemas/CardTransaction'
- type: 'null'
status:
type: string
enum:
- TRANSACTION_CREATED
- NO_EXPIRATION
description: Result status. The API endpoint returns `TRANSACTION_CREATED`.
message:
type: string
description: >-
Human-readable result message - "Points expiration transaction
created".
required:
- transaction
- status
- message
ErrorResponse:
type: object
description: Standard error response returned by all Loyalty v2 endpoints.
properties:
code:
type: integer
description: HTTP status code of the error.
key:
type: string
description: Machine-readable error key.
message:
type: string
description: Human-readable error message.
details:
type: string
description: Additional details about the error.
request_id:
type: string
description: Unique identifier of the request that produced the error.
resource_id:
type: string
description: Unique identifier of the resource that produced the error.
resource_type:
type: string
description: Type of the resource that produced the error.
CardTransaction:
type: object
description: A card transaction.
properties:
id:
type: string
pattern: ^lctx_[a-f0-9]+$
description: Unique card transaction ID assigned by Voucherify.
card_id:
type: string
pattern: ^lcrd_[a-f0-9]+$
description: ID of the card the transaction belongs to. Assigned by Voucherify.
program_id:
type: string
pattern: ^lprg_[a-f0-9]+$
description: ID of the loyalty program. Assigned by Voucherify.
member_id:
type: string
pattern: ^lmbr_[a-f0-9]+$
description: ID of the member owning the card. Assigned by Voucherify.
card_definition_id:
type: string
pattern: ^lcdef_[a-f0-9]+$
description: ID of the card definition of the card. Assigned by Voucherify.
card_type:
type: string
enum:
- INDIVIDUAL
description: Card type.
type:
type: string
enum:
- ADMIN_CREDIT
- ADMIN_DEBIT
- ADMIN_POINTS_EXPIRATION
- POINTS_EARNED
- POINTS_SPENT_ON_REWARD
- POINTS_PURCHASED
- POINTS_PURCHASE_REVERSED
- POINTS_SPENT_ON_ORDER
- POINTS_REFUNDED
- POINTS_RETURNED
- POINTS_EXPIRED
- PENDING_POINTS_ADDED
- PENDING_POINTS_ACTIVATED
- PENDING_POINTS_CANCELED
description: Transaction type.
details:
description: Transaction details; the shape depends on the transaction `type`.
oneOf:
- $ref: '#/components/schemas/CardTransactionDetails'
- type: 'null'
status:
type: string
enum:
- PENDING
- PROCESSING
- APPROVED
- REJECTED
description: >-
Transaction processing status. Transactions are created as `PENDING`
and processed asynchronously.
created_at:
type: string
format: date-time
description: Timestamp when the transaction was created (ISO 8601).
updated_at:
type:
- string
- 'null'
format: date-time
description: >-
Timestamp when the transaction was last updated (ISO 8601), or
`null`.
object:
type: string
const: card_transaction
description: Object type marker, always `card_transaction`.
required:
- id
- card_id
- program_id
- member_id
- card_definition_id
- card_type
- type
- details
- status
- created_at
- updated_at
- object
CardTransactionDetails:
type: object
description: >-
Card transaction details. `reason`, `rejection` and `metadata` are
present on all variants; the remaining fields depend on the transaction
`type`:
- `ADMIN_CREDIT`: `points` (`total`, `expiration_date`)
- `ADMIN_DEBIT`: `points` (`total`)
- `ADMIN_POINTS_EXPIRATION`: `bucket` (the expired points bucket)
- `POINTS_EARNED`: `points` (`total`, `expiration_date`)
- `POINTS_EXPIRED`: `points` (`total`), `date`, `buckets`
- `POINTS_SPENT_ON_REWARD`: `points` (`total`), `reward`,
`reward_transaction`,`target_card`, `purchase_transaction`
- `POINTS_PURCHASED`: `points` (`total`, `expiration_date`,
`expiration_type`), `reward`, `reward_transaction`, `card_transaction`
- `POINTS_PURCHASE_REVERSED`: `points` (`total`, `expiration_date`,
`expiration_type`), `reward`, `purchase`, `reward_transaction`
- `POINTS_SPENT_ON_ORDER`: `points` (`total`), `order`,
`order_transaction`
- `POINTS_REFUNDED`: `points` (`total`)
- `POINTS_RETURNED`: `points` (`total`, `expiration_date`,
`expiration_type`), `reward`, `purchase`, `reward_transaction`
- `PENDING_POINTS_ADDED` / `PENDING_POINTS_ACTIVATED` /
`PENDING_POINTS_CANCELED`: `points` (`total`, `date`, `type`)
properties:
reason:
type:
- string
- 'null'
description: >-
Reason for the transaction (e.g. the reason provided in a manual
adjustment request).
rejection:
description: Rejection details when the transaction was rejected, or `null`.
oneOf:
- type: object
properties:
reason:
type: string
description: Rejection reason.
details:
type: string
description: Detailed rejection description.
- type: 'null'
metadata:
type: object
description: Transaction metadata (empty object when none).
points:
type: object
description: Points affected by the transaction (variant-dependent fields).
properties:
total:
type: number
description: Number of points. Negative for debits.
expiration_date:
type:
- string
- 'null'
format: date
description: >-
Expiration date of the affected points (`YYYY-MM-DD`), or
`null`.
expiration_type:
type:
- string
- 'null'
enum:
- NO_EXPIRATION
- ROLLING_EXPIRATION
- CALENDAR_EXPIRATION
- SLIDING_EXPIRATION
- null
description: Points expiration type of the affected points, or `null`.
date:
type: string
format: date
description: >-
Activation date of the pending points (`YYYY-MM-DD`). Pending
points variants only.
type:
type: string
enum:
- IMMEDIATE
- PERIOD_BASED
- FIXED_DATES
- EVENT_BASED
description: Pending points activation type. Pending points variants only.
bucket:
$ref: '#/components/schemas/CardPointsBucketSimple'
description: The points bucket being expired (`ADMIN_POINTS_EXPIRATION` only).
buckets:
type: array
description: The points buckets that expired (`POINTS_EXPIRED` only).
items:
$ref: '#/components/schemas/CardPointsBucketSimple'
date:
type: string
format: date
description: Expiration date (`POINTS_EXPIRED` only, `YYYY-MM-DD`).
reward:
description: Reference to the reward involved, or `null`.
oneOf:
- type: object
properties:
id:
type: string
description: Reward ID (`lrew_[a-f0-9]+`) assigned by Voucherify.
- type: 'null'
reward_transaction:
description: Reference to the related reward transaction, or `null`.
oneOf:
- type: object
properties:
id:
type: string
description: >-
Reward transaction ID (`lrtx_[a-f0-9]+`) assigned by
Voucherify.
- type: 'null'
card_transaction:
description: >-
Reference to the linked card transaction (e.g. the spend side of a
points purchase), or `null`.
oneOf:
- type: object
properties:
id:
type: string
description: >-
Card transaction ID (`lctx_[a-f0-9]+`) assigned by
Voucherify.
- type: 'null'
purchase:
description: >-
References to the original purchase transactions (reversal/return
variants), or `null`.
oneOf:
- type: object
properties:
card_transaction:
oneOf:
- type: object
properties:
id:
type: string
description: >-
Card transaction ID (`lctx_[a-f0-9]+`) assigned by
Voucherify.
- type: 'null'
reward_transaction:
oneOf:
- type: object
properties:
id:
type: string
description: >-
Reward transaction ID (`lrtx_[a-f0-9]+`) assigned by
Voucherify.
- type: 'null'
- type: 'null'
order:
description: >-
Reference to the order paid with points (`POINTS_SPENT_ON_ORDER`
only), or `null`.
oneOf:
- type: object
properties:
id:
type: string
description: Order ID assigned by Voucherify.
- type: 'null'
order_transaction:
description: >-
Reference to the related order transaction (`POINTS_SPENT_ON_ORDER`
only), or `null`.
oneOf:
- type: object
properties:
id:
type: string
description: >-
Order transaction ID (`lotx_[a-f0-9]+`) assigned by
Voucherify.
- type: 'null'
target_card:
description: >-
Reference to the target card credited by a points purchase
(`POINTS_SPENT_ON_REWARD` only), or `null`.
oneOf:
- type: object
properties:
id:
type: string
description: Card ID (`lcrd_[a-f0-9]+`) assigned by Voucherify.
- type: 'null'
purchase_transaction:
description: >-
Reference to the linked purchase card transaction
(`POINTS_SPENT_ON_REWARD` only), or `null`.
oneOf:
- type: object
properties:
id:
type: string
description: >-
Card transaction ID (`lctx_[a-f0-9]+`) assigned by
Voucherify.
- type: 'null'
CardPointsBucketSimple:
type: object
description: |-
Simple representation of a points expiration bucket, embedded in card
transaction details.
properties:
id:
type: string
pattern: ^lcpeb_[a-f0-9]+$
description: Points expiration bucket ID.
points:
type: object
description: Points held in the bucket.
properties:
total:
type: number
description: Number of points in the bucket.
required:
- total
expiration_date:
type: string
format: date
description: Date when the points in the bucket expire (`YYYY-MM-DD`).
expiration_type:
type: string
enum:
- NO_EXPIRATION
- ROLLING_EXPIRATION
- CALENDAR_EXPIRATION
- SLIDING_EXPIRATION
description: Points expiration type.
required:
- id
- points
- expiration_date
- expiration_type
securitySchemes:
X-App-Id:
type: apiKey
name: X-App-Id
in: header
X-App-Token:
type: apiKey
name: X-App-Token
in: header
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
````