Known Issues: [Product name]
Living, customer-facing register of confirmed defects and
limitations that users can hit in released versions: for each issue
its ID, symptom, affected versions and platforms, workaround, status,
fix version and links, plus the rules for publishing, reviewing and
retiring entries. Release notes and troubleshooting pages link here
instead of keeping their own lists. The troubleshooting and
problem-reporting content is structured in line with
ISO/IEC/IEEE 26514:2022 (information for users). Replace every
[bracketed] value and every row marked Example.
Document control
| Field | Value |
|---|
| Document ID | [KI-REG-001] |
| Product or product line | [Product name] |
| Published at | [https://docs.example.com/changes/known-issues] |
| Feed or subscription | [RSS or Atom URL, mailing list, status page link] |
| Issue tracker | [Tracker name and project key] |
| Version | [1.0] |
| Status | [Draft / Active / Retired] |
| Owner | [@docs-lead] |
| Approvers/reviewers | [@support-lead], [@engineering-manager], [@product-manager], [@security-lead] |
| Last updated | YYYY-MM-DD |
| Last full review | YYYY-MM-DD |
| Classification | Public (register), Internal (sections 1 to 3) |
Approvals
| Role | Name | Decision | Date |
|---|
| Documentation lead | [@name] | [Approve / Approve with conditions / Reject] | YYYY-MM-DD |
| Support lead | [@name] | [Decision] | YYYY-MM-DD |
| Engineering manager | [@name] | [Decision] | YYYY-MM-DD |
| Security lead (disclosure rules) | [@name] | [Decision] | YYYY-MM-DD |
Revision history
| Version | Date | Author | Change summary |
|---|
| 1.0 | YYYY-MM-DD | [@name] | First published register and rules |
| 1.1 | YYYY-MM-DD | [@name] | Example: Added the platform column and the 90-day archive rule |
Contents
1. Scope and publication rules
1.1 What is in scope
| Include | Exclude |
|---|
| Confirmed defects in supported, released versions with a user-visible symptom | Unreproduced reports still in triage |
| Limitations that behave differently from the documentation | Feature requests and roadmap items |
| Third-party or platform problems that affect the product, with a workaround | Active service incidents (use the status page and Incident Communication (dev/incident-communication)) |
| Data product defects visible to consumers (late, missing or wrong fields) | Unfixed security vulnerabilities (coordinated disclosure first) |
| Documentation errors that cause failed tasks, until corrected | Defects only in unreleased builds |
1.2 Publication rules
| Rule ID | Rule |
|---|
| PUB-01 | Publish an entry when an issue is confirmed (reproduced by engineering or support) and at least [n] customers or one high-impact use case is affected, or when support has answered the same question [n] times. |
| PUB-02 | Publish the same business day for impact level SEV1, coordinated with Incident Communication (dev/incident-communication), within [2] business days of confirmation for SEV2, and within [5] business days otherwise. |
| PUB-03 | An entry needs the docs owner and an engineering reviewer. Entries that mention security, privacy or data loss also need the security lead. |
| PUB-04 | Publish a workaround only after someone other than its author has tested it on an affected version. |
| PUB-05 | Do not promise fix dates. State a target release only when it is committed in the release plan, and label it "planned". |
| PUB-06 | Never include customer names, account IDs, personal data, internal hostnames or stack traces with secrets. Use fictional or generic examples. |
| PUB-07 | Each entry keeps its ID for life. IDs are never reused, even after an entry is withdrawn. |
| PUB-08 | Announce new SEV1 and SEV2 entries through [release notes, in-product banner, mailing list]; others appear in the feed only. |
2. Entry fields and status model
2.1 Fields
| Field | Required | Content |
|---|
| ID | Yes | KI-NNN, sequential, never reused |
| Title | Yes | The symptom in user terms, not the internal cause |
| Symptom | Yes | What the user sees: message text, behaviour, where |
| Affected versions | Yes | Exact versions or range, for example 4.2.0 to 4.3.1 |
| Affected platforms | Yes | OS, browser, region, plan, integration or "All" |
| Conditions | Yes | The settings or steps that trigger the issue |
| Impact level | Yes | SEV1 to SEV4 from section 3 |
| Workaround | Yes | Tested steps, or "None available" with the reason |
| Status | Yes | One value from section 2.2 |
| Fix version | When fixed or planned | Version that contains the fix, or "planned for x.y" |
| First published | Yes | YYYY-MM-DD |
| Last updated | Yes | YYYY-MM-DD |
| Links | Yes | Tracker reference, troubleshooting page, release note, status page |
2.2 Status model
| Status | Meaning | Reader action |
|---|
| Investigating | Confirmed and being analysed; cause or fix not yet known | Apply workaround if listed; subscribe for updates |
| Workaround available | A tested workaround exists; fix not yet released | Apply the workaround |
| Fix planned | Fix is committed to a named release | Plan to upgrade to that release |
| Fixed | Fix released in the stated version | Upgrade to the fix version |
| Won't fix | The product will not change; the behaviour is documented | Use the documented alternative |
| Withdrawn | Entry was published in error or is not a defect | None |
3. Impact levels
Impact levels map onto SEV1 to SEV4 from Incident Severity Matrix
(ops/incident-severity-matrix), applied to the impact on users of
an affected version rather than to a live outage. SEV1 to SEV3 keep
the matrix meaning. SEV4 here covers minimal, cosmetic user impact
that needs no workaround; the incident matrix reserves SEV4 for a
risk with no current customer impact, so a SEV4 known issue is
usually not an incident at all.
| Level | User impact | Examples of qualifying symptoms | Publication |
|---|
| SEV1 | Data loss, wrong financial results, or a core task impossible for most users with no workaround | Duplicate charges, records silently dropped | Within PUB-02 limit, announced, pinned at the top |
| SEV2 | Core task impossible for a subset of users, or possible only with a difficult workaround | Checkout fails on one browser version | Within PUB-02 limit, announced |
| SEV3 | Non-core task affected, or a simple workaround exists | Export column order wrong | Feed only |
| SEV4 | Minimal user impact (cosmetic); no workaround needed | Label truncated in one locale | Feed only; may be grouped |
4. Open issues summary
Sort by impact level, then by ID. Show only issues whose status is not
Fixed, Won't fix or Withdrawn; those move to section 6.
| ID | Title | Affected versions | Platforms | Impact | Status | Workaround | Fix version |
|---|
| KI-014 (Example) | Partial refunds over USD 10,000 return error amount_invalid | Checkout API, all versions since 2026-08-01 | All | SEV2 | Fix planned | Split into two refunds | Planned for 2026-11 API release |
| KI-016 (Example) | Saved cards not shown in hosted checkout on one mobile browser version | JavaScript SDK 4.2.0 to 4.3.1 | [Browser] [version] on iOS | SEV2 | Workaround available | Pass savedCards: "always" | Not yet planned |
| KI-012 (Example) | Orders data product: shipped_at null for click-and-collect orders | Orders data product contract 2.1 | Warehouse share, files | SEV3 | Investigating | Use collected_at | Not yet planned |
| KI-017 (Example) | Settlement report CSV uses semicolons when browser locale is German | Dashboard, current | Any browser with de locale | SEV4 | Workaround available | Switch export format to XLSX | Not yet planned |
| [KI-NNN] | [Symptom in user terms] | [Versions] | [Platforms] | [SEVn] | [Status] | [Short workaround] | [Version] |
5. Issue entries
Use the following block for every entry. Keep the heading text as
KI-NNN: [title] so the anchor is predictable.
KI-014: Partial refunds over USD 10,000 return amount_invalid
| Field | Value |
|---|
| ID | KI-014 (Example) |
| Symptom | A partial refund request for more than USD 10,000.00 on a larger payment fails with HTTP 400 and error code amount_invalid. Full refunds of the same payment succeed. |
| Affected versions | Checkout API, all dated versions, behaviour introduced 2026-08-01 |
| Affected platforms | All; API and dashboard |
| Conditions | Payment amount above USD 10,000.00 and a refund amount above USD 10,000.00 that is less than the payment amount |
| Impact | SEV2: affected merchants cannot refund large orders in one step |
| Workaround | Issue two partial refunds, each at or below USD 10,000.00, against the same payment. Use separate idempotency keys for each request. |
| Status | Fix planned |
| Fix version | Planned for the 2026-11 API release (see the release plan) |
| First published | YYYY-MM-DD |
| Last updated | YYYY-MM-DD |
| Links | Tracker [PAY-4821]; troubleshooting entry "Refund fails with amount_invalid"; release note for the fix when published |
How to tell whether you are affected. You call the refunds
endpoint with an amount field above 1,000,000 cents for a payment
larger than that amount, and the response body has
"code": "amount_invalid".
- Split the refund amount into parts of USD 10,000.00 or less.
- Send one refund request per part, each with a new idempotency key.
- Confirm the payment's refunded total equals the intended amount.
KI-016: Saved cards not shown in hosted checkout on one mobile browser version
| Field | Value |
|---|
| ID | KI-016 (Example) |
| Symptom | Returning customers do not see their saved cards in the hosted checkout; the page shows only the new card form. |
| Affected versions | JavaScript SDK 4.2.0 to 4.3.1 |
| Affected platforms | [Browser] [version] on iOS only |
| Conditions | savedCards option left at its default value "auto" |
| Impact | SEV2: affected customers must re-enter card details, which raises abandonment |
| Workaround | Set the savedCards option to "always" when initialising the SDK. Tested on SDK 4.3.1. |
| Status | Workaround available |
| Fix version | Not yet planned |
| First published | YYYY-MM-DD |
| Last updated | YYYY-MM-DD |
| Links | Tracker [SDK-1290]; SDK configuration reference, savedCards option |
KI-012: Orders data product shipped_at is null for click-and-collect orders
| Field | Value |
|---|
| ID | KI-012 (Example) |
| Symptom | In the Orders data product, rows with fulfilment_type = 'collect' have shipped_at null even when the order is complete. |
| Affected versions | Orders data product contract version 2.1 |
| Affected platforms | Warehouse share and daily file export |
| Conditions | Click-and-collect orders created since contract 2.1 was released |
| Impact | SEV3: fulfilment-time metrics exclude these orders |
| Workaround | Use collected_at for click-and-collect orders, for example coalesce(shipped_at, collected_at) |
| Status | Investigating |
| Fix version | Not yet planned |
| First published | YYYY-MM-DD |
| Last updated | YYYY-MM-DD |
| Links | Data contract for the Orders data product; data incident [DI-NNN] if raised |
KI-017: Settlement report CSV uses semicolons when the browser locale is German
| Field | Value |
|---|
| ID | KI-017 (Example) |
| Symptom | The settlement report CSV downloaded from the dashboard separates columns with semicolons, so tools that expect commas show one column. |
| Affected versions | Dashboard, current release |
| Affected platforms | Any browser with the de locale |
| Conditions | Export format CSV selected while the interface locale is German |
| Impact | SEV4: minimal impact, the data is correct and only the separator differs |
| Workaround | Switch the export format to XLSX, or set the import tool's delimiter to semicolon. |
| Status | Workaround available |
| Fix version | Not yet planned |
| First published | YYYY-MM-DD |
| Last updated | YYYY-MM-DD |
| Links | Dashboard export documentation |
KI-NNN: [Symptom in user terms]
| Field | Value |
|---|
| ID | [KI-NNN] |
| Symptom | [What the user sees] |
| Affected versions | [Versions] |
| Affected platforms | [Platforms] |
| Conditions | [Trigger] |
| Impact | [SEVn: reason] |
| Workaround | [Tested steps, or "None available" and why] |
| Status | [Status] |
| Fix version | [Version or "Not yet planned"] |
| First published | YYYY-MM-DD |
| Last updated | YYYY-MM-DD |
| Links | [Tracker], [Troubleshooting], [Release note] |
6. Resolved issues archive
Move entries here when their status becomes Fixed, Won't fix or
Withdrawn. Keep them for [the support life of the last affected
version, or at least 90 days], then move them to a yearly archive page
that stays online. Keep each entry's anchor so old links still work.
| ID | Title | Affected versions | Resolution | Fix version | Resolved on |
|---|
| KI-009 (Example) | Webhook signatures fail after key rotation for up to 10 minutes | Checkout API, events before 2026-07-15 | Fixed | 2026-07-15 platform release | YYYY-MM-DD |
| KI-011 (Example) | Dashboard search ignores accents in customer names | Dashboard | Won't fix: documented, search is accent-insensitive by design in the new search | Not applicable | YYYY-MM-DD |
| KI-013 (Example) | Duplicate entry for KI-012 | Not applicable | Withdrawn | Not applicable | YYYY-MM-DD |
7. Writing rules for entries
- Title the entry with the symptom the user sees, using the exact
error text or UI label where one exists.
- State affected versions as exact numbers or dated ranges. "Recent
versions" and "older browsers" are not allowed.
- Write the workaround as numbered steps in the imperative. Say what
the user gives up by using it, if anything.
- Say "None available" when there is no workaround, and add what users
can do instead (for example, avoid the trigger, contact support).
- Describe cause only when it helps users decide (for example "affects
only accounts created before a date"). Do not speculate.
- Avoid blame towards customers, partners or platform vendors; name a
third-party component only when users need it to recognise the
issue.
- Keep personal data, secrets, internal URLs and customer identities
out of every field (PUB-06).
- Use terms from the product termbase and the same names as the UI,
API and SDK.
- Update "Last updated" on every material change and say what changed
in the entry's first line, for example "Updated YYYY-MM-DD: fix now
planned for 4.4.0."
8. Linking and traceability
8.1 Linking rules
| Rule ID | Rule |
|---|
| LNK-01 | Release notes include a "Known issues" heading that lists the IDs affecting that release and links to this register; they do not duplicate entry text. |
| LNK-02 | When a fix ships, the release note's "Fixed" list references the KI ID, and the KI entry links back to the release note. |
| LNK-03 | Troubleshooting (docs/troubleshooting) symptom entries caused by a known defect link to the KI entry instead of repeating the workaround. |
| LNK-04 | Support macros and status updates link to the entry anchor, not to the register top. |
| LNK-05 | A Won't fix entry links to the documentation that describes the intended behaviour or alternative. |
| LNK-06 | Deprecation-related breakages link to the relevant Deprecation Notice (docs/deprecation-notice). |
8.2 Traceability matrix
| KI ID | Tracker item | Troubleshooting entry | Release note (affected) | Release note (fixed) | Support macro |
|---|
| KI-014 (Example) | PAY-4821 | Refund fails with amount_invalid | 2026-08 API release | Pending | MAC-REF-07 |
| KI-016 (Example) | SDK-1290 | Saved cards missing | SDK 4.2.0 | Pending | MAC-SDK-03 |
| KI-009 (Example) | PLAT-3310 | Signature verification fails | 2026-07 platform release | 2026-07-15 release | MAC-WH-02 |
| [KI-NNN] | [Item] | [Entry] | [Release] | [Release] | [Macro] |
9. Review cadence and ownership
| Activity | Frequency | Owner | Output |
|---|
| Triage of candidate issues from support and engineering | Weekly | [@support-lead] with [@docs-lead] | New entries or a recorded "not published" decision |
| Status check of every open entry | Every [2] weeks | Entry owner | Updated status and "Last updated" date |
| Release review | Each release | [@release-manager] with [@docs-lead] | Fixed entries moved, release notes linked |
| Workaround re-test | Each minor release | [@qa-owner] | Workarounds confirmed or corrected |
| Full register review | Quarterly | [@docs-lead] | Stale entries closed or escalated; archive moves |
Escalate any SEV1 or SEV2 entry that has had no status change for
[30] days to the engineering manager and product manager.
10. Measurement
Use aggregate, consent-respecting, cookieless measurement only;
honour Global Privacy Control and never require readers' personal
data.
| Measure | Definition | Target |
|---|
| Time to publish | Days from confirmation to entry, per impact level | Within PUB-02 limits |
| Freshness | Share of open entries updated within the review interval | [Target]% |
| Deflection signal | Support tickets closed with a KI link, as a share of tickets for that issue | Rising trend |
| Workaround accuracy | Share of workarounds that pass re-test at each release | 100% |
| Page usefulness | Aggregate "Was this helpful?" responses on the register | [Target] |
11. Glossary and references
11.1 Glossary
| Term | Meaning in this document |
|---|
| Known issue | A confirmed, user-visible defect or limitation in a released version, published with its status |
| Workaround | Tested steps that let users avoid or reduce the impact until a fix ships |
| Fix version | The released version that contains the correction |
| Impact level | SEV1 to SEV4, reusing the incident severity scale for user impact |
| Register | The single maintained list of known issues for a product |
| Coordinated disclosure | Publishing a security vulnerability only after a fix or mitigation, by agreement with the reporter |
11.2 References
| Reference | Version or date | Use in this document |
|---|
| ISO/IEC/IEEE 26514:2022, Systems and software engineering, Design and development of information for users, https://www.iso.org/standard/77451.html | Edition 1, 2022 | Structure of troubleshooting and problem-reporting information for users (structure only) |
Incident Severity Matrix (ops/incident-severity-matrix) | Internal | SEV1 to SEV4 definitions |
| [Internal support policy] | [Version] | [Use] |
Standard and licence note
Structure aligned with ISO/IEC/IEEE 26514:2022 for troubleshooting and
problem-reporting information for users. There is no formal standard
for known-issues registers; the fields, status model and rules here
are an original design. No ISO text, table or definition is
reproduced. This template is original text written for this
collection. Check the current official version of the standard before
use. Template licence: MIT.