TABLE OF CONTENTS


What are PayPerLabel Subscriptions?

PayPerLabel subscriptions are subscriptions which contain some kind of Metered/usage-based aspect. At the moment the usage-based model for existing PayPerLabel subscriptions is on a tiered, graduated rate. This means that once a certain usage threshold is passed the price for the next tier is applied. PayPerLabel subscriptions can only be applied on a monthly basis. We can use the subscription "Price Per Label" as an example. For the first 20,000 units the customer will not be charged anything. For the 10,000 units between 20,001 and 30,000 the customer will be billed at £0.0295 per unit and for the next 20,000 after that until 50,000 units they will be billed £0.025 per unit. This pricing model continues until 100,000 units which is the final tier. All units beyond 100,000 will be billed at £0.015.


How are PayPerLabel subscriptions billed?

Understanding Stripe subscription concepts

The model for subscriptions in Stripe is not 1:1 with the model for subscriptions in Shiptheory. To understand how a PayPerLabel subscription is created you must firstly understand the following Stripe concepts:

  • Product: An item to be sold on Stripe
  • Price: Every product can have multiple prices. For example, there is 1 product called Price Per Label, but there are multiple different prices which come under the heading of Price Per Label.
  • Subscription: A recurring payment made up of multiple prices from one or more products. One customer can have many subscriptions.
  • Usage: The number of units of a price which has been used in a billing period
  • Billing period: The time period of one subscription cycle. For example 01/03/2024 14:30:00 -  01/04/2024 14:30:00. Stripe takes into account both date and time for this. 
  • Customer: The record of a single purchaser in Stripe


How Stripe subscription concepts line up with Shiptheory subscription concepts

  • When billing a user with Stripe we will create a customer record for them in Stripe and save a reference to it in Shiptheory. This customer record will have details like default card and billing address saved to it when a user goes through Stripe checkout. There is a 1:1 relationship between a Stripe customer and Shiptheory company. 
  • Subscriptions in Shiptheory are actually the same as 2 prices in Stripe. This will be a price for a monthly cost of the product and the price of the annual cost of the product. 
  • Usage is incremented in Shiptheory every time a Shipment is set from a status not equal to "Complete" to the status of "Complete". In other words every time a label is successfully generated.


How billing is undertaken by Stripe

  • When creating a PayPerLabel subscription we will add 2 prices to it:
    • A flat rate which will equate to the monthly price of an existing subscription
    • The usage-based price
  • Stripe will bill for the flat rate immediately when a customer checks out. This means that a customer will always have to pay the flat rate to start their subscription
  • Shiptheory will send usage reports to Stripe for users on a PayPerLabel subscription at an interval of ~1 minute. 
  • At the start of the next billing period Stripe will create a new invoice which it will attempt to auto charge the customer's default card. The invoice will consist of the usage from the previous month and the charge for next month's subscription.
  • There may be some overlap if the billing period switches over during a reporting cycle and therefore some users may see some shipments attributed to their bill for the next billing period.
  • If a user cancels a PayPerLabel subscription then Stripe will create an invoice for the usage used in the billing period so far. Unlike the start of period invoice this will not include the next period's flat rate. 


Putting a company on a PayPerLabel subscription

  1. Navigate to https://helm.shiptheory.com/accounts/edit/{company_id}
  2. Scroll down until you see the "New Subscription Checkout Link" option and click on it to open the form.
  3. Select a subscription from the dropdown and click "Generate Link"
  4. Copy the generated link and send it to the customer. When they click on it they will be taken to a Stripe Checkout page with the subscription pre-filled and ready to be paid for. All they need to do is pay for the subscription and their subscription will automatically be changed in Shiptheory.
  5. If they have a running subscription in Shiptheory when they do this you will need to go into the Stripe admin UI and manually cancel the old subscription. You can avoid this if you first get the user to cancel their existing subscription in the Shiptheory UI.


Limitations of PayPerLabel subscriptions

  • Using a generated link to buy a PayPerLabel subscription will not cancel a user's existing subscription in their billing source (e.g. Stripe, Shopify, Xero), but will cancel it in Shiptheory. If the user has an existing subscription in their billing source and they use this link, then you will need to got to their billing source and manually cancel the old subscription.
  • Users must have Stripecheckout as their billing source. No other billing source supports PayPerLabel subscriptions.
  • Users on a PayPerLabel subscription cannot change from a PayPerLabel subscription to a non-PayPerLabel subscription
  • Users on a PayPerLabel subscription cannot buy boltons


Adding a new PayPerLabel subscription to Shiptheory

Like all subscriptions there is currently no way for non-developers to add a new PayPerLabel subscription. If you need to add a new PayPerLabel subscription to Shiptheory you must first add it to Stripe. You will then need to get the development team involved to add it to the database.


Adding a the PayPerLabel subscription price in Stripe

  1. Go to the Price Per Label product in Stripe.
  2. Add a new price.
  3. Select the following options
    1. Price Type: Recurring
    2. Pricing Model: Usage-based, per tier, graduated
    3. Include tax in price: Yes
    4. Currency: GBP
    5. Use usage records: Yes, Sum of usage values during period
    6. Billing period: monthly
    7. Description: Something unique and relevant
    8. Tiers: This should be based on the contract or requirements. If a flat fee for the first n labels is required, then the first tier should be from 0 to n. For example if I pay for the 1st 50,000 labels at a flat rate, then tier 1 should be 0 - 50,000 at £0.00. Subsequent tiers should be subject to requirements. You can look at other pricing for examples
  4. Once you've filled in the above, create the price.
  5. Once created save the ID of the price. It should be present on the page in the format "price_somerandomstring". 
  6. Give the price ID along with the name of the price to dev. They will add it to the database.


Adding a base subscription price to Stripe

In some instances you may need to add a new base subscription to be associated with the PayPerLabel subscription. The base subscription dictates how much a customer is charged at the start of the billing cycle and also controls what features a user has access to in Shiptheory. Base subscriptions should be variations of the standard Shiptheory subscription tiers e.g. Earth, Saturn, etc.

  1. Go to the product catalogue in Stripe and search for the base subscription product. For example: Enterprise.
  2. Open the product and add a new price.
  3. Select the following options:
    1. Price Type: Recurring
    2. Pricing Model: Flat Rate
    3. Price amount: Whatever the agreed flat rate is
    4. Include tax in price: Yes
    5. Billing Period: Monthly
    6. Description: Something unique and relevant
  4. Once you've filled in the above, create the price.
  5. Once created save the ID of the price. It should be present on the page in the format "price_somerandomstring". 
  6. Give the price ID, the name of the price and the name of the Shiptheory subscription level the price applies to, to dev. They will add it to the database.


AKA: Previously known as Enterprise Infinity (left here for search)

AKA: Price per label (left here for search)