How to Write Acceptance Criteria in Jira
Acceptance criteria are the contractual boundary between what a PM specifies and what an engineer builds. Written poorly, they leave room for interpretation that leads to rework. Written well in Jira, they become the checklist that QA runs against and the definition of "done" that prevents scope creep after a story ships.
This guide covers writing acceptance criteria directly inside Jira user stories using Given-When-Then format, Jira custom fields, and the integrations that connect criteria to test cases in tools like Zephyr Scale.
Step-by-step guide
Open the user story and add a dedicated AC section
Navigate to your Jira project, open the Story issue, and click into the Description field. Add a bold heading "Acceptance Criteria" below the user story statement. Use the formatting toolbar to create a bulleted list under that heading. Keeping AC in the Description (not Comments) ensures it is visible on the issue card in board view.
Use Given-When-Then format for each criterion
Write each criterion as: Given [a starting condition], When [an action occurs], Then [the expected result]. Example: "Given a workspace admin is on the Members page, When they click Invite and enter an email address, Then the invitation email is sent within 60 seconds and the member appears in Pending Invitations." This format is directly executable as a test case.
Add a custom field for structured AC
In Jira Project Settings, go to Issue Types > Story > Fields. Add a custom text field named "Acceptance Criteria" using Field Configuration. This separates AC from the general description and makes it queryable via JQL: issueFunction in linkedIssuesOf("type = Story AND 'Acceptance Criteria' is not EMPTY"). Ask your Jira admin to enable this field if you do not have project-admin rights.
Tag criteria by type
Prefix each criterion with a tag in brackets: [FUNCTIONAL], [PERFORMANCE], [ACCESSIBILITY], or [ERROR STATE]. This tells QA which test types to run. A single story often has 3-4 functional criteria and 1-2 edge case or error-state criteria that engineers forget to handle.
Link criteria to Zephyr Scale or Xray test cases
If your team uses Zephyr Scale (from the Jira Apps marketplace), create a test case for each AC item. Click "Create Test" in the Zephyr panel within the Story issue. Each test case maps to one criterion. This creates traceability: you can run a test execution cycle and see which AC items pass or fail before marking a story Done.
Review AC in sprint planning
During sprint planning, read the acceptance criteria aloud before accepting a story into the sprint. Engineers should explicitly confirm they understand each criterion. Any ambiguity ("what does 'within 60 seconds' mean on a slow connection?") surfaces here, not during QA. Jira allows you to add a reviewer's name to a comment on the AC section as a sign-off record.
Update AC if scope changes mid-sprint
When scope changes during a sprint, update the Jira Description immediately and add a comment tagging the EM and QA lead. Do not rely on Slack messages alone — the Jira issue is the single source of truth. Use the "Log Work" or "Comment" timestamp to create an audit trail of when AC changed.
Common mistakes
Writing UI instructions instead of outcomes
Bad: "The button should be blue and in the top right corner." Good: "Given a user on the dashboard, When they click Save, Then the current state is persisted and a success toast appears." AC should describe what the system does, not how it looks — design specs live in Figma.
Combining multiple scenarios in one criterion
"The user can invite members and remove members and change their roles" is three separate criteria. One criterion per behavior. This makes it possible to mark individual items as tested without marking the whole story done.
No error-state criteria
Most stories only have happy-path AC. Always add at least one error-state criterion: "Given an invalid email address is entered, When the user clicks Invite, Then an inline error message appears beneath the email field." Engineers who do not see error-state criteria do not build error-state handling.
Writing AC after implementation starts
AC written after engineering begins describes what was built, not what should be built. Write AC during story refinement, before sprint planning. In Jira, use the "Ready for Development" label to signal that AC is complete and reviewed.
Tips
Limit each story to 5-7 acceptance criteria; more than that means the story should be split
Use the Jira bulk edit feature to apply a "Missing AC" label to stories that have none, then filter and fix before the next sprint
Save your Given-When-Then template as a Jira story template so every new story starts with the AC structure pre-formatted
Ask QA to write the first draft of AC — they naturally think in test cases and will catch edge cases PMs miss
How Vantage helps
Vantage generates acceptance criteria automatically when it creates tickets from your PRD requirements. Each ticket includes Given-When-Then criteria derived from the requirement language, covering functional behavior, error states, and edge cases. When you push tickets to Jira, the AC is pre-populated in the issue description — eliminating the manual AC-writing step entirely.