Subscription-now

Appearance

Return to top
On this page

Subscription-now.js API

The public API of the Subscription-now.js is a convenient tool for you to communicate with the library and SN back-end.

It has it some limitations to keep it consistent across all the implementations, however more than enough for all of your client-side needs.

General concept

In order to access the $sn instance we must make sure that it has been loaded and initialized properly.

You can simply do so as simple as in the following code snippet:

window.addEventListener('sn.ready', () => {
    $sn.api.on('sn.order.succeeded', (context, orderData) => {
        alert('Order succeded. Contract ID is: ' + orderData.contract.Id);
    });
});
1
2
3
4
5

Let's recap what happened here:

  1. We have created an event listener for the window object that will be fired upon sn.ready is emitted.
  2. Then we created another event listener through the public API's on namespace that will be fired when an order is successfully put by a customer.

API Methods

Currently, the API consists of 5 main namespaces:

Event Listener Generation

$sn.api.on: This is the method that must be used to create event listener to be fired upon many possible event emissions.

Each of these events emit a context object by default. The context has two properties: customer and cart.

Some events also emit a secondary argument that carries event specific data, like validation errors and such.

Available Events

sn.customer.login: Emitted when a customer is logged in programmatically.

sn.customer.updated: Emitted when a customer information updated.

sn.order.cancelled: Emitted when a customer puts an order cancellation request.

sn.validation.error: Emitted when a form request returns a validation errors.

sn.cart.shown: Emitted after the SN cart is shown.

sn.product.added: Emitted after an item was added to the cart.

sn.product.updated: Emitted after an item in the cart was updated.

sn.product.addFailed: Emitted when an item could not be added to the cart.

sn.product.updateFailed: Emitted when an item in the cart could not be updated.

sn.product.removed: Emitted when an item in the cart was removed.

sn.product.removeFailed: Emitted when an item in the cart could not be removed.

sn.order.changed: Emitted when customer changes address information of an order.

sn.order.succeeded: Emitted when an order has succeeded.

sn.order.failed: Emitted when an order has failed.

sn.order.cancelled: Emitted when an order has cancelled.

sn.giftCode.redeemed: Emitted when a gift was redeemed successfully.

sn.giftCode.failed: Emitted when a gift redemption has failed.

Customer Methods

$sn.api.customer.login(loginDTO) async

Logs in the customer to SN back-end. You have two options.

A. Use auth_key and external_user_id pair. This will

$sn.api.customer.login({
    auth_key: $sn.api.customer.getSignature(), // This should be stored in your DB and retrieved in the next login
    external_user_id: userFromYourDb.id,
    customer: { // Optional customer DTO will update the current data
        first_name: 'Mister',
        last_name: 'Brown',
        email: 'mrbrown@domain.com'
    }
})
1
2
3
4
5
6
7
8
9

B. Or use email and external_user_id pair if you are certain this customer exists in Subscription-now.

$sn.api.customer.login({
    email: 'mrbrown@domain.com', // 
    external_user_id: userFromYourDb.id,
    customer: { // Optional customer DTO will update the current data
        first_name: 'Mister',
        last_name: 'Brown',
        email: 'mrbrown@domain.com'
    }
})
1
2
3
4
5
6
7
8
9

Tip:

You can disable the e-mail field for your returning customers by setting the options.emailReadonly parameter as true.

loginDTO
interface CustomerLoginDTO {
    auth_key: string;
    external_user_id: string;
    customer?: {
        first_name?: string;
        last_name?: string;
        email?: string;
        phone?: string;
        billingAddress?: {
            first_name?: string;
            last_name?: string;
            company?: string;
            email?: string;
            phone?: string;
            street: string;
            addressLine1: string;
            addressLine2?: string;
            houseNumber: string;
            postalCode: string;
            city: string;
            country: string;
        };
        shippingAddress?: {
            first_name?: string;
            last_name?: string;
            company?: string;
            email?: string;
            phone?: string;
            street: string;
            addressLine1: string;
            addressLine2?: string;
            houseNumber: string;
            postalCode: string;
            city: string;
            country: string;
        };
        customFields?: object;
    };
    options?: {
        emailReadonly?: boolean;
    };
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

$sn.api.customer.logout()

Logs out the current customer and returns a fresh cart session

$sn.api.customer.setCustomerData(customerDTO)

Sets customer details without updating SN back-end. Useful for prefilling SN form fields without interacting with back-end.

$sn.api.customer.setCustomerData({
    customer: {
        first_name: 'Mister',
        last_name: 'Brown',
        email: 'mrbrown@domain.com'
    }
})
1
2
3
4
5
6
7
customerDTO
interface CustomerLoginDTO {
    customer?: {
        first_name?: string;
        last_name?: string;
        email?: string;
        phone?: string;
        billingAddress?: {
            first_name?: string;
            last_name?: string;
            company?: string;
            email?: string;
            phone?: string;
            street: string;
            addressLine1: string;
            addressLine2?: string;
            houseNumber: string;
            postalCode: string;
            city: string;
            country: string;
        };
        shippingAddress?: {
            first_name?: string;
            last_name?: string;
            company?: string;
            email?: string;
            phone?: string;
            street: string;
            addressLine1: string;
            addressLine2?: string;
            houseNumber: string;
            postalCode: string;
            city: string;
            country: string;
        };
        customFields?: object;
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

$sn.api.customer.getSignature()

Returns the signature for you to store in your database. This key will be used to login the customer from your database into Subscription-now cart session. (Please refer to $sn.api.customer.login method)

$sn.api.customer.selfService.show()

Shows the self-service interface for the logged-in customer. The customers can do operations for their past orders using this interface.

$sn.api.customer.selfService.hide()

Hides the self-service interface.

$sn.api.settings.setLocale(locale: string)

Changes the UI localization of SN components.

locale
enum Locale {
    en = "en",
    de = "de"
}
1
2
3
4

Products Methods

$sn.api.products.get()

Returns the list of the available products

Cart Methods

$sn.api.cart.get() async

Returns the cartDTO object.

cartDTO
interface CartDTO {
    customer?: {
        first_name?: string;
        last_name?: string;
        email?: string;
        phone?: string;
        billingAddress?: {
            first_name?: string;
            last_name?: string;
            company?: string;
            email?: string;
            phone?: string;
            street: string;
            addressLine1: string;
            addressLine2?: string;
            houseNumber: string;
            postalCode: string;
            city: string;
            country: string;
        };
        shippingAddress?: {
            first_name?: string;
            last_name?: string;
            company?: string;
            email?: string;
            phone?: string;
            street: string;
            addressLine1: string;
            addressLine2?: string;
            houseNumber: string;
            postalCode: string;
            city: string;
            country: string;
        },
    },
    currency: string,
    payment_session_id: string,
    items: [
        {
            productId: string,
            type: "Product"|"Addon",
            quantity: number,
            data: any
        }
    ],
    subscriptionProductId?: string,
    tax: number,
    total: number,
    price: number,
    coupon_code?: string
    discount?: number
    discountAmount?: number|null
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52

$sn.api.cart.add(productExternalID: string, isGift: bool) async

Adds an item to the cart. Returns the cartDTO object.

productExternalID The external ID of the product. i.e. `Billwerk plan variant ID`.
isGift Whether the item is a gift or not. Please keep in mind that the variant must have a gift counterpart variant and a flex component in the same plan group.

$sn.api.cart.remove(productExternalID: string) async

Removes an item to the cart. Returns the cartDTO object.

productExternalID The external ID of the product. i.e. `Billwerk plan variant ID`.

$sn.api.cart.redeemGiftCode(giftCode: string) async

Redeems a gift code and subscribes the customer to the gift plan.

Please keep in mind that a customer must be logged in to the cart session to carry out this operation.

giftCode The gift code can be either obtained from the gift purchaser's order history, or can be received by implementing a custom hook and reading out the gift details from context.

$sn.api.cart.show()

Reveals the slide-in cart

$sn.api.cart.hide()

Hides the slide-in cart

$sn.api.cart.toggle()

Toggles the slide-in cart

$sn.api.cart.setStep(step: number)

Sets the stage of the cart programmatically. Useful for enhanced UX scenarios.

step
enum cartSteps {
    preview = 0,
    expandedPreview = 1,
    checkout = 2
}
1
2
3
4
5

Example:

$sn.api.cart.setStep(2) // Jumps to the checkout step directly
1