Your end users pay on your own Stripe account. ShipRev works in that account through the payment connection of your application: it creates the products and prices of your plans, opens checkout and the billing portal, and follows Stripe's events back. This page is about living with that in Stripe: what you will find there, what you can change there, and how to rehearse. Connecting the account and the webhook events to send are in Take payments on your own Stripe account.
This page covers the connection made with your own Stripe keys.
What ShipRev creates in your account
| When | In Stripe | Details |
|---|---|---|
| You publish a plan version | A product and a recurring price | One new product and one price per published version. The product is named after your product and plan, for example Reports - Pro. The price has the version's amount and currency, and recurs every month or year with the version's billing interval |
| An end user subscribes | A Checkout Session in subscription mode, then a customer and a subscription | One line item, the version's price, quantity 1; the end user's email is prefilled. An unpaid session expires after just under 24 hours |
| An end user changes plan | An update of the subscription's price | The difference for the rest of the period is invoiced at once: on a move up the end user is charged it, and on a move down Stripe does not refund it automatically: the difference is kept as a credit on the customer's balance in Stripe, and the invoice for the change is 0. When the charge does not succeed on the spot, the subscription stays on its current plan version in ShipRev and the end user is sent to the invoice's payment page; see Change plan |
| An end user cancels | cancel_at_period_end on the subscription | The subscription runs to the end of the paid period |
| An end user opens billing | A billing portal session for their customer | return_url must be an https address on a verified brand domain of your application; any other address is refused with INVALID_RETURN_URL |
| An end user tops up their wallet | A Checkout Session in payment mode, in USD | A line item named Credits Top-Up; the end user enters their email on Stripe's page. The card is saved for later automatic charges, whether or not automatic recharges are turned on. Tell your end users that their card is kept for later charges before they pay, on your top-up page or in your terms; ShipRev does not tell them for you. |
| A wallet is recharged automatically | A PaymentIntent, charged off-session to the saved card | Only when the end user turned on automatic recharges |
Charges are made on your account, and ShipRev adds no application fee to them.
Find a customer's objects
ShipRev puts its identifiers in the metadata of what it creates, so you can go from a buyer organization to Stripe and back:
| Stripe object | Metadata |
|---|---|
| Product | project_id, plan_id |
| Price | project_id, plan_id, plan_version_id, version |
| Checkout Session and Subscription of a plan | project_id, organization_id, subscription_id, plan_version_id |
| Checkout Session of a top-up | type set to WALLET_TOPUP, and project_id |
| PaymentIntent of an automatic recharge | type set to AUTO_RECHARGE, project_id, organization_id |
Every Stripe subscription that ShipRev started carries the buyer organization's organization_id in its metadata, and the subscription_id in that metadata is the subscription_id that GET /public/v1/subscriptions returns for that organization. The plan_version_id in a subscription's metadata is the version subscribed to at checkout; a later plan change does not update it, so read the current version from ShipRev.
What you can do in the Stripe Dashboard
ShipRev follows the events listed in The events to send. What it does with changes you make in Stripe:
| You, in Stripe | What ShipRev does |
|---|---|
| Cancel a subscription now | Ends the subscription in ShipRev when customer.subscription.deleted arrives |
| Schedule or undo a cancellation at period end | Follows it from customer.subscription.updated |
| Move a subscription to the price of another published plan version of the same application | Moves the organization to that plan version and rebuilds its entitlements; your backend gets the new ones without a restart |
| Move a subscription to a price ShipRev did not create, or give it several items | Leaves the subscription on its plan version, and records the event as processed with a note that the price maps to no plan version |
| Create a subscription yourself | Nothing: ShipRev only follows subscriptions that started with its own checkout |
Two things to leave alone:
- The prices ShipRev created. A published plan version keeps the price it was given, and renewals bill that price. To change what you charge, publish a new plan version; see Change a price without touching code.
- The metadata. It is how you, and ShipRev's checkout receipts, connect Stripe objects to buyer organizations.
Rehearse in test mode
A test secret key, sk_test_…, makes a test-mode connection; everything above happens in your Stripe account's test data. Rehearse with Stripe's test cards before you switch to live keys.
- Save a test key and register the webhook endpoint in test mode, as in Take payments on your own Stripe account.
- Publish your plans. Each version's price appears in Stripe's test data; a version published before the connection is synced when you save it.
- Subscribe a test end user through
PricingTableand pay with a test card. The subscription becomes active in ShipRev whencheckout.session.completedarrives, and your backend's rulings change without a restart. - Change plan and cancel as that end user, and check Payment Gateway for the events received. The billing portal opens only with a
return_urlon a verified brand domain, so rehearse it once your brand domain is verified.
Before a connection exists, publishing still works: the version is frozen and waits to be synced, and checkout on it is refused with PAYMENT_PROVIDER_NOT_CONFIGURED. To rehearse rulings without Stripe, activate a subscription by hand with POST /mgt/v1/projects/{projectId}/subscriptions/activate.
Going live means new live keys, a live webhook endpoint, and a new version of each plan you sell, because versions synced in test mode keep their test prices; see Test mode and going live.