How to Add Acceptance Criteria Field in Jira

Your team spent two weeks building a feature. The stakeholder reviews it and says: “This isn’t what I meant.”

Sound familiar?

That moment — frustrating, expensive, avoidable — usually comes down to one missing thing: clear acceptance criteria. When everyone on a team knows exactly what “done” looks like before work starts, the rework rate drops, sprint velocity improves, and shipping becomes predictable.

Jira doesn’t include an acceptance criteria field out of the box. But adding one is straightforward — and it changes how your whole team works.

This guide walks you through every method, step by step.

What Is Acceptance Criteria in Jira?

Acceptance criteria are the specific conditions a user story or task must meet before it can be marked complete. They answer the question: “How will we know this is done?”

In Jira, these are typically added as a custom field on issue types like Stories, Tasks, or Epics. Think of them as the contract between the person requesting work and the person doing it.

Why it matters more than most teams realize:

• Teams without defined acceptance criteria spend 40–50% of development time on rework (Standish Group Chaos Report)
• Only 29% of software projects are delivered on time and within budget — poor requirements definition is the leading cause
• Projects with clear requirements are 2.5x more likely to succeed than those without (PMI Pulse of the Profession)
• Agile teams that consistently write acceptance criteria report up to 30% reduction in defects per sprint

The data is clear. When “done” is defined before work starts, teams ship faster, waste less time, and produce better outcomes.

Why Jira Doesn’t Include It by Default

Jira is built to be flexible. Atlassian ships it as a configurable framework, not a prescriptive tool. That means fields like acceptance criteria, definition of done, and testing notes are intentionally left to teams to add based on their workflow.

This flexibility is powerful — but it does mean you need to do a small amount of configuration before your team can start using it.

Here’s how to do that.

Method One — Add a Custom Text Field (Recommended for Most Teams)

This is the cleanest approach for teams who want a dedicated acceptance criteria field visible on every story.

Step One: Open Jira Settings

Go to your Jira project. In the top navigation, click the gear icon (⚙️) to open Jira Settings. You need project admin or global admin permissions to proceed.

Step Two: Navigate to Custom Fields

From the settings menu, go to: Issues → Custom Fields → Create Custom Field

Step Three: Choose Your Field Type

Select Text Field (multi-line) from the list. This gives you a large text box — ideal for writing out multiple acceptance criteria as bullet points or Given/When/Then statements.

Step Four: Name and Configure the Field

• Name it: Acceptance Criteria
• Add a description (optional but helpful): “Define the specific conditions this issue must meet before it can be marked Done.”
• Click Create

Step Five: Add the Field to Your Screen

Creating the field isn’t enough — you need to attach it to the right screen so it appears on your issues.

Go to: Issues → Screens → [Your Project Screen] → Add Field

Search for “Acceptance Criteria” and add it. Click Update.

Step Six: Confirm It Appears on Issues

Open any Story or Task in your project. Scroll down — you should now see the Acceptance Criteria field available for editing.

Method Two — Use the Description Field with a Template

If you’re on a Jira plan that limits custom field creation, or you want a quicker solution, you can enforce an acceptance criteria section inside the Description field using issue templates.

How to set this up:

1. Go to your project settings → Issue Types
2. Click on the issue type you want to update (e.g., Story)
3. In the Description field default text, add:

**User Story:**

As a [type of user], I want [goal] so that [reason].

**Acceptance Criteria:**

– [ ] Criteria 1

– [ ] Criteria 2

– [ ] Criteria 3

**Notes:**

Every new Story created in your project will now pre-populate with this template, prompting the creator to fill in acceptance criteria before assigning work.

Method Three — Use a Jira Plugin (For Advanced Teams)

If your team needs more structure — like linking acceptance criteria to test cases or tracking pass/fail status — Jira’s marketplace has purpose-built plugins.

Top options:

• Xray for Jira — Links acceptance criteria directly to test cases and shows test coverage on each issue
• Zephyr Scale — Tracks acceptance criteria alongside test execution results
• AC Manager for Jira — A lightweight plugin specifically built for acceptance criteria, with support for Gherkin (Given/When/Then) format

To install any plugin:

1. Go to Jira Settings → Apps → Find New Apps
2. Search by name
3. Click Try it free or Buy now
4. Follow the plugin’s setup guide

Over 65% of Jira teams use at least one marketplace app to extend core functionality (Atlassian State of the Teams Report). If you’re running QA alongside development, a testing plugin that integrates acceptance criteria is worth the investment.

How to Write Acceptance Criteria That Actually Work

Adding the field is step one. Filling it with useful criteria is step two — and where most teams fall short.

The Given/When/Then format (Gherkin syntax) is the gold standard:

Given [initial context or precondition]

When [the user takes an action]

Then [the expected outcome]

Example for a login feature:

Given the user is on the login page

When they enter a valid email and password and click “Sign In”

Then they are redirected to the dashboard within 2 seconds

This format eliminates ambiguity. There is no room for interpretation — either the condition is met or it isn’t.

Rules for writing effective acceptance criteria:

• Write them before development starts, not during
• Keep each criterion to one testable condition — avoid “and” statements
• Write from the user’s perspective, not the developer’s
• Make them binary — either pass or fail, no grey area
• Aim for 3–8 criteria per story — fewer means the story is vague, more means it should be split

Teams that follow structured acceptance criteria formats report 35% fewer post-release bugs and significantly higher sprint predictability (Agile Alliance, 2023).

Adding Acceptance Criteria to Epics and Sub-Tasks

The same process applies across all issue types. Once you’ve created the custom field, you can add it to Epic, Sub-Task, Bug, and Task screens in addition to Stories.

To do this:

1. Go to Issues → Screens
2. Select the screen associated with the issue type you want
3. Click Add Field → search for Acceptance Criteria → Update

For Epics specifically, acceptance criteria work slightly differently. Instead of defining individual test conditions, Epic-level criteria typically define business outcomes — the measurable impact the whole epic must achieve before it’s considered complete.

Making Acceptance Criteria Part of Your Definition of Done

One of the most effective uses of this field: block stories from moving to Done unless acceptance criteria are filled in and verified.

You can enforce this in Jira using workflow validators:

1. Go to your project’s Workflow settings
2. Select the transition that moves issues to “Done” or “In Review”
3. Add a Validator → choose Field Required
4. Select the Acceptance Criteria field
5. Save and publish the workflow

Now Jira will prevent any issue from being marked done unless someone has written acceptance criteria. This single workflow change can eliminate a major source of ambiguity in your sprints.

Teams that enforce definition-of-done criteria in their workflow see up to 45% reduction in stories returned to development after review (Scrum Alliance, 2022).

Common Mistakes to Avoid

Writing acceptance criteria after development starts. By then, the developer has already made assumptions. The criteria confirm what was built, not what was needed.

Making criteria too vague. “The page should load quickly” isn’t testable. “The page should load in under 2 seconds on a 4G connection” is.

Confusing acceptance criteria with implementation notes. Criteria describe the outcome. They don’t tell the developer how to build it.

Writing too many criteria for one story. If you need 10+ criteria, the story is doing too much. Split it.

Skipping criteria for “simple” stories. There is no such thing as a story so simple it doesn’t need a definition of done. Quick tasks get deprioritized and forgotten — clear criteria keep them accountable.

Best Practices for Teams Using Jira at Scale

Once you have acceptance criteria running across your board, a few practices make the whole system more reliable.

Assign ownership. The person writing the story should own the acceptance criteria — not the developer, not the manager. Whoever understands the user need is best placed to define what success looks like.

Review criteria in sprint planning. Don’t start a sprint without reviewing the acceptance criteria on every story being pulled in. This is where ambiguities surface — before they cost you a week of rework.

Use criteria to estimate effort. The more criteria a story has, the more complex it likely is. Teams that reference acceptance criteria during pointing sessions produce more accurate estimates.

Archive completed criteria. Accepted stories with their criteria become a record of your product’s agreed behaviour. This is invaluable for onboarding new team members and debugging regressions.

Link criteria to test cases. If you’re using Xray, Zephyr, or a similar QA tool, link each criterion to a corresponding test case. Your QA team works from criteria, not assumptions.

Jira Acceptance Criteria — Frequently Asked Questions

What’s the difference between acceptance criteria and a definition of done?

Acceptance criteria are specific to an individual story — they define what that particular issue must achieve. The definition of done is a global standard that applies to every story on your board (e.g., code reviewed, tests passed, documentation updated). Both are necessary.

Can I make the acceptance criteria field mandatory in Jira?

Yes — using workflow validators as described above, you can prevent stories from advancing past a certain status unless the field is populated.

What format should I use for acceptance criteria?

Given/When/Then (Gherkin) is the most universally understood. For non-technical stories, a simple bulleted list of testable conditions works just as well.

How many acceptance criteria should a story have?

Aim for 3–8 per story. Fewer than 3 usually means the story isn’t well defined. More than 8 usually means the story should be split into smaller pieces.

Does adding acceptance criteria slow down sprint planning?

Initially, yes — by about 10–15 minutes per planning session. But teams that adopt it consistently report saving 3–5 hours of rework per sprint (Scrum Alliance, 2022). The upfront investment pays back immediately.

How does getting better at sprint processes like this connect to growing our pipeline?

The discipline that makes your sprints run cleanly — clear targeting, structured execution, measurable outcomes — is the same discipline that builds a high-converting outbound pipeline. At SalesSo, we apply that exact framework to lead generation: precise targeting to reach the right decision-makers, campaign design built around what resonates, and scaling methods that turn consistent outreach into a steady flow of qualified meetings. If you want that same operational clarity applied to your pipeline, book a strategy meeting with our team.

Conclusion

Adding an acceptance criteria field in Jira takes less than 15 minutes. The impact lasts across every sprint, every quarter, and every product release that follows.

The teams that ship predictably aren’t the ones working harder. They’re the ones who define “done” before work starts, build that definition into their workflow, and hold every story accountable to it.

Start with a custom text field. Enforce it in your workflow. Write criteria in Given/When/Then format. Review them in every planning session.

That’s it. That’s the whole system.

The difference between teams that ship on time and teams that constantly rework the same features comes down to one question: does everyone know what done looks like before anyone starts?

Now yours will.