Accounts API

The Accounts API is used to manage an organization's billing account. Any organization with active services must have a billing account, except organizations that belong to a reseller or parent organization. In hierarchical relationships, the organization at the top of the tree is responsible for the billing of all the organizations beneath it.

Initial State

The section below describes the necessary actions that should be followed before a new user would be able to create their first service.

Default Organization

When a new user sings up, they won't have an organization or billing account. During the authentication workflow, a default organization is created for the user. The user is nominated as the owner of the organization. The newly created organization is also set as the current organization of the user.

Authentication Workflow

During the login process, a check is made to obtain the ID of the users' currently selected organization. The ID is stored in the id claim of the JWT access token. When services are created, the ID claim is used to determine which organization the service belongs to. This ID is essentially the glue that binds resources to an organization.

When to Create a Billing Account

After authentication is completed, a GET should be made to the v1/account endpoint to determine if the user has a billing account. If the user does not have a billing account a no account error will be returned. Under normal circumstances, this endpoint should return a 200 OK response with the account object in the response body.

Creation of a Services

When a user attempts to create a service (this includes paid and free services), the microservice that handles the creation of the service will make a call to the Subscription API to determine if the organization clears the necessary checks to create a service. Service creation will be prevented if the required clearances are not met.

The Account Object

  • Name
    id
    Type
    string
    Description

    The unique identifier of the billing account.

  • Name
    name
    Type
    string
    Description

    The users' full name or business name. Maximum length of 100 characters.

  • Name
    email
    Type
    string
    Description

    The users' email address. Maximum length of 250 characters. This is the email address that will be used to send any billing related emails to. Casts to lowercase.

  • Name
    currency
    Type
    enum
    Description

    During the creation of a billing account, the currency is set based on the selected country. It will be one of the supported currencies.

  • Name
    balance
    Type
    float
    Description

    This is the current balance of the account. The balance is always in the currency of the account.

  • Name
    address.city
    Type
    string
    Description

    City, district, suburb, town, or village. Maximum length of 50 characters.

  • Name
    address.country
    Type
    string
    Description

    Two-letter country code (ISO 3166-1 alpha-2).

  • Name
    address.line1
    Type
    string
    Description

    Address line 1 (e.g., street, PO Box, or company name). Maximum length of 100 characters.

  • Name
    address.line2
    Type
    string
    Description

    Address line 2 (e.g., apartment, suite, unit, or building). Maximum length of 100 characters.

  • Name
    address.postal_code
    Type
    string
    Description

    ZIP or postal code. Maximum length of 10 characters.

  • Name
    address.state
    Type
    string
    Description

    State, county, province, or region. Maximum length of 50 characters.

  • Name
    created_at
    Type
    datetime
    Description

    Time at which the object was created. Returns a datetime string in the format YYYY-MM-DD HH:MM:SS using the timezone claim of the JWT access token. Defaults to UTC.

The Account Object

{
    "id": "cus_OdMmvWHZ8Y2rEH",
    "name": "Hannes Kruger",
    "email": "hannes@mikrocloud.com",
    "currency": "USD",
    "balance": 0,
    "address": {
        "city": "",
        "country": "AU",
        "line1": "",
        "line2": "",
        "postal_code": "",
        "state": ""
    },
    "created_at": "2023-09-14 03:16:36"
}
GET/v1/account

Retrieve an Account

Requires the account:read scope.

Parameters

No parameters are required for this endpoint.

When an account does not yet exist, a no account error will be returned.

Example request

curl -G https://api.mikrocloud.com/v1/account \
-H "Authorization: Bearer {token}"

Example response

{
    "id": "cus_OdMmvWHZ8Y2rEH",
    "name": "Hannes Kruger",
    "email": "hannes@mikrocloud.com",
    "currency": "USD",
    "balance": 0,
    "address": {
        "city": "",
        "country": "AU",
        "line1": "",
        "line2": "",
        "postal_code": "",
        "state": ""
    },
    "created_at": "2023-09-14 03:16:36"
}
POST/v1/account

Create an Account

Requires the account:write scope.

Parameters

During the creation of an account, the parameters below are required. Optional parameters will be ignored during the creation of an account. If you want to add additional information to the account, you can use the Update an Account endpoint.

  • Name
    name
    Type
    string
    Required
    Required
    Description

    The users' full name or business name. Maximum length of 100 characters.

  • Name
    email
    Type
    string
    Required
    Required
    Description

    The users' email address. Maximum length of 250 characters. This is the email address that will be used to send any billing related emails to. Casts to lowercase.

  • Name
    address.country
    Type
    string
    Required
    Required
    Description

    Two-letter country code (ISO 3166-1 alpha-2).

currency is only set during the creation of the first subscription. Directly after the creation of the account it may be an empty string.

Example request

curl -X POST https://api.mikrocloud.com/v1/account \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
    "name": "Hannes Kruger",
    "email": "hannes@mikrocloud.com",
    "address": {
        "country": "AU"
    }
}'

Example response

{
    "id": "cus_OdMmvWHZ8Y2rEH",
    "name": "Hannes Kruger",
    "email": "hannes@mikrocloud.com",
    "currency": "",
    "balance": 0,
    "address": {
        "city": "",
        "country": "AU",
        "line1": "",
        "line2": "",
        "postal_code": "",
        "state": ""
    },
    "created_at": "2023-09-14 03:16:36"
}
PUT/v1/account

Update an Account

Requires the account:write scope.

Parameters

To update an account, you can use the parameters below. Only provided parameters will be updated. If a parameter is not included in the request, its value will remain unchanged in the account. This endpoint allow supports the PATCH method. If you wish to unset a value, you can set it to "" (empty string).

  • Name
    name
    Type
    string
    Required
    Optional
    Description

    The users' full name or business name. Maximum length of 100 characters.

  • Name
    email
    Type
    string
    Required
    Optional
    Description

    The users' email address. Maximum length of 250 characters. This is the email address that will be used to send any billing related emails to. Casts to lowercase.

  • Name
    address.city
    Type
    string
    Required
    Optional
    Description

    City, district, suburb, town, or village. Maximum length of 50 characters.

  • Name
    address.country
    Type
    string
    Required
    Optional
    Description

    Two-letter country code (ISO 3166-1 alpha-2).

  • Name
    address.line1
    Type
    string
    Required
    Optional
    Description

    Address line 1 (e.g., street, PO Box, or company name). Maximum length of 100 characters.

  • Name
    address.line2
    Type
    string
    Required
    Optional
    Description

    Address line 2 (e.g., apartment, suite, unit, or building). Maximum length of 100 characters.

  • Name
    address.postal_code
    Type
    string
    Required
    Optional
    Description

    ZIP or postal code. Maximum length of 10 characters.

  • Name
    address.state
    Type
    string
    Required
    Optional
    Description

    State, county, province, or region. Maximum length of 50 characters.

Example request

curl -X PUT https://api.mikrocloud.com/v1/account \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
    "name": "Hannes Kruger",
    "email": "hkruger@mikrocloud.com",
    "address": {
        "city": "Melbourne",
        "country": "AU",
        "line1": "123 Mikro St",
        "line2": "Apt 4B",
        "postal_code": "3000",
        "state": "VIC"
    }
}'

Example response

{
    "id": "cus_OdMmvWHZ8Y2rEH",
    "name": "Hannes Kruger",
    "email": "hkruger@mikrocloud.com",
    "currency": "USD",
    "balance": 0,
    "address": {
        "city": "Melbourne",
        "country": "AU",
        "line1": "123 Mikro St",
        "line2": "Apt 4B",
        "postal_code": "3000",
        "state": "VIC"
    },
    "created_at": "2023-09-14 03:16:36"
}
DELETE/v1/account

Delete an Account

This endpoint is not yet implemented. Please contact support if you need to delete your account.

No Account Error

422

When a user does not have an account, a 422 response code will be returned. The response body will contain an error message and a link to the documentation.

Example error

{
    "message": "You need to create an account first",
    "documentation_url": "https://docs.mikrocloud.com/api/accounts#create-an-account"
}

Was this page helpful?