Voucher pools and codes tools

search_voucher_pools: List the voucher pools in a project, or fetch one by ID.
list_voucher_codes: List the individual codes inside a pool.

search_voucher_pools

Searches the voucher pools in a project, or fetches one by ID. Voucher pools are named collections of unique discount or promo codes that campaigns draw from when sending to customers. Omit pool_id to list all voucher pools — you get each pool's name, the total number of codes, and how many are still available. Pass pool_id to fetch the full details of a single pool, including a used_by list of the campaigns or resources that draw from it. Use list_voucher_codes to inspect the individual codes inside a pool.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.
`pool_id`	`str \| null`	No	The voucher pool ID for direct lookup. Omit to list all; provide to fetch one.

Response parameters

The tool returns a VoucherPoolsResponse when pool_id is omitted, or a VoucherPoolResponse when it's provided.

The VoucherPoolsResponse object has 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).

The VoucherPoolResponse object has 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 `search_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.