Subscription renewal orders

When an evergreen subscription reaches its billing date, StoreConnect creates a Salesforce Order record and charges the customer. By default this happens on the billing date itself, and is known as a renewal order.

A renewal order is created a set number of days before the subscription billing date. The order exists in Salesforce before any payment is taken, with a checkout_step of pending_renewal. When the billing date arrives and the payment is charged, the payment is applied to the existing renewal order rather than creating a new one.

Creating orders in advance is useful when you need to:

• Report on upcoming subscription revenue before billing runs
• Allow customers to pay their renewal early
• Trigger Salesforce Flows or automations before the charge date (for example, to notify a team or flag an account for review)
• Give customers visibility in their account area of when their next order will be raised

What the customer is charged

A renewal order records what the customer is buying, but it does not set the price. When the subscription is processed, the amount charged comes from Term Price (s_c__Period_Price__c) on the Subscription record.

Editing a renewal order’s line items does not change what the subscription charges. To change the renewal amount, update Term Price on the subscription before the billing date. See Subscription processing, payments and renewals.

:::warning The two customer payment links take their amount from different places. The subscription payment link charges the subscription’s Term Price. The order payment link charges the order’s outstanding balance, which is calculated from its order items. An edited renewal order therefore affects one link and not the other. See Salesforce order payment link. :::

How renewal orders are created

The daily subscription processing job checks every active subscription. When the current date matches the date stored in Subscription__c.Renewal_Order_Date__c, the job creates the renewal Order and links it to the subscription via Subscription__c.Renewal_Order_Id__c.

The Renewal_Order_Date__c is calculated at subscription creation (and at each renewal) by subtracting the Renewal Order Days value from the subscription’s next billing date.

For example, if the next billing date is the 1st of the month and Renewal Order Days is set to 7, the renewal order is created on the 25th of the previous month.

If Renewal Order Days is blank or set to 0, no advance order is created — the order is created on the billing date as normal.

Tax on a renewal order

A renewal order calculates tax from three inputs: the subscription’s period price, the tax records attached to the product, and an address.

Every tax record is scoped to a zone, defined by country, state, or postcode. If the renewal order has no address, no zone matches, and tax is calculated as zero with no error raised. The order still processes and still takes payment.

The address comes from the original order

This is the part that surprises people. A renewal order copies its address from the order that created the subscription, not from the Person Account and not from the Contact. There is no setting that changes this.

So a subscription whose original order has a blank country renews without tax, every time, for the life of the subscription. Correcting the customer’s account address does not fix it, because nothing reads that address at renewal.

:::warning This most often shows up on migrated subscriptions. Orders created by a data import commonly carry street and city but leave country, state, and postcode empty, and every renewal inherits that gap. If renewals are untaxed while storefront checkouts for the same product are taxed correctly, the original order’s address is the first thing to check: checkout takes its country from the address the customer enters, so it is populated there and blank on the migrated order. :::

The country must be the two-letter country code

Renewal tax matches the order’s country as a two-letter ISO 3166 alpha-2 code and nothing else. Store NZ. The three-letter code NZL and the full country name New Zealand each match no zone and are taxed at zero, again without warning.

The two-letter form looks narrower than the instructions elsewhere, and it is. A Zone Country is a lookup to a Country record, which holds the three-letter code, so Configure tax is right to describe zone members that way. The country field on the order is a different thing and takes the two-letter code. Other parts of the platform are more forgiving than renewal tax: shipping zone matching and the Salesforce Calculate Tax action both accept the three-letter code and the full country name.

Where a value like NZL or New Zealand has been written, correct the affected orders and then check whatever produced it, such as an import mapping or an integration, so it emits the two-letter code.

Tax-inclusive pricing hides the symptom

Where prices are tax inclusive, the customer is charged the correct total whether or not tax is calculated. A renewal priced at 118.00 collects 118.00 either way, so nothing is under-collected and no customer is affected.

What is wrong is the record. The tax component is stored as zero, so tax invoices and tax reporting understate it for every affected renewal. Nobody notices until the numbers are reconciled, which is why this is worth checking proactively rather than waiting for a complaint.

Correct untaxed renewals

1. Open a subscription whose renewals are untaxed and find the original order, then check its Billing Country and Shipping Country.
2. Populate the country on that original order, using the two-letter code. Postcode is worth adding as well, though country alone is enough for a country-scoped zone to match.
3. Confirm the fix on the next renewal order created for that subscription, and check that its tax is no longer zero.

:::warning Do not verify this with the Calculate Tax action. It accepts the three-letter code and the full country name, so it reports tax correctly on a value that still renews untaxed. Only the next renewal order tells you whether the fix worked. See Recalculating taxes. :::

This is a data change on the Salesforce side and needs no code or configuration change. Every renewal created after it is taxed correctly.

Renewals already written with zero tax are not corrected retrospectively by this. Whether to adjust them is an accounting decision, since the amounts collected were right.

Configuring renewal orders on a product

Renewal orders are configured per subscription product using the Renewal Order Days field on Product2.

Field label	API name	Description
Renewal Order Days	s_c__Subscription_Renewal_Order_Days__c	Number of days before the billing date to create the renewal order. Leave blank to create the order on the billing date.

1. Open the subscription product in Salesforce.
2. Locate the Renewal Order Days field (add it to the page layout if it is not visible — see Add a subscription product).
3. Enter the number of days in advance you want the renewal order created.
4. Save the product.

The setting takes effect from the next renewal cycle. Existing subscriptions created from this product will have their Renewal_Order_Date__c updated when the subscription is next processed.

Renewal order fields on the Subscription record

When a renewal order has been created (or is scheduled), two fields on Subscription__c are populated:

Field label	API name	Description
Renewal Order Date	s_c__Renewal_Order_Date__c	The date the renewal order will be (or was) automatically generated.
Renewal Order	s_c__Renewal_Order_Id__c	Lookup to the generated renewal Order record. Blank until the order is created.

Add these fields to your Subscription__c page layout if your team monitors subscription records and needs visibility of upcoming renewal orders.

The renewal order in Salesforce

A renewal order is a standard Salesforce Order record. It moves through the following checkout step states:

Checkout step	Meaning
pending_renewal-syncing	Order has been created ahead of billing. No payment has been taken yet.
payment	The subscription charge job has run and is processing the payment.
payment-finalized	Payment has been captured.
complete	Order is fully complete.

The order starts in pending_renewal-syncing and remains there until the billing date, when the charge job picks it up. If a renewal order has been stuck in pending_renewal-syncing longer than expected, the subscription has not yet been charged — check whether the charge job has run or encountered an error.

If you have Flows, Process Builders, or other automation that processes subscription orders, check whether those automations should behave differently for pending_renewal-syncing orders. For example, you may want to:

• Exclude pending_renewal-syncing orders from revenue recognition until the payment is charged
• Trigger a review step on pending_renewal-syncing orders before the billing date
• Send a renewal notification to the customer when a pending_renewal-syncing order is created

Surfacing renewal orders in your store with Liquid

The subscription Liquid drop exposes two properties for renewal orders:

Property	Type	Description
renewal_order	Order	The Order associated with the next renewal. Returns nil until the renewal order has been created.
renewal_order_date	Timestamp	The date the renewal order will be generated.

Use these to show customers when their next renewal order will be raised, or to link through to the renewal order once it exists.

Example — showing the renewal order date on a subscriptions page:

```liquid

{% if subscription.renewal_order_date %} Your next renewal order will be created on {{ subscription.renewal_order_date | date: “%B %d, %Y” }}. {% endif %} ```

Example — linking to the renewal order once it exists:

```liquid

{% if subscription.renewal_order %} View your renewal order {% endif %} ```

The default theme’s subscription index page includes translation keys for these states:

Key	Default value
accounts.subscriptions.index.renewal_order	Renewal Order
accounts.subscriptions.index.no_renewal_order	No renewal order

If your theme overrides the subscriptions index template, add these keys to your theme translations to display renewal order status.

Taking payment on a renewal order manually

StoreConnect’s automatic charge job handles renewal order payment and keeps the subscription record up to date. If a customer needs to pay early, the preferred approaches are:

• Customer pays from their account — the customer can pay directly from their subscription page on your store. This goes through the full subscription payment flow and updates all subscription fields automatically.
• Send the customer a payment link — you can send the customer a direct link to their subscription payment page (/account/subscriptions/{id}/payment). This uses the same flow as above.
• Send the customer the order payment link — the order Payment Link works for renewal orders. Logged-in customers can always use it, and you can allow customers to pay without logging in by enabling a store variable. See Salesforce order payment link for details. When paid this way the subscription is advanced automatically, but the card entered is not saved as the recurring payment method.

If you use the Take Payment action in Salesforce to pay a renewal order directly, that path processes the payment against the order but does not update the subscription. You can handle this with a Salesforce Flow or by updating both records manually.

Paying or updating without the customer logging in

Two separate store variables control what an unauthenticated customer can do with a subscription. They are independent and serve different purposes:

• subscriptions.guest_renewal_payment_enabled — lets a customer pay a renewal order without logging in, through the order Payment Link (/orders/{order_reference_number}/payment). The payment is a one-off using the card they enter; the subscription’s stored recurring card is left unchanged, and the subscription is advanced automatically. Use this when you want the renewal paid immediately. See Salesforce order payment link.
• guest_subscriptions_enabled — lets a customer view their subscription and update the saved card without logging in, from the subscription page (/account/subscriptions/{subscription_id}). This does not charge the renewal — it saves the new card, and the next automatic charge run collects the outstanding amount. Use this when a renewal keeps failing because the card on file has expired or been declined and you want the customer to fix it for future renewals. See Manage customer subscriptions.

The dedicated pay-owing page (/account/subscriptions/{subscription_id}/payment) always requires the customer to be logged in, regardless of these variables.

Automating the update with a Flow

You can build a record-triggered Flow on the Payment object to detect when a renewal order has been paid via Salesforce and update the order and subscription automatically.

Trigger condition: fire when a Payment record is created where: - Origin (s_c__origin__c) equals SF01 (Salesforce payment) - The related Order’s Checkout Step contains pending_renewal

From the Payment record you can navigate to the related Order (s_c__Order_Id__c) and from the Order to the related Subscription (s_c__Renewal_Order_Id__c on the Subscription, or via the Order’s subscription relationship) to apply the same field updates described below.

See Payment origin codes for the full list of origin values.

What to update on the order

Field	What to set
Checkout Step (s_c__checkout_step__c)	Set to complete

What to update on the subscription

Field	What to set
Next Renewal Date (s_c__Next_Renewal_Date__c)	Advance by one term period (e.g. if the subscription bills monthly and the current value is June 1, set it to July 1)
Next Billing Date (s_c__Next_Billing_Date__c)	Set to the new Next Renewal Date, plus the billing delay if one is configured on the subscription
Renewal Order Date (s_c__Renewal_Order_Date__c)	Set to the new Next Renewal Date minus the product’s Renewal Order Days (leave blank if Renewal Order Days is not configured)
Renewal Order (s_c__Renewal_Order_Id__c)	Clear — set to blank

If the subscription was delinquent before payment, also clear these fields:

Field	What to set
Delinquent Date (s_c__Delinquent_Date__c)	Clear
Delinquent Reason (s_c__Delinquent_Reason__c)	Clear
Delinquent Order (s_c__Delinquent_Order_Id__c)	Clear

The term period and billing delay for the subscription are shown on the subscription record’s Term Length, Term Unit, Billing Delay Length, and Billing Delay Unit fields.