Voucher

29 operations. Call any of them with omada_call_operation (or, in full tool mode, as a tool named by its operationId).

Operation	Method	Summary
exportVouchersWithSiteByCloudAccess	POST	Export voucher list to file
uploadVoucherLogo	POST	Upload voucher logo
getVoucherLogo	GET	Get voucher logo
modifyHotspotSetting	PATCH	Modify voucher currency
getVoucherGroupOptions	GET	Get voucher group options
getGridVoucherGroups	GET	Get Voucher Group List
createVoucherGroup	POST	Create a new Voucher Group
deleteVoucherGroup	DELETE	Delete an existing Voucher Group
getVoucherGroupDetail	GET	Get Voucher Group Detail
clearInvalidVouchersInaGroup	DELETE	Delete expired vouchers in a voucher group
editVoucherGroupPattern	PATCH	Edit voucher group pattern
printVoucherGroup	GET	Get unused vouchers in voucher group
clearInvalidVouchersInSelectedGroups	POST	Delete expired vouchers in voucher groups
deleteSelectedVoucherGroups	POST	Delete selected Voucher Groups
printSelectedVoucherGroups	POST	Get unused vouchers in selected voucher groups
getGroupConfigLimit	GET	Get voucher group config limit
getVoucherCurrencyCandidates	GET	Get voucher currency candidates
deleteVoucher	DELETE	Delete an existing voucher
getVoucher	GET	Get a voucher
deleteVouchers	POST	Delete selected vouchers
printVouchers	POST	Get selected vouchers in a voucher group
getVoucherHistoryStatistics	GET	Get voucher history statistics
getVoucherDistributionByDuration	GET	Get voucher distribution by duration
getVoucherDistributionByDurationForGroup	GET	Get voucher distribution of voucher group by duration
getVoucherDistributionByPrice	GET	Get voucher distribution by price
getVoucherDistributionByPriceForGroup	GET	Get voucher distribution of voucher group by price
getVoucherHistoryStatisticsForGroup	GET	Get voucher history statistics of voucher group
getAllTimeVoucherSummary	GET	Get voucher summary
getAllTimeVoucherSummaryForGroup	GET	Get voucher summary for voucher group

exportVouchersWithSiteByCloudAccess

POST /openapi/v1/{omadacId}/files/hotspot/sites/{siteId}/vouchers/export

Export voucher list to file

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)

Request body — application/json (required) — schema ExportVoucherOpenApiVO

Field	Type	Required	Description
format	integer	yes	Export file format, should be a value as follows: 0: csv, 1: xlsx
queryData	OpenApiQueryDataVO	no	(OpenApiQueryDataVO not expanded; call omada_get_schema "OpenApiQueryDataVO")
type	integer	yes	Select type. It should be a value as follows: 0: Represents selecting all voucher groups, this selection does not pass parameter [groupIds]. 1: Parameter [groupIds] includes the IDs of the voucher groups to be selected. 2: Parameter [groupIds] includes the IDs of the voucher groups not to be selected
groupIds	array<string>	no	ID list of voucher groups. Voucher group can be created using 'Create Voucher Group' interface, and Voucher Group ID can be obtained from 'Get Voucher Group list' interface

// omada_call_operation
{
  "operationId": "exportVouchersWithSiteByCloudAccess",
  "params": {
    "siteId": "<siteId>"
  },
  "body": "{...}"
}

Details, permissions and error codes

Export voucher list to file.
The interface requires one of the permissions:
Site Export Data Access
The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-33000 - This site does not exist.
-33004 - Operation failed because other operations (site copying, restoring, template synchronizing, etc.) are being performed on this site. Please wait and try again later.
-44111 - The Grant Type is Invalid.
-44112 - The access token has expired. Please re-initiate the refreshToken process to obtain the access token.

uploadVoucherLogo

POST /openapi/v1/{omadacId}/sites/{siteId}/hotspot/files/voucher/logos

Upload voucher logo

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)

Request body — multipart/form-data (optional). File field(s): file.

Other form fields (sent as JSON parts): data.

// omada_call_operation
{
  "operationId": "uploadVoucherLogo",
  "params": {
    "siteId": "<siteId>"
  },
  "body": {
    "data": "{...}"
  },
  "files": {
    "file": {
      "path": "/path/to/file"
    }
  }
}

Details, permissions and error codes

Upload voucher logo
The interface requires one of the permissions:
Site Hotspot Manager Modify

getVoucherLogo

GET /openapi/v1/{omadacId}/sites/{siteId}/hotspot/files/voucher/logos/{picId}

Get voucher logo

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)
picId	path	string	yes	Voucher logo picture id

// omada_call_operation
{
  "operationId": "getVoucherLogo",
  "params": {
    "siteId": "<siteId>",
    "picId": "<picId>"
  }
}

Details, permissions and error codes

Get voucher logo
The interface requires one of the permissions:
Site Hotspot Manager View Only

modifyHotspotSetting

PATCH /openapi/v1/{omadacId}/sites/{siteId}/hotspot/setting

Modify voucher currency

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)

Request body — application/json (required) — schema HotspotSiteSettingOpenApiVO

Field	Type	Required	Description
currency	string	no	Currency Short Code of voucher. For the values of Currency Short Code, refer to section 5.4.2 of the Open API Access Guide.

// omada_call_operation
{
  "operationId": "modifyHotspotSetting",
  "params": {
    "siteId": "<siteId>"
  },
  "body": "{...}"
}

Details, permissions and error codes

Modify voucher currency of the site.
The interface requires one of the permissions:
Site Hotspot Manager Modify
The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-33000 - This site does not exist.
-33004 - Operation failed because other operations (site copying, restoring, template synchronizing, etc.) are being performed on this site. Please wait and try again later.
-44111 - The Grant Type is Invalid.
-44112 - The access token has expired. Please re-initiate the refreshToken process to obtain the access token.

getVoucherGroupOptions

GET /openapi/v1/{omadacId}/sites/{siteId}/hotspot/voucher-group-options

Get voucher group options

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)
page	query	integer	no	Start page number. Start from 1. (default 1)
pageSize	query	integer	no	Number of entries per page. It should be within the range of 1–1000. (default 100)

// omada_call_operation
{
  "operationId": "getVoucherGroupOptions",
  "params": {
    "siteId": "<siteId>"
  }
}

Details, permissions and error codes

Get voucher group options.
The interface requires one of the permissions:
Site Hotspot Manager View Only
The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-33000 - This site does not exist.
-33004 - Operation failed because other operations (site copying, restoring, template synchronizing, etc.) are being performed on this site. Please wait and try again later.
-44111 - The Grant Type is Invalid.
-44112 - The access token has expired. Please re-initiate the refreshToken process to obtain the access token.

getGridVoucherGroups

GET /openapi/v1/{omadacId}/sites/{siteId}/hotspot/voucher-groups

Get Voucher Group List

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)
page	query	integer	no	Start page number. Start from 1. (default 1)
pageSize	query	integer	no	Number of entries per page. It should be within the range of 1–1000. (default 100)
sorts.name	query	string	no	Sort parameter may be one of asc or desc. Optional parameter. If it is not carried, it means it is not sorted by this field. When there are more than one, the first one takes effect
sorts.createTime	query	string	no	Sort parameter may be one of asc or desc. Optional parameter. If it is not carried, it means it is not sorted by this field. When there are more than one, the first one takes effect
filters.timeStart	query	integer	no	Filter query parameters, support field time range: start timestamp (ms).
filters.timeEnd	query	integer	no	Filter query parameters, support field time range: end timestamp (ms).
searchKey	query	string	no	Fuzzy query parameters, support field name

// omada_call_operation
{
  "operationId": "getGridVoucherGroups",
  "params": {
    "siteId": "<siteId>"
  }
}

Details, permissions and error codes

Get Voucher Group List with the given params.
The interface requires one of the permissions:
Site Hotspot Manager View Only
The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-33000 - This site does not exist.
-33004 - Operation failed because other operations (site copying, restoring, template synchronizing, etc.) are being performed on this site. Please wait and try again later.
-44111 - The Grant Type is Invalid.
-44112 - The access token has expired. Please re-initiate the refreshToken process to obtain the access token.

createVoucherGroup

POST /openapi/v1/{omadacId}/sites/{siteId}/hotspot/voucher-groups

Create a new Voucher Group

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)

Request body — application/json (required) — schema CreateVoucherGroupOpenApiVO

Field	Type	Required	Description
name	string	yes	Voucher group name. It should contain 1-32 characters
amount	integer	yes	The amount of vouchers created. It should be within the range of 1-5000
codeLength	integer	yes	The length of voucher code. It should be within the range of 6–10.
codeForm	array<integer>	yes	The character types contained in the voucher code. It should be a value as follows: 0: Number, 1: Letter. For example, [0] indicates that the code only contains numbers; [0, 1] indicates that the code contains numbers and letters
limitType	integer	yes	The limitations of the voucher. It should be a value as follows: 0: Limited Usage Counts, 1: Limited Online Users, 2: Unlimited
limitNum	integer	no	The number of limitations. It should be within the range of 1–999. If Parameter [limitType] is 0 or 1, [limitNum] should not be null.When Parameter [limitType] is 0, [limitNum] represents the maximum number of times this voucher can be used.When Parameter [limitType] is 1, [limitNum] represents the maximum number of users this voucher can be used at the same time.
durationType	integer	yes	The duration type of the voucher. It should be a value as follows: 0: Client duration, each client expires after the duration is used. 1: Voucher duration, after reaching the voucher duration, clients using the voucher will expire
duration	integer	yes	Duration of one use, unit: minute. It should be within the range of 1–14400000.
timingType	integer	yes	The timing type of the voucher. It should be a value as follows: 0: Timing by time, clients can use vouchers for specified time duration. 1: Timing by usage, clients can use vouchers for the duration of actual usage
rateLimit	RateLimitOpenApiVO	yes	(RateLimitOpenApiVO not expanded; call omada_get_schema "RateLimitOpenApiVO")
trafficLimitEnable	boolean	yes	Whether to enable traffic limit
trafficLimit	integer	no	Traffic limit in MB. It should be within the range of 1–10485760
trafficLimitFrequency	integer	no	Frequency of traffic limit should be a value as follows: 0: total; 1: daily; 2: weekly; 3: monthly.
unitPrice	integer	no	Price of single voucher. It should be within the range of 1–999999999
currency	string	no	Currency Short Code of voucher. For the values of Currency Short Code, refer to section 5.4.2 of the Open API Access Guide.
applyToAllPortals	boolean	yes	Is the voucher effective for all portals, including all newly created portals
portals	array<string>	no	Bound portal ID list. Portal can be created using 'Add portal' interface, and portal ID can be obtained from 'Get portal list in a site' interface
expirationTime	integer	no	The timestamp of the expiration of the voucher, unit: millisecond. When parameter [validityType] is 1, parameter [expirationTime] is required
effectiveTime	integer	no	The timestamp when the voucher takes effect, unit: millisecond. When parameter [validityType] is 1, parameter [effectiveTime] is required
logout	boolean	no	Whether the voucher support portal logout functionality
description	string	no	Description of the voucher group
printComments	string	no	Print comments of the voucher group
validityType	integer	no	The validity type of the voucher. It should be a value as follows: 0: Voucher can be used at any time, parameter [effectiveTime], [expirationTime] and [schedule] should be null. 1: Voucher can be used between the effective time and expiration time, parameter [effectiveTime] and [expirationTime] should not be null, parameter [schedule] should be null. 2: Voucher can be used within a specified time period by schedule, parameter [effectiveTime] and [expirationTime] should be null, parameter [schedule] should not be null
schedule	VoucherScheduleOpenApiVO	no	(VoucherScheduleOpenApiVO not expanded; call omada_get_schema "VoucherScheduleOpenApiVO")

// omada_call_operation
{
  "operationId": "createVoucherGroup",
  "params": {
    "siteId": "<siteId>"
  },
  "body": "{...}"
}

Details, permissions and error codes

Create a Voucher Group with the given params.
The interface requires one of the permissions:
Site Hotspot Manager Modify
The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-33000 - This site does not exist.
-33004 - Operation failed because other operations (site copying, restoring, template synchronizing, etc.) are being performed on this site. Please wait and try again later.
-33732 - The Rate Limit profile does not exist.
-42010 - The number of vouchers has reached the limit. New vouchers cannot be created.
-42036 - Please select at least one portal before creating vouchers.
-42059 - Duplicated voucher group name.
-42060 - Currency is not supported.
-42061 - You are creating voucher groups with different currency in same site, this will prevent collecting incoming amount of vouchers.
-42062 - One or more portals may not exist.
-42063 - The expiration time cannot exceed 1000 days.
-44111 - The Grant Type is Invalid.
-44112 - The access token has expired. Please re-initiate the refreshToken process to obtain the access token.

deleteVoucherGroup

DELETE /openapi/v1/{omadacId}/sites/{siteId}/hotspot/voucher-groups/{groupId}

Delete an existing Voucher Group

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)
groupId	path	string	yes	Voucher Group ID

// omada_call_operation
{
  "operationId": "deleteVoucherGroup",
  "params": {
    "siteId": "<siteId>",
    "groupId": "<groupId>"
  }
}

Details, permissions and error codes

Delete an existing Voucher Group with the given params.
The interface requires one of the permissions:
Site Hotspot Manager Modify
The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-33000 - This site does not exist.
-33004 - Operation failed because other operations (site copying, restoring, template synchronizing, etc.) are being performed on this site. Please wait and try again later.
-44111 - The Grant Type is Invalid.
-44112 - The access token has expired. Please re-initiate the refreshToken process to obtain the access token.

getVoucherGroupDetail

GET /openapi/v1/{omadacId}/sites/{siteId}/hotspot/voucher-groups/{groupId}

Get Voucher Group Detail

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)
groupId	path	string	yes	Voucher Group ID
page	query	integer	no	Start page number. Start from 1. (default 1)
pageSize	query	integer	no	Number of entries per page. It should be within the range of 1–1000. (default 100)
sorts.code	query	string	no	Sort parameter may be one of asc or desc. Optional parameter. If it is not carried, it means it is not sorted by this field. When there are more than one, the first one takes effect
filters.status	query	integer	no	Filter query parameters, support field status for vouchers in the voucher group: 0: unused vouchers, 1: in-use vouchers, 2: expired vouchers
searchKey	query	string	no	Fuzzy query parameters, support field code

// omada_call_operation
{
  "operationId": "getVoucherGroupDetail",
  "params": {
    "siteId": "<siteId>",
    "groupId": "<groupId>"
  }
}

Details, permissions and error codes

Get Voucher Group Detail with the given params.
The interface requires one of the permissions:
Site Hotspot Manager View Only
The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-33000 - This site does not exist.
-33004 - Operation failed because other operations (site copying, restoring, template synchronizing, etc.) are being performed on this site. Please wait and try again later.
-44111 - The Grant Type is Invalid.
-44112 - The access token has expired. Please re-initiate the refreshToken process to obtain the access token.

clearInvalidVouchersInaGroup

DELETE /openapi/v1/{omadacId}/sites/{siteId}/hotspot/voucher-groups/{groupId}/clear-invalid

Delete expired vouchers in a voucher group

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)
groupId	path	string	yes	Voucher Group ID

// omada_call_operation
{
  "operationId": "clearInvalidVouchersInaGroup",
  "params": {
    "siteId": "<siteId>",
    "groupId": "<groupId>"
  }
}

Details, permissions and error codes

Delete expired vouchers in a voucher group.
The interface requires one of the permissions:
Site Hotspot Manager Modify
The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-33000 - This site does not exist.
-33004 - Operation failed because other operations (site copying, restoring, template synchronizing, etc.) are being performed on this site. Please wait and try again later.
-44111 - The Grant Type is Invalid.
-44112 - The access token has expired. Please re-initiate the refreshToken process to obtain the access token.

editVoucherGroupPattern

PATCH /openapi/v1/{omadacId}/sites/{siteId}/hotspot/voucher-groups/{groupId}/pattern

Edit voucher group pattern

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)
groupId	path	string	yes	Voucher group ID

Request body — application/json (required) — schema EditVoucherGroupPatternOpenApiVO

Field	Type	Required	Description
patternType	integer	no	0: Logo, 1: Title, 2: Disable
position	integer	no	0: Left, 1: Right, 2: Middle
logoPictureId	string	no	Logo picture ID
logoSize	integer	no	Logo size. It should be within the range of 50-175
title	string	no	Voucher title
titleSize	integer	no	Voucher title size. It should be within the range of 12-18
ssidNetworkenable	boolean	no	Whether to print SSIDs and networks on the pattern of the voucher
ssidList	array<string>	no	SSID list on the pattern of the voucher
networkList	array<string>	no	Network list on the pattern of the voucher
durationEnable	boolean	no	Whether to print duration of the voucher
limitEnable	boolean	no	Whether to print limit information of the voucher
printComments	string	no	Comments to print on the voucher

// omada_call_operation
{
  "operationId": "editVoucherGroupPattern",
  "params": {
    "siteId": "<siteId>",
    "groupId": "<groupId>"
  },
  "body": "{...}"
}

Details, permissions and error codes

Edit vouvhcer group pattern.
The interface requires one of the permissions:
Site Hotspot Manager Modify
The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-34338 - Some SSIDs do not exist.
-34340 - Some lan networks do not exist.
-42068 - Wrong SSID or Network was selected in the Voucher pattern.
-42069 - The Logo image of the Voucher pattern does not exist.

printVoucherGroup

GET /openapi/v1/{omadacId}/sites/{siteId}/hotspot/voucher-groups/{groupId}/print-unused

Get unused vouchers in voucher group

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)
groupId	path	string	yes	Voucher Group ID

// omada_call_operation
{
  "operationId": "printVoucherGroup",
  "params": {
    "siteId": "<siteId>",
    "groupId": "<groupId>"
  }
}

Details, permissions and error codes

Get unused vouchers brief information in a voucher group.
The interface requires one of the permissions:
Site Hotspot Manager View Only
The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-33000 - This site does not exist.
-33004 - Operation failed because other operations (site copying, restoring, template synchronizing, etc.) are being performed on this site. Please wait and try again later.
-44111 - The Grant Type is Invalid.
-44112 - The access token has expired. Please re-initiate the refreshToken process to obtain the access token.

clearInvalidVouchersInSelectedGroups

POST /openapi/v1/{omadacId}/sites/{siteId}/hotspot/voucher-groups/batch/clear-invalid

Delete expired vouchers in voucher groups

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)

Request body — application/json (required) — schema SelectVoucherGroupOpenApiVO

Field	Type	Required	Description
type	integer	yes	Select type. It should be a value as follows: 0: Represents selecting all voucher groups, this selection does not pass parameter [groupIds]. 1: Parameter [groupIds] includes the IDs of the voucher groups to be selected. 2: Parameter [groupIds] includes the IDs of the voucher groups not to be selected
groupIds	array<string>	no	ID list of voucher groups. Voucher group can be created using 'Create Voucher Group' interface, and Voucher Group ID can be obtained from 'Get Voucher Group list' interface
searchKey	string	no	Fuzzy query parameters, support field: voucher group name, voucher code
timeStart	integer	no	End timestamp filter query parameters, unit: MS

// omada_call_operation
{
  "operationId": "clearInvalidVouchersInSelectedGroups",
  "params": {
    "siteId": "<siteId>"
  },
  "body": "{...}"
}

Details, permissions and error codes

Delete expired vouchers in selected voucher group.
The interface requires one of the permissions:
Site Hotspot Manager Modify
The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-33000 - This site does not exist.
-33004 - Operation failed because other operations (site copying, restoring, template synchronizing, etc.) are being performed on this site. Please wait and try again later.
-44111 - The Grant Type is Invalid.
-44112 - The access token has expired. Please re-initiate the refreshToken process to obtain the access token.

deleteSelectedVoucherGroups

POST /openapi/v1/{omadacId}/sites/{siteId}/hotspot/voucher-groups/batch/delete

Delete selected Voucher Groups

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)

Request body — application/json (required) — schema SelectVoucherGroupOpenApiVO

Field	Type	Required	Description
type	integer	yes	Select type. It should be a value as follows: 0: Represents selecting all voucher groups, this selection does not pass parameter [groupIds]. 1: Parameter [groupIds] includes the IDs of the voucher groups to be selected. 2: Parameter [groupIds] includes the IDs of the voucher groups not to be selected
groupIds	array<string>	no	ID list of voucher groups. Voucher group can be created using 'Create Voucher Group' interface, and Voucher Group ID can be obtained from 'Get Voucher Group list' interface
searchKey	string	no	Fuzzy query parameters, support field: voucher group name, voucher code
timeStart	integer	no	End timestamp filter query parameters, unit: MS

// omada_call_operation
{
  "operationId": "deleteSelectedVoucherGroups",
  "params": {
    "siteId": "<siteId>"
  },
  "body": "{...}"
}

Details, permissions and error codes

Delete selected Voucher Groups with the given params.
The interface requires one of the permissions:
Site Hotspot Manager Modify
The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-33000 - This site does not exist.
-33004 - Operation failed because other operations (site copying, restoring, template synchronizing, etc.) are being performed on this site. Please wait and try again later.
-44111 - The Grant Type is Invalid.
-44112 - The access token has expired. Please re-initiate the refreshToken process to obtain the access token.

printSelectedVoucherGroups

POST /openapi/v1/{omadacId}/sites/{siteId}/hotspot/voucher-groups/batch/print-unused

Get unused vouchers in selected voucher groups

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)

Request body — application/json (required) — schema SelectVoucherGroupOpenApiVO

Field	Type	Required	Description
type	integer	yes	Select type. It should be a value as follows: 0: Represents selecting all voucher groups, this selection does not pass parameter [groupIds]. 1: Parameter [groupIds] includes the IDs of the voucher groups to be selected. 2: Parameter [groupIds] includes the IDs of the voucher groups not to be selected
groupIds	array<string>	no	ID list of voucher groups. Voucher group can be created using 'Create Voucher Group' interface, and Voucher Group ID can be obtained from 'Get Voucher Group list' interface
searchKey	string	no	Fuzzy query parameters, support field: voucher group name, voucher code
timeStart	integer	no	End timestamp filter query parameters, unit: MS

// omada_call_operation
{
  "operationId": "printSelectedVoucherGroups",
  "params": {
    "siteId": "<siteId>"
  },
  "body": "{...}"
}

Details, permissions and error codes

Get unused vouchers brief information in selected voucher groups.
The interface requires one of the permissions:
Site Hotspot Manager View Only
The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-33000 - This site does not exist.
-33004 - Operation failed because other operations (site copying, restoring, template synchronizing, etc.) are being performed on this site. Please wait and try again later.
-44111 - The Grant Type is Invalid.
-44112 - The access token has expired. Please re-initiate the refreshToken process to obtain the access token.

getGroupConfigLimit

GET /openapi/v1/{omadacId}/sites/{siteId}/hotspot/voucher-groups/config-limit

Get voucher group config limit

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)

// omada_call_operation
{
  "operationId": "getGroupConfigLimit",
  "params": {
    "siteId": "<siteId>"
  }
}

Details, permissions and error codes

Get voucher group config limit.
The interface requires one of the permissions:
Site Hotspot Manager View Only
The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-33000 - This site does not exist.
-33004 - Operation failed because other operations (site copying, restoring, template synchronizing, etc.) are being performed on this site. Please wait and try again later.
-44111 - The Grant Type is Invalid.
-44112 - The access token has expired. Please re-initiate the refreshToken process to obtain the access token.

getVoucherCurrencyCandidates

GET /openapi/v1/{omadacId}/sites/{siteId}/hotspot/voucher-groups/currency-list

Get voucher currency candidates

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)

// omada_call_operation
{
  "operationId": "getVoucherCurrencyCandidates",
  "params": {
    "siteId": "<siteId>"
  }
}

Details, permissions and error codes

Get voucher currency candidates.
The interface requires one of the permissions:
Site Hotspot Manager View Only
The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-33000 - This site does not exist.
-33004 - Operation failed because other operations (site copying, restoring, template synchronizing, etc.) are being performed on this site. Please wait and try again later.
-44111 - The Grant Type is Invalid.
-44112 - The access token has expired. Please re-initiate the refreshToken process to obtain the access token.

deleteVoucher

DELETE /openapi/v1/{omadacId}/sites/{siteId}/hotspot/vouchers/{id}

Delete an existing voucher

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)
id	path	string	yes	Voucher ID

// omada_call_operation
{
  "operationId": "deleteVoucher",
  "params": {
    "siteId": "<siteId>",
    "id": "<id>"
  }
}

Details, permissions and error codes

Delete an existing voucher with the given params.
The interface requires one of the permissions:
Site Hotspot Manager Modify
The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-33000 - This site does not exist.
-33004 - Operation failed because other operations (site copying, restoring, template synchronizing, etc.) are being performed on this site. Please wait and try again later.
-44111 - The Grant Type is Invalid.
-44112 - The access token has expired. Please re-initiate the refreshToken process to obtain the access token.

getVoucher

GET /openapi/v1/{omadacId}/sites/{siteId}/hotspot/vouchers/{id}

Get a voucher

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)
id	path	string	yes	Voucher ID

// omada_call_operation
{
  "operationId": "getVoucher",
  "params": {
    "siteId": "<siteId>",
    "id": "<id>"
  }
}

Details, permissions and error codes

Get a voucher with the given params.
The interface requires one of the permissions:
Site Hotspot Manager View Only
The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-33000 - This site does not exist.
-33004 - Operation failed because other operations (site copying, restoring, template synchronizing, etc.) are being performed on this site. Please wait and try again later.
-44111 - The Grant Type is Invalid.
-44112 - The access token has expired. Please re-initiate the refreshToken process to obtain the access token.

deleteVouchers

POST /openapi/v1/{omadacId}/sites/{siteId}/hotspot/vouchers/batch/delete

Delete selected vouchers

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)

Request body — application/json (required) — schema SelectIdsOpenApiVO

Field	Type	Required	Description
type	integer	yes	Select type. It should be a value as follows: 0: Represents selecting all vouchers in the voucher group, this selection does not pass parameter [ids]. 1: Parameter [ids] includes the IDs of vouchers in the voucher group to be selected. 2: Parameter [ids] includes the IDs of vouchers in the voucher group not to be selected
ids	array<string>	no	ID list of vouchers. Voucher can be created using 'Create Voucher Group' interface, and Voucher ID can be obtained from 'Get Voucher Group Detail' interface
groupId	string	yes	Voucher Group ID. Voucher group can be created using 'Create Voucher Group' interface, and Voucher Group ID can be obtained from 'Get Voucher Group list' interface
searchKey	string	no	Fuzzy query parameters, support field: voucher code
status	integer	no	voucher status filter query parameters. It should be a value as follows: 0: Unused vouchers, 1: In use vouchers, 2: Expired vouchers

// omada_call_operation
{
  "operationId": "deleteVouchers",
  "params": {
    "siteId": "<siteId>"
  },
  "body": "{...}"
}

Details, permissions and error codes

Delete selected vouchers with the given params.
The interface requires one of the permissions:
Site Hotspot Manager Modify
The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-33000 - This site does not exist.
-33004 - Operation failed because other operations (site copying, restoring, template synchronizing, etc.) are being performed on this site. Please wait and try again later.
-44111 - The Grant Type is Invalid.
-44112 - The access token has expired. Please re-initiate the refreshToken process to obtain the access token.

printVouchers

POST /openapi/v1/{omadacId}/sites/{siteId}/hotspot/vouchers/batch/print

Get selected vouchers in a voucher group

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)

Request body — application/json (required) — schema SelectIdsOpenApiVO

Field	Type	Required	Description
type	integer	yes	Select type. It should be a value as follows: 0: Represents selecting all vouchers in the voucher group, this selection does not pass parameter [ids]. 1: Parameter [ids] includes the IDs of vouchers in the voucher group to be selected. 2: Parameter [ids] includes the IDs of vouchers in the voucher group not to be selected
ids	array<string>	no	ID list of vouchers. Voucher can be created using 'Create Voucher Group' interface, and Voucher ID can be obtained from 'Get Voucher Group Detail' interface
groupId	string	yes	Voucher Group ID. Voucher group can be created using 'Create Voucher Group' interface, and Voucher Group ID can be obtained from 'Get Voucher Group list' interface
searchKey	string	no	Fuzzy query parameters, support field: voucher code
status	integer	no	voucher status filter query parameters. It should be a value as follows: 0: Unused vouchers, 1: In use vouchers, 2: Expired vouchers

// omada_call_operation
{
  "operationId": "printVouchers",
  "params": {
    "siteId": "<siteId>"
  },
  "body": "{...}"
}

Details, permissions and error codes

Get selected vouchers brief in a voucher group.
The interface requires one of the permissions:
Site Hotspot Manager View Only
The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-33000 - This site does not exist.
-33004 - Operation failed because other operations (site copying, restoring, template synchronizing, etc.) are being performed on this site. Please wait and try again later.
-44111 - The Grant Type is Invalid.
-44112 - The access token has expired. Please re-initiate the refreshToken process to obtain the access token.

getVoucherHistoryStatistics

GET /openapi/v1/{omadacId}/sites/{siteId}/hotspot/vouchers/statistics/history

Get voucher history statistics

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)
filters.timeStart	query	integer	yes	Filter query parameters, support field time range: start timestamp (second).
filters.timeEnd	query	integer	yes	Filter query parameters, support field time range: end timestamp (second).

// omada_call_operation
{
  "operationId": "getVoucherHistoryStatistics",
  "params": {
    "siteId": "<siteId>",
    "filters.timeStart": "<filters.timeStart>",
    "filters.timeEnd": "<filters.timeEnd>"
  }
}

Details, permissions and error codes

Get voucher history statistics.
The interface requires one of the permissions:
Site Hotspot Manager View Only
The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-33000 - This site does not exist.
-33004 - Operation failed because other operations (site copying, restoring, template synchronizing, etc.) are being performed on this site. Please wait and try again later.
-44111 - The Grant Type is Invalid.
-44112 - The access token has expired. Please re-initiate the refreshToken process to obtain the access token.

getVoucherDistributionByDuration

GET /openapi/v1/{omadacId}/sites/{siteId}/hotspot/vouchers/statistics/history/distribution/duration

Get voucher distribution by duration

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)
filters.timeStart	query	integer	yes	Filter query parameters, support field time range: start timestamp (second).
filters.timeEnd	query	integer	yes	Filter query parameters, support field time range: end timestamp (second).

// omada_call_operation
{
  "operationId": "getVoucherDistributionByDuration",
  "params": {
    "siteId": "<siteId>",
    "filters.timeStart": "<filters.timeStart>",
    "filters.timeEnd": "<filters.timeEnd>"
  }
}

Details, permissions and error codes

Get voucher distribution by duration.
The interface requires one of the permissions:
Site Hotspot Manager View Only
The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-33000 - This site does not exist.
-33004 - Operation failed because other operations (site copying, restoring, template synchronizing, etc.) are being performed on this site. Please wait and try again later.
-44111 - The Grant Type is Invalid.
-44112 - The access token has expired. Please re-initiate the refreshToken process to obtain the access token.

getVoucherDistributionByDurationForGroup

GET /openapi/v1/{omadacId}/sites/{siteId}/hotspot/vouchers/statistics/history/distribution/duration/voucher-groups/{groupId}

Get voucher distribution of voucher group by duration

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)
groupId	path	string	yes
page	query	integer	no	Start page number. Start from 1. (default 1)
pageSize	query	integer	no	Number of entries per page. It should be within the range of 1–1000. (default 100)
filters.timeStart	query	integer	yes	Filter query parameters, support field time range: start timestamp (second).
filters.timeEnd	query	integer	yes	Filter query parameters, support field time range: end timestamp (second).

// omada_call_operation
{
  "operationId": "getVoucherDistributionByDurationForGroup",
  "params": {
    "siteId": "<siteId>",
    "groupId": "<groupId>",
    "filters.timeStart": "<filters.timeStart>",
    "filters.timeEnd": "<filters.timeEnd>"
  }
}

Details, permissions and error codes

Get voucher distribution of voucher group by duration.
The interface requires one of the permissions:
Site Hotspot Manager View Only
The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-33000 - This site does not exist.
-33004 - Operation failed because other operations (site copying, restoring, template synchronizing, etc.) are being performed on this site. Please wait and try again later.
-44111 - The Grant Type is Invalid.
-44112 - The access token has expired. Please re-initiate the refreshToken process to obtain the access token.

getVoucherDistributionByPrice

GET /openapi/v1/{omadacId}/sites/{siteId}/hotspot/vouchers/statistics/history/distribution/unit-price

Get voucher distribution by price

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)
filters.timeStart	query	integer	yes	Filter query parameters, support field time range: start timestamp (second).
filters.timeEnd	query	integer	yes	Filter query parameters, support field time range: end timestamp (second).

// omada_call_operation
{
  "operationId": "getVoucherDistributionByPrice",
  "params": {
    "siteId": "<siteId>",
    "filters.timeStart": "<filters.timeStart>",
    "filters.timeEnd": "<filters.timeEnd>"
  }
}

Details, permissions and error codes

Get voucher distribution by price.
The interface requires one of the permissions:
Site Hotspot Manager View Only
The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-33000 - This site does not exist.
-33004 - Operation failed because other operations (site copying, restoring, template synchronizing, etc.) are being performed on this site. Please wait and try again later.
-44111 - The Grant Type is Invalid.
-44112 - The access token has expired. Please re-initiate the refreshToken process to obtain the access token.

getVoucherDistributionByPriceForGroup

GET /openapi/v1/{omadacId}/sites/{siteId}/hotspot/vouchers/statistics/history/distribution/unit-price/voucher-groups/{groupId}

Get voucher distribution of voucher group by price

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)
groupId	path	string	yes
page	query	integer	no	Start page number. Start from 1. (default 1)
pageSize	query	integer	no	Number of entries per page. It should be within the range of 1–1000. (default 100)
filters.timeStart	query	integer	yes	Filter query parameters, support field time range: start timestamp (second).
filters.timeEnd	query	integer	yes	Filter query parameters, support field time range: end timestamp (second).

// omada_call_operation
{
  "operationId": "getVoucherDistributionByPriceForGroup",
  "params": {
    "siteId": "<siteId>",
    "groupId": "<groupId>",
    "filters.timeStart": "<filters.timeStart>",
    "filters.timeEnd": "<filters.timeEnd>"
  }
}

Details, permissions and error codes

Get voucher distribution of voucher group by price.
The interface requires one of the permissions:
Site Hotspot Manager View Only
The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-33000 - This site does not exist.
-33004 - Operation failed because other operations (site copying, restoring, template synchronizing, etc.) are being performed on this site. Please wait and try again later.
-44111 - The Grant Type is Invalid.
-44112 - The access token has expired. Please re-initiate the refreshToken process to obtain the access token.

getVoucherHistoryStatisticsForGroup

GET /openapi/v1/{omadacId}/sites/{siteId}/hotspot/vouchers/statistics/history/voucher-groups/{groupId}

Get voucher history statistics of voucher group

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)
groupId	path	string	yes
filters.timeStart	query	integer	yes	Filter query parameters, support field time range: start timestamp (second).
filters.timeEnd	query	integer	yes	Filter query parameters, support field time range: end timestamp (second).

// omada_call_operation
{
  "operationId": "getVoucherHistoryStatisticsForGroup",
  "params": {
    "siteId": "<siteId>",
    "groupId": "<groupId>",
    "filters.timeStart": "<filters.timeStart>",
    "filters.timeEnd": "<filters.timeEnd>"
  }
}

Details, permissions and error codes

Get voucher history statistics of voucher group.
The interface requires one of the permissions:
Site Hotspot Manager View Only
The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-33000 - This site does not exist.
-33004 - Operation failed because other operations (site copying, restoring, template synchronizing, etc.) are being performed on this site. Please wait and try again later.
-44111 - The Grant Type is Invalid.
-44112 - The access token has expired. Please re-initiate the refreshToken process to obtain the access token.

getAllTimeVoucherSummary

GET /openapi/v1/{omadacId}/sites/{siteId}/hotspot/vouchers/statistics/summary

Get voucher summary

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)

// omada_call_operation
{
  "operationId": "getAllTimeVoucherSummary",
  "params": {
    "siteId": "<siteId>"
  }
}

Details, permissions and error codes

Get voucher summary of all time in the site.
The interface requires one of the permissions:
Site Hotspot Manager View Only
The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-33000 - This site does not exist.
-33004 - Operation failed because other operations (site copying, restoring, template synchronizing, etc.) are being performed on this site. Please wait and try again later.
-44111 - The Grant Type is Invalid.
-44112 - The access token has expired. Please re-initiate the refreshToken process to obtain the access token.

getAllTimeVoucherSummaryForGroup

GET /openapi/v1/{omadacId}/sites/{siteId}/hotspot/vouchers/statistics/summary/voucher-groups/{groupId}

Get voucher summary for voucher group

Parameter	In	Type	Required	Description
omadacId	path	string	auto	Omada ID (filled in automatically)
siteId	path	string	yes	Site ID (site ID or site name)
groupId	path	string	yes	Voucher group ID

// omada_call_operation
{
  "operationId": "getAllTimeVoucherSummaryForGroup",
  "params": {
    "siteId": "<siteId>",
    "groupId": "<groupId>"
  }
}

Details, permissions and error codes

Get voucher summary of all time in the voucher group.
The interface requires one of the permissions:
Site Hotspot Manager View Only
The possible error code for the interface in the returned body is one of the following error codes (non generic error codes):
-33000 - This site does not exist.
-33004 - Operation failed because other operations (site copying, restoring, template synchronizing, etc.) are being performed on this site. Please wait and try again later.
-44111 - The Grant Type is Invalid.
-44112 - The access token has expired. Please re-initiate the refreshToken process to obtain the access token.