swarmtix_discounts_check_code
Checks one discount code against one event and reports whether it would currently be accepted, and why not
swarmtix_discounts_check_code
Checks one discount code against one event and reports whether it would currently be accepted. A code that is unknown, exhausted or outside its valid dates comes back as a normal result saying it is not valid and why — not as an error.
When you would reach for it
- A buyer says their code was rejected and you want to know which reason it was.
- Before sending a campaign, to confirm the code in the email actually works today.
- After creating a code with
swarmtix_discounts_create, as a one-call check that it is live.
Scope
discounts:read
Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
event | string | Yes | — | The event's id (a GUID) or its URL slug. |
code | string | Yes | — | The discount code to check, as a buyer would type it at checkout. |
Example call
{
"name": "swarmtix_discounts_check_code",
"arguments": { "event": "spring-summit-2026", "code": "EARLYBIRD" }
}What comes back when the code is accepted
{
"eventId": "8f14e45f-ceea-467a-9c3d-1b2a5f6e7d80",
"code": "EARLYBIRD",
"valid": true,
"offer": {
"id": "a15c9e02-3b7d-4c61-8f95-6d24e0a7b3c8",
"name": "EARLYBIRD",
"amountOff": 0,
"percentageOff": 20,
"appliesToAllTicketTypes": true,
"unlimited": false,
"usesLimit": 100,
"startsImmediately": true,
"startDate": "2026-08-01T09:00:00",
"runsUntilSalesEnd": false,
"endDate": "2026-09-30T23:59:00"
}
}offer.ticketTypeId is present instead of appliesToAllTicketTypes being true when the offer is scoped to one ticket type.
What comes back when it is not
{
"eventId": "8f14e45f-ceea-467a-9c3d-1b2a5f6e7d80",
"code": "EARLYBIRD",
"valid": false,
"reason": "This code has reached the number of uses it was limited to."
}A rejected code is a completed check, not a failed call. The result carries no error flag. Flagging it as an error would teach an assistant that asking the question was a mistake, and the answer "no, and here is why" is exactly what you asked for.
The four reasons
reason is one of exactly four sentences:
reason | What it means |
|---|---|
No active discount on this event uses this code, or the code is outside the dates it is valid between. | The code does not match a live offer on this event, or it does but today falls outside its window |
This code has reached the number of uses it was limited to. | The offer's redemption limit is used up |
This code does not apply to the ticket type it was checked against. | The offer is scoped to one ticket type and the check landed on a different one |
No active discount on this event uses this code. | No offer on this event carries that code at all |
Anything the checker says that is not one of those four is treated as a genuine fault and reported as Swarmtix could not complete this request. Nothing was changed. rather than passed through. The messages arrive in the same field that carries a database failure when something breaks, and there is no flag distinguishing the two — so matching against a closed set is what keeps an internal error from being published as a discount reason.
What happens when you call it
- The event identifier is resolved and the ownership checks run. The code check itself is the anonymous checkout path and performs no authorization of its own, so this gate is the entire tenancy control for this tool.
codeis required and trimmed. An empty one is refused — it would otherwise reach a query that matches every offer with no code at all.- The code is checked against the event exactly as a buyer's would be.
- A rejection is mapped to one of the four sentences above and returned with
valid: false. - An acceptance returns the offer it belongs to and the reduction it applies.
Troubleshooting
"code is not valid: it was empty. Expected the discount code to check."
The code argument was missing or blank.
"Event not found, or this connection does not have access to it."
The event does not exist, or it belongs to a different organisation than this connection covers.
valid is false for a code that appears in the discount list
Read the reason. In practice it is almost always the date window or the usage limit — both are on the row in swarmtix_discounts_list, as startDate/endDate and timesUsed/usesLimit.
"This code does not apply to the ticket type it was checked against."
The offer is scoped to a single ticket type. It will work for a buyer choosing that tier and not for anyone else. swarmtix_discounts_list shows which tier an offer covers.
"Swarmtix could not complete this request. Nothing was changed."
Either a genuine failure, or a rejection worded in a way this tool does not recognise and therefore will not repeat. Retry; if it persists, quote the time and the code to support.
"This connection is not authorized for discounts:read. Reconnect and grant it to use this tool."
Reconnect and approve discounts:read.
Use cases
- Support triage — one call turns "my code doesn't work" into a specific reason
- Pre-send check on the code in a marketing email
- Verifying a new offer right after creating it
- Monitoring a limited code — the exhausted reason is the signal to raise the limit