Add Fairness billing examples to pricing docs by jpvotta · Pull Request #4427 · temporalio/documentation

jpvotta · 2026-04-10T18:50:08Z

Summary

Adds a ### Fairness pricing section to pricing.mdx under ## Other pricing, consistent with how TRU and High Availability billing are documented
Covers four billing scenarios with worked examples:
- Fairness enabled but no fairness keys in use
- Mix of Workflows with and without fairness keys
- Enabling and disabling Fairness across calendar-hour boundaries
- Enabling Fairness with a backlog of existing work
Updates the one-liner in actions.mdx to link to the new section and to the Task Queue Fairness feature docs

Test plan

yarn start — verify Fairness pricing section renders correctly at /cloud/pricing#fairness-pricing
Confirm link from actions.mdx resolves to /develop/task-queue-priority-fairness#task-queue-fairness
yarn build — no broken links

🤖 Generated with Claude Code

┆Attachments: EDU-6198 Add Fairness billing examples to pricing docs

- Add Fairness pricing section to pricing.mdx under Other pricing, with worked examples covering: no fairness keys in use, mixed workflows, calendar-hour billing boundaries, and backlogged tasks - Update actions.mdx Fairness one-liner to link to the new section and to the Task Queue Fairness feature docs Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

vercel · 2026-04-10T18:50:11Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
temporal-documentation	Ready	Preview, Comment	Apr 13, 2026 10:35pm

github-actions · 2026-04-10T18:50:34Z

📖 Docs PR preview links

Cloud
- Actions
- Pricing

tlotemporal · 2026-04-13T21:37:18Z

+
+**Fairness enabled, but no fairness keys in use**
+
+If Fairness is enabled but no Workflows or Activities send `fairness_key` metadata, all tasks continue to route as before. The surcharge still applies: billing is determined by whether Fairness is enabled on the Namespace.


'Fairness Actions are still applied' instead of 'The surcharge still applies'

Done — changed to "Fairness Actions are still applied".

tlotemporal · 2026-04-13T21:37:44Z

+
+If Fairness is enabled but no Workflows or Activities send `fairness_key` metadata, all tasks continue to route as before. The surcharge still applies: billing is determined by whether Fairness is enabled on the Namespace.
+
+| Hour          | Actions in Namespace | Fairness enabled? | Fairness surcharge | Total billed Actions |


remove surcharge

Done — table header changed to "Fairness Actions".

tlotemporal · 2026-04-13T21:38:05Z

+
+If each queue generates 5,000 Actions in a given hour (10,000 total), the surcharge applies to the full 10,000, not only to the 5,000 from `payment-queue`.
+
+| Hour          | Actions from payment-queue | Actions from notification-queue | Total Namespace Actions | Surcharge (10%) | Total billed Actions |


Just label as 'Fairness' to align with previous table

Done — relabeled to "Fairness" to align with previous table.

tlotemporal · 2026-04-13T21:38:49Z

+
+Suppose Fairness is enabled at 2:45 PM and disabled at 3:20 PM, then re-enabled at 4:50 PM. Billing uses 1-hour windows with no proration: if Fairness is on at any point during a window, the full window is charged. Each re-enable restarts the 1-hour minimum.
+
+| Time (UTC) | Event | Billing window affected | Notes |


Are lines 374 through 380 really needed?

Removed — cut this entire example (calendar-hour boundaries) as it covers general timing concepts independent of fairness.

tlotemporal · 2026-04-13T21:39:17Z

+
+**Enabling Fairness with a backlog of existing work**
+
+Suppose `your-namespace` has a large backlog of queued tasks that were submitted before Fairness was enabled, and Fairness is turned on at 10:00 AM. If workers process 30,000 Actions from backlogged tasks and 10,000 new Actions during the 10:00–11:00 AM window, the surcharge applies to all 40,000. Billing is based on when Actions are processed, not when they were submitted.


can we shorten this section?

Removed — cut this entire example (backlog scenario) for the same reason.

tlotemporal

Left a few comments. Note we should not call this a 'surcharge', these are just 'Fairness' or 'Fairness Actions'.

Additionally I feel like we can cut down/cut out the last two examples as they deal with more general timing concepts that are independent of fairness.

Remove examples 3 (calendar-hour boundaries) and 4 (backlog scenario) per reviewer feedback that they cover general timing concepts independent of fairness. Replace "surcharge" with "Fairness Actions" throughout. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

jpvotta requested review from a team and tlotemporal as code owners April 10, 2026 18:50

vercel bot deployed to Preview April 10, 2026 18:51 View deployment

tlotemporal reviewed Apr 13, 2026

View reviewed changes

tlotemporal requested changes Apr 13, 2026

View reviewed changes

vercel bot deployed to Preview April 13, 2026 22:04 View deployment

tlotemporal approved these changes Apr 13, 2026

View reviewed changes

flippedcoder reviewed Apr 13, 2026

View reviewed changes

Comment thread docs/evaluate/temporal-cloud/pricing.mdx Outdated

Apply suggestion from @flippedcoder

62ffbf8

vercel bot deployed to Preview April 13, 2026 22:34 View deployment

Merge branch 'main' into fairness-billing-examples

b95ceba

vercel bot deployed to Preview April 13, 2026 22:35 View deployment

flippedcoder approved these changes Apr 13, 2026

View reviewed changes

flippedcoder merged commit ad33901 into main Apr 13, 2026
10 checks passed

flippedcoder deleted the fairness-billing-examples branch April 13, 2026 22:37


		Fairness enabled, but no fairness keys in use

		If Fairness is enabled but no Workflows or Activities send `fairness_key` metadata, all tasks continue to route as before. The surcharge still applies: billing is determined by whether Fairness is enabled on the Namespace.


		If Fairness is enabled but no Workflows or Activities send `fairness_key` metadata, all tasks continue to route as before. The surcharge still applies: billing is determined by whether Fairness is enabled on the Namespace.

		\| Hour \| Actions in Namespace \| Fairness enabled? \| Fairness surcharge \| Total billed Actions \|


		If each queue generates 5,000 Actions in a given hour (10,000 total), the surcharge applies to the full 10,000, not only to the 5,000 from `payment-queue`.

		\| Hour \| Actions from payment-queue \| Actions from notification-queue \| Total Namespace Actions \| Surcharge (10%) \| Total billed Actions \|


		Suppose Fairness is enabled at 2:45 PM and disabled at 3:20 PM, then re-enabled at 4:50 PM. Billing uses 1-hour windows with no proration: if Fairness is on at any point during a window, the full window is charged. Each re-enable restarts the 1-hour minimum.

		\| Time (UTC) \| Event \| Billing window affected \| Notes \|


		Enabling Fairness with a backlog of existing work

		Suppose `your-namespace` has a large backlog of queued tasks that were submitted before Fairness was enabled, and Fairness is turned on at 10:00 AM. If workers process 30,000 Actions from backlogged tasks and 10,000 new Actions during the 10:00–11:00 AM window, the surcharge applies to all 40,000. Billing is based on when Actions are processed, not when they were submitted.

Conversation

jpvotta commented Apr 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

vercel bot commented Apr 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Apr 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📖 Docs PR preview links

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tlotemporal left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jpvotta commented Apr 10, 2026 •

edited

Loading

vercel bot commented Apr 10, 2026 •

edited

Loading

github-actions bot commented Apr 10, 2026 •

edited

Loading