Profile, Billing and Access Control API Overview
Structure of an API URL
You can retrieve the API version by calling GET /api.
API URLs follow the subsequent pattern:
/api/category/{slug}/action
API URLs are prefixed by /api/, followed by a category indicator,
followed by a unique identifier (typically the slug of a
profile), followed by a specific action.
Featured API Scenarios
There are four main categories are:
- auth
- This category contains APIs related to authenticating users such as registration, login, updating a user password, etc.
- billing
- This category contains APIs to manage the checkout, billing and accounting workflows, including shopping carts, coupons, charges and balance statements.
- profile
- This category contains APIs to manage profiles, including contact information, password updates, subscriptions, and roles.
- metrics
- This category contains APIs to crunch numbers and create reporting dashboards.
Query parameters and results returned
There are three main formats for results returned:
- a single item
- a list of items
- a table of aggregated values over a metric
When you call an API URL that returns a single item, the result will include
all the details of that item. When you call an API URL that returns a list
of items, each item returned will contain a short version with fields typically
necessary to display in a Human User Interface (ex: printable_name
).
List APIs accept query parameters start_at and
ends_at, which are dates in ISO format to filter items returned
by their creation date. The q parameter is used to do random
searches while the q_f parameter is used to further restrict
which fields are searched for a matching q term.
The items returned can be sorted by a field specified in the o
query parameter, while a minus sign preceding the field name will sort by
reverse order.
List results are paginated, thus the page query parameter
specifies the page of results to return. By default the query returns
the first page.
Fields encoding
Field type
Date
Example field names
created_at, start_at, ends_at,
last_login
Description
date/time in ISO 8601 format.
Field type
Currency unit
Example field names
amount
Description
Amounts are written as natural integers expressing in 1/100th of currency unit.
For example an amount of $10 is written as {"amount": 1000, "unit": "usd"}.
Creating profiles API Overview
Accounts created on a site are either users or profiles (Read more about Accounts, roles and subscriptions). We are interested here in the different use cases under which an profile is created.
There are two ways to create a profile, either directly or as a side-effect of inviting a user to the site. The following APIs are available to create a profile:
Registers a user
The easiest way to create a profile is to do so alongside the initial
registration of a user to the site
(API Reference).
By specifying type as either personal
or organization, the site will registers a new user, create
a profile and connect the profile manager role for the newly created profile
to the registered user.
When the type is set to organization, an
organization_name must be specified alongside the user registration
fields.
curl -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"username": "joe1", "password": "yoyo", "email": "joe+1@example.com", "full_name": "Joe Card1", "type": "personal"}' /api/auth/register
Creates a connected profile
Often you will have a user that becomes familiar with the site because they were invited to contribute to an organization. These users might wish to create their own organization profile for personal use and/or as part of a new project.
Your onboarding flow might be separated in multiple steps where information about the organization is filled after the initial registration.
In those cases, a user already exist. You want to create a new profile and connect the profile manager role for the newly created profile to the user. (API Reference)
JWT_TOKEN=`curl -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"username": "xia", "password": "yoyo"}' /api/auth | jq -r .token`
curl -H "Authorization: Bearer ${JWT_TOKEN}" -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"slug": "myproject", "full_name": "My Project"}' /api/users/xia/profiles
Grants a subscription
In cases where registration is disabled, or the business workflow requires providers to invite subscribers, a profile might be created as part of subscribing an otherwise unknown e-mail address. (API Reference)
JWT_TOKEN=`curl -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"username": "donny", "password": "yoyo"}' /api/auth | jq -r .token`
curl -H "Authorization: Bearer ${JWT_TOKEN}" -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"organization": {"slug": "xia"}}' /api/profile/cowork/plans/premium/subscriptions
Creates a shadow profile
In the use cases where you store data and metrics information into your application database, wish to keep personally identifiable information into the djaoapp database and re-associate both in the client application as necessary, you might create shadow profiles; profiles that solely exist to de-anymize datasets but otherwise have no connected profile manager. (API Reference)
Note that until a profile manager is connected to a shadow profile, updates to the profile requires a broker role, or a provider role on an active subscriptions of that shadow profile.
JWT_TOKEN=`curl -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"username": "xia", "password": "yoyo"}' /api/auth | jq -r .token`
curl -H "Authorization: Bearer ${JWT_TOKEN}" -X POST -H 'Content-Type: application/json; charset=UTF-8' -d '{"email": "xia@locahost.localdomain", "full_name": "Joey Black"}' /api/accounts/profiles
Subscriptions API Overview
Billing and subscriptions are separated concepts. Though it is possible to create a subscription based on an online payment, it is also possible to create subscriptions with no associated charge. The plaftorm manages a payment balance on renewal if necessary. That balance can be paid online or off-line. If you like the platform subscription-based access control features but prefer to manage all payments outside the platform, you can do so easily.
Provider and subscriber
Providers are profiles that manage subscription plans. Other profiles on the platform can subscribe to those provider plans. This profiles are thus called Subscribers whith regards to the subscription relationship.
Thus the API is separated into two, depending on which side of the relationship, subscribers or providers, a profile resides.
Subscriber API
The number of endpoints for a subscriber are limited and straightforward to understand so we will start there.
Provider API
A provider must create a plan in order to have subscribers. The REST APIs for plans are pretty straightforward so we won't spend much time on them here.
A provider can list subscribers accross all its plans, list subscriptions that are active, churned, or active but with no activity from users. That last one can help a product identify subscribers potentially churning when their subscription is over.
Billing API Overview
Internally, subscription orders and payments for invoiced items are recorded in an append-only double-entry bookkeeping general ledger. This structure makes it possible run a balance due and balance credit for all subscribers on the site with some guarantees "numbers add up" (If you are interested in the details, read the documentation for the Open Source code).
Billing is separated from subscriptions in such a way that subscriptions and use subscription-based access control features can be managed outside billing entirely (See Plans and subscribers).
This guide explains the major components to run billing through the DjaoDjin APIs.
Billing is attached to profiles, and managed through a running balance. Therefore, there are two main categories of billing API endpoints:
Related tutorials
Adding to a profile balance due
There are two ways to add to a profile balance:
User-based checkout workflow
A site visitor, and future subscriber, will shop for subscription plans, add then into the cart, then execute a subscription order through a checkout workflow.
Shopping for plans are done through the Cart APIs, typically on the pricing page. These APIs are used to implement steps before the checkout page, and are designed to work with either authenticated users or anonymized visitors.
Once a user commits to buy services, the shopping cart items are transferred to a billing profile balance in an execute order step. Once the order is executed (notification), whether payment is processed, is successful, or not, transactions are created in the ledger and shown in the profile's billing history.
# Add to cart POST /api/cart # Places an order and pay immediately POST /api/billing/{profile}/checkout # Places an order to be paid later POST /api/billing/{profile}/checkout/paylater
Provider-recorded use charges
A provider will add use charges directly to the balance when that provider implements usage-based pricing.
# Adds directly to a profile balance POST /api/billing/{profile}/balance
Subtracting from a profile balance due
Order executed by a subscriber, and use charges recorded by a provider, increase the balance due. That balance can be paid by:
- entering a credit card on a payment link, or
- offline, at the discretion of the provider.
Credit card in this context means a physical or virtual credit card, or any other payment methods supported by Stripe.
In scenarios when payment was recovered offline, or payment is deemed impossible to recover, the balance API should be used.
# Places an order and pay immediately POST /api/billing/{profile}/checkout # Pay an invoice POST /api/billing/payments/{claim_code} # Cancels a balance due POST /api/billing/{profile}/payments/{claim_code}/collected
Debugging
When debugging, it is useful to look at the transactions recorded in the ledger by the various billing API endpoints as a broker.
# Lists ledger transactions GET /api/billing/transactions
- Need help?
- Contact us
- Curious how it is built?
- Visit us on GitHub