Connect your business systems

This article provides information on integration possibilities with 10Duke Scale.

Customer onboarding

Integration logic to onboard new customers can be implemented in a variety of ways. The information in this section focuses on flows supported by the 10Duke Scale Ecom Integration API supplied by 10Duke as part of 10Duke Scale.

The information here applies in a general sense, and equivalent integration implementations can be used instead of the one described here. In the diagrams, “10Duke e-commerce integration/webhooks” can also be read as “the integration service you plan to deploy”.

The 10Duke Scale e-commerce integration service supports these alternative flows for onboarding new customers:

  • Managed: Robust and reliable through the entire customer life cycle

  • E-commerce-driven: The easiest and fastest to get started with, if the e-commerce provider supports sign-up and has sufficient built-in UI features

  • Hybrid: Still easy with support for inhouse developers to drive the implementation a bit more

  • Manual: Case by case, limited automation

The supported e-commerce systems and options:

  • Stripe

    • Subscriptions for recurring payments and subscription licensing

  • FastSpring

    • Orders for perpetual licensing

    • Subscriptions for recurring payments and subscription licensing

Managed onboarding

Managed customer onboarding is defined as an implementation that interacts with the user independently of e-commerce, licensing, and an identity provider.

This usually means a web-based UI that takes the user through the sign-up steps and a server-side application that stays in the driver’s seat. The sign-up service calls the relevant integration points in the background and initiates the main triggers of the process in collaboration with the user.

This alternative is a good choice for enabling the robust handling of returning customers when customer identity is included as part of the implementation. This is because you can require a returning customer to sign in before making additional purchases, which ensures that the customer is able to manage which account the purchase is made for in a more reliable manner.

This is the sequence logic in managed onboarding:

Managed onboarding flow

E-commerce-driven onboarding

E-commerce-driven customer onboarding is an implementation that allows a service such as a payment provider or a recurring billing system to drive the customer onboarding process. This usually means other components react to webhooks.

This is the sequence logic in e-commerce-driven onboarding:

E-commerce-driven onboarding flow

Hybrid onboarding

A common onboarding implementation is a hybrid model that combines aspects of the managed flow and the e-commerce-driven flow.

The hybrid implementation differs from the managed implementation mainly by the sign-up component, which interacts directly with the e-commerce system, followed by other components relying on webhooks from the e-commerce system.

This alternative requires extra care in other components and later stages to enable the robust handling of returning customers.

This is the sequence logic in hybrid onboarding:

Hybrid onboarding flow

Manual onboarding

A manual onboarding implementation involves ad hoc actions carried out by people, and specific point-to-point API integrations between selected components.

It’s important to note that the other types of implementations also usually require some manual ad hoc actions, for example, when network connectivity causes issues.

Manual onboarding may include elements such as manually typed emails during a phone call, paper contracts, and a vendor-supplied service to create accounts on behalf of customers.

The details of manual onboarding are handled case by case, and 10Duke can provide support when needed.

E-commerce systems

10Duke Scale can record contract, order, and subscription information originating from an e-commerce system. This is needed for managing the life cycle of customer licenses based on events in the e-commerce system.

Some e-commerce fields have a one-to-one mapping to 10Duke Scale while others require lookup logic in order to match an entity in 10Duke Scale.

Read more below about the different e-commerce data objects and fields.

Prerequisites

The use cases described in this article assume that customer onboarding has taken place (see above in this article). The customer onboarding process ensures that a mapping of customer records takes place between the e-commerce system and 10Duke Scale.

Customer identity and e-commerce account ID

An e-commerce account is commonly a synonym for a customer (a Licensee in the API) in 10Duke Scale. An account ID in the e-commerce system maps to a Licensee’s customer ID in 10Duke Scale (in the API, the field is named naturalId).

However, in API operations such as issuing new licenses for a customer, the API client needs to specify the unique entity ID of the Licensee in 10Duke Scale using the licenseeId request parameter.

The integration logic can rely on one of the following:

  • Option 1: The unique entity ID from 10Duke Scale is stored in the e-commerce system as metadata.

    How the unique ID gets stored in the e-commerce system is the responsibility of the customer onboarding process.

  • Option 2: The API client first runs a lookup using the e-commerce account ID to get hold of the customer’s unique entity ID in 10Duke Scale.

    The API client uses the API operation GET /licensees/actions/find-by-naturalid and specifies the e-commerce account ID in the naturalId query parameter.

    How the account ID gets stored in 10Duke Scale is the responsibility of the customer onboarding process.

See more information on customer details in 10Duke Scale.

Issuing new licenses

See information below on the e-commerce IDs that can be associated with licenses.

See also how to issue licenses in 10Duke Scale.

E-commerce contract ID

A contract ID in the e-commerce system can be passed along to the API in 10Duke Scale when issuing new licenses. This is done using the request parameter contractReference.

Storing the contract reference in 10Duke Scale helps to look up a customer’s licenses related to a specific contract. This is typically needed for revoking or deleting licenses when a contract is terminated in the e-commerce system.

E-commerce order ID

Orders in the e-commerce system usually correlate to either perpetual or fixed-term licenses.

An order ID in the e-commerce system can be passed along to the API in 10Duke Scale when issuing new licenses. This is done using the request parameter orderReference.

Storing the order reference in 10Duke Scale helps to look up specific licenses for a customer. This is typically needed for revoking or deleting licenses when an order is canceled in the e-commerce system.

E-commerce subscription ID

Subscriptions in the e-commerce system correlate to recurring billing and subscription-based licenses in 10Duke Scale.

A subscription ID in the e-commerce system can be passed along to the API in 10Duke Scale when issuing new licenses. This is done using the request parameter subscriptionReference.

Storing the subscription reference in 10Duke Scale helps to look up specific licenses for a customer. This is typically needed for revoking or deleting licenses when a subscription is deactivated in the e-commerce system.

Note: The time when the subscription is canceled in the e-commerce system is usually not the correct time to revoke or delete licenses. This is because the cancellation request may be made before the current subscription’s term ends.

For a robust integration logic, we recommend that you don’t set an expiration date when issuing subscription licenses, and that you only revoke or delete the licenses when the subscription is deactivated.

E-commerce stock keeping unit (SKU) or other product ID

A stock keeping unit (SKU) in the e-commerce system can be passed along to the API in 10Duke Scale when issuing new licenses. This is done using the request parameter productReference.

Using the SKU is just one option: the 10Duke Scale product reference value can also be used to store a different product ID from the e-commerce system.

Storing the product reference in 10Duke Scale helps to find licenses matching a specific product ID used externally to 10Duke Scale.

Revoking licenses

You can use the IDs from the e-commerce system when there’s a need to revoke licenses related to a specific terminated contract, canceled order, or deactivated subscription.

The generalized integration logic:

  1. The API client identifies the customer by resolving the unique ID of the customer entity in 10Duke Scale based on the e-commerce account ID.

  2. To revoke the customer’s licenses for a specific contract, order, or subscription, the API client uses the API operation PUT /licensees/{licenseeId}/licenses/actions/revoke and uses either the contractReference, orderReference, or subscriptionReference request parameter to provide the applicable e-commerce ID.

See also how to revoke licenses in 10Duke Scale.

Best practices

When issuing licenses, send as rich information as possible to 10Duke Scale. This will help with:

  • Implementing all license revoking use cases over time even if they’re not needed immediately

  • Finding data records in 10Duke Scale using different types of details

Apply strict and eager data validation in the integration layer, and catch and react to errors as early as possible. This will help with:

  • Keeping the integration logic clean

  • Reducing lookup errors

  • Reducing errors on the whole in the e-commerce-driven license management process

  • Reducing the workload of your customer support

Event-based webhook integration

Instead of integrating directly to 10Duke Scale APIs, you can connect your e-commerce system to 10Duke Scale using an event-driven webhook integration.

By setting up webhooks in your e-commerce system, you can trigger actions in 10Duke Scale based on events in the external system.

For example, when a new customer purchases a subscription in your e-commerce system, a customer is created in 10Duke Scale and licenses are issued to the products purchased.

See how to connect to the supported e-commerce systems using webhooks:

Contents