Stripe Prices & Tiers

❗️

Breaking Change

Payments package v5.1 requires Stripe API version 2020-08-27 or above.

We've renamed Plan to Price in order to support Stripe API updates. Customers are required to use Stripe API version 2020-08-27 or above in order to use the Price updates in v5.1.

Stripe Prices track how much and how often to charge for a Subscription. They can be used for recurring or one-time purchases and support various business structures. One way to think of the difference between a one-time price and a recurring price would be that a user is charged a one time fee to setup a subscription and then over time the user is charged a recurring subscription amount.

📘

Price Name Change

The Price object was renamed Stripe Price as of November 2021, Payments Version 5.38.

Create a new Stripe Price

These are the minimal requirement. For the full set of features, look into the Stripe Price Properties section.

  • Create a new Stripe Price record
  • Set the Price Name, Currency and Interval properties.
  • Set Stripe Name (Optional) to use as a nickname alongside Price Name. This allows for up to 255 characters to be referenced. Price Name can only utilize 80 characters.
  • Set the Product lookup (click the lookup selector).
    • The Product must be already pushed into Stripe.
  • Set the Billing Scheme picklist
  • Check the Activecheckbox
  • Save the record
  • Click the Push to Stripe button on the layout

Prices may only be created with products of type service. If the supplied product has type good, a validation error will be thrown.

📘

Note:

If you wish to disable these validations, we have a new custom setting checkbox you can use. For this, navigate to setup->Custom Settings-> Payment Triggers->Manage->Edit and select the checkbox highlighted in the image below.

Additional validations will be executed and you will get an error message if something went wrong. If Price ID field is populated, the Stripe Price is pushed to Stripe and ready to use.You can also pull existing Stripe Prices from Stripe, using the Sync feature on Payment Gateway.

Stripe Price Properties:

  • Product : The product related to this Stripe Price
  • Interval : the frequency with which the subscription will be billed
    • Leave this blank if you are creating a one-time price.

📘

Interval Field Update

Payments packages prior to v5.1 contain Interval as a required field. In order to use one-time prices users will need to update their page layout and remove the required stipulation on Interval.

  • Interval Count: The number of intervals (specified in the interval property) between subscription billings. For example, interval=month and interval_count=3 bills every 3 months.
  • Amount : The amount to be charged. Note that you should not use this field when you have more than one tier.
  • Aggregate Usage: Only for Usage-based prices. The way the usage is calculated at the end of the interval.
  • Billing Scheme: If set to Tiered, you need to set Tiers for the Price
  • Tiers Mode: In volume-based tiering, the maximum quantity within a period determines the per unit price, in graduated tiering pricing can successively change as the quantity grows.
  • Trial Period Days: Default number of trial days when subscribing a customer to this price.

Stripe Price Tiers

Tiered prices must have Tier records. You need to create Tier records before pushing the Stripe Price.

Minimal requirements for Tiers

  • A Tier must have either Flat Amount or Unit Amount value
  • A Tier must have Up To property, which specifies the upper bound of the Tier, which is inclusive.
  • A tiered Price must have at least 2 Tiers
  • The last tier should be open-ended, so the Up To field should left blank.

Both Licensed and Metered Stripe Prices can be tiered.

Tier Pricing Example

A Stripe Price has 3 tiers:

  • 0-10, Flat Amount $100
  • 0-100, Unit Amount 1
  • 100 - null, Unit Amount 0.5

In this case,

  • A Subscription of Quantity=15 will be billed to $105 -- 100 + 5*1
  • A Subscription of Quantity=25 will be billed to $115 -- 100 + 15*1
  • A Subscription of Quantity=200 will be billed to $240 -- 100 + 90*1 + 100*0.5

Update a Stripe Price

You can update the following fields. When you save the record, Stripe is automatically synced.

  • Name (Nickname in Stripe)
  • Active

Note: Once the Stripe Price is pushed to Stripe, only the Name and Active field can be updated.

Push to Stripe checkbox

Instead of using the Push to Stripe button, you can use declaratively the 'Push to Stripe' checkbox (not on the layout in default). When checking this checkbox, the Price data will be pushed to Stripe, and if the operation was successful, the 'Price Id' field gets populated.

Considerations

Do not use the checkbox in asynchronous context, as the trigger starts a future method. If you need to use the checkbox in a future or in a batch context, do the following steps:

  • Select Setup | Change Data Capture
  • Enable Price ( bt_stripe__Plan2__c )
  • Go to Custom Settings | Blackthorn | Payments Triggers
  • Click Manage
  • Check Disable Plan_PushToStripe
  • Save

Now the 'Push To Stripe' checkbox should work also in asynchronous context. Note that if you run the insert Price operations in batch, set your batch size around 30 (you need to consider the time limits as well the callout limits).


Did this page help you?