# Subscriptions

Within the Zaikio App Store, any authorized software vendor can sell their apps. We allow very flexible cost models, add-ons and localized offers in different countries and currencies. In this guide we explain how to manage and create offerings, plans and subscriptions.

# 1. Authorize for payout

In order to offer subscriptions for your app, you must meet the following criteria:

The owner has accepted Zaikio's terms and conditions
The owner has verified his/her email
A billing address for the organization has been provided (it will be used for the credit notes)
A valid tax identifier has been provided for the organization
A valid payout account has been provided, created through Zaikio's partner Stripe.

The information can be entered under the menu item Billing.

On sandbox you can also offer plans without providing all details.

After everything is set up, you will receive a credit note every month and a payment of your earnings, minus the Zaikio commission, to your reference account. You will receive multiple credit notes if you offer multiple currencies.

# 2. Offerings and plans

Zaikio distinguishes between offerings and plans. An offering can have multiple plans (but should have at least one). The offering is intended to create a regional app offering and also to offer a different pricing model.

To make it as simple as possible, an offering can cover multiple countries (for example, Germany and Austria), but only one currency. The currency that needs to be selected is the one that is supported in the respective countries.

A fixed monthly fee can be set (in the currency of the offering). Even if this fee is monthly, Zaikio prorates the fee based on the days used.

As an additional option to the monthly fee, the pricing model can also reflect usage costs. However, your app must tell Zaikio which units were consumed (see Increment cost usages).

Plans as well as offerings have to be activated first to be visible in the App store. In addition, the app must be successfully reviewed by Zaikio.

# Changing plans

It is not possible to change the plan of the subscription without the user's approval. In order to provide full cost transparency and security to all organizations, the prices of an active plan cannot be changed.

Of course, it may happen that a pricing model is updated. In this case it is possible to deactivate the existing plans. This means that they will continue to work for existing subscriptions but will no longer be available in the App Store for signing up new subscriptions. The user can then change the plan on their own.

# 3. Accepting subscriptions

Since Zaikio takes care of all the payment processing, all your app has to do is make sure it displays the right content depending on the plan, activates the subscription, as well as responds to state changes. You may also need to increment usage units if that's how the cost model you've chosen is configured.

# Subscription Lifecycle

Once an organization has created a subscription on Zaikio, it is marked as provisioning. As long as it is in this status, the customer does not have to pay anything yet. We recommend activating the subscription immediately, if possible. Then the customer should also be given access to all usage content.

The customer has the possibility to cancel at any time (from any condition). In this case, the app must deny access again.

Furthermore, the customer may not have been able to successfully cover the last invoice. In this case, there will be no payout from Zaikio and we recommend denying access until the problem is solved. Of course, it is up to the app vendor to be as accommodating as possible. The subscription will then be in the unpaid state.

For all state changes there are corresponding Loom events. All events should be processed as described:

directory.subscription_created A new subscription has been created, it will have the state provisioning
directory.subscription_plan_changed A subscription's plan has been changed, it will have the state provisioning
directory.subscription_payment_failed The latest payment failed, it will have the state unpaid
directory.subscription_payment_issues_resolved The latest payment recovered, it will have the state active
directory.subscription_canceled The organisation canceled the subscription (can happen in any state), the subscription will be null (or result in a 404 not found). Since the monthly fee is prorated by Zaikio, there is nothing to do besides revoking all access.

# Receiving state and plan of a subscription

There are two ways to access the subscription data. The simplest one is via GET /organization or GET /person (through organization_memberships). The response is extended here with some details about the subscription:

{
  "id": "b1475f65-236c-58b8-96e1-e1778b43beb7",
  "name": "Bounty Soap Inc.",
  "slug": "bounty_soap_inc",
  "connected": true,
  ...,
  "subscription": {
    "status": "active", // active, provisioning, unpaid
    "plan": "advanced"
  }
}

If no subscription exists, null will be returned instead. This way, you can relatively easily determine the organization's access to your content without making another request.

If you want to retrieve detailed data about the subscription, for example because the subscription has the state unpaid, you can also use the GET /subscriptions endpoint (using Basic Auth):

curl --request GET \
  --url https://hub.sandbox.zaikio.com/api/v1/subscriptions/Organization-d2e78ba7-5cfc-4359-9d8a-43ce0fa3a795 \
  --header 'authorization: Basic dGVzdDp0ZXN0'

d2e78ba7-5cfc-4359-9d8a-43ce0fa3a795 is the UUID of the organisation.

The following information about the subscription is returned:

{
  "subscriber_type": "Organization",
  "subscriber_id": "b1475f65-236c-58b8-96e1-e1778b43beb7",
  "status": "active",
  "activated_at": "2020-08-08T00:00:00.000Z",
  "last_billed_at": null,
  "last_paid_at": null,
  "trial_ended_at": null,
  "created_at": "2020-08-26T07:37:59.965Z",
  "updated_at": "2020-08-26T07:37:59.965Z",
  "plan": "advanced",
  "preceding_plan": null,
  "changed_plan_at": null,
  "usages_in_current_billing_period": {
    "orders_created": 12
  }
}

For detailed information, check out the Zaikio Hub OpenAPI specification on subscriptions.

# Activate subscription

To activate a subscription, the subscriptions endpoint must be called with Basic Auth. It is necessary that the app authorizes itself with confidential credentials, because only it is allowed to activate a subscription.

The request looks like this:

curl --request PATCH \
  --url https://hub.sandbox.zaikio.com/api/v1/subscriptions/Organization-d2e78ba7-5cfc-4359-9d8a-43ce0fa3a795 \
  --header 'authorization: Basic dGVzdDp0ZXN0' \
  --header 'content-type: application/json' \
  --data '{
  "subscription": {
    "status": "active"
  }
}'

d2e78ba7-5cfc-4359-9d8a-43ce0fa3a795 is the UUID of the organisation. Once the subscription is activated, the organization is charged over the useful life. Zaikio prorates the cost per day.

# Increment usage costs

Similar to activating a subscription, usage costs can also be incremented. Not the sum is transmitted, but the value by which the units are to be incremented.

curl --request PATCH \
  --url https://hub.sandbox.zaikio.com/api/v1/subscriptions/Organization-d2e78ba7-5cfc-4359-9d8a-43ce0fa3a795 \
  --header 'authorization: Basic dGVzdDp0ZXN0' \
  --header 'content-type: application/json' \
  --data '{
  "subscription": {
    "increment_usages_in_current_billing_period": {
			"my_usage_cost": 1
		}
  }
}'

We recommend to execute this request as soon as another unit has been consumed and to increase the value by 1.

Zaikio Core

Reference