Lunar Return Premium PDF Report: A Built-In Monthly Retention Loop

What shipped

This launch is less about a new calculation and more about a business mechanic that most astrology apps leave on the table. A lunar return happens roughly every 27.3 days. That timing is the product. It gives every user in your app a reason to open it again, on a predictable cadence, with content that is freshly personalized each cycle. You do not write that content. You do not schedule it. The sky does both.

The retention math nobody runs

Start with the number that matters. The lunar cycle from one return to the next averages about 27.3 days. Divide a year by that and you get roughly 13 returns per user, per year. Thirteen distinct, personalized touchpoints. Not thirteen generic "your June horoscope" blasts that read the same for everyone with the same Sun sign - thirteen reports computed against one specific person's natal chart and the exact timing of their own Moon.

Compare that to how monthly engagement usually works in a wellness or astrology app. You build a content calendar. Someone writes copy. You schedule pushes. The content is the same for thousands of users, so it feels generic, and engagement decays as people learn the messages do not really know them. The lunar return inverts that. The cadence is fixed by orbital mechanics, the content is unique per user, and your marketing team writes none of it.

For a subscription product, re-engagement frequency is the lever underneath retention, and retention is the lever underneath lifetime value. A user who has a concrete reason to return every ~27 days, tied to something that feels personally theirs, is a user who keeps the app installed and the card on file. The lunar return gives you that reason as a calendar event you can compute years in advance for every user.

It also smooths out a problem most teams hit with daily content: daily horoscopes drive frequency but burn out fast, because a person cannot feel a meaningful shift in their life every 24 hours, and the daily read starts to feel like filler. A monthly anchor sits at a more believable scale. A lunar month is long enough to actually contain a chapter of someone's life - a project, a mood, a relationship beat - so the report has room to say something that lands. Daily content keeps users checking in; the monthly return gives them something worth checking in for. Run both and you cover the two timescales people actually experience.

What the JSON endpoint returns

The payload covers:

• Moon phase at the return and the quarter-moon dates across the month, so you can mark the rhythm of the cycle
• Void-of-course (VOC) windows - the periods when the Moon makes no more major aspects before changing sign, flagged per day
• Lunar mansion and fixed-star contacts for the return Moon
• Sabian symbol for the return Moon's degree
• Ascendant and MC sign of the return chart, plus angular planets sitting on those angles
• Moon dispositor - the planet ruling the sign the Moon falls in, which colors the whole month
• Ingress timing for the Moon's sign changes through the cycle
• Eclipse proximity when a return lands near an eclipse, which raises the stakes of that month
• Sequence and continuity data that ties this return to the previous and next, so a monthly feature reads as a story rather than disconnected snapshots
• Solar-return cross-reference linking the month to the user's current solar return year theme

That last point is worth sitting with. A lunar return read in isolation is a month. Read against the solar return, it becomes a chapter inside the user's year. The cross-reference is what lets you build a narrative thread that runs across all 13 reports, which is exactly the kind of continuity that keeps people subscribed past the first renewal.

The sequence and continuity data does similar work at the month-to-month scale. Each report knows what the previous return set up and what the next one opens, so when a user reads June's report it can reference how May resolved and point at what July brings. That callback effect is small per report and large in aggregate: it turns twelve disconnected readings into one ongoing account of the user's year, and a user reading an ongoing account is far less likely to cancel mid-story than one reading isolated monthly snapshots.

What the PDF endpoint returns

The PDF is visual, not a wall of text:

• A natal-plus-lunar-return dual wheel so the user sees their birth chart and the month's chart together
• A VOC month ribbon giving an at-a-glance map of the void windows, plus per-day 24-hour bars that show exactly when each window opens and closes
• Favorable-window ribbons highlighting the better stretches of the month for action
• Phase emblems marking the new, quarter, and full moons
• Timeline and dispositor visuals that turn the dispositor chain and ingress sequence into something a non-astrologer can follow
• Output in 12 languages, and white-label so your brand sits on the cover, not ours

Time-to-build: one call versus a month of plumbing

Here is what building a credible lunar return feature looks like without this endpoint.

You compute the return chart, which means finding the precise timestamp the transiting Moon hits its natal longitude - an iterative solve, not a lookup. You calculate the Moon's phase progression for the month. You detect every void-of-course window, which requires checking the Moon's remaining aspects before each sign change. You resolve the dispositor chain. You find ingress times. You check eclipse proximity. Then you write interpretation copy for every combination, in every language you support, and keep it consistent across months so the narrative holds. Then you lay all of it out as a document a paying user will accept.

The endpoint collapses that into one request:

1curl -X POST https://api.astrology-api.io/api/v3/pdf/lunar-return-report \
2  -H "Authorization: Bearer $ASTROLOGY_API_KEY" \
3  -H "Content-Type: application/json" \
4  -o lunar-return.pdf \
5  -d '{
6    "birth": { "date": "1992-03-14", "time": "08:25", "lat": 40.7128, "lon": -74.0060 },
7    "returnDate": "2026-07-02",
8    "language": "en",
9    "whiteLabel": { "brandName": "Your App" }
10  }'

You get a PDF back. The JSON endpoint follows the same shape if you would rather render your own screens. Either way, the calculation and the interpretation are solved. You spend your engineering time on the part that is actually yours: where this fits in your product.

Where it fits in a product

There are three slots this drops into cleanly.

On the market for monthly forecasts

Monthly forecasting is one of the most durable formats in consumer astrology. The monthly horoscope predates apps by decades, and the habit transferred to mobile intact - people expect a fresh read at the start of each cycle, and they come looking for it. That is demand you do not have to create; it already exists and it recurs.

What most apps ship against that demand is the generic Sun-sign monthly: twelve write-ups, same for everyone born in a given month-range, refreshed by a content team. It satisfies the habit at the lowest fidelity. The lunar return serves the same habit at the opposite end of personalization - the timing is the user's own, the chart is the user's own, the narrative threads across their year. You are meeting an established, recurring expectation with something that actually knows who the user is. That gap, between generic monthly content and genuinely personal monthly content, is the room this product gives you to differentiate and to charge.

How the two endpoints relate

Use the JSON endpoint when you want to build the experience yourself - custom screens, your own typography, data feeding into other features. Use the PDF endpoint when you want a finished, sellable artifact with no front-end work. Many teams use both: the JSON for an in-app summary screen that drives the user to tap through, and the PDF as the premium download behind the paywall.

Both share the same calculation core, so the numbers match. The summary your user sees on screen agrees with the document they download, which matters more than it sounds - mismatched data between a teaser and a paid report is a fast way to lose trust.

Pricing

The Lunar Return Report endpoints are available on Professional ($37/mo) and above. The JSON enrichment counts as one request. The PDF endpoint counts as one request and returns the full document. Because returns happen on a fixed ~27-day cadence, your per-user volume is predictable: about 13 calls per user per year if you generate one report per return. That predictability makes it easy to model against your tier before you ship.

What's next

We are working on a return-calendar endpoint that returns every lunar return date for a user across a full year in one call, so you can schedule a year of pushes in a single request instead of computing each return as it approaches. After that: an opt-in webhook that fires when a user's return is imminent, so the scheduling lives on our side and your app just listens. And we are extending the Solar-return cross-reference into a combined yearly-plus-monthly narrative export, so the 13 monthly reports and the annual report read as one continuous story.