The guest holds up a phone, the scanner beeps or doesn’t, and the ticket gets rejected. Staff type the number in by hand, the line backs up, and nobody is sure whether the problem is the scanner, the ticket, or Altru. The good news is that scan failures almost always fall into one of two groups, and a five-minute test tells you which one you have.
First, split the problem in two
Watch what the scanner does when the ticket fails:
- No beep, or the scanner keeps trying: the device can’t read the barcode at all. This is a hardware, settings, or image-quality problem.
- It beeps, but Altru says the ticket isn’t found or isn’t valid: the scanner read something, but what it sent doesn’t match a valid ticket. This is either a data-format problem (extra or wrong characters) or a real ticket-status issue.
These have completely different fixes, so don’t start swapping hardware until you know which one you’re dealing with.
The Notepad test
Most USB and Bluetooth scanners act like a keyboard: they “type” whatever they read into the field that has focus. That makes them easy to test outside Altru.
- Open a plain text editor (Notepad on Windows, TextEdit in plain-text mode on a Mac) on the same computer the scanner is connected to.
- Scan a failing e-ticket from a phone, and a printed copy of the same ticket if you have one.
- Compare what appears in the editor with the ticket number shown on the transaction in Altru.
If nothing appears, you have a read problem. If text appears but differs from the ticket number, you have a format problem. If the text matches exactly and Altru still rejects it, the issue is the ticket itself.
When the scanner reads extra characters
A common version of this: the ticket number comes through correctly, followed by stray characters such as a tilde and a few more digits or letters. Altru then looks up a value that doesn’t exist and rejects it. Typical causes:
- A prefix or suffix programmed into the scanner. Many scanners can add characters before or after every scan, and some ship with one turned on, or someone configured it for a different system. The manufacturer’s programming guide will have barcodes you scan to clear prefixes and suffixes. Most setups only want a carriage return (Enter) at the end.
- Keyboard language mismatch. If the scanner is set to one keyboard layout and the computer uses another, certain characters get translated into the wrong symbols. Tildes, dashes, and other punctuation are the usual casualties. Set the scanner’s keyboard country to match the workstation.
- The barcode contains more than the ticket number. Depending on how your e-ticket template builds the barcode, it may encode extra data alongside the number. Scan it with the Notepad test and check what the barcode actually holds. If the template is producing it, the fix belongs in the template, not the scanner. If you’re unsure how your Altru e-ticket barcode is supposed to be formatted, Blackbaud support can confirm what the scan field expects.
When the scanner can’t read the barcode at all
Scanner settings
Many scanners only have common one-dimensional barcode types enabled by default. If your e-tickets use a 2D code (a QR code, for example) and the scanner is a basic 1D model, it will never read them, no matter how bright the screen. Check that the scanner supports and has enabled the symbology your tickets use. Older laser scanners generally can’t read phone screens reliably at all; imager-style scanners do much better.
The image on the guest’s phone
- Screen brightness turned down, or a dark-mode email app inverting colors.
- Cracked screens and heavy screen protectors that scatter light.
- Email clients that block images until the guest taps “load images,” so there’s no barcode to scan.
- Screenshots that were cropped, compressed, or zoomed until the bars blur together.
Coach staff to ask guests to raise brightness and hold the phone flat, a few inches from the scanner, before giving up.
The image in your template
If almost every phone fails but printed tickets scan fine, look at the e-ticket email itself. A barcode that renders too small, gets stretched horizontally, or sits too close to other content can be unreadable on a phone. Send test tickets to a few different email apps and phone models and scan each one before your next busy season.
When the number matches and Altru still says no
At this point the scanner is doing its job. Look up the ticket in Altru and check:
- Whether it has already been redeemed, maybe by a guest who forwarded the email to a friend.
- Whether the order was refunded, exchanged, or voided after the email was sent.
- Whether the ticket is for a different date, time slot, or program than the one staff are scanning for.
- Whether the station is set up to accept the kind of item being scanned (a membership barcode at a ticket-only station, for example).
Exchanges deserve special attention. If a guest changed their date and is showing the original email, the barcode on their phone may belong to a ticket that no longer exists.
Keep a short log for a week
Ask door staff to jot down each failure: the ticket number, phone or paper, and what the scanner did. After a few days, the pattern usually points straight at one cause, whether that’s one scanner with a stray suffix, one email app, or exchanged tickets.
Scanning on mobile devices
Some organizations also want to scan away from a fixed workstation, at an outdoor gate or a second entrance. Social Good’s Ticket Scanner scans Altru tickets and membership barcodes on mobile devices at the door. The troubleshooting above still applies: a dim screen or a refunded ticket fails anywhere.
Quick answers
Why does manual entry work when scanning doesn’t?
Staff are typing only the ticket number, so they skip any extra characters the scanner adds and any image-quality problem. Run the Notepad test to see what the scanner is actually sending.
Do I need new scanners?
Only if yours can’t read the barcode type your tickets use or struggle with phone screens. Try clearing prefixes and suffixes and checking symbology settings first.
