---
title: "Batch assign/unassign tier structures"
method: POST
path: "/v2/loyalties/programs/{programId}/tier-structures/batch"
tags: ["Programs"]
---

# Batch assign/unassign tier structures

`POST /v2/loyalties/programs/{programId}/tier-structures/batch`

<Warning>

<Badge color="yellow">BETA endpoint</Badge>

This is a work-in-progress documentation of a BETA endpoint. The parameters, fields, request and response bodies, and other data may 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.

</Warning>

Assigns and/or unassigns tier structures to/from a program in a single batch.
Unassign operations are processed before assign operations. Unassigning is only
allowed while the program is in `DRAFT` status - otherwise the request is rejected
with `423 Locked` (key `non_draft_program`). A program can have at most one tier
structure assigned. In strict mode (default) missing tier structures, inactive tier
structures or missing assignments cause the whole batch to fail.

## Path parameters

- `id` string, required

## Request body

- ProgramTierStructureBatchRequest — Batch of tier structure assignment operations. `unassign` operations are processed before `assign` operations. Duplicate ids within a batch are rejected.
  - `assign` ProgramTierStructureAssignItem[], nullable — Tier structures to assign.
    - `id` string, required — Unique tier structure identifier.
  - `unassign` ProgramTierStructureUnassignItem[], nullable — Tier structures to unassign.
    - `id` string, required — Unique tier structure identifier.

## Response `200`

Batch processing result.

- ProgramTierStructureBatchResponse — Result of a tier structure assignment batch. Keys are null when the corresponding operation list was not provided.
  - `assigned` ProgramTierStructureAssignment[], nullable — Assignments created by the batch, or null when no assign operations were requested.
    - `tier_structure_id` string — Unique tier structure identifier.
    - `created_at` string, date-time — Assignment creation timestamp (ISO 8601).
    - `object` 'program_tier_structure' — Object type marker.
  - `unassigned` ProgramTierStructureAssignment[], nullable — Assignments removed by the batch, or null when no unassign operations were requested.
    - `tier_structure_id` string — Unique tier structure identifier.
    - `created_at` string, date-time — Assignment creation timestamp (ISO 8601).
    - `object` 'program_tier_structure' — Object type marker.

## Other responses

- `400` — Validation error - request body or query parameters failed validation, or the operation is not allowed in the current resource state.
- `404` — Resource not found.
- `409` — Conflict - e.g. duplicate resource or invalid state transition.
- `423` — Resource locked - a related resource is in a state that prevents this operation.
- `500` — Internal server error.

---

[API](https://skmtc.net/voucherifyio/apis/voucherify-loyalty-v2-api.md) · [All operations](https://skmtc.net/voucherifyio/apis/voucherify-loyalty-v2-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/voucherifyio/voucherify-loyalty-v2-api/versions/f6f2f3388362/schema)