MOmonta
Promotion Codes

Issue many single-use credit promotion codes

Changed on

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.
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

Request body

namestring required

Name shared by every code in the batch

descriptionstring nullable

Description shared by every code in the batch

codesstring[] 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.

amountnumber 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.

startAtstring 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.

endAtstring date-time nullable

When the codes expire (ISO8601: yyyy-MM-ddTHH:mm:ssZ)

Example request

{
  "name": "Newsagent voucher",
  "description": "45 EUR welcome credit",
  "codes": [
    "logista-a7f3k2",
    "logista-b1c9d4"
  ],
  "amount": 45,
  "startAt": "2030-01-01T00:00:00Z",
  "endAt": "2026-12-31T23:59:59Z"
}

Response

Promotion codes created

skippedExistingCodesstring[] 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.

Example response

{
  "created": [
    {
      "id": 604,
      "code": "logista-a7f3k2"
    }
  ],
  "skippedExistingCodes": []
}

Changes