Subscription Voucher Codes

Promotional/discount codes parents can redeem against a subscription invoice. Creating, listing, updating, and deleting codes is System Admin only; redeeming and previewing a discount are parent-facing but included here since they're reachable from the admin dashboard's voucher-redeemer lookup too.

7 endpoint(s)

GET List Vouchers {{url}}/subscription-voucher-codes ▸

Paginated, filterable list of subscription voucher codes — the admin dashboard's System Settings → Vouchers tab.

Query Parameters

status (string, optional): pending or used.
code (string, optional): partial match.
parent_id (integer, optional): filter by the redeeming user's internal id.
search (string, optional): matches code or the redeeming user's name/email.
per_page (integer, optional, max 100).

Notes

Requires a bearer token (auth:api).

Auth

Bearer token

Sample Response (200 OK)

{
    "status": 200,
    "data": {
        "data": [
            {
                "id": "a1b2c3d4-1111-4a11-8888-abcde1234567",
                "code": "TERRA-FREE-2026",
                "amount": 1500,
                "duration": 1,
                "user_id": null,
                "status": "pending",
                "created_at": "2026-07-13T10:00:00.000000Z",
                "updated_at": "2026-07-13T10:00:00.000000Z"
            }
        ],
        "total": 1,
        "per_page": 20,
        "current_page": 1,
        "last_page": 1
    },
    "message": "success"
}

POST Create Voucher {{url}}/subscription-voucher-codes/add ▸

Create a new subscription voucher code.

Request Body

code (string, required, unique).
amount (number, required, min 0).
duration (integer, required): number of billing cycles the voucher discounts; -1 means forever (see SubscriptionVoucherCode::DURATION_FOREVER).

Notes

Requires a bearer token (auth:api).

Auth

Bearer token

Request Body

{
    "code": "TERRA-FREE-2026",
    "amount": 1500,
    "duration": 1
}

Sample Response (200 OK)

{
    "status": 200,
    "data": {
        "id": "a1b2c3d4-1111-4a11-8888-abcde1234567",
        "code": "TERRA-FREE-2026",
        "amount": 1500,
        "duration": 1,
        "user_id": null,
        "status": "pending",
        "created_at": "2026-07-13T10:00:00.000000Z",
        "updated_at": "2026-07-13T10:00:00.000000Z"
    },
    "message": "Voucher created successfully"
}

GET Get Voucher {{url}}/subscription-voucher-codes/a1b2c3d4-1111-4a11-8888-abcde1234567 ▸

Retrieve a single voucher code by UUID.

Notes

Requires a bearer token (auth:api).

Auth

Bearer token

Sample Response (200 OK)

{
    "status": 200,
    "data": {
        "id": "a1b2c3d4-1111-4a11-8888-abcde1234567",
        "code": "TERRA-FREE-2026",
        "amount": 1500,
        "duration": 1,
        "user_id": null,
        "status": "pending",
        "created_at": "2026-07-13T10:00:00.000000Z",
        "updated_at": "2026-07-13T10:00:00.000000Z"
    },
    "message": "success"
}

PUT Update Voucher {{url}}/subscription-voucher-codes/update/a1b2c3d4-1111-4a11-8888-abcde1234567 ▸

Update a voucher's code, amount, duration, or status.

Request Body (all optional)

code (string, unique).
amount (number, min 0).
duration (integer).
status (string): pending/Pending or used/Used.

Notes

Requires a bearer token (auth:api).

Auth

Bearer token

Request Body

{
    "amount": 2000
}

Sample Response (200 OK)

{
    "status": 200,
    "data": {
        "id": "a1b2c3d4-1111-4a11-8888-abcde1234567",
        "code": "TERRA-FREE-2026",
        "amount": 2000,
        "duration": 1,
        "user_id": null,
        "status": "pending",
        "created_at": "2026-07-13T10:00:00.000000Z",
        "updated_at": "2026-07-13T10:00:00.000000Z"
    },
    "message": "Voucher updated successfully"
}

DELETE Delete Voucher {{url}}/subscription-voucher-codes/delete/a1b2c3d4-1111-4a11-8888-abcde1234567 ▸

Soft-delete a voucher code.

Notes

Requires a bearer token (auth:api).

Auth

Bearer token

Sample Response (200 OK)

{
    "status": 200,
    "data": null,
    "message": "Voucher deleted successfully"
}

POST Redeem Voucher {{url}}/subscription-voucher-codes/redeem ▸

A parent redeems a voucher code, attaching it to their account and (if they have a pending invoice) applying its discount immediately.

Request Body

code (string, required).
parent_id (string UUID, required).

Notes

Not admin-only in principle (parent-facing), but reachable from the admin dashboard's voucher-redeemer lookup.
Requires a bearer token (auth:api).

Auth

Bearer token

Request Body

{
    "code": "TERRA-FREE-2026",
    "parent_id": "35438f0b-b488-4ea0-b69d-73e214910ab9"
}

Sample Response (200 OK)

{
    "status": 200,
    "data": {
        "voucher": {
            "id": "a1b2c3d4-1111-4a11-8888-abcde1234567",
            "code": "TERRA-FREE-2026",
            "amount": 1500,
            "duration": 1,
            "user_id": null,
            "status": "used",
            "created_at": "2026-07-13T10:00:00.000000Z",
            "updated_at": "2026-07-13T10:00:00.000000Z"
        },
        "user": {
            "id": "35438f0b-b488-4ea0-b69d-73e214910ab9",
            "is_active": true
        },
        "invoices_updated": [],
        "total_discount_applied": 1500,
        "remaining_duration": 0,
        "user_is_active": true
    },
    "message": "Voucher redeemed and applied successfully"
}

POST Preview Voucher Discount {{url}}/subscription-voucher-codes/apply-discount ▸

Preview how much of a subscription amount a parent's pending voucher would discount, without consuming the voucher.

Request Body

parent_id (string UUID, required).
subscription_amount (number, required, min 0).

Notes

Requires a bearer token (auth:api).

Auth

Bearer token

Request Body

{
    "parent_id": "35438f0b-b488-4ea0-b69d-73e214910ab9",
    "subscription_amount": 1500
}

Sample Response (200 OK)

{
    "status": 200,
    "data": {
        "discount_amount": 1500,
        "final_amount": 0,
        "has_voucher": true,
        "voucher_code": "TERRA-FREE-2026",
        "remaining_duration": 0
    },
    "message": "success"
}