> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voucherify.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Batch assign/unassign rewards
>
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.
Assigns and/or unassigns rewards to/from a program in a single batch.
Unassign operations are processed before assign operations. Each reward to assign
must include its `stock` configuration. In strict mode (default) missing rewards
or missing assignments cause the whole batch to fail (`404 Not Found`).
## OpenAPI
````yaml /openapi/loyalties-v2.json post /v2/loyalties/programs/{programId}/rewards/batch
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}/rewards/batch:
post:
tags:
- Programs
summary: Batch assign/unassign rewards
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.
Assigns and/or unassigns rewards to/from a program in a single batch.
Unassign operations are processed before assign operations. Each reward
to assign
must include its `stock` configuration. In strict mode (default) missing
rewards
or missing assignments cause the whole batch to fail (`404 Not Found`).
operationId: batchProgramRewardAssignments
parameters:
- name: programId
in: path
required: true
description: Unique program identifier.
schema:
type: string
pattern: ^lprg_[a-f0-9]+$
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ProgramRewardBatchRequest'
responses:
'200':
description: Batch processing result.
content:
application/json:
schema:
$ref: '#/components/schemas/ProgramRewardBatchResponse'
'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'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
schemas:
ProgramRewardBatchRequest:
type: object
description: >-
Batch of reward assignment operations. `unassign` operations are
processed
before `assign` operations. Duplicate ids within a batch are rejected.
properties:
assign:
description: Rewards to assign, each with its stock configuration.
oneOf:
- type: array
items:
$ref: '#/components/schemas/ProgramRewardAssignItem'
maxItems: 10
- type: 'null'
unassign:
description: Rewards to unassign.
oneOf:
- type: array
items:
$ref: '#/components/schemas/ProgramRewardUnassignItem'
maxItems: 10
- type: 'null'
additionalProperties: false
ProgramRewardBatchResponse:
type: object
description: >-
Result of a reward assignment batch. Keys are null when the
corresponding operation list was not provided.
properties:
assigned:
description: >-
Assignments created by the batch, or `null` when no assign
operations were requested.
oneOf:
- type: array
items:
$ref: '#/components/schemas/ProgramRewardAssignment'
- type: 'null'
unassigned:
description: >-
Assignments removed by the batch, or `null` when no unassign
operations were requested.
oneOf:
- type: array
items:
$ref: '#/components/schemas/ProgramRewardAssignment'
- type: 'null'
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.
ProgramRewardAssignItem:
type: object
description: Reward to assign to the program, together with its stock configuration.
properties:
id:
type: string
description: Unique reward identifier.
pattern: ^lrew_[a-f0-9]+$
stock:
$ref: '#/components/schemas/ProgramRewardAssignmentStock'
required:
- id
- stock
additionalProperties: false
ProgramRewardUnassignItem:
type: object
description: Reward to unassign from the program.
properties:
id:
type: string
description: Unique reward identifier.
pattern: ^lrew_[a-f0-9]+$
required:
- id
additionalProperties: false
ProgramRewardAssignment:
type: object
description: >-
A reward assigned to a program, with stock configuration and redemption
counter.
properties:
reward_id:
type: string
description: Unique reward identifier.
pattern: ^lrew_[a-f0-9]+$
stock:
$ref: '#/components/schemas/ProgramRewardAssignmentStock'
description: Stock configuration of the assignment.
redeemed:
type: number
description: >-
Number of times the reward has been redeemed within the program.
Defaults to 0.
created_at:
type: string
format: date-time
description: Assignment creation timestamp (ISO 8601).
updated_at:
type:
- string
- 'null'
format: date-time
description: Last update timestamp (ISO 8601), or `null` when never updated.
object:
type: string
description: Object type marker.
const: program_reward
ProgramRewardAssignmentStock:
type: object
description: >-
Reward stock configuration. When `type` is `UNLIMITED`, `limited` must
not be provided.
When `type` is `LIMITED`, `limited` is required.
properties:
type:
type: string
description: Stock type.
enum:
- UNLIMITED
- LIMITED
limited:
description: >-
Limited stock details. Required when `type` is `LIMITED`; must not
be provided when `type` is `UNLIMITED`.
oneOf:
- $ref: '#/components/schemas/ProgramRewardAssignmentStockLimited'
- type: 'null'
required:
- type
additionalProperties: false
allOf:
- if:
properties:
type:
const: UNLIMITED
then:
not:
required:
- limited
- if:
properties:
type:
const: LIMITED
then:
required:
- limited
properties:
limited:
$ref: '#/components/schemas/ProgramRewardAssignmentStockLimited'
ProgramRewardAssignmentStockLimited:
type: object
description: Limited stock configuration.
properties:
quantity:
type: integer
description: Available stock quantity.
minimum: 0
maximum: 9007199254740991
required:
- quantity
additionalProperties: false
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
````