Skip to Content
Last modified by Admin User on 2026/07/30 19:10
From version 6.1
edited by Admin User
on 2026/07/30 19:03
Change comment: There is no comment for this version
To version 1.1
edited by Admin User
on 2026/07/30 19:03
Change comment: Changed document syntax from [XWiki 2.1] to [xwiki/2.1].

Summary

Details

Page properties
Title
... ... @@ -1,1 +1,0 @@
1 -1. Overview
Content
... ... @@ -1,211 +1,0 @@
1 -
2 -
3 -
4 -
5 -
6 -
7 -
8 -
9 -
10 -
11 -
12 -
13 -ONEcount Fulfillment
14 - Revenue Recognition &
15 - Financial Export
16 -
17 -Earned vs. deferred revenue, GL mapping,
18 - automated journal entries, and Superset dashboards
19 -
20 -= 1. Overview =
21 -
22 -ONEcount computes subscription revenue recognition (earned vs. deferred revenue) and produces GL-mapped financial exports that your accounting team can import into their ERP system (NetSuite, QuickBooks, Sage, etc.).
23 -
24 -The revenue recognition system has three layers:
25 -
26 -* Compute — a scheduled job that reads payment events and subscription data, computes how much revenue was earned in each period, and how much remains deferred.
27 -* Visualize — Superset dashboards showing deferred revenue waterfall, earned revenue trend, and payment analysis.
28 -* Export — GL-mapped journal entries in CSV or JSON format, deliverable via download, REST API, or SFTP.
29 -
30 -= 2. Revenue Recognition Models =
31 -
32 -ONEcount supports two recognition models, configured per publication via the Billing Model setting in Fulfillment Setup then Publications:
33 -
34 -== 2.1 Time-based recognition ==
35 -
36 -Revenue is recognized ratably over the subscription term, regardless of how many issues are published. This is the default model and is appropriate for most publications.
37 -
38 -Example:
39 -
40 -* Subscriber pays $120 for a 12-month annual subscription starting January 1.
41 -* January: $10 earned, $110 deferred.
42 -* February: $10 earned (total $20), $100 deferred.
43 -* June (6 months in): $60 earned, $60 deferred.
44 -* December (12 months in): $120 earned, $0 deferred.
45 -
46 -Partial months are prorated. If a subscription starts mid-month, the first and last months are proportionally allocated.
47 -
48 -== 2.2 Issue-based recognition ==
49 -
50 -Revenue is recognized per issue delivered. Each time an issue is mailed to the subscriber (recorded in the fulfillment issue serve log), a proportional amount of revenue is earned.
51 -
52 -Example:
53 -
54 -* Subscriber pays $120 for a 6-issue subscription.
55 -* Issue 1 mailed: $20 earned, $100 deferred.
56 -* Issue 3 mailed: $60 earned (cumulative), $60 deferred.
57 -* Issue 6 mailed: $120 earned, $0 deferred.
58 -
59 -This model is appropriate for publications where the delivery of each issue is the performance obligation (the event that triggers revenue recognition under ASC 606).
60 -
61 -= 3. Running the Revenue Compute Job =
62 -
63 -Revenue recognition is computed by a scheduled job that runs nightly (or on demand). The job processes all active paid subscriptions for each publication and writes the earned/deferred allocation to Cassandra.
64 -
65 -== 3.1 Command ==
66 -
67 -Run from the command line:
68 -
69 -* All publications for current month: php scripts/compute_revenue_schedule.php ~-~-silo=yoursilo
70 -* Specific publication: php scripts/compute_revenue_schedule.php ~-~-silo=yoursilo ~-~-pub=1
71 -* Specific month: php scripts/compute_revenue_schedule.php ~-~-silo=yoursilo ~-~-month=202607
72 -
73 -== 3.2 Cron schedule ==
74 -
75 -Recommended cron entry (run nightly at 2 AM):
76 -
77 -**0 2 * * * php /pub/cust/scripts/compute_revenue_schedule.php ~-~-silo=yoursilo**
78 -
79 -== 3.3 Output ==
80 -
81 -The job prints a summary to stdout showing subscriptions processed, earned revenue, deferred revenue, and refunds for each publication. The detailed per-subscriber schedule is written to Cassandra (revenue_schedule_by_subscriber) and the aggregates are written to revenue_summary_by_month.
82 -
83 -= 4. GL Account Mapping =
84 -
85 -Before you can export financial data, you need to map each event type to your chart of accounts. This tells the export system which GL account code to use for each type of journal entry.
86 -
87 -== 4.1 Navigate to GL Mapping ==
88 -
89 -Go to Fulfillment, then Setup, then GL Account Mapping. Select a publication from the dropdown.
90 -
91 -[[image:fulfillment-revenue-export-howto_40366f7770be3c6d.png||height="430" width="586"]]
92 -
93 -== 4.2 Configure the mappings ==
94 -
95 -Five event types need mapping:
96 -
97 -* Payments received (charge) — the GL account for cash or accounts receivable when a payment is collected. Typically a debit to Cash (e.g., GL 1000) or a credit to Deferred Revenue.
98 -* Refunds issued (refund) — the GL account debited when a refund is processed.
99 -* Earned subscription revenue (earned_revenue) — the revenue account credited when revenue is recognized. Typically GL 4100 or similar.
100 -* Deferred revenue (deferred_revenue) — the liability account debited when deferred revenue is reduced (i.e., when revenue is earned). Typically GL 2300 or similar.
101 -* Bad debt write-off (write_off) — the expense account debited when a subscription is written off as uncollectible.
102 -
103 -For each event type, enter the GL account code, a descriptive name, and whether the entry is a debit or credit. Click Save Mapping when done.
104 -
105 -== 4.3 Example mapping ==
106 -
107 -* charge → GL 1000 (Cash), debit
108 -* charge → GL 2300 (Deferred Revenue), credit
109 -* earned_revenue → GL 4100 (Subscription Revenue), credit
110 -* deferred_revenue → GL 2300 (Deferred Revenue), debit
111 -* refund → GL 4100 (Subscription Revenue), debit
112 -
113 -Note: the current system supports one GL code per event type per publication. For double-entry bookkeeping where a single event needs both a debit and credit line, configure the primary entry here and add the offsetting entry in your ERP's import rules.
114 -
115 -= 5. Exporting Financial Data =
116 -
117 -ONEcount automates financial exports through scheduled jobs. You configure the export once — publication, frequency, date range, file format, delivery method, and notification email — and the system generates and delivers the journal entry files on schedule.
118 -
119 -== 5.1 Navigate to Financial Exports ==
120 -
121 -Go to Fulfillment, then Setup, then Financial Exports. The page shows all configured export schedules with their status, last run time, and delivery method.
122 -
123 -[[image:fulfillment-revenue-export-howto_71339635f9a45a56.png||height="430" width="586"]]
124 -
125 -== 5.2 Create an export schedule ==
126 -
127 -Click Add Schedule to create a new export job:
128 -
129 -[[image:fulfillment-revenue-export-howto_24be28444b4e62f9.png||height="430" width="586"]]
130 -
131 -**Configure the schedule:**
132 -
133 -* Schedule name — a descriptive label (e.g., 'Monthly GL Export - Aviators Guide').
134 -* Publication — the publication whose revenue data to export.
135 -* Frequency — how often to run: Daily, Weekly, Monthly, or Custom (one-time). For Weekly, the Day field is the day of the week (0 = Sunday). For Monthly, it is the day of the month.
136 -* Time of day — when to run (server timezone).
137 -* Date range — what period to cover: Last day, Last week, Last month, or Custom dates.
138 -* File format — CSV or JSON.
139 -* Delivery method — Local file only, SFTP, or FTP. If you choose SFTP or FTP, fields appear for host, port, username, password, and remote path.
140 -* Notification email — an email address that receives a notification when the export completes (or fails).
141 -
142 -When delivery is set to SFTP or FTP, the SFTP credential fields appear:
143 -
144 -[[image:fulfillment-revenue-export-howto_73f401e66b5b1a8c.png||height="411" width="586"]]
145 -
146 -Click Create Schedule. The schedule appears in the list with status 'Active'. The multi-silo wrapper script runs hourly and checks which schedules are due based on their frequency, day, and time. When a schedule is due, it generates the GL-mapped journal entry file, delivers it via SFTP if configured, and sends the notification email.
147 -
148 -You can pause, resume, edit, or delete schedules at any time from the list. Paused schedules are not processed by the wrapper script until reactivated.
149 -
150 -== 5.3 CSV format ==
151 -
152 -The exported CSV has these columns:
153 -
154 -* journal_date — the last day of the period month.
155 -* gl_account — the GL account code from your mapping.
156 -* gl_name — the GL account name.
157 -* debit — debit amount (blank if credit).
158 -* credit — credit amount (blank if debit).
159 -* reference — publication identifier + period (e.g., AVIATORSGUIDE-202607).
160 -* description — human-readable description of the entry.
161 -
162 -= 6. Superset Dashboards =
163 -
164 -After the MongoDB sync job runs, payment events and revenue summary data are available as Superset datasets. The sync job creates two MongoDB collections:
165 -
166 -* payment_events — one document per payment event (charge, refund, renewal, failure). Includes amount in both cents and dollars, event type, publication, subscriber, and timestamps.
167 -* revenue_summary — one document per publication per month. Includes earned, deferred, refunded, and new orders in both cents and dollars.
168 -
169 -== 6.1 Running the sync ==
170 -
171 -Run after the revenue compute job:
172 -
173 -**php scripts/sync_payments_to_mongo.php ~-~-silo=yoursilo ~-~-month=202607**
174 -
175 -Recommended cron: run at 3 AM, one hour after the revenue compute job.
176 -
177 -== 6.2 Suggested charts ==
178 -
179 -With the data in Superset, you can build:
180 -
181 -* Deferred revenue waterfall — monthly bars showing opening balance, new orders added, revenue earned (reducing the liability), refunds, and closing balance.
182 -* Earned revenue trend — line chart of monthly earned revenue per publication, with prior-year comparison.
183 -* Payment method distribution — pie chart of card brand breakdown (Visa, Mastercard, Amex) from payment_events.
184 -* Failed payment funnel — count of failed payments, retries, recoveries, and final cancellations.
185 -* Revenue by channel — if source_code is populated on payment events, break down revenue by acquisition channel.
186 -
187 -= 7. Troubleshooting =
188 -
189 -== Revenue compute shows 0 subscriptions processed ==
190 -
191 -Check that the publication has a resource_id linked to products with AccessDuration and Price set. The compute job joins gcn_el_expire (expiration dates) with site_products (term duration and price). If either table is empty for this publication, there is nothing to compute.
192 -
193 -== Financial export shows 'No GL mapping configured' ==
194 -
195 -You must configure GL account codes before exports work. Go to Fulfillment, then Setup, then GL Account Mapping. Select the publication and enter your chart of accounts.
196 -
197 -== MongoDB sync fails with connection error ==
198 -
199 -The sync script connects to MongoDB using the host configured in your silo's system-configs-ocdb.cnf. Verify the MongoDB host is reachable and the database name matches your silo.
200 -
201 -== Superset shows stale data ==
202 -
203 -Superset reads from MongoDB, which is populated by the sync job. If the sync job has not run since the last revenue compute, the Superset data will be stale. Run the sync job and refresh the Superset dataset.
204 -
205 -= 8. Where to Learn More =
206 -
207 -* ASC 606 revenue recognition standard overview: fasb.org/page/PageContent?pageId=/standards/606.html
208 -* Stripe Payments How-To: docs/fulfillment/howto-stripe-payments/
209 -* Recurring Billing How-To: docs/fulfillment/howto-recurring-billing/
210 -* CDS Global financial export format (industry reference): contact your CDS Global account representative for file specs.
211 -* Architecture Decision Record: docs/decisions/0005-stripe-payments-revenue-recognition.md
fulfillment-revenue-export-howto_24be28444b4e62f9.png
Author
... ... @@ -1,1 +1,0 @@
1 -XWiki.admin
Size
... ... @@ -1,1 +1,0 @@
1 -78.9 KB
Content
fulfillment-revenue-export-howto_40366f7770be3c6d.png
Author
... ... @@ -1,1 +1,0 @@
1 -XWiki.admin
Size
... ... @@ -1,1 +1,0 @@
1 -102.1 KB
Content
fulfillment-revenue-export-howto_71339635f9a45a56.png
Author
... ... @@ -1,1 +1,0 @@
1 -XWiki.admin
Size
... ... @@ -1,1 +1,0 @@
1 -51.9 KB
Content
fulfillment-revenue-export-howto_73f401e66b5b1a8c.png
Author
... ... @@ -1,1 +1,0 @@
1 -XWiki.admin
Size
... ... @@ -1,1 +1,0 @@
1 -78.5 KB
Content