A custom software project can be delivered on time, pass a developer’s tests and still disappoint the people who commissioned it. The screens exist, the buttons work and the demo looks convincing. Yet finance cannot reconcile a report, a manager can approve their own request, or an integration silently duplicates transactions. The disagreement is not always about poor coding. Often, the buyer and development team never agreed on the conditions that would prove the software was ready.
Acceptance criteria turn an intention such as “build an approval workflow” into observable outcomes: who can submit, who may approve, what happens when a request is rejected, which records change and how everyone can tell the action succeeded. They are especially important in custom software because the requirements cannot be borrowed wholesale from a packaged product.
This guide explains how business owners, product managers and procurement teams can write practical acceptance criteria before development begins, without trying to become software engineers. It includes realistic examples, a reusable template, a sign-off model and common failure patterns.
What are software acceptance criteria?
Software acceptance criteria are specific, verifiable conditions a feature or workflow must satisfy for an authorized business stakeholder to accept it. They translate a requirement into evidence. “Users can export orders” is a feature description; “a finance user can export only orders in their assigned business unit, with the selected date range and the same totals shown on screen” is closer to a testable acceptance criterion.
Acceptance criteria are not a substitute for discovery, design, architecture or quality assurance. They are the bridge between those activities and the buyer’s definition of a successful outcome. A useful criterion can be checked by a tester, demonstrated by a developer and understood by the person responsible for the business process.
As Atlassian’s guidance on user stories explains, a user story states who needs something and why, while acceptance criteria make the expected result testable. The business value should come first; technical implementation details belong in the design unless the implementation itself is a genuine constraint.
Acceptance criteria, definition of done and UAT are different
These three concepts often get mixed together in contracts and sprint meetings. Acceptance criteria describe the required behavior of a particular feature. A team-wide definition of done establishes quality and delivery conditions that apply across work items, such as code review, automated tests, documentation and deployment to a test environment. User acceptance testing (UAT) is the business-led exercise that checks whether the delivered system supports real processes and is acceptable for use.
A feature can meet its narrow acceptance criteria but fail the definition of done because security tests were not completed. Conversely, it can satisfy engineering standards but fail UAT because an operational exception was never considered. Atlassian’s explanation of the definition of done makes the distinction explicit; ISTQB’s definition of acceptance testing focuses on business needs and the decision to accept a system.
For buyers, the practical rule is simple: agree on feature behavior, agree on cross-cutting release standards and agree on who has authority to sign off. Do not collapse all three into a vague sentence such as “system to be fully tested and working.”
Start with a business outcome, not a screen
Before writing criteria, identify the workflow, actor, trigger, decision and resulting business record. Ask: What action is the user trying to complete? Which system is the source of truth? What is the expected change? Who must be prevented from doing it? What happens if an external service is unavailable? How will the user know the result?
For example, “build a customer onboarding form” leaves too much open. A better business outcome is: “An operations coordinator can create a new customer, validate mandatory tax and contact information, and submit the record for review without creating a duplicate customer.” That statement points directly toward success paths, validation, permissions and duplicate handling.
During discovery, write criteria alongside workflow maps and sample records. For complex portals, custom web application development services should begin with the operational decisions the application must support, not a list of attractive interface components.
The seven dimensions every critical workflow should cover
1. Happy path: what must happen when everything is valid?
Define the starting state, authorized actor, input and expected output. Specify the record status, confirmation and downstream action. Avoid “works as expected.” For an approval request, say that a valid submission creates one request with a unique ID, sets status to Pending Review and makes it visible to the designated approver.
2. Validation and edge cases: what must not be accepted?
Consider missing values, invalid formats, duplicate submissions, expired records, out-of-range amounts, empty results and simultaneous edits. State the user-visible response and whether data is saved, rejected or left unchanged. A validation message is useful only when it tells the user how to recover.
3. Permissions: who can view, create, change and approve?
List roles and scope separately. A regional manager may have permission to approve requests but only within their region. A finance analyst may view financial amounts without being able to modify them. Test both allowed and denied actions, including direct API requests, not just hidden buttons.
Identify source systems, rounding rules, date and time conventions, units, currency, record matching and reconciliation. If a report shows gross margin, define the calculation and whether canceled orders, refunds or tax are included. A report can be visually perfect and financially wrong.
5. Integrations and failure recovery: what happens beyond the application?
Specify what must happen when an API succeeds, times out, returns an error or accepts a request but the response is lost. Define retry behavior, duplicate protection, status visibility and exception ownership. If an external CRM is unavailable, should the application queue the change, block submission or allow a draft? The answer is a business decision as well as a technical one.
6. Non-functional requirements: how well must it work?
Capture performance, accessibility, security, availability, device support and data retention where material. “Fast” is not testable. “The order search returns the first page within three seconds for the agreed test dataset and load profile” is testable, but the threshold should be selected after assessing real business needs and feasibility, not copied from an arbitrary template.
7. Evidence and ownership: who will prove and approve it?
Assign a business owner and a test method to each important criterion. Evidence may be a test execution record, screenshot, audit entry, API trace, reconciliation report or demonstration against an agreed dataset. A criterion without an owner or evidence can become a late-stage argument.
A reusable acceptance-criteria template
Use one compact record for each meaningful behavior. The fields below work in a spreadsheet, ticketing system or requirements document; they do not require a specialized platform.
- Feature ID and business outcome: a unique reference plus the user decision or process being supported.
- Actor and preconditions: role, organization or region, record state, permissions and required data.
- Trigger and inputs: action performed, fields entered, files uploaded or event received.
- Expected result: visible outcome, state transition, stored data and any downstream effect.
- Exceptions and prohibited outcomes: validation, duplicate handling, unauthorized access and external failures.
- Test data and environment: representative records, boundary values, integrations and load assumptions.
- Verification and sign-off: test steps, evidence, owner, priority and acceptance decision.
A practical Given/When/Then structure can make a single criterion easier to review: Given an approved supplier and a purchase order in Draft, when an authorized buyer submits the order, then the status becomes Submitted, the order is locked against ordinary edits and the audit history records the submitting user and timestamp. This is a communication format, not a requirement to use a particular testing tool.
Example 1: approval workflow in an internal operations portal
Imagine a company replacing email-based expense approvals with a custom portal. The business story is: “As a department manager, I need to approve or reject employee expenses within my assigned department so finance receives a controlled, auditable decision.”
- AC-01: Given a submitted expense assigned to the manager’s department, the manager can approve or reject it and must provide a reason when rejecting.
- AC-02: A manager cannot approve their own expense, even if they can access the record through a saved URL or API call.
- AC-03: An approved expense changes to Approved once, records approver and decision time, and appears in finance’s approved-expense queue.
- AC-04: If two authorized managers act on the same pending request, only the first valid decision succeeds; the second receives a clear status-changed message.
- AC-05: An unauthorized user cannot retrieve the expense details or decision history, not merely the approval button.
Notice that these criteria cover concurrency, auditability and authorization, not just the click path. The organization still needs to decide limits, delegation rules, supporting documents, currency handling and retention. Those decisions should be resolved during refinement rather than silently assumed by developers.
Example 2: importing sales data from an external system
Consider a distributor that imports daily order files into an operations platform. “Import CSV” sounds straightforward until suppliers send duplicate rows, mismatched product codes and partial files. Here the acceptance criteria should protect data integrity and make failures visible.
- AC-01: An authorized operator can upload a file matching the approved schema; the system reports total rows received, accepted, rejected and skipped.
- AC-02: Invalid product codes and missing mandatory fields are rejected with row-level reasons; valid rows follow the agreed partial-import policy.
- AC-03: Re-uploading the same file or retrying after a network interruption does not create duplicate orders under the agreed business key.
- AC-04: The system stores the import ID, user, timestamp, source filename and processing outcome, with access restricted by role.
- AC-05: Imported order counts and financial totals can be reconciled against the accepted source rows; discrepancies appear in an exception report.
This is where the scope may extend beyond a single application screen into custom solutions and integrations. Buyers should identify the authoritative data source, duplicate key, exception queue and operational owner before implementation. Otherwise the interface may work while the underlying process remains unreliable.
Example 3: executive reporting and financial calculations
A dashboard requirement such as “show monthly revenue by region” is incomplete. Which month? Which region mapping? Does revenue include taxes, credits or canceled invoices? Are values converted into a common currency? When does a month close? Those decisions determine whether executives can trust the result.
- AC-01: Revenue equals the sum of approved invoice line amounts net of agreed credits, excluding canceled invoices, for the selected accounting period.
- AC-02: Region is derived from the approved customer-to-region mapping effective on the invoice date; unmapped customers are shown in an exception category.
- AC-03: Dashboard totals reconcile to the agreed finance control report for a signed-off test period, with documented rounding tolerance.
- AC-04: Users see the last successful data-refresh time and a visible warning when the agreed freshness threshold is exceeded.
- AC-05: A user with access to only one region cannot view another region’s underlying transactions through exports or drill-through.
A critical lesson: criteria should name the business definition and reference dataset, not merely ask the development team to match an existing dashboard whose logic may itself be undocumented.
How to write non-functional acceptance criteria without inventing targets
Performance, security and reliability requirements deserve explicit tests, but generic numbers can be counterproductive. Instead of declaring that every page must load in one second, classify workflows by criticality. Measure a baseline where one exists, define representative users and data volume, then agree on a target that is valuable and achievable.
For performance, specify the operation, dataset, concurrent user count, percentile and measurement environment. For example: “At the agreed staging load of 50 concurrent users and 100,000 searchable orders, the 95th-percentile search response is under the mutually approved threshold.” The actual threshold belongs in the project’s performance schedule.
For security, use observable requirements: an unauthorized user receives no protected record data; privileged changes are auditable; session expiry follows the agreed policy; sensitive exports are access-controlled. Security criteria must also be supported by appropriate engineering tests and review, not only by a business user clicking through screens.
For accessibility, agree on the applicable standard and test scope, including keyboard navigation, labels, focus order, contrast and error messaging. For integrations, specify recovery time expectations and what happens to pending work during outages. For backups and recovery, define the restoration objective, test evidence and owner rather than assuming that cloud hosting makes recovery automatic.
A practical sign-off matrix for buyers
A single “client approval” checkbox is too coarse for a substantial custom system. A more defensible sign-off model assigns responsibility by area. The process owner accepts business workflows; finance signs off financial calculations; security or IT reviews access and infrastructure controls; the integration owner validates cross-system data; the product owner coordinates the final release decision.
Classify criteria by impact. A critical criterion protects money, sensitive data, legal obligations or essential operations. A high-priority criterion blocks a major workflow. A medium-priority criterion affects efficiency or usability but may permit a documented workaround. A low-priority issue is cosmetic or otherwise non-blocking. Agree on severity definitions before testing, because a defect’s label should not be negotiated only after it appears.
For each criterion, track Not Tested, Passed, Failed or Blocked, with evidence and defect references. Record any accepted deviation with its impact, workaround, owner and target resolution. Do not treat “blocked because the external test environment was unavailable” as a pass.
The handoff between development QA and business UAT
The delivery team should test implementation correctness through unit, integration, regression, security and other appropriate checks. Business users should validate that the delivered workflows match operational reality. Asking end users to discover basic broken buttons during UAT wastes their time; asking developers alone to decide whether finance’s month-end process is acceptable misses business context.
Prepare UAT using realistic but appropriately protected test data, named user roles, known expected results and an agreed defect process. Include normal transactions, exceptions and recovery. Give testers a short script that states the business objective and expected outcome while leaving room for exploratory observations.
Before go-live, produce a traceability view connecting each major business requirement to acceptance criteria, test evidence, defects and final disposition. It need not be elaborate. A well-maintained table is more valuable than a large document nobody updates.
What to put in the contract or statement of work
For fixed-scope work, attach a baseline of prioritized features and acceptance criteria, with an explicit change-control process. Define review windows, testing responsibilities, access to test environments, what constitutes evidence, how defects are categorized and who can approve exceptions. Avoid language that implies every conceivable future requirement is included.
For iterative or time-and-materials delivery, acceptance criteria still matter. Agree them at the story or release level before work starts, then update them through controlled refinement. A change in business rules may legitimately change scope, effort and delivery dates. The key is to make that decision visible.
Acceptance should not automatically mean that all warranty or support obligations end. Separate feature acceptance, release approval, production handover and post-launch defect remediation. Also define who owns source code, configuration, documentation, deployment credentials and third-party accounts, as appropriate to the commercial arrangement.
Five mistakes that create expensive acceptance disputes
Mistake 1: Writing adjectives instead of outcomes
“Intuitive,” “seamless,” “robust” and “enterprise-grade” express aspirations, not proof. Replace them with scenarios, observable behavior and agreed thresholds. User experience can still be evaluated, but the method and participants should be identified.
Mistake 2: Covering only the successful demonstration
A polished demo rarely includes duplicate submissions, concurrent edits, expired sessions or an unavailable API. For important workflows, write at least one negative and one recovery scenario alongside the normal path.
Mistake 3: Leaving calculations and definitions implicit
“Sales,” “active customer” and “completed order” may mean different things across departments. Document formulas, source fields, effective dates and exclusions, then validate them against known examples.
Developers can demonstrate that code matches a specification. They should not be asked to decide whether an ambiguous commercial policy is correct. Name the business decision-maker and establish escalation when stakeholders disagree.
Mistake 5: Freezing unclear criteria or endlessly changing clear ones
Both extremes cause trouble. Clarify unknowns early, record assumptions and use a lightweight approval process when new information changes an agreed criterion. Maintain version history so everyone knows what was accepted at the time of development.
A four-week acceptance-readiness plan
Week 1: map critical workflows and decisions
Interview process owners and front-line users. Identify the five to ten workflows whose failure would have the greatest operational impact. Capture actors, source systems, business rules, exceptions and sample records. Mark unresolved policy decisions rather than allowing them to become hidden development assumptions.
Week 2: draft and challenge the criteria
Write outcome-oriented criteria for the high-priority workflows. Ask developers and testers to challenge ambiguity, edge cases and feasibility. Confirm permissions, reconciliation logic, external dependencies and non-functional targets. Split oversized requirements into separately testable behaviors.
Week 3: prepare verification and sign-off
Create a traceability matrix, representative test data and test accounts for each role. Assign owners, evidence types and severity definitions. Confirm which tests the delivery team performs and which scenarios business users will execute during UAT.
Week 4: baseline the release agreement
Approve the prioritized acceptance baseline and change process. Check that every critical requirement has a named approver and test method. Confirm how blocked tests, third-party outages, waivers and post-launch defects will be handled. This is the point to surface disagreements, not the night before launch.
The buyer’s acceptance-criteria checklist
- Can a non-technical stakeholder explain the business outcome of each critical feature?
- Does every criterion describe a verifiable result rather than an aspiration?
- Have authorization, invalid inputs, duplicate actions and failure recovery been considered?
- Are business calculations, data sources, time conventions and reconciliation rules explicit?
- Are performance, security, accessibility and reliability targets agreed where relevant?
- Is there realistic test data, an accountable reviewer and an evidence requirement?
- Is there a documented decision for failed, blocked and waived criteria?
- Are changes to scope and acceptance criteria controlled and visible to both parties?
Frequently asked questions
What is a simple example of software acceptance criteria?
For a password-reset workflow: “Given a registered user requests a reset, when a valid one-time reset link is used within the agreed expiry period, then the user can set a new password and the previous reset link can no longer be used.” Additional criteria should cover unknown accounts, expired links, rate limits and notifications.
Who should write acceptance criteria for custom software?
The product owner or business analyst usually drafts them with input from users, developers, QA and relevant control owners. The business owner should approve the intended behavior. Developers should challenge feasibility and ambiguity, but should not silently invent business policy.
When should acceptance criteria be finalized?
Agree them before implementing the corresponding feature. In iterative projects, refine them continuously as the backlog is prepared. The initial contract can contain a high-level baseline while detailed criteria are approved before each development cycle.
How many acceptance criteria should one feature have?
Enough to describe its essential success, failure and control conditions without turning every internal implementation detail into a contractual obligation. If a story needs dozens of unrelated criteria, it may contain several features and should be split.
Are Given/When/Then statements mandatory?
No. They are a useful way to remove ambiguity, especially for workflows and state changes. A concise checklist or decision table can be clearer for complex validation rules or role-permission matrices.
What is the difference between acceptance criteria and test cases?
Acceptance criteria define what must be true. Test cases define the steps, data and expected observations used to verify those conditions. Multiple test cases may be required to demonstrate one criterion, particularly where permissions and boundary conditions are involved.
Can non-functional requirements be acceptance criteria?
Yes. A performance, security, accessibility or availability requirement can be accepted when it has an agreed measurement method and realistic environment. Do not treat an unmeasured adjective such as “secure” as a complete criterion.
What happens when a requirement changes after development starts?
Record the revised criterion, its business reason, estimated impact and approval. Decide whether the change belongs in the current release or a later one. Preserve the previous baseline so acceptance and commercial discussions remain traceable.
Can a release be accepted with known defects?
Sometimes, if authorized stakeholders explicitly accept the risk, a workaround and a remediation plan. Critical failures involving data integrity, unauthorized access or essential operations should not be casually waived. The release policy should specify which severities can be deferred.
Do acceptance criteria replace a statement of work or UAT?
No. The statement of work sets commercial scope and responsibilities; acceptance criteria define testable behavior; UAT supplies business evidence for acceptance. They should reinforce one another rather than substitute for one another.
The best acceptance criteria do not attempt to predict every future feature. They remove avoidable ambiguity from the decisions that matter now: who can do what, which data changes, how exceptions are handled, what quality level is required and who confirms the outcome. Buyers gain a clearer basis for budgeting and sign-off; delivery teams gain a more reliable target for design and testing.
If your organization is preparing a custom application or modernizing an operational workflow, contact Actiknow about a requirements review. The discussion can focus on workflow mapping, integrations, acceptance evidence and the practical boundaries of the first release before development commitments are made.
Further reading
For additional definitions, see Atlassian’s guidance on user stories, its explanation of the definition of done and ISTQB’s definition of acceptance testing. These resources provide terminology; the acceptance baseline for a particular project must still reflect its own business processes and risk profile.