Credits
Your plan gives you credits every month (Manila calendar month). One sealed PDF costs one credit. Everything that helps you get that PDF right is free.
Call · Credits; POST /api/v1/engine/fill/{form_id}: a new PDF · 1; The same, with ?revise=<document_id>: an edit · 0; The same values on the same form again, this month: a repeat · 0; POST /api/v1/engine/batch/{form_id} · 1 per row that becomes a new PDF (a repeated row or a refused row: 0) — priced before it starts, refused with 402 if the month cannot pay for it; POST /api/v1/engine/scan/{form_id}: read a filled paper copy · 3 per page that lined up; POST /api/v1/engine/ingest/{form_id}: read documents with AI (how) · 10 per call; check, parameters, engine/forms, verify, the studio preview · 0; Any call with a test key (pk_test_…) · 0 (the PDF says TEST - NOT FOR FILING) — up to 500 test PDFs a month per account
Plan credits (your plan's monthly credits, the 30-day trial's included) pay for everything on this list: fills, batches, hooks, scans and AI reads. Prepaid credits pay only for single fills (/engine/fill, from your code, the MCP server or the studio). A batch, a hook, a scan or an AI read always uses plan credits. A page that didn't line up with the form costs nothing.
Prepaid credits come two ways, and they're the same credit. A form pack (1 for ₱79, 5 for ₱299) is sized for someone who needs one form once. An API credit pack is sized for code, and per credit it is much cheaper. Buy the form pack only if a handful is all you'll ever need. Either one pays for a fill made from the studio, your code or an agent. No subscription? Buy prepaid API credits on /pricing: 100 for ₱199, 1,000 for ₱999, 10,000 for ₱4,999, each good for 12 months. They're spent one per PDF, once the plan's own credits are used up or if the plan would watermark the PDF.
Bonus credits are the same credit, given instead of bought: 20 when you join with a friend's referral link and confirm your email, 30 when a friend you referred makes their first clean PDF, and a few for your first clean PDF, telling us your role, a second week and feedback (at most 55 a year outside referrals). They last 120 days and have no cash value. One credit makes any one form clean, a later form in a pack too. Passes (2307 Quarter Pass, 2316 Year-End Pass) are credits that work only on those certificates and expire sooner.
A fill paid with a prepaid credit says X-Credit-Cost: 1 and adds X-Credit-Remaining, your prepaid balance. Buying opens when GET /api/v1/plans says is_checkout_available: true; until then, the trial is the way in.
Every metered response says what it used in X-Credit-Cost, plus X-Quota-Used and X-Quota-Limit for the month. When the month runs out, a paid plan keeps going at its overage price; Free and the trial get a 402 with code: "quota_exceeded".
Test keys are free and never touch your credits, up to 500 test PDFs a month per account (test_fill_quota in GET /api/v1/plans; resets on the 1st, Manila time). On a test-key fill, X-Quota-Used and X-Quota-Limit count those test PDFs (X-Quota-Limit: 500), not your plan's credits. Past them a test-key fill is a 402 with code: "test_key_limit".
When is a form "filled"?
A form is filled when PhilForms issues a sealed PDF for it. That PDF has a document id (X-Document-Id) and a seal anyone can check with POST /api/v1/verify (Seals). That's the thing a credit pays for. A PDF that holds several copies of a form, because your rows ran past what one page prints (the SSS R-3, the PhilHealth RF-1), is still one sealed PDF and one credit. A check, a preview, or a refused fill (a 400) makes no PDF and costs nothing.
When is it "complete"?
Every fill tells you how complete it is:
- X-Is-Complete: true means every *core* field has a value. Core fields are the ones the form marks required. If it marks none, they're the filer's ID (TIN, SSS, PhilHealth, Pag-IBIG or GSIS number), name and address. On a form that *gives* you the number, like a registration, the number isn't core, because you don't have it yet. - X-Fields-Missing lists the core fields you left blank. - X-Missing-Count counts every blank field. A tick box left unticked is an answer ("no"), so it isn't counted. Signatures, thumbmarks and photos are usually added by hand after printing, so they're never core.
An incomplete PDF still costs one credit, because it's still a sealed PDF. To make sure you never pay for one, add ?require=core (or ?require=all, or ?require=tin,last_name). The fill is then refused with a free 400 until those fields are there. Or run the free check first: it returns missing_core and missing.
What counts as an edit?
You made a PDF and then spotted a typo, a wrong amount, a wrong name or a forgotten box. Fill it again with the first document's id. An edit is a full re-fill, not a patch: send every value the form should carry, not only the one you're changing. Anything you leave out is blank on the new PDF.
curl -X POST "https://philforms.com/api/v1/engine/fill/bir-2307?revise=$DOCUMENT_ID" \ -H "Authorization: Bearer $PHILFORMS_API_KEY" -H "Content-Type: application/json" \ -d '{ "payee_tin": "123-456-789-000", "payee_name": "DELA CRUZ, JUAN P.", "...": "..." }'
The edit is free when all of these hold:
1. You made the first document, with the same kind of key (live or test). 2. It's the same form. 3. It's within 7 days of the first fill. 4. It has had fewer than 5 edits. Editing an edit counts against the first document. X-Revise-Remaining says how many are left. 5. It's still about the same filer. If the form has a filer ID (TIN, SSS, PhilHealth, Pag-IBIG or GSIS number), the ID must be the same, and the name may change in any way (the ID is what says who it is). The "filer" is whoever the form's core ID belongs to, which GET /api/v1/parameters/{form_id} marks is_core. On BIR 2307 that's the payee, so an edit has to keep the payee's TIN. If it has no ID, at most one part of the name may change.
If any of these fail, you get a 409 that says why, and nothing is charged. Fill without ?revise to make it a new document. A different person's form is always a new document.
An edit is as clean as the PDF it edits. Editing a prepaid (₱79) form gives a clean PDF; editing a Free-plan PDF keeps the Free watermark. The new PDF has its own document id and seal. The old one still verifies as genuine, so file the newest one.
We don't store your values to tell edits apart. Each document keeps a short keyed fingerprint (an HMAC) of the filer's ID and name parts, which is enough to tell "same person" from "different person" and nothing more.
Downloading the same PDF again
Fill a form with exactly the values you sent before, this calendar month, and it costs nothing. This covers a retry after a timeout, a double click, an agent that runs the same step twice, or simply downloading it again. The response says X-Credit-Cost: 0 and X-Replay-Of: <document_id>, the document you already paid for. It works past a used-up month too, since the PDF was paid for when it was first made.
- "Exactly the same" means the same form, the same values and the same style. The order of keys, blank fields and 2 vs "2" don't matter. Spelling does: 123-456-789-000 and 123456789000 print the same but count as different values, so send them the same way each time. - One changed value is a new PDF and costs 1 credit (or, for a fix to a PDF you already made, use ?revise, which is free). - The repeat is as clean as the first PDF: a repeat of a prepaid form is clean and spends no second credit. - It gets its own document id and seal, and verifies on its own. Either copy is good to file. - A batch row that repeats an earlier PDF (or an earlier row in the same batch) shows credit_cost: 0 and replay_of in the manifest. - It resets with the month: the same values next month are a new filing, 1 credit.
We don't store your values for this either: each document keeps one keyed fingerprint (an HMAC) of what it printed.
Two identical requests sent at the same moment are charged once: just before the usage is recorded the repeat check runs again, with nothing in between, so the later one becomes the earlier one's free repeat. With an Idempotency-Key the second request also waits for the first and gets the very same PDF (same bytes, same document id). Measured: 20 identical fills sent at once to a test server — one charged, 19 at X-Credit-Cost: 0.
Agents and the API cost the same
An AI agent working through the MCP server or llms.txt uses the same calls as your own code. Searching, reading parameters and checking are free, and the fill is 1 credit. An agent that retries a refused fill until it's right pays only for the PDF that comes out, and an agent that repeats a fill it already made pays nothing. Reading a person's documents with AI (ingest) costs 10 credits because it runs a model on every page; your agent can skip it and send the values itself.