---
title: "Issue many single-use credit promotion codes"
method: POST
path: "/api/v1/promotion-codes/bulk"
tags: ["Promotion Codes"]
---

# Issue many single-use credit promotion codes

`POST /api/v1/promotion-codes/bulk`

## Request

- Base URL: `https://partner-api.monta.com`
- URL: `https://partner-api.monta.com/api/v1/promotion-codes/bulk`
- Auth: HTTP bearer

Required scope: `promotion-codes:write` </br>Organization authorization: `supported`

Creates one single-use `credit` code per string in `codes`, for handing a credit to a large group of drivers as one code each rather than a shared code. You choose the codes, so they can follow your own naming scheme. Up to 5000 per request; issue a larger run as several requests.

- The response carries the id of every code created. `GET /promotion-codes?codePrefix=` lists a batch again if the codes share a prefix.
- Retrying is safe. A replayed request finds every code already taken, so it creates nothing new and returns them all in `skippedExistingCodes`.
- Codes are unique across all operators. One already taken is reported in `skippedExistingCodes` rather than failing the whole batch, so check that list and reissue those codes under new strings.
- Set `startAt` in the future to issue the batch inactive, then activate a code with `PATCH /promotion-codes/{id}` when it is sold. Until then it cannot be redeemed.
- `credit` must be enabled for your operator, otherwise the request is rejected with 422.
- Your operator wallet is debited as each code is redeemed, not when the batch is created.

## Request body

- BulkCreatePromotionCode
  - `name` string, required: Name shared by every code in the batch
  - `description` string, nullable: Description shared by every code in the batch
  - `codes` string[], required: The codes to create, chosen by you, up to 5000 per request. Each must be lowercase alphanumeric with optional hyphens, at most 64 characters, and unique within the request. A shared prefix is worth keeping: pass it to `GET /promotion-codes?codePrefix=` to list the batch again.
  - `amount` number, double, required: Currency amount deposited into the driver's wallet when a code is redeemed (max 500). Every code in the batch carries the same amount and is single-use — send one request per amount.
  - `startAt` string, date-time, nullable: When the codes become redeemable (ISO8601: yyyy-MM-ddTHH:mm:ssZ). Set a future date to issue the batch inactive — a code stays unredeemable until this passes, so vouchers can be printed and distributed before they carry value, then activated per code with `PATCH /promotion-codes/{id}` when one is sold.
  - `endAt` string, date-time, nullable: When the codes expire (ISO8601: yyyy-MM-ddTHH:mm:ssZ)

## Response `201`

Promotion codes created

- PromotionCodeBulkResult
  - `created` CreatedPromotionCode[], required: The codes created by this request
    - `id` integer, required: ID of the created promotion code
    - `code` string, required: The code a driver redeems
  - `skippedExistingCodes` string[], required: The requested codes that already existed and were therefore not created again. Codes are unique across all operators, so a code held elsewhere is reported here instead of failing the batch. A replayed request returns an empty `created` list and every code here, so retrying is safe.

## Other responses

- `400`: The request is invalid
- `401`: Consumer with provided credentials was not found
- `403`: Operator doesn't have access to resource
- `404`: Entity with the provided id was not found
- `422`: Validation failed — more than 5000 `codes`, a code repeated within the request, a code that is not lowercase alphanumeric, `amount` above 500, or credit promotion codes are not enabled for this operator

## Changes

- **2026-11-03** `0ca400461c52`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/monta/apis/monta-partner-api/changes/api/v1/promotion-codes/bulk/post.md)

---

[API](https://skmtc.dev/monta/apis/monta-partner-api.md) - [All operations](https://skmtc.dev/monta/apis/monta-partner-api/llms.txt) - [OpenAPI document](https://skmtc.dev/monta/apis/monta-partner-api/revisions/0ca400461c52?raw)