Storefront API Reference

Do you have a specific scenario you need to support or other questions?
Reach out to us through the support channel, or at developers@moonbase.sh.

If you are experiencing CORS issues trying to call Moonbase APIs from the browser, make sure you have whitelisted the URL of your storefront in your Moonbase account settings.

Identity

The storefront endpoints documented below are made to be called from customer facing storefronts, with the customer initiating any actions. Therefore, most of the endpoints are publicly available, only some requiring authentication in the form of JWT tokens. These JWT tokens can be obtained by authenticating the user through /api/customer/identity/sign-in, and the tokens refreshed by handing them in through /api/customer/identity/refresh.

In addition to providing authentication, the identity endpoints below can also be used to update customer details, request password resets and more.

POST/api/customer/identity/sign-in

This endpoint allows you to sign in a customer given a combination of email address and password. The JWT returned contains an access token with a default lifetime of 15 minutes. Refresh tokens can be used to get new access tokens.

Required query parameters

Name
email
Type
string
Description
The email of the customer.

Required body content

The password of the customer.

Request

POST

/api/customer/identity/sign-in

POST https://demo.moonbase.sh/api/customer/identity/sign-in?email=user@example.com
Content-Type: text/plain

Password1234!

Response

{
    "id": "e891f4b0-6d73-48ed-8fc1-c6b166c5379a",
    "name": "Example User",
    "email": "user@example.com",
    "tenantId": "demo",
    "userType": "Customer",
    "accessToken": "eyJhbGciOiJIUzUxMiIsInR5c...",
    "refreshToken": "MDAxNDhiZGUtMzY1Yi00MTYx..."
}

POST/api/customer/identity/refresh

Refresh a token

This endpoint allows you to exchange a refresh token + access token for a new pair of tokens.

Required query parameters

Name
token
Type
string
Description
The refresh token you got during the last refresh or sign-in if first time refreshing.

Required body content

The access token belonging to the refresh token.

Request

POST

/api/customer/identity/refresh

POST https://demo.moonbase.sh/api/customer/identity/refresh?token=MDAxNDhiZGUtMzY1Yi00MTYx...
Content-Type: text/plain

eyJhbGciOiJIUzUxMiIsInR5c...

Response

{
    "id": "e891f4b0-6d73-48ed-8fc1-c6b166c5379a",
    "name": "Example User",
    "email": "user@example.com",
    "tenantId": "demo",
    "userType": "Customer",
    "accessToken": "eyJhbGciOiJIUzUxMiIsInR5c...",
    "refreshToken": "MDAxNDhiZGUtMzY1Yi00MTYx..."
}

POST/api/customer/identity/sign-up

This endpoint allows you to sign up a new customer on your account.

Required body properties

Name
name
Type
string
Description
Full name of the user.
Name
email
Type
string
Description
Email address of the user. Will be used as username. Can be changed by the user.
Name
password
Type
string
Description
The initial password for the user. Must contain lower case characters, uppercase characters, numbers and a symbol.

Optional body properties

Name
address
Type
object
Description
A billing address for the user. Will be used when purchasing new products.
Contains the following properties:
- Name
  countryCode
  Type
  string
  Description
  ISO 3166-1 alpha-2 two-letter country code.
- Name
  streetAddress1
  Type
  string
  Description
  First line of the regular street address.
- Name
  streetAddress2
  Type
  string
  Optionality
  optional
  Description
  Second line of the regular street address.
- Name
  postCode
  Type
  string
  Description
  Postal code of the address.
- Name
  locality
  Type
  string
  Description
  Locality of the address, only required if no region is given.
  Also known as City.
- Name
  region
  Type
  string
  Description
  Region of the address, only required if no locality is given.
  Also known as State.

Optional query parameters

Name
communicationOptIn
Type
boolean
Description
Set this parameter to true if the customer has opted in to marketing communications.
It will be propagated to any marketing tools you may have integrated with your Moonbase account.

Request

POST

/api/customer/identity/sign-up

POST https://demo.moonbase.sh/api/customer/identity/sign-up
Content-Type: application/json

{
    "name": "Example User",
    "email": "user@example.com",
    "password": "Password1234!",
    "address": {
        "countryCode": "NO",
        "streetAddress1": "Slottsplassen 1",
        "streetAddress2": null,
        "postCode": "0010",
        "region": "Oslo",
        "locality": null
    }
}

Response

{
    "id": "e891f4b0-6d73-48ed-8fc1-c6b166c5379a",
    "name": "Example User",
    "email": "user@example.com",
    "tenantId": "demo",
    "userType": "Customer",
    "accessToken": "eyJhbGciOiJIUzUxMiIsInR5c...",
    "refreshToken": "MDAxNDhiZGUtMzY1Yi00MTYx..."
}

PATCH Authenticated/api/customer/identity

Update

This endpoint allows you to update a customers details like name, email and communication preferences. Note that all root properties are optional, and only the defined ones will be updated.

Required headers

Name
Authorization
Type
string
Description
Access token for the authenticated customer in your app, in the form of a JWT bearer token.

Optional body properties

Name
name
Type
string
Description
New full name of the user.
Name
email
Type
string
Description
New email address of the user. Will be used as the new username.
Name
address
Type
object
Description
A billing address for the user. Will be used when purchasing new products.
Contains the following properties:
- Name
  countryCode
  Type
  string
  Description
  ISO 3166-1 alpha-2 two-letter country code.
- Name
  streetAddress1
  Type
  string
  Description
  First line of the regular street address.
- Name
  streetAddress2
  Type
  string
  Optionality
  optional
  Description
  Second line of the regular street address.
- Name
  postCode
  Type
  string
  Description
  Postal code of the address.
- Name
  locality
  Type
  string
  Description
  Locality of the address, only required if no region is given.
  Also known as City.
- Name
  region
  Type
  string
  Description
  Region of the address, only required if no locality is given.
  Also known as State.
Name
communicationPreferences
Type
object
Description
The new communication preferences for the customer.
- Name
  newsletterOptIn
  Type
  boolean
  Description
  Flag for whether or not the customer has opted in for newsletters

Request

PATCH

/api/customer/identity

PATCH https://demo.moonbase.sh/api/customer/identity
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJuYW1laWQiOiJiY...

{
    "name": "Example User",
    "communicationPreferences": {
        "newsletterOptIn": true
    }
}

Response

{
    "id": "e891f4b0-6d73-48ed-8fc1-c6b166c5379a",
    "name": "Example User",
    "email": "user@example.com",
    "tenantId": "demo",
    "userType": "Customer",
    "accessToken": "eyJhbGciOiJIUzUxMiIsInR5c...",
    "refreshToken": "MDAxNDhiZGUtMzY1Yi00MTYx..."
}

POST Authenticated/api/customer/identity/set-password

Set password

Can be used to update the password of an existing customer. Returns a 200 OK on success with no body content.

Required headers

Name
Authorization
Type
string
Description
Access token for the authenticated customer in your app, in the form of a JWT bearer token.

Required body properties

Name
currentPassword
Type
string
Description
The current password of the user.
Name
newPassword
Type
string
Description
New password for the user. Must meet all password requirements.

Request

POST

/api/customer/identity/set-password

POST https://demo.moonbase.sh/api/customer/identity/set-password
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJuYW1laWQiOiJiY...

{
    "currentPassword": "OldPassword99#",
    "newPassword": "NewPassword042!?"
}

POST/api/customer/identity/forgot-password

Forgot password

If a customer has forgotten their password, call this endpoint to send them a password reset email. No authentication is required to call this endpoint.

Required query parameters

Name
email
Type
string
Description
The email of the user for which to send a reset email.

Request

POST

/api/customer/identity/forgot-password

POST https://demo.moonbase.sh/api/customer/identity/forgot-password?email=user@example.com

POST/api/customer/identity/reset-password

Reset password

Once a user has requested a password reset, they will be linked to the configured website of your account with a code to reset the password. This code needs to be handed to this endpoint along with a new password for the user.

Required query parameters

Name
email
Type
string
Description
The email of the user to reset password for.
Name
code
Type
string
Description
The code coming from the password reset email.

Required body content

The new password for the user.

Request

POST

/api/customer/identity/reset-password

POST https://demo.moonbase.sh/api/customer/identity/reset-password?email=user@example.com&code=ey9xsal41x...
Content-Type: text/plain

NewPassword042!?

Storefront Products & Bundles

To get all products and bundles that are purchasable from your Moonbase account, this endpoint can be used. The returned items will have pricing evaluated on them based on any customer that might be authenticated, or other factors like tracking parameters. It is intended to be used when rendering your storefront when you need to reason about current prices and variations.

GET/api/customer/storefront

Get storefront

Fetches all products and bundles, along with a suggested currency to use based on customer geo location. Since some discounts might be time limited, the response also includes a nullable validUntil ISO-8601 date and time that can be considered as the point where any caching of this storefront should be invalidated.

Optional headers

Name
Authorization
Type
string
Description
Access token for the authenticated customer in your app, in the form of a JWT bearer token. If this is not included, pricing will not consider any personalized pricing for the authenticated customer.

Optional query parameters

Since discounts might target specific UTM campaign trackers, this endpoint can take in any UTM parameters that you might have captured on page load. To learn more about marketing tracking, check out our marketing revenue tracking page. All of the below parameters are therefore optional.

Name
utm_source
Type
string
Description
The source site or channel of the campaign.
Name
utm_medium
Type
string
Description
The type of link used, like ad or email CTAs.
Name
utm_campaign
Type
string
Description
An identifier for the specific campaign.
Name
utm_term
Type
string
Description
Search terms used by the customer to find the campaign.
Name
utm_content
Type
string
Description
Description of what brought the customer to the site originally.
Name
utm_referrer
Type
string
Description
The referrer that brought the customer to the site originally.

Request

GET

/api/customer/storefront

GET https://demo.moonbase.sh/api/customer/storefront?utm_source=moonbase.sh
Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJuYW1laWQiOiJiY...

Response

{
    "suggestedCurrency": "EUR",
    "validUntil": null,
    "bundles": [ ... ],
    "products": [ ... ]
}

Products

The storefront product payload contains everything you should need to build rich storefronts.

Name
id
Type
string
Description
The Moonbase ID of the product.
Name
name
Type
string
Description
The name of the product as configured in Moonbase.
Name
tagline
Type
string
Description
The tagline of the product as configured in Moonbase.
Name
website
Type
string
Description
The website URL of the product as configured in Moonbase.
Name
iconUrl
Type
string
Nullability
nullable
Description
URL to the Moonbase hosted icon for the product.
Name
owned
Type
boolean
Description
Flag indicating if the authenticated customer owns the product or not.
Name
currentVersion
Type
string
Optionality
optional
Description
The currently released version of the product.
Name
downloads
Type
array
Optionality
optional
Description
A list of the downloads belonging to the currently released version of the product.
- Name
  name
  Type
  string
  Description
  File name of the downloadable file.
- Name
  key
  Type
  string
  Description
  Unique key to identify the asset.
- Name
  platform
  Type
  enum(Windows|Mac|Linux|Universal)
  Description
  The target platform for the downloadable asset.
- Name
  size
  Type
  number
  Description
  Size of the asset in bytes.
- Name
  path
  Type
  string
  Description
  URL to download the asset. Note that this might not be publically available depending on the security configuration you have set in Moonbase.
Name
defaultVariation
Type
object
Optionality
optional
Description
The default pricing variation for the product. See the below variations schema for examples of this structure.
Name
variations
Type
array
Optionality
optional
Description
A collection of available pricing variations for this product.
- Name
  id
  Type
  string
  Description
  Unique identifier for this variation.
- Name
  name
  Type
  string
  Description
  Name of the variation.
- Name
  originalPrice
  Type
  record<currency, number>
  Description
  The original price of this variation.
- Name
  price
  Type
  record<currency, number>
  Description
  The current price of this variation after discounts have been applied.
- Name
  hasDiscount
  Type
  boolean
  Description
  Flag for if there has been any discounts applied to the variation.
- Name
  discount
  Type
  object
  Optionality
  optional
  Description
  The discount that has been applied to the variation. Note that this can be one of two types of discount, discriminated based on the type property:
  Flat amount off discount
  
  Name
  type
  Type
  'FlatAmountOffDiscount'
  Description
  Discount type discriminator.
  Name
  name
  Type
  string
  Description
  Name of the discount.
  Name
  description
  Type
  string
  Optionality
  optional
  Description
  Description of the discount.
  Name
  total
  Type
  record<currency, number>
  Description
  The total amount of money that has been discounted from the variation.
  Percentage off discount
  
  Name
  type
  Type
  'PercentageOffDiscount'
  Description
  Discount type discriminator.
  Name
  name
  Type
  string
  Description
  Name of the discount.
  Name
  description
  Type
  string
  Optionality
  optional
  Description
  Description of the discount.
  Name
  percentage
  Type
  number
  Description
  The percentage that the discount discounts, normalized to between 0 and 1.
  Name
  total
  Type
  record<currency, number>
  Description
  The total amount of money that has been discounted from the variation.

Product example

{
    "id": "demo-product",
    "name": "Demo Product",
    "tagline": "This product is used for demo purposes",
    "website": null,
    "iconUrl": "https://assets.moonbase.sh/demo/products/demo-product/icon/...",
    "owned": true,
    "currentVersion": "1.0.4",
    "downloads": [
        {
            "name": "Example App.pkg",
            "key": "4dc59922-5476-41aa-a600-2c5e4b9086d5",
            "platform": "Mac",
            "size": 143112160,
            "path": "https://demo.moonbase.sh/api/customer/inventory/products/demo-product/download/1.0.4/4dc59922-5476-41aa-a600-2c5e4b9086d5"
        },
        {
            "name": "Example App.exe",
            "key": "1c950e85-07c8-40c2-aead-8fb91ceb0623",
            "platform": "Windows",
            "size": 149396521,
            "path": "https://demo.moonbase.sh/api/customer/inventory/products/demo-product/download/1.0.4/1c950e85-07c8-40c2-aead-8fb91ceb0623"
        }
    ],
    "defaultVariation": { ... },
    "variations": [
        {
            "id": "default",
            "name": "Default",
            "originalPrice": {
                "EUR": 69
            },
            "price": {
                "EUR": 62.1
            },
            "hasDiscount": true,
            "discount": {
                "type": "PercentageOffDiscount",
                "name": "10% off",
                "total": {
                    "EUR": 6.9
                },
                "percentage": 0.1,
                "isExclusive": false
            }
        }
    ]
}

Bundles

The storefront bundle payload is very similar to the product schema, with the following key differences:

Name
partial
Type
boolean
Description
Flag indicating if the bundle will be a partial purchase. If true, each product in the products array will also have a included flag to indicate whether or not they are included in the bundle. Bundles are partial if they have partial purchases enabled in your Moonbase account, and if the authenticated customer already owns some of the products in the bundle.
Name
products
Type
array
Description
Array of products that the bundle contains. See the above products schema for more details on the shape of these objects.

Bundle example

{
    "id": "demo-bundle",
    "name": "Demo Bundle",
    "tagline": "This bundle is used for demo purposes",
    "iconUrl": "https://assets.moonbase.sh/demo/bundles/demo-bundle/icon/...",
    "owned": true,
    "partial": false,
    "products": [ ... ],
    "defaultVariation": {
        "id": "default",
        "name": "Lifetime pass",
        "originalPrice": {
            "EUR": 599
        },
        "price": {
            "EUR": 599
        },
        "hasDiscount": false
    },
    "variations": [
        {
            "id": "default",
            "name": "Lifetime pass",
            "originalPrice": {
                "EUR": 599
            },
            "price": {
                "EUR": 599
            },
            "hasDiscount": false
            }
        ]
    }

Orders

Orders in Moonbase are the main vehicle for performing purchases, and can be considered a "cart" before completely paid. As customers shop, you can push products and bundles to the order, and then redirect the customer to the checkout URL to finish their purchase.

Name
id
Type
string
Description
Unique identifier of the order.
Name
status
Type
enum(Open|Completed)
Description
The current status of the order, Open if still shopping, Completed if paid and fulfilled.
Name
currency
Type
string
Description
The currency used for this order. This should be used when rendering cart contents to make sure what you display on the storefront is the same as during checkout.
Name
items
Type
array
Description
Collection of items part of the order. Note that this can be either products or bundles, and they are discriminated using the type property.
- Name
  type
  Type
  'Product'
  Description
  Discount type discriminator.
- Name
  productId
  Type
  string
  Description
  The unique ID of the product.
- Name
  variationId
  Type
  string
  Description
  The unique ID of the pricing variation selected.
- Name
  quantity
  Type
  number
  Description
  Quantity of this item.
- Name
  type
  Type
  'Bundle'
  Description
  Discount type discriminator.
- Name
  bundleId
  Type
  string
  Description
  The unique ID of the bundle.
- Name
  variationId
  Type
  string
  Description
  The unique ID of the pricing variation selected.
- Name
  quantity
  Type
  number
  Description
  Quantity of this item.
Name
checkoutUrl
Type
string
Optionality
optional
Description
URL to pay for the order. This property is only present when specifically requesting a checkout URL while pushing content.

Order example

{
    "id": "5d3a2c26-d09f-45b3-b018-3461c20efc23",
    "status": "Open",
    "currency": "EUR",
    "items": [
        {
            "type": "Product",
            "productId": "demo-app",
            "variationId": "v802c5",
            "quantity": 1,
        }
    ]
}

GET/api/customer/orders/{orderId}

Get order

Fetches a single order based in its unique ID. The returned order might still be open for modification, but it might also be completed, in which case no further modifications can be done to the order. When building storefronts, this is usually an indication that the cart is no longer necessary and can be reset with a new order ID.

Optional headers

Name
Authorization
Type
string
Description
Access token for the authenticated customer in your app, in the form of a JWT bearer token. If you have an authenticated user, sending this token will automatically attribute the order to that customer, streamlining the checkout process by pre-filling name, address, and business details.

Request

GET

/api/customer/orders/{orderId}

GET https://demo.moonbase.sh/api/customer/orders/5d3a2c26-d09f-45b3-b018-3461c20efc23
Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJuYW1laWQiOiJiY...

Response

{
    "id": "5d3a2c26-d09f-45b3-b018-3461c20efc23",
    "status": "Open",
    "currency": "EUR",
    "items": [ ... ]
}

PATCH/api/customer/orders/{orderId}

Update

You can update order content as long as it has not yet been paid for. This is a partial update, which means you can opt to only update part of the order.

Optional headers

Name
Authorization
Type
string
Description
Access token for the authenticated customer in your app, in the form of a JWT bearer token. If you have an authenticated user, sending this token will automatically attribute the order to that customer, streamlining the checkout process by pre-filling name, address, and business details.

Optional query parameters

Name
checkout
Type
boolean
Description
Flag for if a checkout URL should be generated in the response. Typically you set this true for the last push before a redirect to the checkout page.
Name
returnUrl
Type
string
Description
If using the checkout parameter, you may also pass a return URL for where the customer should get redirected after a successful purchase.

Additionally, since discounts might target specific UTM campaign trackers, this endpoint can take in any UTM parameters that you might have captured on page load. To learn more about marketing tracking, check out our marketing revenue tracking page. This endpoint will store the given UTM parameters on order so that you can correctly track marketing campaign revenue.

Name
utm_source
Type
string
Description
The source site or channel of the campaign.
Name
utm_medium
Type
string
Description
The type of link used, like ad or email CTAs.
Name
utm_campaign
Type
string
Description
An identifier for the specific campaign.
Name
utm_term
Type
string
Description
Search terms used by the customer to find the campaign.
Name
utm_content
Type
string
Description
Description of what brought the customer to the site originally.
Name
utm_referrer
Type
string
Description
The referrer that brought the customer to the site originally.

Optional body properties

Name
currency
Type
string
Description
Desired currency to use for the order.
Name
items
Type
array
Description
A list of items in the cart, either products or bundles. The schema of these is the same as described above.

Request

PATCH

/api/customer/orders/{orderId}

PATCH https://demo.moonbase.sh/api/customer/orders/5d3a2c26-d09f-45b3-b018-3461c20efc23
Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJuYW1laWQiOiJiY...
Content-Type: application/json

{
    "currency": "EUR",
    "items": [
        {
            "type": "Product",
            "productId": "demo-app",
            "variationId": "v802c5",
            "quantity": 1
        }
    ]
}

Response

{
    "id": "5d3a2c26-d09f-45b3-b018-3461c20efc23",
    "status": "Open",
    "currency": "EUR",
    "items": [ ... ]
}

Vouchers

Vouchers are one-time-use codes used to redeem licenses to products and bundles. These are usually distributed through 3rd party channels, or given as part of marketing campaigns.

Name
id
Type
string
Description
Unique identifier of the voucher.
Name
name
Type
string
Description
Name of the voucher.
Name
description
Type
string
Description
Description of the voucher.
Name
code
Type
string
Description
The code used to redeem the voucher.
Name
redeemed
Type
boolean
Description
Flag for if the voucher has been redeemed yet or not.
Name
redeemsProducts
Type
array
Description
List of products that this voucher redeems, wrapped in a quantity/value object.
- Name
  quantity
  Type
  number
  Description
  The number of licenses for the above product being granted.
- Name
  value
  Type
  object
  Description
  The product being granted. This object is the same shape as the storefront product described above.
Name
redeemsBundles
Type
array
Description
List of bundles that this voucher redeems, wrapped in a value/quantity object.
- Name
  quantity
  Type
  number
  Description
  The number of licenses for the above bundle being granted.
- Name
  value
  Type
  object
  Description
  The bundle being granted. This object is the same shape as the storefront bundle described above.

Voucher example

{
    "id": "58927685-61ad-4caa-ad6f-8613d7200d4f",
    "name": "Demo voucher",
    "description": "Used for demo purposes",
    "code": "001DC49B-37FB-40D7-AB4C-8E68C6E9093C",
    "redeemed": true,
    "redeemsProducts": [
        {
            "quantity": 1,
            "value": {
                "id": "demo-app",
                "name": "Demo App",
                "tagline": "Product used for demoing Moonbase features",
                "website": null,
                "iconUrl": "https://assets.moonbase.sh/demo/products/demo-app/icon/...",
                "currentVersion": "1.0.0"
            }
        }
    ],
    "redeemsBundles": [...]
}

GET/api/customer/vouchers

Peek

If you want to preview what a code redeems, you can peek the contents of a voucher. This can be done without any authenticated user, and performs no changes to the voucher itself. Will return a 403: Forbidden if the voucher has been redeemed by someone else than the current authenticated user.

Optional headers

Name
Authorization
Type
string
Description
Access token for the authenticated customer in your app, in the form of a JWT bearer token. If you have an authenticated user, sending this token will allow you to also peek vouchers redeemed by the authenticated user.

Required query parameters

Name
code
Type
string
Description
The voucher code being redeemed.

Request

GET

/api/customer/vouchers

GET https://demo.moonbase.sh/api/customer/vouchers?code=001DC49B-37FB-40D7-AB4C-8E68C6E9093C
Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJuYW1laWQiOiJiY...

Response

{
    "id": "58927685-61ad-4caa-ad6f-8613d7200d4f",
    "name": "Demo voucher",
    "description": "Used for demo purposes",
    "code": "001DC49B-37FB-40D7-AB4C-8E68C6E9093C",
    "redeemed": true,
    "redeemsProducts": [ ... ],
    "redeemsBundles": [...]
}

POST Authenticated/api/customer/vouchers/redeem

Redeem

To redeem a code and issue the licenses to the currently authenticated user, call this endpoint.

Required headers

Name
Authorization
Type
string
Description
Access token for the authenticated customer in your app, in the form of a JWT bearer token.

Required query parameters

Name
code
Type
string
Description
The voucher code being redeemed.

Request

POST

/api/customer/vouchers/redeem

POST https://demo.moonbase.sh/api/customer/vouchers/redeem?code=001DC49B-37FB-40D7-AB4C-8E68C6E9093C
Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJuYW1laWQiOiJiY...

Response

{
    "id": "58927685-61ad-4caa-ad6f-8613d7200d4f",
    "name": "Demo voucher",
    "description": "Used for demo purposes",
    "code": "001DC49B-37FB-40D7-AB4C-8E68C6E9093C",
    "redeemed": true,
    "redeemsProducts": [ ... ],
    "redeemsBundles": [...]
}

Inventory

To fetch details about what products a customer owns, and their relevant licenses and license activations, you can use our inventory endpoints. All of the below endpoints expect an authenticated customer, and will implicitly return their owned products and licenses.

By no means do you have to utilize all of these endpoints to build your storefronts; they are merely made to offer flexibility in how you render customer inventory.

Unlike the other endpoints for your storefront, these endpoints have the potential to return a large amount of data in the rare case customers may own many licenses and products. That's why many endpoints here return paginated responses, which allows for user-controlled pagination of results.

Pagination

Paginated response are wrapped in a page object:

Name
items
Type
array
Description
The items contain object of the type that is expected of the particular endpoint.
Name
hasMore
Type
boolean
Description
Flag for if there are any more results to be fetched.
Name
next
Type
string
Nullability
nullable
Description
Null if no more items to be fetched, otherwise a path to fetch the next page of results.

Response

{
    "items": [...],
    "hasMore": true,
    "next": "/api/customer/inventory/..."
}

GET Authenticated/api/customer/inventory/products

Get owned products

Gets all owned products

Required headers

Name
Authorization
Type
string
Description
Access token for the authenticated customer in your app, in the form of a JWT bearer token.

Response content

The response body will contain a paginated list of products with ownership details. See above for details on the pagination wrapper, the inner product objects has the following schema:

Name
id
Type
string
Description
The Moonbase ID of the product.
Name
name
Type
string
Description
The name of the product as configured in Moonbase.
Name
tagline
Type
string
Description
The tagline of the product as configured in Moonbase.
Name
website
Type
string
Optionality
optional
Description
The website URL of the product as configured in Moonbase.
Name
iconUrl
Type
string
Optionality
optional
Description
URL to the Moonbase hosted icon for the product.
Name
currentVersion
Type
string
Optionality
optional
Description
The currently released version of the product.
Name
numberOfLicenses
Type
number
Description
Number of licenses the current customer owns.
Name
numberOfTrials
Type
number
Description
Number of trials the current customer has started.
Name
currentActivations
Type
number
Description
Number of license activations the current user has active.
Name
maxActivations
Type
number
Description
Max number of possible license activations the current user can perform.
Name
downloadsNeedsUser
Type
boolean
Description
Flag for if the products needs an authenticated user to download.
Name
downloadsNeedsOwnership
Type
boolean
Description
Flag for if the products needs an authenticated owner to download.
Name
downloads
Type
array
Optionality
optional
Description
A list of the downloads belonging to the currently released version of the product.
- Name
  name
  Type
  string
  Description
  File name of the downloadable file.
- Name
  key
  Type
  string
  Description
  Unique key to identify the asset.
- Name
  platform
  Type
  enum(Windows|Mac|Linux|Universal)
  Description
  The target platform for the downloadable asset.
- Name
  size
  Type
  number
  Description
  Size of the asset in bytes.
- Name
  path
  Type
  string
  Description
  URL to download the asset. Note that this might not be publically available depending on the security configuration you have set in Moonbase.

Request

GET

/api/customer/inventory/products

GET https://demo.moonbase.sh/api/customer/inventory/products
Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJuYW1laWQiOiJiY...

Response

{
    "items": [
        {
            "id": "demo-product",
            "name": "Demo Product",
            "tagline": "This product is used for demo purposes",
            "iconUrl": "https://assets.moonbase.sh/demo/products/demo-product/icon/...",
            "currentVersion": "1.0.0",
            "numberOfLicenses": 7,
            "numberOfTrials": 0,
            "currentActivations": 1,
            "maxActivations": 7,
            "downloadsNeedsUser": false,
            "downloadsNeedsOwnership": false,
            "downloads": [
                {
                    "name": "Example App.pkg",
                    "key": "4dc59922-5476-41aa-a600-2c5e4b9086d5",
                    "platform": "Mac",
                    "size": 143112160,
                    "path": "https://demo.moonbase.sh/api/customer/inventory/products/demo-product/download/1.0.4/4dc59922-5476-41aa-a600-2c5e4b9086d5"
                },
                {
                    "name": "Example App.exe",
                    "key": "1c950e85-07c8-40c2-aead-8fb91ceb0623",
                    "platform": "Windows",
                    "size": 149396521,
                    "path": "https://demo.moonbase.sh/api/customer/inventory/products/demo-product/download/1.0.4/1c950e85-07c8-40c2-aead-8fb91ceb0623"
                }
            ]
        }
    ],
    "hasMore": false,
    "next": null
}

GET Authenticated/api/customer/inventory/products/{productId}/licenses

Get licenses for product

Gets all licenses for a given product.

Required headers

Name
Authorization
Type
string
Description
Access token for the authenticated customer in your app, in the form of a JWT bearer token.

Response content

The response body will contain a paginated list of licenses with ownership details. See above for details on the pagination wrapper, the inner license objects has the following schema:

Name
id
Type
string
Description
The Moonbase ID of the license.
Name
product
Type
object
Description
The product that the license belongs to. See the above endpoint for object schema.
Name
activeNumberOfActivations
Type
number
Description
Number of active activations that the license has.
Name
maxNumberOfActivations
Type
number
Description
Max number of possible license activations the license allows.
Name
createdAt
Type
datetime
Description
ISO-8601 date and time for when the license was created.

Request

GET

/.../inventory/products/{productId}/licenses

GET https://demo.moonbase.sh/api/customer/inventory/products/demo-product/licenses
Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJuYW1laWQiOiJiY...

Response

{
    "items": [
        {
            "id": "b8ce5f27-cd8d-4165-abce-6398b09ca6ec",
            "product": { ... },
            "activeNumberOfActivations": 1,
            "maxNumberOfActivations": 1,
            "createdAt": "2024-07-11T01:44:49.7269357Z"
        }
    ],
    "hasMore": false,
    "next": null
}

GET Authenticated/api/customer/inventory/products/{productId}/licenses/activations

Get activations for product

Gets all license activations for a given product.

Required headers

Name
Authorization
Type
string
Description
Access token for the authenticated customer in your app, in the form of a JWT bearer token.

Response content

The response body will contain a paginated list of license activations for a product. See above for details on the pagination wrapper, the inner license activation objects has the following schema:

Name
id
Type
string
Description
The Moonbase ID of the license activation.
Name
licenseId
Type
string
Description
The Moonbase ID of the license.
Name
name
Type
string
Description
Name of the device activated.
Name
activationMethod
Type
enum(Online|Offline)
Description
Enum that indicates in what way the device was activated.
Name
lastValidatedAt
Type
datetime
Description
ISO-8601 date and time for when the activation was last validated.

Request

GET

../products/{productId}/licenses/activations

GET https://demo.moonbase.sh/api/customer/inventory/products/demo-product/licenses/activations
Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJuYW1laWQiOiJiY...

Response

{
    "items": [
        {
            "id": "d7b6b018e39d2734b8d8d4415b00abff",
            "licenseId": "b8ce5f27-cd8d-4165-abce-6398b09ca6ec",
            "name": "demo-device",
            "activationMethod": "Online",
            "lastValidatedAt": "2024-07-27T07:06:24.2066639Z"
        }
    ],
    "hasMore": false,
    "next": null
}

GET Authenticated/api/customer/inventory/licenses

Get owned licenses

Gets all owned licenses.

Required headers

Name
Authorization
Type
string
Description
Access token for the authenticated customer in your app, in the form of a JWT bearer token.

Response content

The response body will contain a paginated list of licenses with ownership details. See above for details on the pagination wrapper, the inner license objects has the following schema:

Name
id
Type
string
Description
The Moonbase ID of the license.
Name
product
Type
object
Description
The product that the license belongs to. See the above endpoint for object schema.
Name
activeNumberOfActivations
Type
number
Description
Number of active activations that the license has.
Name
maxNumberOfActivations
Type
number
Description
Max number of possible license activations the license allows.
Name
createdAt
Type
datetime
Description
ISO-8601 date and time for when the license was created.

Request

GET

/api/customer/inventory/licenses

GET https://demo.moonbase.sh/api/customer/inventory/licenses
Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJuYW1laWQiOiJiY...

Response

{
    "items": [
        {
            "id": "b8ce5f27-cd8d-4165-abce-6398b09ca6ec",
            "product": { ... },
            "activeNumberOfActivations": 1,
            "maxNumberOfActivations": 1,
            "createdAt": "2024-07-11T01:44:49.7269357Z"
        }
    ],
    "hasMore": false,
    "next": null
}

GET Authenticated/api/customer/inventory/licenses/{licenseId}/activations

Get activations for license

Gets all license activations for a given license.

Required headers

Name
Authorization
Type
string
Description
Access token for the authenticated customer in your app, in the form of a JWT bearer token.

Response content

The response body will contain a paginated list of license activations for a license. See above for details on the pagination wrapper, the inner license activation objects has the following schema:

Name
id
Type
string
Description
The Moonbase ID of the license activation.
Name
licenseId
Type
string
Description
The Moonbase ID of the license.
Name
name
Type
string
Description
Name of the device activated.
Name
activationMethod
Type
enum(Online|Offline)
Description
Enum that indicates in what way the device was activated.
Name
lastValidatedAt
Type
datetime
Description
ISO-8601 date and time for when the activation was last validated.

Request

GET

../inventory/licenses/{licenseId}/activations

GET https://demo.moonbase.sh/api/customer/inventory/licenses/b8ce5f27-cd8d-4165-abce-6398b09ca6ec/activations
Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJuYW1laWQiOiJiY...

Response

{
    "items": [
        {
            "id": "d7b6b018e39d2734b8d8d4415b00abff",
            "licenseId": "b8ce5f27-cd8d-4165-abce-6398b09ca6ec",
            "name": "demo-device",
            "activationMethod": "Online",
            "lastValidatedAt": "2024-07-27T07:06:24.2066639Z"
        }
    ],
    "hasMore": false,
    "next": null
}

POST Authenticated/api/customer/inventory/licenses/{licenseId}/activations/{activationId}/revoke

Revoke license activation

Lets a customer revoke a license activation from one of their licenses. Note that this might not always be possible due to activation method or Moonbase configuration.

Required headers

Name
Authorization
Type
string
Description
Access token for the authenticated customer in your app, in the form of a JWT bearer token.

Request

POST

../{licenseId}/activations/{activationId}/revoke

POST https://demo.moonbase.sh/api/customer/inventory/licenses/b8ce5f27-cd8d-4165-abce-6398b09ca6ec/activations/d7b6b018e39d2734b8d8d4415b00abff/revoke
Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJuYW1laWQiOiJiY...

Storefront API Reference

Required query parameters

Required body content

Request

Response

Required query parameters

Required body content

Request

Response

Required body properties

Optional body properties

Optional query parameters

Request

Response

Required headers

Optional body properties

Request

Response

Required headers

Required body properties

Request

Required query parameters

Request

Required query parameters

Required body content

Request

Optional headers

Optional query parameters

Request

Response

Products

Flat amount off discount

Percentage off discount

Product example

Bundles

Bundle example

Product line item

Bundle line item

Order example

Optional headers

Request

Response

Optional headers

Optional query parameters

Optional body properties

Request

Response

Voucher example

Optional headers

Required query parameters

Request

Response

Required headers

Required query parameters

Request

Response

Pagination

Response

Required headers

Response content

Request

Response

Required headers

Response content

Request

Response

Required headers

Response content

Request

Response

Required headers

Response content

Request

Response

Required headers

Response content

Request

Response

Required headers

Request