Subscriptions & Subscription Items
  • 27 Mar 2023
  • 8 Minutes to read
  • Dark

Subscriptions & Subscription Items

  • Dark

Article Summary

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, 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.
Proration Behavior Update

If a Stripe Billing Subscription Proration Behavior = “--None--” or is left blank, any changes made to the Subscription will no longer be prorated.

Not Seeing a Picklist Value?
  1. Check that you have installed the latest Payments package.
  2. Navigate to Blackthorn | Payment Admin -> Metadata Updates -> Click Add Picklist Values.

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 StartStartDate EndedCurrent Period StartCurrent Period EndProcessed 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 Update Limitations

If a Subscription field is NOT added to the list above that means you will not be able to use it to update a Subscription record. Some examples might include the fields Pending Invoice Item Interval and Pending Invoice Item Interval Count.

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).

When adding a One-Time Price as a Subscription Item to an existing Subscription record, the additional Subscription Item will sync to Stripe as an Invoice Item and be added to the next Invoice generated by the Subscription.

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.


  • 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

WhenError Message
No customer lookup setNo Customer on the Subscription.
No Payment gateway setPlease define payment gateway on the Customer.
Billing Method = Send Invoice, but no Payment Method added for the customerIn order to create invoices that are charged automatically, the Customer must have a Payment Method. Add a Payment Method or select Send Invoice.
Billing Method = Send Invoice, but customer email blankIn order to create invoices that are sent to the customer, the customer must have a valid email.
Payment Method status not valid/verifiedThe Customer's Payment Method is not Valid or Verified.
Billing Method = Send Invoice, but Days until due blankIf the Billing Method is Send Invoice, the Days Until Due field should be set.
No price/ subscription item addedNo Items or Prices are on the Subscription.
Date of Billing Cycle Anchor is <= Today.The Billing Cycle Anchor (First Invoice) date needs to be in the future. Please update the date and try again.
If we are trying to update the value of Billing cycle Anchor after pushing the subscription to Stripe. (this is set only one time)You can change a Subscription’s Billing Cycle by setting a Trial End Date. As a reminder, you probably want to also set Prorate to False so the customer is not credited for previously paid, but unused time.
Trying to update the Trial end date in past after pushing to StripeThe Trial End Date needs to be a future date.
If Payment Method for ACH on subscription not validated/verifiedThe customer’s payment method is not valid or Verified.
Attempting to set Proration Behavior = "Send Invoice" on the initial push to Stripe.You can't use Send Invoice proration behavior for a new subscription.