Skip to main content

Portal Concepts

The EMD Digital Portal API enables managing your payment infrastructure for digital platforms. Admins can create Plans with customizable payment tiers for their digital Products, which represent standalone platforms. Users can then subscribe to individual plans, and view usage details for those Subscriptions.

Concepts​

Products​

Products represent a digital product in our catalog. They have a discrete set of payment options known as Plans, both of which you can create via the API or using the admin dashboard. Each product belongs to a team of product administrators. You can invite and new administrators to the team to share access to a product.

Plans​

Plans are a collection of items for which you can track a user's usage. For example, a single plan could include a monthly fee, and also charge the user a per-unit cost for accessing other resources. Once created, plans can only be deleted when there are no active subscriptions to that plan. Plans can be marked inactive to prevent new users from subscribing to them. Plans can also be restricted to users from a certain domain; or they can be accessible to anyone on your platform.

Once a plan has been created, its dimensions and pricing information cannot be changed anymore. This ensures that a user's subscription stays consistent with the plan they are subscribed to. To make a price change, simply create a new plan and transition users to the new plan.

Plans can only be deleted if there are no active subscribers on the plan and if the plan status has been set to INACTIVE. In cases where there are subscriptions in flight (i.e. a user is currently on the checkout page to subscribe), deleting the plan will fail. In that case, please wait 24h after the plan was set to INACTIVE and try again to ensure that no users are currently in the checkout workflow.

Subscriptions​

Subscriptions are created when a user selects a plan and completes checkout through Stripe. A checkout session will expire after 24 hours if the user doesn't complete the payment form. Once a user has subscribed to a plan, their usage can be recorded using the Metering API. Usage is recorded and reported per plan item (each plan item is created as a Metering API Resource).

Usage Flow​

Subscribing to a Plan​

Products and plans can be created through the admin dashboard. After creating plans, check that they're available in your application via the listPlans endpoint: GET /plans (you will need to pass your user's access token as an Authentication header). Use this endpoint in your frontend to show plans to a user.

Users can now select which plan they would like to subscribe to. To subscribe, use the createSubscription endpoint: POST /subscriptions, which returns a checkoutUrl to which you should redirect the user. You'll need to provide the planId, along with a cancelUrl and successUrl: your user will get redirected to one of these from Stripe's checkout. A successful checkout will subscribe the user to the plan - this may take a brief moment, after which a call to listSubscriptions (GET /subscriptions) will show the activated subscription!

Recording Usage​

Once a user has a subscription, they can start accessing resources defined in the underlying plan. Your backend should handle the user's requests to access resources by interacting with the Metering API: the user's subscription has a meteringKeyId, and each plan item has a meteringResourceId. Using these you can create and manage transactions using your backend token (see Metering API docs). The metering service will enforce limits on usage as defined in your plan (and throw a 400 Bad Request error if the transaction would exceed those limits).

Canceling a Subscription​

A user is able to cancel their subscription only when no pending transactions exist. Subscriptions can be canceled at the end of the period; or instantly, which will prorate the user's account based on the length of the subscription.