Log in
Sign up
Docs

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

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.

If your Moonbase account has the Require confirmed email to sign in feature enabled and the customer has not yet confirmed their email address, this endpoint returns 403 Forbidden with a problem detail of Email not confirmed. A confirmation email is sent as a side effect — customers should follow the link to confirm their account and then retry sign-in.

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

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..."
}
POST/api/customer/identity/confirm-account

Confirm account

Redeems the confirmation code that was emailed to a customer after sign-up, or as part of a deferred-takeover flow (for example, after the customer was first created as an accountless newsletter subscriber). On success, the response is identical in shape to a sign-in response — frontends should branch on the status field rather than checking whether tokens are present.

Required query parameters

  • Name
    email
    Type
    string
    Description

    The email of the customer that is confirming their account.

  • Name
    code
    Type
    string
    Description

    The confirmation code from the email link. Carries either an email-confirmation token or a pending-activation token — the endpoint figures out which.

Response statuses

  • Name
    SignedIn
    Description

    The customer's password was already set at sign-up and the confirmation click completed the takeover. The response carries accessToken and refreshToken — transition the user into the signed-in app shell.

  • Name
    PasswordSetupRequired
    Description

    The customer has no password yet. Show a password-setup screen and submit the new password using the resetPasswordToken from the response against /api/customer/identity/reset-password.

Request

POST
/api/customer/identity/confirm-account
POST https://demo.moonbase.sh/api/customer/identity/confirm-account?email=user@example.com&code=ey9xsal41x...

Response (SignedIn)

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

Response (PasswordSetupRequired)

{
    "id": "e891f4b0-6d73-48ed-8fc1-c6b166c5379a",
    "name": "Example User",
    "email": "user@example.com",
    "tenantId": "demo",
    "userType": "Customer",
    "status": "PasswordSetupRequired",
    "resetPasswordToken": "CfDJ8..."
}
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!?

Communications

The communications endpoints handle newsletter and product-update opt-ins for visitors who don't necessarily have a customer account yet — for example, a footer newsletter form on a marketing site. All endpoints in this group are anonymous: the management endpoints are authenticated by a long-lived unsubscribe token that Moonbase emails to the customer alongside every marketing message, not by a customer JWT.

POST/api/customer/communications/subscribe

Subscribe

Subscribes an email to the newsletter, product updates, or both. If the email is new, Moonbase sends a double-opt-in confirmation email and the response indicates confirmation_sent; if the email belongs to an existing customer with the right consents, the subscription is recorded directly and the response indicates subscribed.

At least one of newsletter or productUpdates must be true, otherwise the endpoint returns 400 Bad Request.

Required body properties

  • Name
    email
    Type
    string
    Description

    The email address being subscribed.

  • Name
    newsletter
    Type
    boolean
    Description

    Opt in to general newsletter communications.

  • Name
    productUpdates
    Type
    boolean
    Description

    Opt in to product update announcements.

Optional body properties

  • Name
    name
    Type
    string
    Optionality
    optional
    Description

    Display name for the subscriber, used in personalized emails.

Request

POST
/api/customer/communications/subscribe
POST https://demo.moonbase.sh/api/customer/communications/subscribe
Content-Type: application/json

{
    "email": "user@example.com",
    "name": "Example User",
    "newsletter": true,
    "productUpdates": false
}

Response

{
    "status": "confirmation_sent"
}
POST/api/customer/communications/confirm

Confirm subscription

Confirms a pending newsletter subscription using the token from the double-opt-in confirmation email. Returns 200 OK on success.

Required query parameters

  • Name
    email
    Type
    string
    Description

    The email of the subscriber being confirmed.

  • Name
    token
    Type
    string
    Description

    The confirmation token from the email link.

Request

POST
/api/customer/communications/confirm
POST https://demo.moonbase.sh/api/customer/communications/confirm?email=user@example.com&token=ey9xsal41x...
GET/api/customer/communications/preferences

Get preferences

Returns the current communication preferences for a subscriber, identified by the long-lived unsubscribe token included in every marketing email. Use this to back a "manage your preferences" page.

Required query parameters

  • Name
    email
    Type
    string
    Description

    The email of the subscriber.

  • Name
    token
    Type
    string
    Description

    The subscriber's unsubscribe token.

Request

GET
/api/customer/communications/preferences
GET https://demo.moonbase.sh/api/customer/communications/preferences?email=user@example.com&token=ey9xsal41x...

Response

{
    "email": "user@example.com",
    "name": "Example User",
    "newsletter": true,
    "productUpdates": false
}
POST/api/customer/communications/preferences

Update preferences

Applies an exact set of preferences for a subscriber, allowing them to drop newsletter while keeping product updates (or vice versa) — granular control that the all-off unsubscribe endpoint cannot express. Returns the updated preferences.

Required query parameters

  • Name
    email
    Type
    string
    Description

    The email of the subscriber.

  • Name
    token
    Type
    string
    Description

    The subscriber's unsubscribe token.

Required body properties

  • Name
    newsletter
    Type
    boolean
    Description

    Whether the subscriber wants to receive newsletters.

  • Name
    productUpdates
    Type
    boolean
    Description

    Whether the subscriber wants to receive product update announcements.

Request

POST
/api/customer/communications/preferences
POST https://demo.moonbase.sh/api/customer/communications/preferences?email=user@example.com&token=ey9xsal41x...
Content-Type: application/json

{
    "newsletter": false,
    "productUpdates": true
}

Response

{
    "email": "user@example.com",
    "name": "Example User",
    "newsletter": false,
    "productUpdates": true
}
POST/api/customer/communications/unsubscribe

Unsubscribe

Unsubscribes the subscriber from all marketing communications. This is the one-click "unsubscribe from everything" target for the footer of marketing emails. For granular preference management, use Update preferences instead.

Required query parameters

  • Name
    email
    Type
    string
    Description

    The email of the subscriber.

  • Name
    token
    Type
    string
    Description

    The subscriber's unsubscribe token.

Request

POST
/api/customer/communications/unsubscribe
POST https://demo.moonbase.sh/api/customer/communications/unsubscribe?email=user@example.com&token=ey9xsal41x...

Storefront

To get all products, bundles, offers, promotions and metadata for 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, bundles, offers and promotions, 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.

When tax estimation is enabled for your Moonbase account, the response also includes an estimatedTax object describing the tax rate that will be applied at checkout for the visitor's detected region — useful for surfacing "incl. VAT" prices on the storefront. The object contains:

  • Name
    rate
    Type
    number
    Description

    The decimal tax rate (for example, 0.25 for 25%).

  • Name
    mode
    Type
    enum(Exclusive|Inclusive)
    Description

    Whether the rate is added on top of the listed price (Exclusive) or already included in it (Inclusive).

  • Name
    countryCode
    Type
    string
    Description

    ISO 3166-1 alpha-2 country code the estimate is for.

  • Name
    region
    Type
    string
    Optionality
    optional
    Description

    Sub-national region code, when the rate varies within the country.

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",
    "enabledCurrencies": ["EUR", "USD"],
    "validUntil": null,
    "bundles": [ ... ],
    "products": [ ... ],
    "offers": [ ... ],
    "promotions": [ ... ],
    "estimatedTax": {
        "rate": 0.25,
        "mode": "Exclusive",
        "countryCode": "NO"
    }
}

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
    properties
    Type
    object
    Optionality
    optional
    Description

    Custom properties attached to this product that have been marked as public. Values are flattened to key-value pairs without the type wrapper. See the Core API documentation for more details on custom properties.

  • 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
      arch
      Type
      enum(Unknown|Universal|X86|X64|Arm|Arm64)
      Optionality
      optional
      Description

      CPU architecture for the downloadable asset. Present when the merchant has tagged the download with an architecture.

    • 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.

      When the price came from a sale you are running, both types also carry:

      • Name
        promotionId
        Type
        string
        Optionality
        optional
        Description

        The promotion that produced this price, matching the id of an entry in promotions. A variation only ever shows its single best discount, so this is the way to tell which items a promotion is actually pricing.

      • Name
        validFrom
        Type
        datetime
        Optionality
        optional
        Description

        ISO-8601 date and time for when the discount became valid.

      • Name
        validUntil
        Type
        datetime
        Optionality
        optional
        Description

        ISO-8601 date and time for when the discount stops being valid, useful for rendering a countdown.

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,
    "properties": {
        "category": "Audio Tools"
    },
    "currentVersion": "1.0.4",
    "downloads": [
        {
            "name": "Example App.pkg",
            "key": "4dc59922-5476-41aa-a600-2c5e4b9086d5",
            "platform": "Mac",
            "arch": "Arm64",
            "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",
            "arch": "X64",
            "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. Bundles also include a properties field for any public custom properties, just like products.

  • 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
    subscribed
    Type
    boolean
    Description

    Flag indicating whether the authenticated customer currently holds an active subscription that covers this bundle. Use this — instead of owned — to decide whether to show a "Manage subscription" affordance for recurring bundles.

  • 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,
    "subscribed": 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
            }
        ]
    }

Offers

Offers are conditional discounts that get attached to an order. An offer is scoped either to a single line item, where it discounts the product or bundle it targets, or to the cart, where it discounts the order as a whole. Item offers are picked by the customer, by passing the offer ID along when the target item is added to the cart. Cart offers apply themselves as soon as their condition holds, and drop off again if the cart falls back below it.

  • Name
    id
    Type
    string
    Description

    Unique ID of this offer. For an item offer, use this when adding the target product or bundle to cart. For a cart offer, use it as the offerId on the order.

  • Name
    scope
    Type
    enum(Item|Cart)
    Description

    What the discount applies to. Item discounts the targeted line item, Cart discounts the order as a whole. Every offer carries a scope, and the ones you created before cart offers existed report Item, which is how they have always behaved.

  • Name
    targets
    Type
    array
    Description

    The products and bundles this offer applies to, each paired with the pricing variations it is restricted to. A cart offer may have an empty list, in which case every line item in the order is discounted. A non-empty list on a cart offer narrows which lines are discounted, but the condition is still measured against the whole cart. Each entry has the following properties:

    • Name
      item
      Type
      object
      Description

      The target product or bundle, using the schema described above with an additional type property of Product or Bundle.

    • Name
      variations
      Type
      array
      Description

      List of relevant pricing variation IDs on the item for this offer. If the list is empty, then any variation is relevant.

  • Name
    condition
    Type
    object
    Description

    Offers depend on something being true about the cart. This is a discriminated object based on the type property, and can be one of two conditions:

    Cart contains items


    • Name
      type
      Type
      'CartContainsItems'
      Description

      Condition type discriminator.

    • Name
      minimumItems
      Type
      number
      Description

      Minimum number of items there should be in the cart for this condition to be true.

    • Name
      relevantItemVariations
      Type
      record<string, array>
      Description

      Map of items IDs to list of variation IDs that this condition will include in the count. Item IDs are prefixed with Product/ or Bundle/ to indicate what type of item it is. This map should be an exhaustive list of all relevant items & variations currently available in the storefront.

    Cart total


    • Name
      type
      Type
      'CartTotal'
      Description

      Condition type discriminator.

    • Name
      minimumTotal
      Type
      record<currency, number>
      Nullability
      nullable
      Description

      Lowest cart total this offer applies from, given in every enabled currency so you can tell the customer how much further they have to go.

    • Name
      maximumTotal
      Type
      record<currency, number>
      Nullability
      nullable
      Description

      Highest cart total this offer applies to, given in every enabled currency.

    The cart total is measured as every line's price less its product discount, times quantity. It is deliberately measured before offers and coupons, so redeeming a code can neither drop the cart under a threshold nor shrink what a cart offer is calculated on.

  • Name
    discount
    Type
    object
    Description

    Standard discount model, where the name and description are based on the configured Offer in Moonbase. You can safely apply this discount on top of the prices on items, to calculate final price if the offer is applied to the item.

    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 offer.

    • Name
      description
      Type
      string
      Optionality
      optional
      Description

      Description of the offer.

    Percentage off discount


    • Name
      type
      Type
      'PercentageOffDiscount'
      Description

      Discount type discriminator.

    • Name
      name
      Type
      string
      Description

      Name of the offer.

    • Name
      description
      Type
      string
      Optionality
      optional
      Description

      Description of the offer.

    • Name
      percentage
      Type
      number
      Description

      The percentage that the offer discounts, normalized to between 0 and 1.

    Both types carry the same set of shared properties:

    • Name
      isExclusive
      Type
      boolean
      Description

      Whether this discount replaces any other discount on the item instead of stacking on top of it.

    • Name
      total
      Type
      record<currency, number>
      Optionality
      optional
      Description

      The amount taken off, given in every enabled currency. Always present on a flat amount off discount, and omitted on a percentage off discount that has no resolved amount yet.

    • Name
      recurringPaymentUseCount
      Type
      number
      Optionality
      optional
      Description

      Number of recurring payments the discount applies to before it expires, for subscription variations.

    • Name
      promotionId
      Type
      string
      Optionality
      optional
      Description

      Set when the discount comes from a promotion, matching the id of an entry in promotions. This is the authoritative signal for which promotion produced a price.

    • Name
      validFrom
      Type
      datetime
      Optionality
      optional
      Description

      ISO-8601 date and time for when the discount became valid.

    • Name
      validUntil
      Type
      datetime
      Optionality
      optional
      Description

      ISO-8601 date and time for when the discount stops being valid.

Cart offers always use a percentage off discount, and cannot be limited to a number of recurring payments.

Offer example

{
    "id": "07995551-5097-4ac8-a165-b9c0b44087ee",
    "scope": "Item",
    "targets": [
        {
            "item": { ... },
            "variations": ["perpetual", "subscription"]
        }
    ],
    "condition": {
        "type": "CartContainsItems",
        "minimumItems": 1,
        "relevantItemVariations": {
            "Product/example-product": [
                "perpetual",
                "subscription"
            ]
        }
    },
    "discount": {
        "type": "PercentageOffDiscount",
        "name": "Companion Product Promo",
        "description": "Also get Compation Product for a limited time only discount",
        "percentage": 0.25,
        "isExclusive": false
    }
}

Cart offer example

{
    "id": "1f4d6e88-2b31-4a0c-9d77-5c2f0a1b3e64",
    "scope": "Cart",
    "targets": [],
    "condition": {
        "type": "CartTotal",
        "minimumTotal": {
            "EUR": 100,
            "USD": 110
        },
        "maximumTotal": null
    },
    "discount": {
        "type": "PercentageOffDiscount",
        "name": "Spend more, save more",
        "description": "10% off when your order passes 100 euros",
        "percentage": 0.1,
        "isExclusive": false
    }
}

Promotions

Promotions are sales you coordinate across your catalogue from Moonbase, rather than something a customer opts into. A promotion discounts the products and bundles it targets, and those discounted prices are already reflected on the pricing variations returned above, so a storefront that renders discounts needs no extra work to run a sale. The promotions list exists so you can also present the sale itself, for example as a banner announcing it.

Only promotions that apply to this visitor right now are returned. The validity window, the audience restriction, and whether the promotion still has something purchasable to target are all evaluated before the response is sent, so never filter this list again on the client. The list changes when the customer signs in or out, since that changes who qualifies.

  • Name
    id
    Type
    string
    Description

    Unique ID of this promotion.

  • Name
    name
    Type
    string
    Description

    Name of the promotion, suitable as a heading.

  • Name
    description
    Type
    string
    Optionality
    optional
    Description

    Longer description of the promotion.

  • Name
    imageUrl
    Type
    string
    Optionality
    optional
    Description

    Artwork for the promotion, uploaded to Moonbase.

  • Name
    cta
    Type
    object
    Optionality
    optional
    Description

    Call to action for the promotion, where both properties are always present together:

    • Name
      url
      Type
      string
      Description

      Where the customer is sent when they act on the promotion.

    • Name
      label
      Type
      string
      Description

      The label to put on the call to action.

  • Name
    display
    Type
    array
    Description

    The surfaces you have asked this promotion to be shown on, any of Banner and Popup. An empty list means the promotion runs without being announced anywhere. Treat unrecognized values as surfaces you do not render.

  • Name
    targets
    Type
    array
    Description

    The products and bundles this promotion was aimed at. Each entry has the following properties:

    • Name
      referenceId
      Type
      string
      Description

      The targeted item, prefixed with Product/ or Bundle/ to indicate what type of item it is. Note that this differs from offers, where the whole product or bundle is embedded.

    • Name
      variations
      Type
      array
      Description

      List of pricing variation IDs on the item this promotion was aimed at. If the list is empty, then every variation was targeted.

  • Name
    discount
    Type
    object
    Description

    The discount this promotion applies, using the same discount model described under Offers above. Its promotionId matches this promotion's id.

  • Name
    validFrom
    Type
    datetime
    Optionality
    optional
    Description

    ISO-8601 date and time for when the promotion started. Omitted on a permanent promotion.

  • Name
    validUntil
    Type
    datetime
    Optionality
    optional
    Description

    ISO-8601 date and time for when the promotion ends. Omitted on a permanent promotion, and useful for rendering a countdown.

  • Name
    properties
    Type
    object
    Optionality
    optional
    Description

    Any custom properties configured on the promotion in Moonbase.

Take care with targets: it is what the promotion was aimed at, not what is actually showing the sale price. Each pricing variation only ever displays its single best discount, so a targeted item may well be showing a better one from elsewhere. To find out which items a promotion is really pricing, look for promotionId on the discount of a pricing variation.

Promotion example

{
    "id": "3f1b0c22-8a94-4d2e-b6f1-7c0e5a91d418",
    "name": "Summer Sale",
    "description": "20% off the whole catalogue until the end of August",
    "imageUrl": "https://assets.moonbase.sh/demo/promotions/summer-sale.png",
    "cta": {
        "url": "https://demo.moonbase.sh/summer",
        "label": "Shop the sale"
    },
    "display": ["Banner"],
    "targets": [
        {
            "referenceId": "Product/example-product",
            "variations": []
        }
    ],
    "discount": {
        "type": "PercentageOffDiscount",
        "name": "Summer Sale",
        "description": "20% off the whole catalogue until the end of August",
        "percentage": 0.2,
        "isExclusive": false,
        "promotionId": "3f1b0c22-8a94-4d2e-b6f1-7c0e5a91d418"
    },
    "validFrom": "2026-06-01T00:00:00Z",
    "validUntil": "2026-08-31T00:00:00Z"
}

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.

Asking for checkout URLs returns three of them, and which one you use decides how checkout is presented: checkoutUrl follows the storefront mode configured on your Moonbase account, hostedCheckoutUrl is always the Moonbase hosted checkout as a full-page navigation, and embeddedCheckoutUrl is the same checkout for an iframe on a page of your own.

For a signed-in customer, checkoutUrl and hostedCheckoutUrl carry a short-lived login token so the hosted checkout can sign them in and prefill their details. Pass embedded=false when you are going to navigate the customer to the hosted checkout yourself, and the token is left off entirely, so a credential never ends up in the address bar, in browser history, or in the logs of everything in between. The embedded checkout URL never carries one either way.

  • 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.

      Product line item

    • 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.

      Bundle line 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
    offerId
    Type
    string
    Optionality
    optional
    Description

    The cart offer attached to the order as a whole. This is what the customer is going for, so it stays on the order even while the cart sits below the offer's threshold, letting them build the cart back up without losing it. Offers picked for a single item live on that item instead.

  • Name
    appliedOffer
    Type
    object
    Optionality
    optional
    Description

    The cart offer that is actually applied, using the same discount model described under Offers above. Absent when no cart offer is attached, or while the attached offer's condition does not hold. Its saving is spread across the line items and totalled in total.cartOfferDiscount.

  • Name
    total
    Type
    object
    Optionality
    optional
    Description

    Calculated total for the order, present once the order has a currency. Each value is an object with currency and amount properties:

    • original: The original amount before discounts.
    • discount: The total amount of discounts applied.
    • subtotal: The total amount after discounts have been removed.
    • taxes: Total taxes to pay, may be inclusive or exclusive of the subtotal depending on configuration, currency and region.
    • due: How much is being paid in total by the customer.
    • cartOfferDiscount: How much of discount came from a cart offer, so you can show it as one order-wide saving rather than a share on every line. Omitted when no cart offer applied.
  • Name
    checkoutUrl
    Type
    string
    Optionality
    optional
    Description

    URL to pay for the order, pointing at whichever checkout the storefront mode of your Moonbase account is configured for. Only present when you ask for checkout URLs with checkout=true.

  • Name
    hostedCheckoutUrl
    Type
    string
    Optionality
    optional
    Description

    URL to pay for the order on the Moonbase hosted checkout, as a full-page navigation. Only present when you ask for checkout URLs with checkout=true.

  • Name
    embeddedCheckoutUrl
    Type
    string
    Optionality
    optional
    Description

    URL to pay for the order in an iframe on a page of your own. It never carries a login token, whether or not the customer is signed in. Only present when you ask for checkout URLs with checkout=true.

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.

Optional query parameters

  • Name
    checkout
    Type
    boolean
    Description

    Flag for if checkout URLs should be generated in the response.

  • Name
    embedded
    Type
    boolean
    Description

    Whether you intend to open embeddedCheckoutUrl in an iframe rather than navigating the customer to hostedCheckoutUrl. Only consulted when checkout is true, and treated as true when omitted.

  • Name
    returnUrl
    Type
    string
    Description

    Where the customer should be sent after a successful purchase, used with the checkout parameter.

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 checkout URLs should be generated in the response. Typically you set this true for the last push before sending the customer to checkout.

  • Name
    embedded
    Type
    boolean
    Description

    Whether you intend to open embeddedCheckoutUrl in an iframe rather than navigating the customer to hostedCheckoutUrl. Only consulted when checkout is true, and treated as true when omitted.

  • 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.

  • Name
    offerId
    Type
    string
    Description

    The cart offer to attach to the order as a whole. Offers picked for a single item stay on that item, as an offerId on the item itself.

The cart offer is part of the cart payload, which means a push that sends items without an offerId clears it. Always pass the current one straight back through when you push, or use the endpoint below to drop it deliberately.

A push is rejected with 400 Bad Request if the same offer is used both on the cart and on a line item, and if any offer is applied to a subscription renewal order.

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": [ ... ]
}
DELETE/api/customer/orders/{orderId}/offer

Remove cart offer

Takes the cart offer off the order without re-sending the cart. Offers picked for a single item come off by pushing the cart again without them.

Calling this on an order that has no cart offer does nothing and still succeeds, so it is safe to call whenever the customer dismisses an offer. Orders that have already been paid for cannot be modified, and return 400 Bad Request.

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

DELETE
/api/customer/orders/{orderId}/offer
DELETE https://demo.moonbase.sh/api/customer/orders/5d3a2c26-d09f-45b3-b018-3461c20efc23/offer
Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJuYW1laWQiOiJiY...

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.

  • Name
    properties
    Type
    object
    Optionality
    optional
    Description

    Public custom properties attached to this voucher. Values are flattened to key-value pairs without the type wrapper. See the Core API documentation for more details on custom properties.

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
    downloadsNeedsGroupMembership
    Type
    boolean
    Description

    Flag for if downloading requires the customer to be a member of a customer group. The group itself is never named in the response.

  • Name
    downloadsAllowed
    Type
    boolean
    Description

    Whether this caller actually clears the requirements above, resolved the same way the download endpoints enforce them. Gate your download UI on this rather than deriving it from the three flags: group membership is not something a client can determine on its own, so a release restricted to a group is indistinguishable from an open one without this verdict.

  • 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
      arch
      Type
      enum(Unknown|Universal|X86|X64|Arm|Arm64)
      Optionality
      optional
      Description

      CPU architecture for the downloadable asset. Present when the merchant has tagged the download with an architecture.

    • 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
    releaseDescription
    Type
    string
    Optionality
    optional
    Description

    The description of the current release, often used as a changelog.

  • Name
    properties
    Type
    object
    Optionality
    optional
    Description

    Public custom properties attached to this product. Values are flattened to key-value pairs without the type wrapper. See the Core API documentation for more details on custom properties.

  • Name
    releaseProperties
    Type
    object
    Optionality
    optional
    Description

    Public custom properties attached to the current release of this product. Values are flattened to key-value pairs without the type wrapper. See the Core API documentation for more details on custom properties.

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,
            "downloadsNeedsGroupMembership": false,
            "downloadsAllowed": true,
            "downloads": [
                {
                    "name": "Example App.pkg",
                    "key": "4dc59922-5476-41aa-a600-2c5e4b9086d5",
                    "platform": "Mac",
                    "arch": "Arm64",
                    "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",
                    "arch": "X64",
                    "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
    properties
    Type
    object
    Optionality
    optional
    Description

    Public custom properties attached to this license. Values are flattened to key-value pairs without the type wrapper. See the Core API documentation for more details on custom properties.

  • 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
    properties
    Type
    object
    Optionality
    optional
    Description

    Public custom properties attached to this license. Values are flattened to key-value pairs without the type wrapper. See the Core API documentation for more details on custom properties.

  • 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...
POST Authenticated/api/customer/inventory/activate

Activate product

Takes a device token as a plain text body and exchanges it for a license token usable for activating products offline. To learn more, check out our documentation on offline activations.

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
    method
    Type
    'Offline'|'Online'
    Description

    The desired activation method, use Offline to get an actual offline license token back.

Required body content

The device token for the device and product to activate.

Response headers

The response headers will contain a location header that contains a URL that can be visited to actually download the license token.

  • Name
    location
    Type
    string
    Description

    URL for where to fetch the newly exchanged license token.

Response content

The response body will contain a summary of the license that was just used to activate the device.

  • Name
    id
    Type
    string
    Description

    The Moonbase ID of the license.

  • Name
    product
    Type
    object
    Description

    The product that the license belongs to. See above endpoints 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
    properties
    Type
    object
    Optionality
    optional
    Description

    Public custom properties attached to this license. Values are flattened to key-value pairs without the type wrapper. See the Core API documentation for more details on custom properties.

  • Name
    createdAt
    Type
    datetime
    Description

    ISO-8601 date and time for when the license was created.

Request

POST
/customer/inventory/activate
POST https://demo.moonbase.sh/api/customer/inventory/activate?method=Offline
Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJuYW1laWQiOiJiY...
Content-Type: text/plain

eyJpZCI6IjVXUzA0RUg5Q003TkJQVEQ4R1JQRzZUQjAwWEJGR0UzTTQ5TlQyWVAxNkhRMDhTSkJLQjAiLCJuYW1lIjoiRXhhbXBsZSBkZXZpY2UiLCJwcm9kdWN0SWQiOiJleGFtcGxlLXByb2R1Y3QiLCJmb3JtYXQiOiJKV1QifQ==

Response

{
    "id": "fb886728-aa63-4f1b-af93-07f739bb499c",
    "status": "Active",
    "product": { ... },
    "activeNumberOfActivations": 1,
    "maxNumberOfActivations": 1,
    "createdAt": "2024-11-06T14:01:54.4380108Z"
}

Was this page helpful?