Subscriptions & Subscription Items

Subscriptions are the life blood of Stripe Billing! The initial creation of one can be simple, using just the Subscription object, or more thorough, using both Subscription and Subscription Item.

Use only the Subscription object if your Subscription has just one Stripe Price. Subscription has fields for Stripe Price, Quantity, and other single-price related fields. After pushing to Stripe, a Subscription Item will be auto-created for the single Stripe Price and updated in Salesforce.

Use both Subscription and Subscription Item if your Subscription has 2+ Prices. Each Subscription Item represents one Stripe Price. If you're used to Opportunity and Products, it's the equivalent of having 2+ Opportunity Products.

When creating a Subscription, fill out all applicable initial fields before pushing it to Stripe. If there are multiple Subscription Items, create each one then navigate to the Subscription and click the Push to Stripe button.

Create a Subscription

These are the minimal requirements.

1. Create a new Subscription record by navigating to the Subscription object and clicking New.
2. Select Subscription as your record type. The Subscription Schedule Phase record type is used with the Subscription Schedule object.
3. Set the Price lookup field if there is only one Price (click the lookup selector).Setting up the Price will automatically set the Product look up.
4. Set the Customer lookup (click the lookup selector).Customer is the Payment Gateway Customer to be used (required by Stripe). The email address of this Stripe Customer will be the recipient of the invoices sent with each billing.
5. Populate the Quantity field.Optional: Populate the Memo field so it is included in invoice PDFs, invoice emails, and the Hosted Invoice Page.
6. Save the record.
7. Click the Push to Stripe button. You'll know the Subscription was successfully created in Stripe if you see the Subscription ID field populated.

As a convenience feature, the Payment Method will be populated with the Customer's default source (i.e. their card or ACH account).

Subscription Fields

• Price : The Price for which the Customer is subscribing.
• Customer : The subject of the Subscription.
• Payment Method : If left blank, the default is used.
• Enable Payment Methods: You can choose which payment methods will be available to pay for a Subscription when an invoice is issued. The following Values are available to choose from: ACH Credit (pushed by them), ACH Debit (pulled by you), Canadian pre-authorized debit, BECS Direct Debit, Bacs Direct Debit, Bancontact, Boleto, Card, EPS, FPX, giropay, iDEAL, Przelewy24, SEPA Direct Debit, SOFORT, and Wechat Pay.
• Subscription Name : You can set an arbitrary name for reference; if left blank, populated automatically.
• Quantity : Quantity of the items subscribed to. Leave blank for metered prices.
• Billing Cycle Anchor (First Invoice) : Determines the date of the first full invoice, and, for prices with Month or Year intervals, the day of the month for subsequent invoices. If not left blank, the first invoice will be prorated.
• Billing Method : When charging automatically, Stripe will attempt to pay this subscription at the end of the cycle using the default source attached to the customer. When sending an invoice, Stripe will email your customer an invoice with payment instructions.
• Days until due : Number of days a customer has to pay invoices generated by this subscription. This value will be null for subscriptions where Billing method = Charge Automatically.
• Upcoming Invoice Amount : This field will auto-populate with the upcoming invoice amount from Stripe.
• Proration Behavior : Determines how to handle prorations when the billing cycle changes (e.g., when switching plans, resetting billing_cycle_anchor=now, or starting a trial), or if an item’s quantity changes. When editing a Subscription record you can use "Send Invoice" if you want the customer to immediately pay the price difference when switching to a more expensive subscription on the same billing cycle. See the Stripe Docs for more detail.

Subscription Date Fields

• Trial End : Set this field on creation if you want your billing to begin at a future date. Not a backdated date. If set, the first full interval invoice is created for zero dollars, and the first dollar amount invoice is created at the end of the trial. Payment Source is not a required criteria in order to create the Subscription
• Backdate Start Date : If the subscription started in the past, set this date on subscription creation. This field does not effect billing and is for historical purposes, unless proration handling is invoked. See more information here on backdating.
• Billing Cycle Anchor (First Invoice) : If your invoicing should occur on a certain date, set this value, and it will override the trial-date invoicing. Just be mindful of setting or not setting proration. See more information about prorating here. If you want to reset this date post-subscription creation, use Reset Billing Cycle Anchor.

The rest of these fields are not editable from Salesforce and are set automatically after subscription creation. Trial Start, Start, Date Ended, Current Period Start, Current Period End, Processed Date (Created).

Update a Subscription

You can update a Subscription record if it is already pushed to Stripe. If you edit any of the below fields after the Subscription is already in Stripe, Salesforce will update the Stripe Subscription in real-time upon saving. The following fields are updatable:

• Quantity : Can be updated only if there is only one Subscription Item.
• Price : Can be updated only if there is only one Subscription Item.
• Payment Method: Updates the Source which is used for the Subscription
• Coupon : You can add a Coupon. If you delete the field, the Coupon is removed.
• Billing Method
• Days Until Due : only if Billing Method is set to 'Send Invoice'.

Subscription Items

One Subscription can have more than one Stripe Price. In this scenario, instead of setting the Price field on Subscription, create separate Subscription Item records. You need to create Subscription Items before pushing the Subscription. Also note that if you are setting the Stripe Price and Quantity on the Subscription during creation, a Subscription Item will be created automatically using these parameters (as referenced at the top of this page).

Update Subscription Items

You can update existing Subscription Items with the below fields. This will trigger updates to the Stripe Subscription and invoke upgrade, downgrade, credit, and prorate logic.

• Quantity: Once changed, updates to the Stripe Subscription will be made.
• Price: Changing the Price on the Subscription / Subscription Item is no longer possible as the change isn't accepted/reflected in the Stripe Billing Dashboard. Please follow the steps below to update the Price.
  1. Make a new Stripe Price.
  2. Create a new Subscription Item.
  3. Delete the old Subscription Item.
  4. Click Push to Stripe.
  5. Click Save in Stripe.
  6. Click Return to Record.
  7. Click the Stripe URL to confirm the change.

Delete Subscription Items

If you delete a Subscription Item record, it is deleted in Stripe as well. You can't delete the last Subscription Item record, so at least one Item should stay on the Subscription.

Restrictions

• On a Subscription every product can be included only once; i.e. Stripe Prices with the same Product are not allowed
• Stripe Price Interval and Interval Count should be matched. For example, you cannot include a weekly and a daily Stripe Price on the same Subscription

Pausing a Subscription

In Stripe you have the ability to pause a subscription when you need to stop payments for a period of time. We've added a couple fields to the Subscription object that track those updates with webhooks. You will not be able to pause a subscription from Salesforce and send to Stripe. These fields only update based on changes in Stripe. More details on pausing a payment collection in Stripe can be found here .

• Paused? will be checked if a user has paused the subscription in the Stripe dashboard.

• Resumes At is a date/time field that will be updated with the value the user sets in the Strip dashboard to resume subscription payments.

• Paused Invoice Behavior : If a Subscription record is paused this field could be populated with one of the three following values: "Keep As Draft", "Mark Uncollectible", or "Void".

  Note: You will need to add these fields to your Subscription page layout.

Subscription validations before syncing with Stripe