Voucher pools and codes tools

list_voucher_pools: List the voucher pools in a project.
get_voucher_pool: Get the full details of a voucher pool.
list_voucher_codes: List the individual codes inside a pool.

list_voucher_pools

Lists every voucher pool in a project. Voucher pools are named collections of unique discount or promo codes that campaigns draw from when sending to customers. The response gives you each pool's name, the total number of codes, and how many are still available.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.

Response parameters

The tool returns a VoucherPoolsResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`list[VoucherPoolSummary]`	The voucher pools defined in the project.
`error`	`str \| null`	Error message if the request failed.

The VoucherPoolSummary object has the following fields:

Field	Type	Description
`id`	`str`	The voucher pool's unique ID.
`name`	`str`	The pool's display name. Unique within the project.
`total`	`int`	The total number of codes in the pool.
`available`	`int`	The number of codes still available (not yet assigned or redeemed).

get_voucher_pool

Returns the full details of a single voucher pool, including the pool's name, code counts, and a used_by list of the campaigns or resources that draw from it. Use list_voucher_codes to inspect the individual codes inside the pool.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.
`pool_id`	`str`	Yes	The voucher pool ID returned by `list_voucher_pools`.

Response parameters

The tool returns a VoucherPoolResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`VoucherPool \| null`	The full voucher pool record.
`error`	`str \| null`	Error message if the request failed.

The VoucherPool object adds the following fields on top of the summary record:

Field	Type	Description
`company_id`	`str`	The project ID this pool belongs to.
`used_by`	`list[any]`	Campaigns or other resources that draw from this pool.

list_voucher_codes

Lists the individual codes inside a voucher pool. Each code has a status — available (not yet used), assigned (given to a customer but not redeemed), or redeemed (fully used) — plus assignment and redemption timestamps where applicable. There is no detail endpoint for individual codes; this list is the only way to inspect them.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.
`pool_id`	`str`	Yes	The voucher pool ID returned by `list_voucher_pools`.
`skip`	`int`	No	Pagination offset. Defaults to 0.
`count`	`int`	No	Number of codes to return. Defaults to 20. Maximum 1,000.

Response parameters

The tool returns a VoucherCodesResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`list[VoucherCode]`	The voucher code records on this page.
`matched`	`int \| null`	The total number of codes in the pool that match the current filter.
`matched_limited`	`bool \| null`	Whether the matched count was capped by a server limit.
`skip`	`int`	The pagination offset that was applied.
`limit`	`int`	The maximum number of records returned.
`error`	`str \| null`	Error message if the request failed.

The VoucherCode object has the following fields:

Field	Type	Description
`code`	`str`	The voucher code string, for example `SUMMER20` or `ABC-123`.
`status`	`str`	One of `available`, `assigned` (given but not redeemed), or `redeemed`.
`assigned_time`	`float \| null`	Unix timestamp of when the code was assigned to a customer.
`redeemed_time`	`float \| null`	Unix timestamp of when the code was redeemed.