{"id":"fiscal-period","title":"Fiscal year, quarter and period for a date: month-aligned or 52/53-week (4-4-5, 4-5-4, 5-4-4) calendars","description":"Maps up to 100 dates to a fiscal year, quarter, period and week for a caller-defined fiscal calendar: a month-aligned year (starts on day 1 of a named month) or a 52/53-week year ending on a given weekday last in or closest to a month end, in a 4-4-5, 4-5-4 or 5-4-4 pattern with the 53rd week appended to the final period; detects 53-week years and checks an asserted fiscal year, quarter or period. You must state how fiscal years are labelled (by the calendar year they start or end in). It carries no company's calendar and does not know which convention a company uses; Retail and corporate calendars differ in those parameters.","roi":"FY labelling and 53-week years are the commonest cause of year-over-year period misalignment.","audience":"business","package":"calendar-deadline-kit","channels":["x402","mcp"],"endpoint":{"method":"POST","url":"https://agents.writerslogic.com/api/v1/fiscal-period","path":"/api/v1/fiscal-period","contentType":"application/json"},"price":{"amount":"0.005","currency":"USDC","network":"base","perCall":true,"failedCallsCharged":false},"inputSchema":{"type":"object","additionalProperties":false,"required":["type","yearLabel","items"],"properties":{"type":{"type":"string","enum":["month-aligned","52-53-week"]},"yearLabel":{"type":"string","enum":["start","end"],"description":"start: the fiscal year is named for the calendar year it begins in. end: for the calendar year it ends in (US federal FY2027 begins 2026-10-01)."},"startMonth":{"type":"integer","minimum":1,"maximum":12,"description":"month-aligned: month in which the fiscal year starts, on day 1."},"endWeekday":{"type":"integer","minimum":0,"maximum":6,"description":"52-53-week: weekday the year ends on, 0=Sunday."},"endMonth":{"type":"integer","minimum":1,"maximum":12,"description":"52-53-week: month near whose end the year ends."},"endRule":{"type":"string","enum":["last","closest"],"description":"52-53-week: last endWeekday in endMonth, or the endWeekday closest to endMonth's last day."},"pattern":{"type":"string","enum":["4-4-5","4-5-4","5-4-4"],"description":"52-53-week: weeks per period within each quarter."},"items":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"object","required":["date"],"properties":{"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","maxLength":10},"claimedFiscalYear":{"type":"integer","minimum":1000,"maximum":3000},"claimedQuarter":{"type":"integer","minimum":1,"maximum":4},"claimedPeriod":{"type":"integer","minimum":1,"maximum":12}}}}}},"resultSchema":{"type":"object","properties":{"status":{"type":"string","enum":["pass","fail","unknown","unsupported"],"description":"pass: every rule held. fail: a rule was violated (see witnesses). unknown: the input lacks the evidence to decide. unsupported: outside what this engine covers. Missing evidence is never a pass."},"items":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"date":{"type":"string"},"fiscalYear":{"type":"integer"},"quarter":{"type":"integer"},"period":{"type":"integer"},"week":{"type":"integer"},"periodStart":{"type":"string"},"periodEnd":{"type":"string"},"fiscalYearStart":{"type":"string"},"fiscalYearEnd":{"type":"string"},"weeksInYear":{"type":"integer"}}}},"witnesses":{"type":"array","items":{"type":"object","properties":{"ruleId":{"type":"string"},"detail":{"type":"string"},"path":{"type":"string","description":"JSON pointer or dotted path into the input."},"offset":{"type":"integer"},"index":{"type":"integer"},"expected":{"description":"What the rule required."},"actual":{"description":"What the input had."}}}},"versions":{"type":"object","description":"Every semantic dependency of this answer (engine, tables and their as-of dates, tokenizer, calendar, rounding profile)."},"limits":{"type":"array","items":{"type":"string"}},"deterministic":{"type":"boolean","description":"Always true: pure code, no model."}}},"outputSchema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string","enum":["pass","fail","unknown","unsupported"],"description":"pass: every rule held. fail: a rule was violated (see witnesses). unknown: the input lacks the evidence to decide. unsupported: outside what this engine covers. Missing evidence is never a pass."},"items":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"date":{"type":"string"},"fiscalYear":{"type":"integer"},"quarter":{"type":"integer"},"period":{"type":"integer"},"week":{"type":"integer"},"periodStart":{"type":"string"},"periodEnd":{"type":"string"},"fiscalYearStart":{"type":"string"},"fiscalYearEnd":{"type":"string"},"weeksInYear":{"type":"integer"}}}},"witnesses":{"type":"array","items":{"type":"object","properties":{"ruleId":{"type":"string"},"detail":{"type":"string"},"path":{"type":"string","description":"JSON pointer or dotted path into the input."},"offset":{"type":"integer"},"index":{"type":"integer"},"expected":{"description":"What the rule required."},"actual":{"description":"What the input had."}}}},"versions":{"type":"object","description":"Every semantic dependency of this answer (engine, tables and their as-of dates, tokenizer, calendar, rounding profile)."},"limits":{"type":"array","items":{"type":"string"}},"deterministic":{"type":"boolean","description":"Always true: pure code, no model."}}},"_provenance":{"type":"object","description":"C2PA-aligned manifest and W3C VC 2.0 (eddsa-jcs-2022) issued by the hub DID; verify at POST /api/v1/verify-provenance"}},"required":["data","_provenance"]},"example":{"type":"month-aligned","yearLabel":"end","startMonth":10,"items":[{"date":"2026-10-01","claimedFiscalYear":2027},{"date":"2026-09-30"}]},"openapiOperation":{"operationId":"fiscal_period","summary":"Fiscal year, quarter and period for a date: month-aligned or 52/53-week (4-4-5, 4-5-4, 5-4-4) calendars","description":"Maps up to 100 dates to a fiscal year, quarter, period and week for a caller-defined fiscal calendar: a month-aligned year (starts on day 1 of a named month) or a 52/53-week year ending on a given weekday last in or closest to a month end, in a 4-4-5, 4-5-4 or 5-4-4 pattern with the 53rd week appended to the final period; detects 53-week years and checks an asserted fiscal year, quarter or period. You must state how fiscal years are labelled (by the calendar year they start or end in). It carries no company's calendar and does not know which convention a company uses; Retail and corporate calendars differ in those parameters.\n\nPrice: 0.005 USDC on Base (x402).","x-x402-price-usdc":"0.005","x-x402-amount":"5000","x-payment-info":{"protocols":["x402"],"price":{"mode":"fixed","currency":"USD","amount":"0.005"}},"x-audience":"business","x-sample-url":"https://agents.writerslogic.com/api/v1/samples/fiscal-period","security":[{"x402":[]},{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["type","yearLabel","items"],"properties":{"type":{"type":"string","enum":["month-aligned","52-53-week"]},"yearLabel":{"type":"string","enum":["start","end"],"description":"start: the fiscal year is named for the calendar year it begins in. end: for the calendar year it ends in (US federal FY2027 begins 2026-10-01)."},"startMonth":{"type":"integer","minimum":1,"maximum":12,"description":"month-aligned: month in which the fiscal year starts, on day 1."},"endWeekday":{"type":"integer","minimum":0,"maximum":6,"description":"52-53-week: weekday the year ends on, 0=Sunday."},"endMonth":{"type":"integer","minimum":1,"maximum":12,"description":"52-53-week: month near whose end the year ends."},"endRule":{"type":"string","enum":["last","closest"],"description":"52-53-week: last endWeekday in endMonth, or the endWeekday closest to endMonth's last day."},"pattern":{"type":"string","enum":["4-4-5","4-5-4","5-4-4"],"description":"52-53-week: weeks per period within each quarter."},"items":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"object","required":["date"],"properties":{"date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","maxLength":10},"claimedFiscalYear":{"type":"integer","minimum":1000,"maximum":3000},"claimedQuarter":{"type":"integer","minimum":1,"maximum":4},"claimedPeriod":{"type":"integer","minimum":1,"maximum":12}}}}}},"example":{"type":"month-aligned","yearLabel":"end","startMonth":10,"items":[{"date":"2026-10-01","claimedFiscalYear":2027},{"date":"2026-09-30"}]}}}},"responses":{"200":{"description":"Paid result with provenance","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string","enum":["pass","fail","unknown","unsupported"],"description":"pass: every rule held. fail: a rule was violated (see witnesses). unknown: the input lacks the evidence to decide. unsupported: outside what this engine covers. Missing evidence is never a pass."},"items":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"date":{"type":"string"},"fiscalYear":{"type":"integer"},"quarter":{"type":"integer"},"period":{"type":"integer"},"week":{"type":"integer"},"periodStart":{"type":"string"},"periodEnd":{"type":"string"},"fiscalYearStart":{"type":"string"},"fiscalYearEnd":{"type":"string"},"weeksInYear":{"type":"integer"}}}},"witnesses":{"type":"array","items":{"type":"object","properties":{"ruleId":{"type":"string"},"detail":{"type":"string"},"path":{"type":"string","description":"JSON pointer or dotted path into the input."},"offset":{"type":"integer"},"index":{"type":"integer"},"expected":{"description":"What the rule required."},"actual":{"description":"What the input had."}}}},"versions":{"type":"object","description":"Every semantic dependency of this answer (engine, tables and their as-of dates, tokenizer, calendar, rounding profile)."},"limits":{"type":"array","items":{"type":"string"}},"deterministic":{"type":"boolean","description":"Always true: pure code, no model."}}},"_provenance":{"type":"object","description":"C2PA-aligned manifest and W3C VC 2.0 (eddsa-jcs-2022) issued by the hub DID; verify at POST /api/v1/verify-provenance"}},"required":["data","_provenance"]}}}},"400":{"description":"Invalid request (no payment consumed)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"401":{"description":"Invalid X-API-KEY","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}},"402":{"description":"Payment required or invalid","content":{"application/json":{"schema":{"type":"object","description":"x402 v2 PaymentRequired (also base64 in the PAYMENT-REQUIRED header)","properties":{"x402Version":{"type":"integer"},"error":{"type":"string"},"code":{"type":"string"},"resource":{"type":"object"},"accepts":{"type":"array","items":{"type":"object"}},"extensions":{"type":"object"}}}}}},"502":{"description":"Upstream failure; the payment is released or not settled","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}}}}}}},"links":{"docs":"https://agents.writerslogic.com/docs/fiscal-period/","docsJson":"https://agents.writerslogic.com/docs/fiscal-period.json","sample":"https://agents.writerslogic.com/api/v1/samples/fiscal-period","openapi":"https://agents.writerslogic.com/openapi.json","catalog":"https://agents.writerslogic.com/api/v1/catalog","verifyProvenance":"https://agents.writerslogic.com/api/v1/verify-provenance","index":"https://agents.writerslogic.com/docs/index.json"}}