API and HTML pages

The API is split in four sections:

  • Profiles to manage the identity, such as name or email address, of users and organizations registered to the site.

  • Subscriptions to define the relationship between a subscriber and a provider through a plan.

  • Billing to manage the checkout, billing and accounting workflows, including shopping carts, coupons, charges and balance statements.

  • Metrics to crunch numbers and return various insight into the performance of the business.

The HTML Views implement workflows and dashboards pages for subscriber-facing and provider-facing use cases. The code logic is fully implemented so progress and redirects happen properly. The HTML templates are minimal for you to understand how to hook-up the Vue components.

Design tip: If you want to present a completely different user interface to customers and managers of the provider backend, you will choose to have both sets of templates inherit from a different base template. If you are building an interface where managers see an augmented interface overlayed on top of regular subscriber interface, you might prefer all your templates to inherit from a common base template.

For an example of fully functional pages styled with Bootstrap, take a look at DjaoApp default theme.

Subscriber facing pages

All the pages in this group are accessible to a subscriber, either to establish a relationship with the site by subscribing to a plan or to manage her billing profile, active subscriptions, etc.

You will want to edit these templates first since they directly impact the look and feel a customer will have of your site.

class saas.views.legal.AgreementListView(**kwargs)

List all agreements and policies for a provider site. This typically include terms of service, security policies, etc.

Template:

To edit the layout of this page, create a local saas/legal/index.html (example).

Template context:
  • agreement_list List of agreements published by the provider

  • organization The provider of the product

  • request The HTTP request object

class saas.views.legal.AgreementDetailView(**kwargs)

Show a single agreement (or policy) document. The content of the agreement is read from saas/agreements/<slug>.md.

Template:

To edit the layout of this page, create a local saas/legal/agreement.html (example).

Template context:
  • page The content of the agreement formatted as HTML.

  • organization The provider of the product

  • request The HTTP request object

class saas.views.legal.AgreementSignView(**kwargs)

For a the request user to sign a legal agreement.

Template:

To edit the layout of this page, create a local saas/legal/sign.html (example).

Template context:
  • page The content of the agreement formatted as HTML.

  • organization The provider of the product

  • request The HTTP request object

class saas.views.plans.CartPlanListView(**kwargs)

GET displays the active plans available for subscription.

Template:

To edit the layout of this page, create a local saas/pricing.html (example).

Template context:
  • plan_list List of plans a customer can subscribed to

  • items_selected List of items currently in the request user cart.

  • organization The provider of the product

  • request The HTTP request object

POST adds the selected plan into the request user cart.

class saas.views.billing.RedeemCouponView(**kwargs)

Stores a Coupon into the session for further use in the checkout pipeline.

CartView.get(request, *args, **kwargs)

Prompt the user to enter her credit card and place an order.

On POST, the credit card will be charged and the organization subscribed to the plans ordered.

Template:

To edit the layout of this page, create a local saas/billing/cart.html (example). This template is responsible to create a token on Stripe that will then be posted back to the site.

Template context:
  • STRIPE_PUB_KEY Public key to send to stripe.com

  • invoicables List of items to be invoiced (with options)

  • organization The provider of the product

  • request The HTTP request object

class saas.views.billing.CartPeriodsView(**kwargs)

Optional page to pay multiple periods in advance.

Template:

To edit the layout of this page, create a local saas/billing/cart-periods.html (example).

Template context:
  • invoicables List of items to be invoiced (with options)

  • organization The provider of the product

  • request The HTTP request object

class saas.views.billing.CartSeatsView(**kwargs)

Optional page to subcribe multiple organizations to a Plan while paying through through a third-party Organization (i.e. self.organization).

Template:

To edit the layout of this page, create a local saas/billing/cart-seats.html (example).

Template context:
  • invoicables List of items to be invoiced (with options)

  • organization The provider of the product

  • request The HTTP request object

class saas.views.billing.ChargeReceiptView(**kwargs)

Display a receipt for a Charge.

Template:

To edit the layout of this page, create a local saas/billing/receipt.html (example).

Template context:
  • charge The charge object

  • organization The provider of the product

  • request The HTTP request object

This page will be accessible in the payment flow as well as through a subscriber profile interface. The template should take both usage under consideration.

Manage subscriptions

These pages enable a subscriber to manage her profile on the site. She can update her personal information (email address, etc.), change her credit card on file, review the list of charges by a provider, pay a balance due, etc.

The business requirements might require or prevent a manager or a custom role (ex: contributor) of a provider to access specific information about a subscriber. For example, you might allow your customer support team to update a subscriber credit card over the phone for convienience. You might also believe it is too much risk, deny the ability to do so by your customer support people and instruct them to hand out instructions to the subscriber on how to do so by herself. All scenarios can easily be implemented through a Flexible Security Framework.

class saas.views.billing.BillingStatementView(**kwargs)

This page shows a statement of Subscription orders, Charge created and payment refunded.

Template:

To edit the layout of this page, create a local saas/billing/index.html (example). You should insure the page will call back the /api/billing/{profile}/history API end point to fetch the set of transactions.

Template context:
  • balance_price A tuple of the balance amount due by the subscriber

    and unit this balance is expressed in (ex: usd).

  • organization The subscriber object

  • request The HTTP request object

BalanceView.get_queryset()
class saas.views.billing.CardUpdateView(**kwargs)

Page to update the Credit Card information associated to a subscriber.

Template:

To edit the layout of this page, create a local saas/billing/card.html (example).

Template context:
  • STRIPE_PUB_KEY Public key to send to stripe.com

  • organization The subscriber object

  • request The HTTP request object

class saas.views.profile.OrganizationProfileView(**kwargs)

Page to update contact information of an Organization.

Template:

To edit the layout of this page, create a local saas/profile/index.html (example).

Template context:
  • urls.organization.password_chage URL to update user password.

  • organization The organization object

  • request The HTTP request object

class saas.views.profile.SubscriptionListView(**kwargs)

List of Plans this organization is subscribed to.

Template:

To edit the layout of this page, create a local saas/profile/subscriptions.html (example). You should insure the page will call back the /api/profile/{profile}/subscriptions API end point to fetch the set of subscriptions for the organization.

Template context:
  • organization The subscriber object

  • request The HTTP request object

class saas.views.profile.RoleListView(**kwargs)

List all RoleDescription for an organization and the users under each role.

class saas.views.users.ProductListView(**kwargs)

List of organizations a :user has a role with.

Template:

To edit the layout of this page, create a local saas/users/roles/index.html (example). You should insure the page will call the /api/users/{user}/accessibles API end point to fetch the set of organization accessible by the user.

Template context:
  • user The organization object users have permissions to.

  • request The HTTP request object

Provider facing pages

Provider facing pages are only accessible to its managers. They are used to assess the performance of the business, set pricing strategy, and help with customer support.

Pricing strategy

class saas.views.billing.CouponListView(**kwargs)

View to manage discounts (i.e. Coupon)

Template:

To edit the layout of this page, create a local saas/billing/coupons.html (example). You should insure the page will call the /api/billing/{profile}/coupons <https://www.djaodjin.com/docs/reference/djaoapp/latest/api/#listCouponListCreate> API end point to fetch the set of coupons for the provider organization.

Template context:
  • organization The provider for the coupons

  • request The HTTP request object

class saas.views.plans.PlanCreateView(**kwargs)

Create a new Plan for an Organization.

Template:

To edit the layout of this page, create a local saas/profile/plans/plan.html (example).

Template context:
  • organization The provider for the plans

  • request The HTTP request object

class saas.views.plans.PlanUpdateView(**kwargs)

Update information about a Plan.

Template:

To edit the layout of this page, create a local saas/profile/plans/plan.html (example).

Template context:
  • plan The plan to update

  • show_delete True if there never were subscriber to the plan

  • organization The provider of the plan

  • request The HTTP request object

Transfer subscriber payments to provider bank

class saas.views.billing.TransferListView(**kwargs)

List of payments made to a provider or funds transfered out of the platform to the provider bank account.

Template:

To edit the layout of this page, create a local saas/billing/transfers.html (example). You should insure the page will call the /api/billing/{profile}/transfers API end point to fetch the set of transactions.

Template context:
  • organization The provider transactions refer to

  • request The HTTP request object

class saas.views.billing.ImportTransactionsView(**kwargs)

Insert transactions that were done offline for the purpose of computing accurate metrics.

Template:

To edit the layout of this page, create a local saas/billing/import.html (example).

Template context:
  • organization The provider object

  • request The HTTP request object

Manage subscribers and business performance

class saas.views.metrics.CouponMetricsView(**kwargs)

Performance of Coupon based on CartItem.

Template:

To edit the layout of this page, create a local saas/metrics/coupons.html (example).

Template context:
  • coupon The coupon the list of uses refers to

  • organization The provider object

  • request The HTTP request object

class saas.views.profile.DashboardView(**kwargs)

High-level dashboard for a quick glance of the business in real-time.

Template:

To edit the layout of this page, create a local saas/metrics/dashboard.html (example).

Template context:
  • organization The provider object

  • request The HTTP request object

class saas.views.metrics.PlansMetricsView(**kwargs)

Performance of Plans for a time period (as a count of subscribers per plan per month)

Template:

To edit the layout of this page, create a local saas/metrics/plans.html (example). The page will typically call /api/metrics/{profile}/plans to fetch the 12 month trailing performance in terms of subscribers of the plans of a provider.

Template context:
  • organization The provider object

  • request The HTTP request object

class saas.views.metrics.RevenueMetricsView(**kwargs)

Reports cash flow and revenue in currency units.

Template:

To edit the layout of this page, create a local saas/metrics/revenue.html (example).

The page will typically call /api/metrics/{profile}/funds <https://www.djaodjin.com/docs/reference/djaoapp/latest/api/#listRevenueMetric> to fetch the 12 month trailing cash flow table, and/or /api/metrics/{profile}/balances to fetch the 12 month trailing receivable/backlog/income revenue.

The example page also calls /api/metrics/{profile}/customers to fetch the distinct number of customers that generated the cash transactions.

Template context:
  • organization The provider object

  • request The HTTP request object

class saas.views.profile.SubscriberListView(**kwargs)

List of organizations subscribed to a plan provided by the organization.

Template:

To edit the layout of this page, create a local saas/profile/subscribers.html (example).

This page will typically call back /api/profile/{profile}/subscribers/subscriptions and/or /api/profile/{profile}/subscribers/subscriptions/churned to fetch the set of active and/or churned subscribers for a provider plans.

Template context:
  • organization The provider object

  • request The HTTP request object

class saas.views.metrics.BalancesView(**kwargs)

Display a balance sheet named :report.

Template:

To edit the layout of this page, create a local saas/metrics/balances.html (example).

Template context:
  • organization The provider object

  • request The HTTP request object