Acceptance Criteria: How to Write Them (With Examples)

Acceptance criteria checklist on a user story card

Acceptance criteria are the conditions a user story must satisfy before your team considers it ready to ship. Get them right and you cut rework, arguments, and surprise bugs at review time.

What are acceptance criteria?

Acceptance criteria are a set of specific, testable conditions attached to a single user story. They define what the feature must do (and not do) from the user's perspective. When every condition passes, the story is accepted. When even one fails, work continues.

Think of them as the contract between the person who requested the feature and the team building it. No guessing. No "I thought you meant something else." Just a clear list of pass-or-fail conditions written before development starts.

Acceptance criteria live at the story level. They answer: "How will we know this story is done?" That's a different question from "How will we know the sprint is done?" which is what the definition of done answers.

Key Facts

  • The Given-When-Then format for acceptance criteria was introduced by Dan North as part of behaviour-driven development (BDD) around 2006, giving teams a structured, testable way to express expected behavior. (Source: Dan North, "Introducing BDD," dannorth.net, 2006.)
  • The Agile Alliance notes that ambiguous or missing acceptance criteria are among the most common causes of rework in agile projects. (Source: Agile Alliance Glossary, agilealliance.org.)
  • Teams that write acceptance criteria before coding report faster handoffs from development to QA because testers already know what to verify.

Formats for writing acceptance criteria

There are two formats that teams use most. Neither is universally better. Pick the one that fits how your team works.

Given-When-Then (scenario-based)

Also called Gherkin format, this comes from behaviour-driven development (BDD). It structures each condition as a scenario with three parts:

  • Given -- the starting state or context
  • When -- the action the user takes
  • Then -- the expected outcome

Example -- user login:

Given a registered user is on the login page
When they enter a valid email and correct password and click "Sign In"
Then they are redirected to their dashboard and see a welcome message

Given a registered user is on the login page
When they enter a valid email and an incorrect password
Then they see an error message: "Email or password is incorrect" and remain on the login page

This format works well when the behavior is sequential and you can write multiple failure scenarios alongside happy paths. QA engineers can turn each scenario directly into a test case.

Rule-based (checklist)

Some teams prefer a simpler bulleted list of rules. This format suits stories where the conditions are independent rather than sequential.

Example -- product search:

- Search results appear within 2 seconds for any query
- Results are sorted by relevance by default
- Users can filter results by category, price range, and rating
- If no results are found, the page shows: "No results for [query]. Try different keywords."
- The search bar retains the user's query after results load

Rule-based acceptance criteria are faster to write and easier to scan. They work best for UI constraints, performance requirements, and edge cases that don't map neatly to a user action sequence.

Acceptance criteria vs definition of done

These two concepts are often confused. They solve different problems.

Acceptance criteria Definition of done
Scope One user story Every story, every sprint
Who writes it Product owner with the team The whole team together
When it's written Before development starts Once per project or sprint cycle
What it covers Functional conditions for this feature Cross-cutting quality gates (tests, reviews, documentation)
What happens when it fails That story is not accepted No story in the sprint ships

A story can pass all its acceptance criteria and still fail the definition of done -- for example, if it lacks unit tests or wasn't peer-reviewed. Both lists must pass before work is truly complete.

See the full breakdown in the definition of done article.

Characteristics of good acceptance criteria

Not every list of conditions qualifies as good acceptance criteria. Here's what separates useful from vague:

Testable. Each condition must have a clear pass or fail. "The UI looks nice" is not testable. "The button meets a 4.5:1 contrast ratio" is.

Written from the user's perspective. Acceptance criteria describe what the user experiences, not how the code is structured. Avoid implementation details like "the API returns a 200 status." Prefer "the user sees their updated profile immediately."

Specific. Numbers, states, and labels matter. "Fast response" becomes "response under 1.5 seconds." "An error message" becomes "the exact text: 'Password must be at least 8 characters.'"

Agreed before development starts. Criteria written after the feature is built tend to rationalize what was built rather than describe what was needed. Write them during backlog refinement.

Not too many. Three to eight conditions is a healthy range. A story with fifteen acceptance criteria is probably two or three stories hiding inside one.

How to write acceptance criteria

Step 1: Start with the user story

You can't write acceptance criteria without a clear user story. Confirm you have one in this format:

As a [persona], I want [goal], so that [reason].

If the story is vague, sharpen it before writing conditions.

Step 2: Ask "what must be true for this to work?"

List the behaviors and outcomes the feature must produce. Cover the happy path first, then the edge cases and failure states.

Step 3: Choose a format

Pick Given-When-Then if the behavior is sequential and QA will drive test creation. Pick rule-based if the conditions are independent or you're under time pressure.

Step 4: Write in testable language

Replace vague words. "Quickly" becomes a number. "Properly formatted" becomes the exact format. "Should work on mobile" becomes "layout is responsive at 375px width."

Step 5: Review with the team before development starts

Share the draft with developers, QA, and stakeholders. Developers will catch conditions that are technically impossible. QA will spot missing edge cases. Stakeholders will catch business logic errors. Do this during backlog refinement or sprint planning so everyone aligns before a line of code is written.

Step 6: Attach them to the story

Add the finalized criteria to the story in your product backlog. They stay attached throughout development and are the checklist your team uses during the sprint review.

Acceptance criteria examples

Here are three worked examples across different story types.

Example 1: User login

Story: As a returning user, I want to sign in with my email and password, so that I can access my account.

Given the user is on the sign-in page
When they enter a registered email and correct password and click "Sign In"
Then they are redirected to their dashboard within 2 seconds

Given the user enters an incorrect password three times
When they attempt a fourth login
Then the account is locked for 30 minutes and the user sees:
"Too many failed attempts. Try again in 30 minutes."

Given the user is signed in
When they click "Sign Out"
Then their session ends and they are redirected to the homepage

Example 2: Checkout total

Story: As a shopper, I want to see my order total before I pay, so that I know exactly what I owe.

Condition Pass when
Subtotal is shown Line items sum correctly
Tax is itemized Tax rate and amount shown separately
Discount is applied Promo code reduces subtotal before tax
Shipping is shown Cost displayed or "Free shipping" if eligible
Total updates in real time Total recalculates when cart changes without page reload

Example 3: Search with no results

Story: As a user, I want to know when my search returns nothing, so that I can try different keywords.

- When a search returns zero results, the page displays: "No results for '[query]'. Try different keywords."
- The search bar retains the user's original query
- Related category suggestions appear below the message if available
- The page title updates to reflect the empty search state

Common mistakes to avoid

Writing them after the fact. Acceptance criteria written post-development describe what was built, not what was needed. Write them first.

Being vague about error states. Happy-path-only criteria leave developers guessing about failure handling. Always include at least one failure scenario.

Mixing in technical implementation. "The service calls the payment API with a POST request" is not an acceptance criterion. "The user sees a payment confirmation within 3 seconds" is.

Making them too large. If your acceptance criteria cover multiple distinct features, split the story. A good story with good criteria fits on an index card.

Skipping the team review. Criteria written solo (usually by the product owner) miss developer constraints and QA edge cases. Review together before the sprint starts. Use agile ceremonies like refinement to do this consistently.

Frequently asked questions

What are acceptance criteria?

Acceptance criteria are the specific, testable conditions a user story must satisfy before the team accepts it as complete. They define what the feature must do from the user's perspective, and they're written before development starts.

Who writes acceptance criteria?

The product owner typically drafts acceptance criteria, but the whole team -- developers, QA, and sometimes stakeholders -- reviews and refines them before development begins. Writing criteria in isolation leads to missed edge cases and rework.

What is the difference between acceptance criteria and the definition of done?

Acceptance criteria are per-story: they describe what one specific feature must do. The definition of done is global: it's a checklist that applies to every story in the sprint (peer review, test coverage, documentation, etc.). A story must pass both before it ships.

What is Given-When-Then?

Given-When-Then is a structured format for writing acceptance criteria as testable scenarios. "Given" sets the context, "When" describes the user's action, and "Then" states the expected outcome. It was introduced by Dan North as part of behaviour-driven development (BDD) around 2006 and is widely used in agile teams today.

How many acceptance criteria should a user story have?

Aim for three to eight. Fewer than three often means the story is underspecified. More than eight usually means the story is too large and should be split into smaller stories.

Good acceptance criteria don't guarantee a great product, but they prevent a specific category of failure: building something that nobody meant to build. Write them early, review them together, and you'll find your sprint reviews go from debates about what "done" means to straightforward demonstrations of working software.