Skip to Content

Wiki source code of Contents

Version 5.1 by Admin User on 2026/09/01 16:44
Show last authors
1
2
3
4
5
6
7
8
9
10
11
12
13 **ONEcount Fulfillment Module**
14
15 Gift Subscriptions — User Guide
16
17 = Contents =
18
19 ~1. Overview
20
21 2. Gift Subscription Types
22
23 3. Creating a Gift Subscription
24
25 4. Redemption Codes
26
27 5. Managing Gifts
28
29 6. Renewal Flow
30
31 7. Gift Notifications
32
33 8. Reporting
34
35 9. Setup & Configuration
36
37 10. Permissions
38
39 = 1. Overview =
40
41 Gift subscriptions allow one user (the giver) to purchase a subscription on behalf of another user (the recipient). The giver pays for the subscription, and the recipient receives access to the gated content.
42
43 Gift subscriptions support two fulfillment models:
44
45 * Direct fulfillment — The giver provides the recipient’s details at purchase time. The subscription is created immediately.
46 * Redemption code — The giver receives a unique code (e.g., GFT-DEMO-7X92K) that can be shared with the recipient. The recipient redeems the code to activate their subscription.
47
48 Both models integrate with the existing fulfillment reporting pipeline. Gift recipients appear in circulation reports, issue serve logs, and adds/removals tracking with full audit provenance.
49
50 [[image:fulfillment-gift-subscriptions_ff4b9b3968548bfb.png||height="430" width="586"]]
51
52 //The Gift Subscriptions list showing direct gifts, redemption codes, and various statuses.//
53
54 = 2. Gift Subscription Types =
55
56 == 2.1 Direct Fulfillment ==
57
58 In the direct fulfillment model, the giver provides the recipient’s OCID (or the admin enters both OCIDs) at the time of purchase. The system immediately:
59
60 * Creates a subscription record (gcn_transactionlog) for the recipient
61 * Sets up the subscription expiration (gcn_el_expire)
62 * Links the gift relationship in the fulfillment_gift table
63 * Logs an adds/removals event with reason code GIFT_NEW
64
65 The recipient has immediate access to the gated content as soon as the gift is created.
66
67 In the screenshot above, gifts #6 and #14 are direct fulfillment examples — OCID 12050 gifted Aviator’s Guide to OCID 42843, and OCID 3723 gifted Aviator’s Destinations to OCID 244.
68
69 == 2.2 Redemption Code ==
70
71 In the redemption code model, the system generates a unique code with the prefix GFT- followed by alphanumeric characters (e.g., GFT-DEMO-7X92K). The code uses a character set that avoids ambiguous characters (no 0/O or 1/I).
72
73 The gift starts in “pending” status. No subscription is created until the recipient redeems the code. When redeemed:
74
75 * The recipient’s subscription is created
76 * The gift status changes to “redeemed”
77 * The redemption code is consumed and cannot be reused
78 * An adds/removals event is logged with reason code GIFT_REDEEMED
79
80 In the screenshot, gift #22 shows a pending code (GFT-DEMO-7X92K) awaiting redemption, while gift #30 (GFT-DEMO-A3B8F) has been successfully redeemed by OCID 33264.
81
82 Redemption codes can have an expiration date. If the code expires before redemption, the gift status changes to “expired” and the code becomes invalid.
83
84 = 3. Creating a Gift Subscription =
85
86 == 3.1 From the Admin UI ==
87
88 Navigate to Fulfillment › Gift Subscriptions in the admin sidebar. Click the red “Create Gift” button to open the creation modal.
89
90 [[image:fulfillment-gift-subscriptions_d55d269bebfbd1ef.png||height="411" width="586"]]
91
92 //The Create Gift modal with gift type, giver/recipient fields, and product-or-package selection.//
93
94 Fill in the following fields:
95
96 |**Field**|**Required**|**Description**
97 |**Gift type**|Yes|Direct fulfillment or Redemption code
98 |**Giver OCID**|Yes|The OCID of the person paying for the gift
99 |**Recipient OCID**|Direct only|The OCID of the person receiving the gift
100 |**Package**|Yes|Select a product or package from the dropdown (grouped by type)
101 |**Term**|Yes|Select the term — options cascade based on the selected product or package
102 |**Publication**|No|The fulfillment publication (for magazine gifts)
103 |**Gift message**|No|Personal message from giver to recipient
104 |**Notification date**|No|Date to send notification email to recipient
105 |**Code expires**|Code only|Expiration date for the redemption code
106
107 == 3.2 Product/Package and Term Selection ==
108
109 The “Product or Package” dropdown is organized into two groups: Products (individual resources from site_resources) and Packages (bundles from fe_groups). When you select either a product or a package, the Term dropdown automatically updates to show only the terms that belong to that selection, along with their prices.
110
111 This means standalone products that are not part of any package are now accessible, alongside traditional package-based subscriptions.
112
113 [[image:fulfillment-gift-subscriptions_ce5ae00033b5984f.png||height="411" width="586"]]
114
115 //After selecting “Aviator’s Guide” from the Products group, the Term dropdown shows its three terms with prices.//
116
117 == 3.3 Via Stripe Payment ==
118
119 When a Stripe PaymentIntent includes gift metadata (gift_type, recipient_ocid, gift_message), the webhook handler automatically creates the gift subscription on successful payment. This enables front-end checkout flows to offer gift subscriptions without additional backend work.
120
121 = 4. Redemption Codes =
122
123 To redeem a gift code, use the gift-redeem AJAX endpoint or the admin UI. The process requires:
124
125 * The redemption code (case-insensitive)
126 * The recipient’s OCID
127
128 The system validates that the code exists, is in “pending” status, and has not expired. If validation passes, the recipient’s subscription is created and the gift status updates to “redeemed.”
129
130 //Each redemption code can only be used once. After redemption, the code is removed from the fast-lookup table in Cassandra.//
131
132 = 5. Managing Gifts =
133
134 The Gift Subscriptions page (Fulfillment › Gift Subscriptions) provides a filterable list of all gifts. Filters include:
135
136 * Status (pending, active, redeemed, expired, cancelled)
137 * Publication
138 * Giver OCID
139
140 [[image:fulfillment-gift-subscriptions_47ecc3faa047e7a6.png||height="430" width="586"]]
141
142 //The gift list filtered to show only active subscriptions.//
143
144 Available actions:
145
146 |**Action**|**Description**
147 |**Cancel**|Cancels the gift. If the recipient has an active subscription, it is noted in the audit trail with reason code GIFT_CANCELLED.
148 |**Renew**|Extends the subscription for another term. Either the giver or recipient can renew (see Renewal Flow).
149
150 = 6. Renewal Flow =
151
152 Gift subscriptions support renewal by either party:
153
154 == 6.1 Giver Renewal ==
155
156 A daily cron job (gift_renewal_notices.php) checks for gift subscriptions whose recipient’s subscription expires within a configurable window (default: 30 days). The giver receives a courtesy email with a renewal link. If the giver renews, the subscription extends and the gift record is updated with renewed_by = “giver.”
157
158 == 6.2 Recipient Fallback ==
159
160 If the giver does not renew within a configurable fallback window (default: 14 days before expiry), the recipient enters the standard renewal/dunning series. If the recipient renews, the gift record is updated with renewed_by = “recipient.” The gift relationship is preserved for audit trail purposes.
161
162 = 7. Gift Notifications =
163
164 Gift notifications are email messages sent to the recipient at a scheduled date. When creating a gift, the giver can specify a notification_date (e.g., a birthday or holiday).
165
166 The daily cron job (gift_notifications.php) processes pending notifications and marks them as sent. Email delivery integration uses the platform’s existing email service.
167
168 = 8. Reporting =
169
170 Gift subscriptions are fully integrated with fulfillment reporting:
171
172 |**Report**|**How Gifts Appear**
173 |**RPT-01 (Circulation by Issue)**|Gift recipients are counted in their classification bucket (paid_print, paid_digital_replica, etc.) based on the term format. Optional subscription_source breakdown shows gift vs. individual counts.
174 |**RPT-09 (Adds & Removals)**|Gift-specific reason codes (GIFT_NEW, GIFT_REDEEMED, GIFT_EXPIRED, GIFT_CANCELLED) appear automatically in the reason code grouping.
175 |**RPT-19 (Mail File)**|Gift recipients with valid addresses appear in the mail file. The serve log includes gift_id and subscription_source columns for provenance.
176 |**Issue Builder**|Gift recipients appear in saved lists like any subscriber. They have real subscriptions.
177
178 = 9. Setup & Configuration =
179
180 Navigate to Fulfillment › Setup › Gift Settings to configure:
181
182 |**Setting**|**Default**|**Description**
183 |**Enable gift subscriptions**|Off|Master toggle for the gift feature
184 |**Default code expiry (days)**|90|How long redemption codes remain valid
185 |**Giver renewal notice (days)**|30|Days before expiry to send giver a renewal notice
186 |**Recipient fallback (days)**|14|Days before expiry to enter recipient into standard renewal series
187
188 = 10. Permissions =
189
190 Gift subscription management requires the FULFILLMENT_GIFT_MANAGE permission module. Superadmin users (user_type = “F”) automatically have access.
191
192 The FULFILLMENT_VIEW permission is sufficient to see the gift list (read-only). Creating, cancelling, and renewing gifts requires FULFILLMENT_GIFT_MANAGE.