What Makes Acceptance Criteria Buildable for Trade Portals

Three weeks into a portal build, a developer will ask you a question you thought you already answered. That question is almost always about what happens when something goes wrong — a missing commodity code, a user with the wrong permissions, a shipment record that's half-complete. If your acceptance criteria don't say, the answer gets invented in code, and you find out at UAT.

This is the defining failure mode for importer and exporter portals: the spec describes the happy path in reasonable detail, and says almost nothing about the conditions that actually govern whether a shipment clears or stalls. A portal that touches customs data, duty deferment accounts, or compliance documentation has a long tail of edge cases. Every one of them is a build decision. If your criteria don't make those decisions, someone else will.

What 'acceptance criteria' actually means in this context

Acceptance criteria are the conditions a feature must meet before it's marked done. Not the feature description. Not the design brief. The specific, testable conditions.

The test that matters is what you might call the QA cold-read: hand your criterion to a tester who has never met you and never heard of your business. Can they confirm pass or fail without asking a single follow-up question? If the answer is no, the criterion isn't a criterion. It's a note to self.

'The portal should handle partial shipment records' fails the cold-read immediately. What does 'handle' mean? What constitutes partial? What happens next — does the record save, does it warn, does it block export?

'If a shipment record is saved without a commodity code, it enters Draft status and is excluded from all compliance exports until the code is added' passes. A tester can open the app, remove a commodity code, save the record, check its status, and run an export. Done.

The gap between those two sentences is where most portal projects spend their time in rework.

The four things every criterion needs

For a trade portal specifically — where data integrity has real compliance consequences — each criterion should nail four things:

1. The triggering condition. What state must the system or user be in for this criterion to apply? 'When a Logistics Admin clicks Approve on a shipment in Pending Review status…' is a condition. 'When approving a shipment…' is not — it leaves role and status undefined.

2. The expected system response. What does the system do? Not what the user sees — what the system actually does. 'The shipment status changes to Approved, a timestamp is written to the audit log, and a notification email is sent to the shipper's registered address.' That's a system response. 'The shipment is approved' is not.

3. The error or failure state. What happens when the condition can't be met? This is the most skipped part of trade portal specs, and the most expensive omission. What if the commodity code lookup times out? What if the duty deferment number is invalid? What if two users try to approve the same record simultaneously? These are not hypotheticals — they're daily occurrences in live logistics environments.

4. The role boundary. Who can do this, and who explicitly cannot? Multi-tenant portals — where an importer's team, a freight forwarder, and a customs broker might all have logins — are particularly prone to role-bleed. 'Admin can manage users' is not a role boundary. 'A Company Admin can invite, deactivate and reassign users within their own company account and cannot view shipments or users belonging to any other company' is.

Where trade portal criteria most often break down

Having worked through briefs for B2B ops portals, the same gaps appear in almost every first draft.

Screen-level thinking. The brief describes what a page looks like, not what it must do. 'The dashboard shows pending shipments' is a UI note, not a criterion. How are pending shipments defined? Which user roles see which shipments? What happens if there are none? Criteria should describe outcomes and rules, not layouts.

Missing commodity and compliance fields. A brief might say 'the portal supports customs documentation' and leave it there. But HS codes, country of origin, duty deferment account numbers, and incoterms all have specific validation rules that need to be written out. 'HS code must be 6–10 digits and validated against the UK Global Tariff lookup at submission' is a criterion. 'Customs fields are included' is not.

No definition of 'complete'. Shipment records in live trade environments are rarely completed in one sitting. The spec needs to say what a Draft record can and cannot do — whether it can be submitted, exported, or shared with third parties in that state. If the portal blocks export on incomplete records, that logic needs to be in the criteria, not discovered during UAT.

Assuming the integration just works. Portals that connect to carrier APIs, HMRC systems, or freight management platforms need criteria that cover what happens when those connections fail or return unexpected data. 'The portal integrates with [API]' is a milestone, not a criterion. 'If the carrier API returns a timeout, the system displays an inline error and queues the request for retry, logging the failure with timestamp and payload' is a criterion.

How AI-assisted scoping fits in

One practical shift that's changed how product studios approach this: using an AI tool to draft an initial criterion set from a plain-English process description.

You describe the workflow — say, a freight forwarder submitting a pre-arrival notification on behalf of an importer, with the importer's ops team reviewing before it goes to HMRC — and the tool generates a first-pass criterion list covering the obvious states, roles, and error conditions. It won't know your specific business rules, but it will surface the questions you hadn't thought to answer: what happens if the ops team reviewer is on leave? Can anyone else approve, or does it queue? Is there an escalation timer?

This is the value AI brings to scoping right now — not writing the final spec, but making sure the blank spaces in your thinking become visible before a developer hits them at sprint two. The human with domain knowledge still has to answer those questions. But finding them early is worth real money on a fixed-price build. If you want to understand how a studio should use that scoping process, What Your Discovery Phase Should Actually Deliver is worth reading before you book a call.

Getting to a brief a studio can build from

Once your criteria are drafted, the practical filter before handing to a studio is simple: go through each one and ask whether a QA engineer could test it in isolation, with no additional context, and return a clear pass or fail.

Any criterion that needs a verbal explanation to make sense goes back into rewrite. Any criterion that describes a screen rather than a rule gets split into the actual system behaviour it implies. Any criterion that says 'the system should handle X' without defining what handling means gets a specific response, a specific error state, and a specific role attached to it.

That process is slower than writing a feature list. It's also the difference between a portal that passes UAT in week eight and one that's still in rework in week fourteen. Studios that do fixed-price contracts — and that question is worth reading through before you sign anything — Fixed Price vs Time and Materials: Which Contract Wins? — need this level of specificity to hold price without building risk into their margin. Studios doing time-and-materials builds need it to avoid billing you for the discovery they should have done before code started.

Either way, the brief is your asset. A well-written criterion set is also what you take with you if you ever need to move studios — which is a practical consideration worth building in from day one. Five Questions That Separate Good Dev Studios from Expensive Ones covers what to ask before you hand over a brief at all.

If you're about to scope a trade portal and you're not sure your criteria are at the right level of detail, the fastest check is this: pick your most complex workflow — the one with the most conditional logic, the most user roles, the most third-party dependencies — and write its acceptance criteria out in full. If you run out of things to say before you've covered the error states, you're not done yet.

Useful tool

Try Samvara's Incoterms Chooser — Pick a practical Incoterm.