{"title":"Upgrade guide — v20 to v21 — Subscriptions and vouchers","slug":"upgrade-guide-v20-to-v21-subscriptions","url":"https://support.storeconnect.com/articles/upgrade-guide-v20-to-v21-subscriptions","url_markdown":"https://support.storeconnect.com/articles/upgrade-guide-v20-to-v21-subscriptions.md","subtitle":null,"summary":"Upgrade steps for subscription and voucher users moving from v20 to v21, covering delinquency tracking, voucher activation deadlines, audit logging, and eWay 3DS token rotation.","type":"Release_Notes","video_url":"","keywords":null,"last_modified":"2026-08-21T07:12:35+0000","body_markdown":"Skip this section if you do not use StoreConnect subscriptions or vouchers.\n\n\n## Salesforce package changes\n\n### Review: Payment Method field on Subscription__c\n\n`Payment_Method_Id__c` is a lookup to `Payment_Method__c` on `Subscription__c`. It is an alternative to the existing `Payment_Token__c` field, which stores the gateway token as plain text directly on the subscription record.\n\nWhen `Payment_Method_Id__c` is populated, renewals use the token stored on the linked `Payment_Method__c` record instead of `Payment_Token__c`. This indirection means the token can be updated on the `Payment_Method__c` record without modifying the subscription itself, which is what enables features such as eWay 3DS token rotation.\n\n`Payment_Method_Id__c` is populated at subscription creation when the gateway supports saving a payment method as a dedicated record. Subscriptions created through gateways that do not support this will continue to use `Payment_Token__c` and will leave `Payment_Method_Id__c` blank.\n\nReview whether `Payment_Method_Id__c` should be added to your `Subscription__c` page layouts.\n\nSee [Subscription Object Reference](subscription-object-reference) for full field documentation.\n\n\n### Action required: Voucher Log field changes\n\nTwo fields on `Voucher_Log__c` have been renamed or replaced in v21. Both old fields remain temporarily but must be migrated before they are removed in a future release.\n\n| Old field | New field | Notes |\n|---|---|---|\n| `Event_Result__c` | `Success__c` | Replaced by a boolean field |\n| `Reason_Code__c` | `Reason__c` | Renamed to a picklist field |\n\n1. **Salesforce reports and list views** — search for any reports filtered or grouped on `Voucher Log: Event Result` or `Voucher Log: Reason Code` and update them to use `Success` and `Reason` respectively.\n2. **Flows and Process Builder** — search for any automations that read or write `Event_Result__c` or `Reason_Code__c` on `Voucher_Log__c` records and update the field references.\n3. **Apex or API integrations** — update any code querying or updating these fields by API name.\n4. **Liquid templates** — if your theme or POS layouts reference voucher log fields, update to `success` and `reason`.\n\nSee [Voucher Log Object Reference](voucher-log-object-reference) for full field documentation.\n\n\n### Review: Voucher activation deadline field\n\nA new `Activate_Before_Datetime__c` date-time field on `Voucher__c` allows you to enforce a deadline by which a voucher must be activated. Vouchers not activated before this date and time cannot be redeemed.\n\nReview whether `Activate_Before_Datetime__c` should be added to your `Voucher__c` page layouts. If your business requires voucher activation windows, assess which existing vouchers should have a deadline set.\n\nSee [Voucher Object Reference](voucher-object-reference) for full field documentation.\n\n\n### Review: Plan Change Mode field on Product2\n\n`Subscription_Plan_Change_Mode__c` (label: Plan Change Mode) is a new field on `Product2` that controls how proration is handled when a customer changes subscription plan. Available options are:\n\n- **Prorate Immediately** (default): charges the pro-rata difference at the time of the plan change\n- **Prorate on Renewal**: adds the pro-rata difference to the next invoice\n- **No Proration**: charges the full new price at the next renewal with no mid-cycle adjustment\n\nReview whether this field should be added to your `Product2` page layouts and whether any subscription products should use a non-default plan change mode.\n\n\n## Behavior changes\n\n### Review: Subscription delinquency tracking\n\nv21 adds new fields to `Subscription__c` to track delinquency status. A subscription is marked as delinquent when it has missed one or more payment cycles. These fields are populated automatically and require no configuration.\n\nReview your existing subscription reports and list views to determine whether delinquency data should be incorporated. If you have existing manual processes for identifying missed payments, assess whether the new fields can replace or supplement them.\n\nSee [Manage Delinquent Subscription Payments](manage-delinquent-subscription-payments) for guidance on handling delinquent subscriptions.\n\n\n### Review: Voucher audit logging\n\nStoreConnect now records changes to voucher records, capturing who made each change and when. This audit trail is available via the new `Voucher_Log__c` object and requires no configuration to activate.\n\nIf you have existing custom processes for tracking voucher changes, review whether they are still needed alongside the built-in logging.\n\nSee [Voucher Log Object Reference](voucher-log-object-reference) for full field documentation.\n\n\n### Review: eWay 3DS subscription token rotation\n\neWay v2 subscription payments now support 3DS token rotation, allowing the stored payment token for a subscription to be updated as part of the 3DS authentication flow.\n\nIf you use eWay v2 for subscription billing, test your subscription renewal flow after upgrading to confirm tokens are being handled correctly.\n\nSee [eWay Payment Provider](eway-payment-provider) for eWay configuration documentation."}