Week 53 and Year End: Avoiding Date Errors in Your Shop

Week numbering under ISO 8601 follows three rules: a week starts on Monday, the weeks of a year are numbered from 01 to 52 or 53, and week 01 is the first week with at least four days in the new year (strftime(3)). The same manual page puts it another way: week 01 is the week containing the first Thursday of the year, or the week that contains January 4. That is the heart of the problem. A calendar week does not belong to the year in which its Monday falls, but to the year in which its Thursday falls. That year is called the ISO week-based year, and at the edges it differs from the calendar year.

For the turn of 2026/2027 this means: January 1, 2026 was a Thursday, so ISO week-based year 2026 already began on Monday, December 29, 2025. The week from December 28, 2026 to January 3, 2027 contains Thursday, December 31, 2026, and therefore counts as week 53 of 2026. New Year's Day and January 2 and 3, 2027 thus fall in the new calendar year but in the old week-based year. Week 1 of 2027 only begins on Monday, January 4, 2027. The Python documentation describes the same thing from the calendar side: an ISO year consists of 52 or 53 full weeks that start on Monday and end on Sunday (Python documentation). By the same rules, 2015 and 2020 also had a week 53, and the next one comes in 2032.

The manual page offers an example that reads like a template for 2027: January 1, 2010 was a Friday, only three days of that calendar week fell in the new year, and so they counted as week 53 of 2009 (strftime(3)). The same situation last occurred on January 1, 2021, and it returns on January 1, 2027. If you have rebuilt your shop's date logic or added extensions since then, do not assume it still handles the case. The table shows the affected days.

Many weekly reports are not built in PHP but directly in SQL: revenue per calendar week, returns per week, orders compared with the same week last year. MariaDB calculates the week number with WEEK(), and the result depends on a mode. Modes 0 to 7 differ in whether the week starts on Sunday or Monday, whether counting starts at 0 or 1, and which week counts as the first; only mode 3 numbers weeks according to ISO 8601 (MariaDB documentation). If the second argument is omitted, the value of the system variable default_week_format applies (MariaDB documentation), and its default is 0, meaning weeks start on Sunday and counting starts at week 0 (MariaDB documentation).

Measured on MariaDB 11.8, the call without a mode returns week 0 for January 1, 2027, and the ISO mode returns week 53. Putting YEAR() next to it rebuilds the label "2027-W53". The correct choice is YEARWEEK(date, 3): the function returns year and week together, and the documentation points out that the year in the result may differ from the year of the date in the first and the last week of the year (MariaDB documentation). Here, that is exactly what you want.

For reporting, this leads to a simple rule: calculate the week label in exactly one place, as a pair of ISO week-based year and ISO week, and have every report, export and dashboard take it from there. Where a spreadsheet processes the data further, put the finished label into the export file as text instead of letting the spreadsheet recalculate it from the date. Comparing week 53 with the previous year needs an additional decision, because 2025 had no week 53. You can compare it with week 52 of the previous year or with the same calendar days; the report should state which option applies, so nobody reads a January slump into what is merely a counting convention.

Number ranges are a well-known checkpoint at year end, which is why they are only one of several here. Shopware describes number ranges as series of characters and digits that uniquely identify orders, customers or documents; depending on requirements, it may be necessary to include day, month or year in the number range (Shopware documentation). In advanced mode, a pattern accepts placeholders such as {date} or {date_d.m.Y}, while the incrementing number sits in {n} and starts at the specified start number (Shopware documentation). The documentation does not describe an automatic restart on January 1.

For invoices, the German VAT Act requires a sequential number with one or more series of numbers that the issuer assigns only once (§ 14 Abs. 4 Nr. 4 UStG). A year component in the number is therefore possible, but it needs care at the year boundary: it has to reflect the calendar year, not the week-based year, it has to be generated in the same time zone as the invoice date, and switching the pattern on January 1 must not produce any number a second time. Whether and how a number range restarts at year end is something to agree with your tax advisor. What you can check technically in advance is which number the first document of the new year will get and which date it will show.

Deletion jobs also depend on the year boundary. Under the German Fiscal Code, the retention period starts at the end of the calendar year in which, for example, the accounting voucher was created (§ 147 AO). Books and records must be kept for ten years, accounting vouchers for eight years and other documents for six years, unless other tax laws allow shorter periods (§ 147 AO). A deletion job that calculates "creation date plus eight years" therefore deletes too early: an accounting voucher from January 5, 2026 must not be removed as early as January 2034, because its period ends at the end of 2034 at the earliest. How retention and data protection fit together in a shop is covered in the article on GDPR-compliant backup and retention.

For retail, the turn of the year falls in a high-revenue season. The German Retail Federation puts the share of the last two months in annual retail sales at 18.5 percent (HDE). For online retail it forecast sales of 22.2 billion euros in the 2025 Christmas season (HDE), and vouchers once again topped the list of the most popular Christmas gifts (HDE). For date logic this means many promotions expire shortly before the turn of the year, and many vouchers are redeemed shortly after it.

Shopware promotions have one field each for the start and end of validity, which define whether and for what period a promotion runs (Shopware documentation). At year end, three details are worth a look. First, the time of day: a promotion "until December 31" should run until 11:59 p.m. and not end at midnight at the start of that day. Second, the time zone: check the end in the dry run against Berlin time, not just in the form. Third, the follow-up promotion: a New Year promotion that starts at midnight on January 1 must not overlap with the expiring one if the two are not meant to be combined. How to protect discount codes against abuse during peak season is covered in the article on discount codes in Black Week.

Vouchers are the second point. The standard limitation period is three years (§ 195 BGB) and, unless otherwise provided, begins at the end of the year in which the claim arose and the creditor became aware of it or should have become aware of it without gross negligence (§ 199 BGB). A validity of "three years from purchase" and one of "three years from year end" therefore lead to different end dates, for a voucher bought on December 20, 2026 either December 20, 2029 or December 31, 2029. Which validity applies to your vouchers is a question for legal advice. Maintenance makes sure that the setting in the shop matches what your terms say.

Waiting for December 31 is not a test strategy. Most of the errors described here can be triggered in advance if a staging environment sets its clock to the critical points in time: December 31, 2026 at 11:30 p.m., January 1, 2027 at 12:30 a.m., and January 4, 2027 as the first working day of week 1. At code level there are dedicated tools for this. In PHP applications built on Symfony, the Clock component provides a test clock that starts at a fixed point in time and does not move forward on its own (Symfony documentation). Your own code that takes its time from such a clock can be moved across the year change on purpose.

For a dry run of the whole application that is not enough, because the database, the cron service and extensions determine the time themselves. There, the system time of the staging environment is set forward, and only there. A few precautions are part of it: mail delivery and payment integrations in test mode, no connection to live interfaces, and a look at certificates and tokens whose validity may look different with the clock set forward. How to set up a staging environment for this is covered in the article on staging environments for safe updates.

The dry run is also a chance to make the check permanent. An automated test that checks the week label for December 29, 2025, January 1, 2027 and January 3, 2027 costs a few lines and fails on every later change that swaps o back to Y. The same goes for a test that creates an invoice at 12:30 a.m. on New Year's morning and checks its date.

Date errors at year end are rarely spectacular, but they are expensive afterward: reports have to be recalculated, documents checked and exports delivered again, often in a week with thin staffing. Shopware maintenance covers monitoring and maintaining Shopware cron jobs and message queue workers as well as updates that are tested on a staging environment first. The year change can be added there as a fixed checkpoint in the maintenance plan, with a code search, a time zone review and a dry run. Monitoring watches availability and error logs around the clock, including the night before January 1.

The year change is not the only date that belongs in the maintenance plan during these weeks. If you review access and responsibilities before year end, also keep calls from fake service providers in mind, and if you are planning a security assessment for 2027, the article on the penetration test for your shop helps with the decision. Questions about your own shop can be raised via the contact page.