DS-452 Helper: User Instructions

Compatible with DS-452 Helper v0.6.3-d7b170fd4d · https://ds452-helper.pages.dev/ · Full instructions

Unofficial personal guide · not a U.S. government product. Discussion: BRDCD WhatsApp group.

1. What the app is for

DS-452 Helper prepares the DS-452 Official Courier Accompanied Pouch Charges form (05-2017 edition). The DS-452 authorizes payment against an air waybill (AWB). The app works out each AWB line, the Total Other Cost, the TOTAL and the US$ amount, checks them against the waybill, and makes a PDF that looks like the real form. The original AWB is attached as page 2.

• Your data stays on your device. Drafts, your profile and imported documents are kept only in this browser on this device. Nothing is uploaded.
• One optional network call. When a DS-452 needs an exchange rate and there's no pick-up sheet rate in Settings and none printed on the AWB, the app can look up today's rate at open.er-api.com (ExchangeRate-API). That request sends only the address https://open.er-api.com/v6/latest/USD: no form data, no cookies, no names. It is the only network address the app may contact (section 8). Turn it off in Settings > Defaults for new forms.
• Fewer repeated entries. Much of a DS-452 stays the same from trip to trip. The app fills what it can from your documents, your saved passport and your defaults, and every field with more than one known value has a ▾ drop-down list. You can still type anything.
• It's an unofficial preparation aid. It is not a U.S. Department of State product. You, the courier, are responsible for the figures you sign.
• One DS-452 can hold up to 4 table rows. AWB lines, the DS-7600 weight row and the Total Other Cost row share those 4 rows.

2. Install it and use it offline

• Open https://ds452-helper.pages.dev/ once while online. After that the app works offline.
• Install it (optional) so it opens like a regular app. In Chrome or Edge, use Install app in the address bar or browser menu. On Android, tap the menu, then Add to Home screen. On an iPhone, open the site in Safari, tap Share, then Add to Home Screen.
• The scanner (OCR) for photos and scanned PDFs is about 7 MB. It downloads the first time you scan a photo. If you'll be offline, go to Settings > Scanner and tap Download scanner for offline use first. Text PDFs and pasted text don't need it.
• Help is built in. Tap ? at the top of any screen for this guide. The in-app guide works offline too.
• Updates. When a new version is published, the app downloads it in the background the next time you open it online, and uses it from the following start. The version number is at the bottom of the home screen.

3. One-time setup in Settings

Tap the gear icon on the home screen.

• Courier profile. Enter your Name (as on your diplomatic passport), Diplomatic passport No. and Paying post. The paying post is the "Payment will be made by U.S. Embassy/Consulate at" line (field 18). It starts as Bangkok, Thailand. These fill every new DS-452. Changing them doesn't change saved drafts.
• Passports (up to 4) (changed in 0.6.3). Passports are uploaded only here, not on a DS-452. Tap Scan photo or PDF (the photo page, read on the device), Type MRZ or Enter manually. The app checks the MRZ check digits and shows an expiry badge. You're warned when a passport has expired or expires within 6 months of the flight. Tap Use in profile to make one your profile passport; the profile passport, or the first valid saved passport, fills each new DS-452. Only the number, name and expiry date are kept: the scan, the MRZ lines and the date of birth are never stored. A scan of the open passport booklet saved as a PDF is read reliably (the app looks for the two MRZ lines band by band and compares several readings). If the very last MRZ character was unreadable but every other check digit is valid, it is filled in and a note asks you to compare the numbers with the passport.
• Fiscal (accounting) line. The Fiscal year starts as 2026 and the Accounting classification (field 21) starts as WSP END: 19___X0113000H 1069 106926A2789 175600 5731 2225 DS9995. Both can be edited: type the line exactly as it should print, then tap Save fiscal line. The line changes every U.S. fiscal year (FY starts 1 Oct). When the FY rolls over, a banner on the home screen reminds you to re-enter it (FY2027 began on 1 Oct 2026, so the built-in FY2026 line shows that reminder until you save the FY2027 line). Ignore the fiscal line printed on old blank forms.
• Defaults for new forms. See section 4.
• Saved signature (optional). Draw a signature once to reuse it. You still choose to apply it on each DS-452.

4. Defaults for new forms

The defaults are set up for a Bangkok outbound trip. They pre-fill each new DS-452 only. Saved drafts never change.

• Change a default in Settings > Defaults for new forms. Tap Restore the Bangkok outbound defaults to go back to the values above.
• A default is only a starting value. A field that still holds the default shows From: Default · Settings under it and the hint "Default from Settings". When you import an AWB, the document's value replaces a default. Anything you type or pick yourself is never replaced. So a Korean Air AWB booked through an agent fills in its own company and airline.
• The default exchange rate is the "current pick-up sheet rate". On Step 4, Use current pick-up sheet rate uses it with its source. The last rate you used is still offered in the rate field's ▾ list as Last used.
• Online rate lookup (on by default): see section 8. Untick Look up the exchange rate online (open.er-api.com)… to keep the app fully offline; you can still choose Look up the rate online on a form when you want it.
• Save as default. On Step 4, the Save as default buttons under the exchange rate and the Exchange Rate Source make the current values the new defaults. The rate is saved for the month of the flight.
• Keep the rate current. Settings shows a warning when the default rate is for an earlier month. Update it whenever the rate changes.
• Changing the default currency (drop-down) clears the default rate, because a rate belongs to its currency.

5. Making a DS-452: the 5 steps

Tap New DS-452, then choose Blank form (it starts with your defaults) or Copy from an existing DS-452 (section 11). There is no way to import a DS-452 from a file: the app has no way to share forms (section 12). The tabs at the top let you jump between steps. The app saves as you go, and Back or Done keeps your work.

Drop-downs and red fields (all steps).

• A field with known values (from your imported documents, saved passport, Settings defaults or earlier forms) has a ▾ button with the number of values. Tap it to pick one; the line under the field says where the value came from (From: …). Typing is always allowed, and the line then says Typed.
• A field the form needs that is still blank is red and labelled · needed. It turns normal as soon as you fill it.

Step 1: Carrier and flight

• Start with your documents (changed in 0.6.3). Step 1 asks you to upload or scan, in this order: 1 Air Waybill, 2 DS-7600(s) and 3 itinerary (ticket number only). Tap Upload or scan documents (section 6). They are read on the device and fill the form straight away. Passports are not uploaded here: upload your passport only in Settings > Passports (profile settings). Your name and passport number come from your profile.
• Your documents as a list (new in 0.6). Under each document type the imported files are listed one below the other, each name cut to its first 30 characters (a long name ends in …). Tap a name to open the original in a new browser tab (changed in 0.6.1): nothing is downloaded. On a phone or browser without a PDF viewer (Android, or the app installed on an iPhone home screen) the tab shows the PDF's pages as pictures. If your browser blocks the new tab, the app shows a button to open it. The same list is at the top of steps 2 to 4. A pasted text has no file, so tapping it shows the text that was read.
• Which flight reaches the final destination? (changed in 0.6.2). The flights come from the AWB's flight and routing boxes. With several, Step 1 asks you to choose the one that arrives at the final destination (outlined in red until you choose); with one, it is used automatically; with none, type the flight number and the destination airport (e.g. IAD). The destination (To) comes from the AWB's destination box and can always be edited. Your choice sets the Flight No., the Airline, and the AWB line's Date and To; you can still change each field afterwards.
• Company (carrier and agent, as on the AWB), Airline (flown on), Flight No. and Ticket No. (13 digits from your e-ticket). Scan itinerary for ticket number (next to Ticket No., new in 0.6.2) reads an itinerary or e-ticket on the device, puts ONLY the ticket number in Ticket No. and discards the rest at once (file, text, flights, names, dates); nothing from it is stored or listed. Left blank, E-TICKET prints on the form. Use ▾ to pick a value found in your documents, or type.

Step 2: Courier

• Name (as on the passport) and Diplomatic passport No. come from your profile (Settings: your profile, or the passport saved in Settings > Passports). You can also type them here. The name is never taken from the airline ticket or itinerary.
• Payment will be made by U.S. Embassy/Consulate at (the paying post, field 18) comes from the Shipper block of the imported AWB, as city and country (e.g. Bangkok, Thailand). If the AWB has no readable shipper, your default is used. Check it on inbound legs, where the shipper may be another post.
• The passport field shows its expiry status. If you change these here, Save these to my profile updates your profile.

Step 3: Air waybill

• Choose the Weight unit (kg or lb) and the AWB currency from the drop-down list: THB – Thai Baht (฿) (the default), USD, EUR, JPY, GBP, AUD, CAD, CHF, CNY, INR, BRL, ZAR, NZD, MXN, TRY, EGP, or Other (type code). For Other, type the code as it should print, e.g. KZT. The PDF prints the 3-letter code (e.g. "INR 1,234.00"), because the form's font can't print symbols such as ฿, ₹ or ₺. An imported AWB selects its currency automatically (or Other with its code).
• One air waybill per DS-452 (new in 0.6). A DS-452 has one AWB and one AWB line. For another waybill, make a separate DS-452 (Copy to a new DS-452 on Step 5). If you import a second AWB it fills nothing, and you are warned. Older drafts with more than one line must have the extra lines removed before the PDF can be made.
• On the AWB line enter the Date, From and To (3-letter IATA codes), the Air Waybill No., the Pieces, the Gross weight, the Chargeable weight and the Rate per kg. Tick Flat / minimum charge for rate class M, then enter the flat amount.
• Two weights. The chargeable weight is always used for the cost (chargeable weight × rate), and it prints on the form. The gross weight is for information only. You're warned if the chargeable weight is less than the gross weight, because that is unusual.
• Gross = chargeable when loose-loaded. The two are often the same, especially when the pouches are loose-loaded with no ULDs (containers). The app reads both from the AWB. If it finds only one, it fills the other with the same figure only when the AWB says the cargo is loose / no ULD, or when it prints a single weight that × the rate gives the weight charge; the line under the field says so (= gross weight (loose-loaded, no ULD)). Otherwise the missing weight is left blank and shown red: read it off the waybill.
• Checks as you type: the AWB check digit (the 8th serial digit is the first 7 digits mod 7), the carrier from the AWB prefix (e.g. 217 = Thai Airways), and known IATA airport codes.
• Checked against your DS-7600s (new in 0.6). When DS-7600s are imported, Step 3 shows their totals (weight, pieces, volume in CBM, one row per shipment) and checks the AWB against them: ✓ when the AWB gross weight equals the DS-7600 total weight (within 0.5 kg) and the AWB pieces equal the DS-7600 pouch count, ⚠ otherwise, and a warning when the chargeable weight is below the DS-7600 weight. The DS-7600s are always taken as correct (0.6.1): the piece count and the gross weight come from the DS-7600s, and when the AWB shows a different number the check is outlined and says The AWB may be wrong, with both figures. The AWB fields stay as printed (so you can compare), but the Step 5 summary uses the DS-7600 figures. On a ULD shipment the AWB prints the loose pieces in brackets, e.g. "2 / ULD (87 PCS)": the bracketed figure is used as the pieces.

Step 4: Charges and rate

• DS-7600 total weight (new in 0.6). Taken from the scanned DS-7600s: the total weight of every DS-7600 imported for this DS-452, added together (the same shipment imported twice counts once). The field is read-only and says how many DS-7600s it comes from; remove a DS-7600 in Documents to change it. Only when no DS-7600 is imported do you type the weight yourself. It prints in the "Total DS 7600 wt" row.
• Total other charges (Total Other Cost) (changed in 0.6.3). Only the AWB's total other charges figure is used, as one figure per AWB (the "Total other charges" boxes, due carrier + due agent added together). The charges are not itemized: the individual charge lines on the waybill are not copied into the form or listed. An imported AWB fills the figure from its "Total other charges" boxes; if the AWB has no such box the app adds up the charge lines it can read and shows a yellow warning (check the total against the waybill). It prints as the one Total Other Cost row, and the AWB check (section 7) uses this figure. If the figure differs from what the AWB's boxes read, a red line shows the AWB's figure. Older drafts that were itemized are added up into one total automatically.
• Exchange rate (units of the currency per US$1), and the Exchange Rate Source (i.e. Pick-up sheet week / revision), filled to match the rate you use and printed on the PDF. USD = TOTAL ÷ rate; for a USD form the rate is 1. Choose where the rate comes from (section 8):
  • Use current pick-up sheet rate: the rate and its sheet week / revision from Settings > Defaults for new forms (the default).
  • Rate printed on the AWB: shown only when the AWB prints one (e.g. "USD 1 = THB 33.50"); the source becomes Air Waybill <AWB No.>.
  • Look up the rate online: today's rate from open.er-api.com, shown in red until you confirm it.
  • Enter the rate myself: type the rate and its source.
• Check against the AWB. Enter (or import) the AWB total, the final total printed on the waybill. See section 7.

Step 5: Review and sign

• Check the Summary and the Checks. Errors must be fixed before Preview & create PDF becomes available. Warnings don't block the PDF.
• Choose how to sign: Draw signature (finger or mouse, or Use my saved signature), Sign later with PIV (Acrobat) (section 10) or Sign on paper.
• Leave "Signature of Company's Agent and Date Stamp" for the airline agent.
• The Review screen shows the marking SBU - PRIVACY OR PII at its top and bottom, as on the PDF (section 9).
• From here you can also Copy to a new DS-452 or Delete this DS-452.

6. Importing the AWB, DS-7600s and itinerary (ticket No. only)

Tap Import (or Manage) at the top of steps 1 to 4.

• DS-7600s (new in 0.6). Import every DS-7600 that travels on the AWB (often one per shipment; there may be several). Each one is recognised as DS-7600 and shows its shipment number, total weight, pouch count and volume (CBM). On a DS-7600 that runs over several pages, the shipment totals printed on each page ("675.0 of 1749.0" kg, "20 of 71" pouches) are used, so the total is right even if a page is missing. If a type was guessed wrong, choose DS-7600 under Document type.
• One AWB and its DS-7600s per DS-452 (new in 0.6.2). An AWB or DS-7600 is never reused for another mission. Importing a new AWB replaces the previous AWB, clears the values it filled and removes the DS-7600s already attached (notice: "Previous AWB and DS-7600s replaced"). Importing DS-7600s again replaces the earlier set. DS-7600s picked together in one go are totalled together; to add one more to the same AWB later, use Add another DS-7600 to this AWB. Replaced documents are deleted from the list and from this device. Other DS-452s are not affected.
• Draft DS-7600s (new in 0.6.2). A DS-7600 whose shipment number starts with D (e.g. D-BKKCL - 14777) is a draft. It is labelled DRAFT, its figures are used, and an amber warning asks you to replace it with the final DS-7600 before submitting. Importing the final DS-7600 with the same number replaces the draft automatically.

• PDF file: text PDFs are read exactly. Scanned (image-only) PDFs are read with OCR.
• Photo or scan or Take photo: read with OCR on the device. Expect some wrong characters, so check every value. Since 0.5.2 colour scans are handled too: a waybill printed in red or pink, or a photo with a blue/green cast, is cleaned by colour before reading. When a digit of the AWB number or of a charge is a look-alike misread (e.g. 3/8, 0/9), the app repairs it only when the check digit or the AWB totals prove it, and says so in a note: check it against the paper.
• Paste text: e.g. AWB or DS-7600 text copied from an e-mail.
• What is kept (0.6.3): for an AWB or DS-7600, the text read and the original file, on this device only. For an itinerary, only the ticket number (it goes into Ticket No.; the itinerary is not listed or stored). Passports are not imported with documents: if a passport is picked in Documents the app says so and keeps nothing; upload it in Settings > Passports. Passports in drafts saved by older versions are removed from the document list when the app opens (only the expiry date stays, so an expired passport is still caught).
• Expired passport (0.6.2, changed in 0.6.3): if the passport on a DS-452 expired before its flight date (or today, with no date), a red box says This passport has expired. Upload your current passport in profile settings. Tap Open profile settings and upload the current passport under Settings > Passports, or enter a valid passport number in Step 2. The PDF can't be created until then.
• Waybill math (0.6.2; total other charges in 0.6.3): the app checks the AWB silently: chargeable weight × rate = weight charge, the minimum charge, weight charge + total other charges = AWB total, and the DS-7600s against the AWB pieces and weights. When all is well you see one small green line, Waybill math checked. When a check fails (or a value it needs could not be read), a red box lists each calculation with the expected and found figures, and the inputs concerned (AWB total, AWB pieces, AWB gross weight, total other charges) appear so you can correct them. They are otherwise hidden; Show waybill details opens them at any time. The Review step works the same way.
• Each document shows what was found. Change its Document type (Air waybill, DS-7600, Other) if it was guessed wrong.
• Filling is automatic. Each document fills the empty fields (and fields still holding a default) as soon as it is read, and a message says how many. It never overwrites a value you typed. Fill empty fields from all documents does the same for every document again.
• What comes from where: your profile (or a passport saved in Settings > Passports) gives your name and passport number; the AWB gives the company, AWB number, route, dates, weights, rate per kg, total other charges, the AWB total and the paying post (Shipper block); the AWB's flight boxes also give the flight number; an itinerary gives only the ticket number.
• The original file is kept on this device only, so the AWB can be attached to the PDF. Remove a document to delete it and its file.

7. Total Other Cost and the AWB check

(Chargeable weight × rate) + Total Other Cost must equal the AWB's final total.

• The AWB total is shown next to the computed TOTAL with ✓ matches or ✗ differs by …. With several AWBs, each AWB is checked on its own and all together.
• A difference of more than 0.01 shows a red warning with the difference. First check the weights, the rate and the total other charges against the AWB.
• If everything agrees with the AWB, the waybill itself may contain an error. Raise it with the carrier or agent. To create the PDF anyway, tick Generate anyway: I have checked the AWB and the difference is on the waybill. If any figure changes afterwards, the app asks again.
• A missing AWB total, or other charges not assigned to an AWB, only gives a yellow warning.
• Total Other Cost = the AWB's total other charges.
• With one total other charges figure per AWB, each AWB's check is (chargeable weight × rate) + its total other charges = its AWB total.

8. The exchange rate: pick-up sheet, AWB or online

Step 4 asks where the rate comes from. Whichever you choose, the Exchange Rate Source (i.e. Pick-up sheet week / revision) field is filled to match. It stays editable, and the PDF prints it under the rate line at the bottom of the form (Exchange rate source: …).

1. Use current pick-up sheet rate. Uses the rate and source saved in Settings > Defaults for new forms, e.g. 33.48 THB per US$1, Week 41b original. It is selected automatically when Settings has a rate for the form's currency. Keep the default current; you're warned when it is for another month.
2. Rate printed on the AWB. If the AWB prints an exchange rate, it is offered and used when there is no pick-up sheet rate.
3. Look up the rate online. When there's no pick-up sheet rate for the currency and none on the AWB, the app looks up today's rate once from open.er-api.com (ExchangeRate-API, free; xe.com has no free service). The source reads e.g. Online: open.er-api.com (ExchangeRate-API), 3 Oct 2026.
4. Enter the rate myself. Type the rate and the Exchange Rate Source. Typing a rate switches to this choice.

9. Creating the PDF; the AWB as page 2

• Exchange rate in bold red (new in 0.6). On the PDF (and the preview) the exchange-rate line ("THB 33.48 = $ 1.00 * THB 17,500.00 = $ 522.70") and the Exchange rate source line print in bold red, so the conversion stands out. Nothing else on the form is red.
• Preview shows the form exactly as it will print. Then tap Download PDF, Share (your device's share sheet) or Open.
• The file is named DS-452 - YYYYMMDD - AWB No. - Flight.pdf.
• Page 1 is the DS-452. The original AWB file(s) follow from page 2, in AWB line order. PDF pages are copied, slightly reduced (to about 92%) so that the SBU marking fits in the margin without covering anything. Photos are turned upright and fitted to a Letter page.
• Each document has an Attach to PDF switch (on for AWBs, off for others). For multi-copy AWB PDFs, the first page is attached unless you choose All N pages. The preview lists what will be attached.
• If a file can't be attached, the DS-452 is still created and the app names the file.
• SBU marking. A filled DS-452 holds personal information (your name and passport number), so the PDF is marked SBU - PRIVACY OR PII (Sensitive But Unclassified) at the top and bottom of every page, centred, including the attached AWB page(s). The marking is small bold grey text in the page margin and never covers a form field. The preview shows it too. Handle, store and send the PDF as SBU (12 FAM 540): e.g. only to the people who need it, and by Department-approved means.

10. Signing: drawn or PIV in Acrobat

• Drawn: the signature is placed on the courier signature line, and the date and time are kept with the draft.
• PIV: in-app PIV signing isn't possible. The PDF has an empty signature field named DiplomaticCourierSignature over "Diplomatic Courier". Open the PDF in Adobe Acrobat or Acrobat Reader on a PC with your PIV card inserted, click the field and choose your PIV certificate. Acrobat applies the digital signature and locks the form. The dashed box in the preview doesn't print.
• Paper: the signature space is left blank for a wet-ink signature after printing.

11. Drafts: copy, duplicate and delete

• The home list shows each DS-452 with its total, Draft or PDF created, and when it was last edited. Tap one to open it. The ⋮ menu has Duplicate, Copy to a new DS-452 and Delete.
• Copy to a new DS-452 (or New DS-452 > Copy from an existing DS-452) makes a new draft for the next trip. The original isn't changed.

• Changed in 0.6.3: a copy starts with every cost, weight and piece count blank. An AWB and its DS-7600s belong to one mission and are never reused, so the copy does not carry them or anything read from them. Import the new trip's AWB and DS-7600s (in that order) and enter the rest.

• Your profile, fiscal year and accounting settings and the courier / passport choice come from Settings as on any new DS-452. Copied carrier values act like defaults: importing the new trip's AWB replaces them.
• Duplicate makes an exact copy of the same DS-452, documents included but without the signature (e.g. to sign it another way).
• Delete asks you to confirm. It removes the DS-452, its imported documents and their original files from this device. PDFs you already saved or shared aren't affected. It can't be undone.
• Delete all data (Settings > Data on this device) wipes your profile, passports, signature and every draft from this device.

12. Privacy: no sharing, no backups

• Your DS-452s stay on this device. Drafts, passports, your signature and imported documents are kept only in this browser on this device.
• There is no way to share an editable DS-452 with another courier, and no way to import one. To protect PII (SBU), the app has no share or export of draft files and no backup export or restore. (Draft files that older versions made for sharing can't be opened.)
• To start from an earlier trip, use Copy to a new DS-452 (section 11). Copying stays on this device.
• The PDF is the only thing you send. Use Download PDF, Share or Open on the Preview screen. It is marked SBU - PRIVACY OR PII on every page (section 9).
• New phone or browser: your drafts don't move with you. Keep the PDFs you created; start new forms on the new device.

13. Troubleshooting and FAQ

• Preview & create PDF is greyed out. Fix the errors listed under Checks on Step 5. Each step also lists its problems at the bottom.
• "Totals do not match the AWB." See section 7. Check the figures, then tick Generate anyway only if the difference is on the waybill.
• "The exchange rate … is for October 2026, but this DS-452 is for November 2026." The rate came from a default or a copy for another month. Enter the current rate, or update the default.
• An import didn't replace a value. You typed or picked that value, so it's protected. Open the field's ▾ list and pick the document's value instead.
• My drafts have disappeared. Drafts are stored only in that browser on that device. A different browser or device, private browsing, or clearing site data won't show them. There are no backups: keep the PDFs.
• The AWB wasn't attached. The original file isn't on this device (e.g. it was pasted text, or the document was removed), or Attach to PDF is off. Import the AWB again.
• "Some characters … will show as ?". The form fonts can't print Thai characters or ฿. Use plain letters.
• The total other charges are wrong or missing. Compare the Total other charges figure (Step 4) with the AWB's "Total other charges" boxes and type the right figure. The app does not itemize charges.
• A photographed AWB reads badly. Photograph it flat, in good light, filling the frame; a copier or office-scanner PDF reads best. Fields that could not be read stay red: type them from the paper.
• Scanning is slow the first time. The scanner downloads once (about 7 MB), then works offline.
• Can I send an editable DS-452 to another courier? No. Since version 0.5 the app can't share or import forms (section 12). Send the PDF; the other courier makes their own form, or copies one of their own.
• No internet. The app, the guide and (once downloaded) the scanner all work offline. Only the optional online rate lookup needs a connection; without one, enter the pick-up sheet rate.
• The exchange rate is red. It was looked up online. Check it, then tick the confirmation under the rate, or use the pick-up sheet rate (section 8).
• A field is red and says "needed". The form needs it and it's blank. Fill it in, or pick a value from its ▾ list.
• The paying post is another city. It was read from the AWB's Shipper block. On an inbound leg the shipper may be another post: pick your post from the ▾ list or type it.

Document revision: 6 Nov 2026 (Asia/Kuala_Lumpur). App version and document revision are separate.