> ## 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.
# Activate a pending points bucket
>
BETA endpoint
This is a work-in-progress documentation of a BETA endpoint. The parameters, fields, request and response bodies, and other data may be subject to change. If you want to share feedback or improvements, contact [Voucherify support](https://www.voucherify.io/contact-support) or your Technical Account Manager.
Manually activates a pending points bucket before its scheduled activation date,
creating a `PENDING_POINTS_ACTIVATED` card transaction (status `PENDING`, processed
asynchronously). No request body.
The program and member must be in `ACTIVE` status, the card definition must have
pending points enabled, the bucket must be in `PENDING` status, and the bucket's
activation date must be in the future (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}/pending-points/{bucketId}/activate
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, 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}/pending-points/{bucketId}/activate:
post:
tags:
- Programs
summary: Activate a pending points bucket
description: >-
BETA endpoint
This is a work-in-progress documentation of a BETA endpoint. The
parameters, fields, request and response bodies, and other data may be
subject to change. If you want to share feedback or improvements,
contact [Voucherify support](https://www.voucherify.io/contact-support)
or your Technical Account Manager.
Manually activates a pending points bucket before its scheduled
activation date,
creating a `PENDING_POINTS_ACTIVATED` card transaction (status
`PENDING`, processed
asynchronously). No request body.
The program and member must be in `ACTIVE` status, the card definition
must have
pending points enabled, the bucket must be in `PENDING` status, and the
bucket's
activation date must be in the future (423 otherwise). Returns 404 when
the
program, member, card or bucket does not exist.
operationId: activateCardPendingPointsBucket
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]+`).
schema:
type: string
pattern: ^lmbr_[a-f0-9]+$
- name: cardId
in: path
required: true
description: Loyalty card ID (format `lcrd_[a-f0-9]+`).
schema:
type: string
pattern: ^lcrd_[a-f0-9]+$
- name: bucketId
in: path
required: true
description: Pending points bucket ID (format `lcppb_[a-f0-9]+`).
schema:
type: string
pattern: ^lcppb_[a-f0-9]+$
responses:
'200':
description: Result of the pending points activation.
content:
application/json:
schema:
$ref: '#/components/schemas/CardPendingPointsActivationResult'
'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:
CardPendingPointsActivationResult:
type: object
description: >-
Result of a manual pending points activation. This endpoint always
returns
status `TRANSACTION_CREATED` on success.
properties:
transaction:
description: The created `PENDING_POINTS_ACTIVATED` card transaction, or `null`.
oneOf:
- $ref: '#/components/schemas/CardTransaction'
- type: 'null'
status:
type: string
enum:
- TRANSACTION_CREATED
- NO_ACTIVATION
description: Result status. The API endpoint returns `TRANSACTION_CREATED`.
message:
type: string
description: >-
Human-readable result message - "Points activation 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.
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]+`).
- 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]+`).
- 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]+`).
- 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]+`).
- type: 'null'
reward_transaction:
oneOf:
- type: object
properties:
id:
type: string
description: Reward transaction ID (`lrtx_[a-f0-9]+`).
- 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.
- 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]+`).
- 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]+`).
- 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]+`).
- 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
````