Backend API: Manage discount voucher codes

Last updated:
Edit on GitHub

This document describes how to manage the voucher codes of a discount using the Backend API. A voucher discount is applied only when the customer redeems one of its codes. The endpoints cover what the Back Office Discount page offers for a voucher pool: listing the codes with their usage, generating a batch of codes, removing codes one by one or all at once, and downloading all codes as a CSV file.

Voucher codes belong to a discount and are addressed below it, by the discount uuid and the code itself. The discount must be of the voucher type; to create one, see Backend API: Manage discounts.

Installation

These endpoints are implemented using API Platform. To install and enable it, see Enable API Platform.

For the modules that provide the voucher code endpoints and their installation instructions, see Install the Discounts Backend API.

Conventions

Request headers, pagination, and the filter and sort syntax are the same for every Backend API resource—see Backend API conventions. This page lists only what is specific to voucher codes.

Retrieve voucher codes

To retrieve a paginated collection of the voucher codes of a discount, send the request:

GET /discounts/{{discount_uuid}}/voucher-codes

PATH PARAMETER DESCRIPTION
{{discount_uuid}} UUID of the discount whose codes to retrieve. To get it, retrieve discounts.

Request

HEADER KEY HEADER VALUE REQUIRED DESCRIPTION
Authorization string ✓ Alphanumeric string that authorizes the Back Office user to send requests to protected resources. Get it by authenticating as a Back Office user.
QUERY PARAMETER DESCRIPTION POSSIBLE VALUES
page[limit] Maximum number of items to return per page. From 1 to 100. Defaults to 10.
page[offset] Number of items to skip before the page begins. From 0 to any. Defaults to 0.
filter[discount-voucher-codes.code] Filters the collection by a partial code, matched case-insensitively. Any string.
filter[discount-voucher-codes.voucherBatch] Filters the collection down to the codes generated in one batch. Batch number as returned by Generate voucher codes. 0 matches the codes created one by one in the Back Office.
sort Sorts the collection by the given field. Prefix a field with - to sort in descending order. Separate several fields with a comma. code, numberOfUses, maxNumberOfUses, createdAt, voucherBatch

Without a sort parameter, the collection is ordered by createdAt descending, so the newest code leads. Sorting by a field that is not on the list returns 400 with the error code 5740. A voucherBatch filter that is not an integer returns 422 with the error code 901.

REQUEST USAGE
GET https://glue-backend.mysprykershop.com/discounts/2e622c64-5ddb-58dd-b313-af61c15c65ba/voucher-codes Retrieve the first page of voucher codes of the discount.
GET https://glue-backend.mysprykershop.com/discounts/2e622c64-5ddb-58dd-b313-af61c15c65ba/voucher-codes?filter[discount-voucher-codes.voucherBatch]=3&sort=code Retrieve the codes of batch 3 in alphabetical order.
GET https://glue-backend.mysprykershop.com/discounts/2e622c64-5ddb-58dd-b313-af61c15c65ba/voucher-codes?filter[discount-voucher-codes.code]=SALE- Retrieve the codes containing SALE-.
GET https://glue-backend.mysprykershop.com/discounts/2e622c64-5ddb-58dd-b313-af61c15c65ba/voucher-codes?sort=-numberOfUses&page[limit]=100 Retrieve the 100 most redeemed codes.

Response

Response sample: retrieve voucher codes 
{
    "data": [
        {
            "type": "discount-voucher-codes",
            "id": "discountUuid=2e622c64-5ddb-58dd-b313-af61c15c65ba;code=SALE-7GH2KQ",
            "attributes": {
                "discountUuid": "2e622c64-5ddb-58dd-b313-af61c15c65ba",
                "code": "SALE-7GH2KQ",
                "maxNumberOfUses": 1,
                "numberOfUses": 1,
                "isActive": true,
                "voucherBatch": 3,
                "createdAt": "2026-09-29 09:28:50"
            }
        },
        {
            "type": "discount-voucher-codes",
            "id": "discountUuid=2e622c64-5ddb-58dd-b313-af61c15c65ba;code=SALE-M4XP9A",
            "attributes": {
                "discountUuid": "2e622c64-5ddb-58dd-b313-af61c15c65ba",
                "code": "SALE-M4XP9A",
                "maxNumberOfUses": 1,
                "numberOfUses": 0,
                "isActive": true,
                "voucherBatch": 3,
                "createdAt": "2026-09-29 09:28:50"
            }
        }
    ],
    "meta": {
        "pagination": {
            "numFound": 100,
            "currentPage": 1,
            "maxPage": 10,
            "currentItemsPerPage": 10
        }
    },
    "links": {
        "self": "https://glue-backend.mysprykershop.com/discounts/2e622c64-5ddb-58dd-b313-af61c15c65ba/voucher-codes",
        "first": "https://glue-backend.mysprykershop.com/discounts/2e622c64-5ddb-58dd-b313-af61c15c65ba/voucher-codes?page[limit]=10&page[offset]=0",
        "last": "https://glue-backend.mysprykershop.com/discounts/2e622c64-5ddb-58dd-b313-af61c15c65ba/voucher-codes?page[limit]=10&page[offset]=90",
        "next": "https://glue-backend.mysprykershop.com/discounts/2e622c64-5ddb-58dd-b313-af61c15c65ba/voucher-codes?page[limit]=10&page[offset]=10"
    }
}
ATTRIBUTE TYPE DESCRIPTION
discountUuid String UUID of the discount the code belongs to.
code String The voucher code the customer redeems. Together with discountUuid, it forms the resource id.
maxNumberOfUses Integer How many times the code can be redeemed in total. 0 means unlimited, also for a code created without a limit in the Back Office.
numberOfUses Integer How many times the code has been redeemed so far. 0 for a code that has never been redeemed.
isActive Boolean Whether the code can be redeemed. Codes are generated active; the flag is cleared only by a data import, there is no action in the API or the Back Office that toggles it.
voucherBatch Integer Number of the generation batch the code was created in. 0 for a code created one by one in the Back Office.
createdAt String Date and time when the code was created.

A collection response carries its pagination summary in the top-level meta.pagination object:

ATTRIBUTE TYPE DESCRIPTION
meta.pagination.numFound Integer Total number of items found.
meta.pagination.currentPage Integer Current page number.
meta.pagination.maxPage Integer Total number of pages.
meta.pagination.currentItemsPerPage Integer Number of items per page.

The top-level links object carries the first and last links, plus prev and next when those pages exist. Each link repeats the query parameters of the request and rewrites the window as page[limit] and page[offset], so you can follow it as it is.

Generate voucher codes

To generate a batch of voucher codes for a discount, send the request:

POST /discounts/{{discount_uuid}}/voucher-codes/generate

PATH PARAMETER DESCRIPTION
{{discount_uuid}} UUID of the voucher discount to generate codes for. To get it, retrieve discounts.

Request

HEADER KEY HEADER VALUE REQUIRED DESCRIPTION
Authorization string ✓ Alphanumeric string that authorizes the Back Office user to send requests to protected resources. Get it by authenticating as a Back Office user.
Content-Type application/vnd.api+json ✓ Media type of the request body.

Request sample: generate three single-use codes with a prefix

POST https://glue-backend.mysprykershop.com/discounts/2e622c64-5ddb-58dd-b313-af61c15c65ba/voucher-codes/generate

{
    "data": {
        "type": "discount-voucher-codes-generate",
        "attributes": {
            "quantity": 3,
            "codeLength": 6,
            "customCode": "SALE-[code]",
            "maxNumberOfUses": 1
        }
    }
}

Request sample: generate 10 random codes that can be redeemed without limit

POST https://glue-backend.mysprykershop.com/discounts/2e622c64-5ddb-58dd-b313-af61c15c65ba/voucher-codes/generate

{
    "data": {
        "type": "discount-voucher-codes-generate",
        "attributes": {
            "quantity": 10,
            "codeLength": 8
        }
    }
}
ATTRIBUTE TYPE REQUIRED DESCRIPTION
quantity Integer ✓ Number of codes to generate, from 1 to 14000. The allowed range is listed in voucherCodesQuantity by Retrieve discount options.
codeLength Integer Length of the random part of each code, from 3 to 10. Required when customCode is not given. The allowed range is listed in voucherCodeLength by Retrieve discount options.
customCode String Template of the codes, at most 245 characters. The [code] placeholder is replaced by the random part; without the placeholder, the random part is appended to the template. Required when codeLength is not given.
maxNumberOfUses Integer How many times each generated code can be redeemed. 0 means unlimited. Defaults to 0.

The response lists the generated codes. To read them again later, retrieve voucher codes filtered by the returned voucherBatch, or export voucher codes.

Response

Response sample:

{
    "data": {
        "type": "discount-voucher-codes-generate",
        "id": "2e622c64-5ddb-58dd-b313-af61c15c65ba",
        "attributes": {
            "discountUuid": "2e622c64-5ddb-58dd-b313-af61c15c65ba",
            "voucherBatch": 3,
            "generatedCount": 3,
            "codes": [
                "SALE-7GH2KQ",
                "SALE-M4XP9A",
                "SALE-Q2WD8N"
            ]
        }
    }
}

A successful request returns the 201 Created status code.

ATTRIBUTE TYPE DESCRIPTION
discountUuid String UUID of the discount the codes were generated for.
voucherBatch Integer Number assigned to the batch. Use it as the voucherBatch filter of Retrieve voucher codes.
generatedCount Integer Number of codes actually generated.
codes Array The codes created by this request, in the order they were created. Only these codes are listed, even for batch 0.
Codes are unique across the shop

A generated code must not exist in any voucher pool. When every attempt to generate a code collides with an existing one—for example, because a short codeLength is exhausted—the request is rejected with 422 and the error code 5726. Increase codeLength or change customCode.

Delete voucher codes

To delete voucher codes of a discount, send the request:

POST /discounts/{{discount_uuid}}/voucher-codes/delete

PATH PARAMETER DESCRIPTION
{{discount_uuid}} UUID of the discount the codes belong to.

Request

HEADER KEY HEADER VALUE REQUIRED DESCRIPTION
Authorization string ✓ Alphanumeric string that authorizes the Back Office user to send requests to protected resources. Get it by authenticating as a Back Office user.

Request sample: delete the listed codes

POST https://glue-backend.mysprykershop.com/discounts/2e622c64-5ddb-58dd-b313-af61c15c65ba/voucher-codes/delete

{
    "data": {
        "type": "discount-voucher-codes",
        "attributes": {
            "codes": ["SALE-7GH2KQ", "SALE-M4XP9A"]
        }
    }
}

Request sample: delete all codes of the discount

POST https://glue-backend.mysprykershop.com/discounts/2e622c64-5ddb-58dd-b313-af61c15c65ba/voucher-codes/delete

{
    "data": {
        "type": "discount-voucher-codes",
        "attributes": {
            "all": true
        }
    }
}
ATTRIBUTE TYPE REQUIRED DESCRIPTION
codes Array ✓ unless all is true Codes to delete, at most 100 per request. To get them, retrieve voucher codes. Send either codes or all, not both.
all Boolean ✓ unless codes is given Set to true to delete every voucher code of the discount.

Response

A successful request returns the 204 No Content status code with an empty body. The codes are deleted permanently.

The code list is all-or-nothing: if any listed code does not belong to the discount, nothing is deleted, and the response is 404 with one error per offending code. The error code is 5720, and detail names the list position, for example, codes.1 => Voucher code "SALE-M4XP9A" was not found for discount with uuid "2e622c64-...".

all: true deletes whatever codes the discount has and returns 204 even when the pool is already empty. A body that carries neither a non-empty codes list nor all: true, or carries both, returns 400 with the error code 5722.

Export voucher codes

To download all voucher codes of a discount as a CSV file, send the request:

GET /discounts/{{discount_uuid}}/voucher-codes/export

PATH PARAMETER DESCRIPTION
{{discount_uuid}} UUID of the discount whose codes to export.

The URL is also provided as the voucherCodesExport link of a voucher discount in Retrieve a discount.

Request

HEADER KEY HEADER VALUE REQUIRED DESCRIPTION
Authorization string ✓ Alphanumeric string that authorizes the Back Office user to send requests to protected resources. Get it by authenticating as a Back Office user.

Request sample: GET https://glue-backend.mysprykershop.com/discounts/2e622c64-5ddb-58dd-b313-af61c15c65ba/voucher-codes/export

Response

The response is not a JSON:API document. It carries the Content-Type: text/csv; charset=UTF-8 and Content-Disposition: attachment; filename="vouchers.csv" headers, and its body is the file, with a header row followed by one row per code:

code,maxNumberOfUses,numberOfUses,isActive
SALE-7GH2KQ,1,1,1
SALE-M4XP9A,1,0,1
COLUMN DESCRIPTION
code The voucher code.
maxNumberOfUses How many times the code can be redeemed in total. 0 means unlimited.
numberOfUses How many times the code has been redeemed. 0 for a code that has never been redeemed.
isActive 1 if the code can be redeemed, 0 otherwise.

The file is the same the Back Office produces with Export voucher codes. A voucher discount without codes returns the header row only; a cart rule returns the header row as well, because it has no voucher pool.

Possible errors

CODE REASON
901 The request body or a query parameter failed schema validation—for example, quantity is out of range, neither codeLength nor customCode is given, customCode is longer than 245 characters, maxNumberOfUses is negative, more than 100 codes are listed, or filter[discount-voucher-codes.voucherBatch] is not an integer. Each body error names the rejected attribute in source.pointer.
5700 No discount matches the given UUID.
5720 A listed voucher code does not belong to the discount. Nothing is deleted; the response carries one error per such code.
5722 The delete request carries neither a non-empty codes list nor all: true, or carries both.
5721 Voucher codes can be generated for a voucher discount only, and the discount is a cart rule.
5726 No code could be generated for the given length and template, because every candidate collides with an existing code.
5740 The sort parameter names a field that the collection does not support.

To view generic errors, see API errors and troubleshooting.