Skip to Content

Wiki source code of How-To: Gift Subscriptions

Last modified by Admin User on 2026/09/01 16:46
Show last authors
1
2
3 = 1. Overview =
4
5 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.
6
7 Gift subscriptions support two fulfillment models:
8
9 * Direct fulfillment — The giver provides the recipient’s details at purchase time. The subscription is created immediately.
10 * 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.
11
12 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.
13
14 [[image:fulfillment-gift-subscriptions_ff4b9b3968548bfb.png||height="430" width="586"]]
15
16 //The Gift Subscriptions list showing direct gifts, redemption codes, and various statuses.//
17
18 = 2. Gift Subscription Types =
19
20 == 2.1 Direct Fulfillment ==
21
22 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:
23
24 * Creates a subscription record (gcn_transactionlog) for the recipient
25 * Sets up the subscription expiration (gcn_el_expire)
26 * Links the gift relationship in the fulfillment_gift table
27 * Logs an adds/removals event with reason code GIFT_NEW
28
29 The recipient has immediate access to the gated content as soon as the gift is created.
30
31 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.
32
33 == 2.2 Redemption Code ==
34
35 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).
36
37 The gift starts in “pending” status. No subscription is created until the recipient redeems the code. When redeemed:
38
39 * The recipient’s subscription is created
40 * The gift status changes to “redeemed”
41 * The redemption code is consumed and cannot be reused
42 * An adds/removals event is logged with reason code GIFT_REDEEMED
43
44 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.
45
46 Redemption codes can have an expiration date. If the code expires before redemption, the gift status changes to “expired” and the code becomes invalid.
47
48 = 3. Creating a Gift Subscription =
49
50 == 3.1 From the Admin UI ==
51
52 Navigate to Fulfillment › Gift Subscriptions in the admin sidebar. Click the red “Create Gift” button to open the creation modal.
53
54 [[image:fulfillment-gift-subscriptions_d55d269bebfbd1ef.png||height="411" width="586"]]
55
56 //The Create Gift modal with gift type, giver/recipient fields, and product-or-package selection.//
57
58 Fill in the following fields:
59
60 |**Field**|**Required**|**Description**
61 |**Gift type**|Yes|Direct fulfillment or Redemption code
62 |**Giver OCID**|Yes|The OCID of the person paying for the gift
63 |**Recipient OCID**|Direct only|The OCID of the person receiving the gift
64 |**Package**|Yes|Select a product or package from the dropdown (grouped by type)
65 |**Term**|Yes|Select the term — options cascade based on the selected product or package
66 |**Publication**|No|The fulfillment publication (for magazine gifts)
67 |**Gift message**|No|Personal message from giver to recipient
68 |**Notification date**|No|Date to send notification email to recipient
69 |**Code expires**|Code only|Expiration date for the redemption code
70
71 == 3.2 Product/Package and Term Selection ==
72
73 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.
74
75 This means standalone products that are not part of any package are now accessible, alongside traditional package-based subscriptions.
76
77 [[image:fulfillment-gift-subscriptions_ce5ae00033b5984f.png||height="411" width="586"]]
78
79 //After selecting “Aviator’s Guide” from the Products group, the Term dropdown shows its three terms with prices.//
80
81 == 3.3 Via Stripe Payment ==
82
83 When a Stripe Payment 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.
84
85 = 4. Redemption Codes =
86
87 To redeem a gift code, use the gift-redeem AJAX endpoint or the admin UI. The process requires:
88
89 * The redemption code (case-insensitive)
90 * The recipient’s OCID
91
92 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.”
93
94 //Each redemption code can only be used once. After redemption, the code is removed from the fast-lookup table in Cassandra.//
95
96 = 5. Managing Gifts =
97
98 The Gift Subscriptions page (Fulfillment › Gift Subscriptions) provides a filterable list of all gifts. Filters include:
99
100 * Status (pending, active, redeemed, expired, cancelled)
101 * Publication
102 * Giver OCID
103
104 [[image:fulfillment-gift-subscriptions_47ecc3faa047e7a6.png||height="430" width="586"]]
105
106 //The gift list filtered to show only active subscriptions.//
107
108 Available actions:
109
110 |**Action**|**Description**
111 |**Cancel**|Cancels the gift. If the recipient has an active subscription, it is noted in the audit trail with reason code GIFT_CANCELLED.
112 |**Renew**|Extends the subscription for another term. Either the giver or recipient can renew (see Renewal Flow).
113
114 = 6. Renewal Flow =
115
116 Gift subscriptions support renewal by either party:
117
118 == 6.1 Giver Renewal ==
119
120 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.”
121
122 == 6.2 Recipient Fallback ==
123
124 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.
125
126 = 7. Gift Notifications =
127
128 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).
129
130 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.
131
132 = 8. Reporting =
133
134 Gift subscriptions are fully integrated with fulfillment reporting:
135
136 |**Report**|**How Gifts Appear**
137 |**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.
138 |**RPT-09 (Adds & Removals)**|Gift-specific reason codes (GIFT_NEW, GIFT_REDEEMED, GIFT_EXPIRED, GIFT_CANCELLED) appear automatically in the reason code grouping.
139 |**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.
140 |**Issue Builder**|Gift recipients appear in saved lists like any subscriber. They have real subscriptions.
141
142 = 9. Setup & Configuration =
143
144 Navigate to Fulfillment › Setup › Gift Settings to configure:
145
146 |**Setting**|**Default**|**Description**
147 |**Enable gift subscriptions**|Off|Master toggle for the gift feature
148 |**Default code expiry (days)**|90|How long redemption codes remain valid
149 |**Giver renewal notice (days)**|30|Days before expiry to send giver a renewal notice
150 |**Recipient fallback (days)**|14|Days before expiry to enter recipient into standard renewal series
151
152 = 10. Permissions =
153
154 Gift subscription management requires the FULFILLMENT_GIFT_MANAGE permission module. Superadmin users (user_type = “F”) automatically have access.
155
156 The FULFILLMENT_VIEW permission is sufficient to see the gift list (read-only). Creating, cancelling, and renewing gifts requires FULFILLMENT_GIFT_MANAGE.