Writing Acceptance Criteria That Actually Work: A Guide for Business Stakeholders and Developers

Overview

Acceptance criteria define the conditions that a software feature must satisfy to be accepted by the stakeholder. Well-written acceptance criteria prevent the most common cause of custom software failure: building the wrong thing.

This guide is for both business stakeholders (who define what they need) and developers (who need to understand what to build).

1. The Given-When-Then Format

The most effective format for acceptance criteria is Given-When-Then (also called Gherkin syntax):

Given [a precondition or context]
When [an action is performed]
Then [the expected outcome]
And [additional expected outcomes]
But [outcomes that should NOT happen]

1.1 Example: Order Creation

User Story: As a sales agent, I want to create a new customer order so that I can record the customer's purchase.

Acceptance Criteria:

Scenario 1: Successful order creation
Given I am logged in as a sales agent
And I am on the "New Order" page
When I select a customer from the customer list
And I add at least one product with a valid quantity
And I click "Submit Order"
Then the order is saved with status "Pending"
And the order number is displayed (format: ORD-YYYY-XXXXXX)
And the customer receives an order confirmation email within 2 minutes
And the order appears in the "Pending Orders" list
And the inventory for the selected products is reserved (not deducted)

Scenario 2: Insufficient stock
Given I am on the "New Order" page
And Product A has 10 units in stock
When I add Product A with quantity 15
Then an error message is displayed: "Only 10 units available for [Product Name]"
And the order cannot be submitted until the quantity is corrected
And no inventory is reserved

Scenario 3: Customer with credit hold
Given Customer X has a credit hold flag set to true
When I select Customer X as the order customer
Then a warning banner is displayed: "This customer has a credit hold. Orders require manager approval."
And the "Submit Order" button is replaced with "Submit for Approval"
And submitting the order creates it with status "Pending Approval" (not "Pending")
And the customer's assigned manager receives an approval request notification

Scenario 4: Session timeout during order entry
Given I have been entering an order for 25 minutes
And my session is about to expire
When my session expires
Then the order data I have entered is saved as a draft
And I am redirected to the login page
And after logging in, I am returned to the draft order

2. Common Acceptance Criteria Mistakes

2.1 Too Vague

Bad:

The system should be fast.
The user interface should be intuitive.
The system should handle errors gracefully.

Good:

Given the order list contains 1,000 orders
When I navigate to the order list page
Then the page loads within 2 seconds on a standard broadband connection

Given I enter an invalid email address in the customer email field
When I click "Save"
Then an inline error message is displayed below the email field: "Please enter a valid email address"
And the form is not submitted
And focus is moved to the email field

2.2 Missing Edge Cases

Most acceptance criteria cover the "happy path" (everything works correctly) but miss edge cases. For every feature, ask:

•What happens if the input is empty?
•What happens if the input is too long?
•What happens if the network connection drops mid-operation?
•What happens if the user navigates away before completing the action?
•What happens if two users perform the same action simultaneously?
•What happens if the data doesn't exist (e.g., customer not found)?
•What happens if the user doesn't have permission?

2.3 Mixing Business Rules with UI Behaviour

Bad (mixes business rule with UI):

When the order total exceeds ₹1,00,000, show a warning and require manager approval, 
and the approval button should be green and the warning should be in a yellow box.

Good (separate scenarios):

Scenario: High-value order approval requirement (business rule)
Given an order total exceeds ₹1,00,000
When the sales agent clicks "Submit Order"
Then the order is created with status "Pending Approval"
And the sales agent's manager receives an approval notification
And the order cannot be fulfilled until approved

Scenario: High-value order warning display (UI behaviour)
Given an order total exceeds ₹1,00,000
Then a warning banner is displayed above the order total
And the "Submit Order" button label changes to "Submit for Approval"

3. Non-Functional Acceptance Criteria

Non-functional requirements (performance, security, accessibility) are often forgotten. Include them explicitly.

3.1 Performance

Performance: Order list page
Given the order list contains up to 10,000 orders
When I navigate to the order list page
Then the page loads within 2 seconds (P95 response time)
And the page remains responsive during loading (no browser freeze)

Performance: Order search
Given I type a search term in the order search box
Then search results appear within 500ms of the last keystroke

3.2 Security

Security: Role-based access
Given I am logged in as a "Sales Agent" (not a manager)
When I navigate to the "All Orders" page
Then I can only see orders assigned to my territory
And I cannot see orders from other territories
And attempting to access another territory's order by URL returns a 403 error

Security: Session management
Given I have been inactive for 30 minutes
When I try to perform any action
Then I am redirected to the login page
And my session data is cleared

3.3 Data Validation

Validation: Customer phone number
Given I am entering a new customer
When I enter a phone number
Then the field accepts only 10-digit Indian mobile numbers (starting with 6, 7, 8, or 9)
And the field rejects numbers with fewer or more than 10 digits
And the field rejects numbers starting with 0–5
And the error message is: "Please enter a valid 10-digit Indian mobile number"

Validation: Order quantity
Given I am adding a product to an order
When I enter a quantity
Then the field accepts only positive integers
And the field rejects decimal values, negative numbers, and zero
And the maximum quantity is 9,999 per line item

4. Acceptance Criteria Review Checklist

Before development begins, review every acceptance criterion against this checklist:

Completeness

Happy path is covered
Error cases are covered (invalid input, missing data, permission denied)
Edge cases are covered (empty state, maximum values, concurrent users)
Non-functional requirements are specified (performance, security)

Clarity

Each criterion has exactly one interpretation
Technical jargon is avoided (or explained)
Specific values are used (not "fast" but "under 2 seconds")
UI behaviour and business rules are in separate scenarios

Testability

Each criterion can be verified by a specific test
The expected outcome is observable (visible in the UI, in the database, in an email)
The preconditions can be set up in a test environment

Consistency

No contradictions with other acceptance criteria
Consistent with stated business rules
Consistent with existing system behaviour (for enhancements)

5. Acceptance Criteria Templates by Feature Type

5.1 List/Search Feature

Scenario: Default list display
Given I navigate to the [entity] list page
Then I see a list of [entities] sorted by [default sort field] [ascending/descending]
And the list shows [X] items per page
And the total count is displayed: "[N] [entities]"

Scenario: Search
Given I type "[search term]" in the search box
Then the list filters to show only [entities] where [field] contains "[search term]"
And the search is case-insensitive
And results appear within 500ms

Scenario: Empty search results
Given I search for a term that matches no [entities]
Then the list shows an empty state message: "No [entities] found matching '[search term]'"
And a "Clear search" link is displayed

Scenario: Pagination
Given the list contains more than [X] items
When I click "Next page"
Then the next [X] items are displayed
And the URL updates to reflect the current page
And the browser back button returns to the previous page

5.2 Form/Create Feature

Scenario: Successful creation
Given I fill in all required fields with valid data
When I click "Save"
Then the [entity] is created
And I am redirected to the [entity] detail page
And a success message is displayed: "[Entity] created successfully"

Scenario: Required field validation
Given I leave a required field empty
When I click "Save"
Then the form is not submitted
And an error message is displayed below the empty field: "This field is required"
And focus is moved to the first empty required field

Scenario: Duplicate detection
Given a [entity] with [unique field] = "[value]" already exists
When I try to create a new [entity] with the same [unique field]
Then an error message is displayed: "A [entity] with this [field name] already exists"
And the form is not submitted

Scenario: Unsaved changes warning
Given I have made changes to the form
When I try to navigate away without saving
Then a confirmation dialog is displayed: "You have unsaved changes. Are you sure you want to leave?"
And clicking "Stay" returns me to the form with my changes intact
And clicking "Leave" discards my changes and navigates away

6. Acceptance Criteria Sign-Off Process

1Draft: Developer or BA writes acceptance criteria based on user story discussion
2Review: Business stakeholder reviews and annotates (agrees / disagrees / adds missing scenarios)
3Revision: Developer updates based on feedback
4Sign-off: Business stakeholder signs off (email confirmation or system approval)
5Lock: Acceptance criteria are locked before development begins. Changes require a formal change request.

Sign-off statement:

"I confirm that the acceptance criteria for [User Story Name] correctly describe the expected behaviour of the system. I understand that the development team will build to these criteria, and that changes after sign-off will require a formal change request."

*See how IdeaSprout manages requirements for custom software projects →*

acceptance criteriarequirementsuser storiescustom softwareagilesoftware development