Buy-link template for ordering a service via Storefront

When a customer orders a new service via Storefront, a buy-link attached to the Buy now (or Try it) button on the product page (see Product page) is used. A buy-link is generated using a template and includes information required for ordering a service. By clicking the button, a customer is redirected to the Customer Control Panel for creating a sales order.

In this article:

Template

A buy-link for ordering a service via Storefront is generated using the following template:

https://{base_url}/external_dispatcher/settle?shopping_cart_items[][plan_id]={plan_id}&shopping_cart_items[][plan_period_id]={plan_period_id}&shopping_cart_items[][type]=application&manager_key={manager_key}&shopping_cart_items[][type]=topup&shopping_cart_items[][amount]={topup_amount}&skip_all_steps=1

Attributes in a buy-link are specified via &. Some attributes are optional (see the description and examples below). The attribute &shopping_cart_items[][type]=application does not require modifications and should always be specified as is.

Attributes

AttributeRequired/OptionalDescription
base_urlRequiredThe domain name of the reseller linked to the Customer Store (see Viewing and updating reseller domain information)
plan_idRequiredThe ID of the plan to which a subscription is ordered (see Viewing the list of plans)
plan_period_idRequired

The ID of the plan period to which a subscription is ordered (see Updating plan periods)

In Storefront, on the product page, the ID of a plan period corresponding to a subscription with the minimal price within the plan is automatically linked to the Buy now button. The ID of a trial plan period is automatically linked to the Try it button (see Product page). A customer can change the plan period on the subscription configuration step in the Customer Control Panel.

manager_keyOptional

The key of a manager if it is necessary to link the customer's account to a given manager. In Storefront, the manager's key is not displayed in the URLs of its pages. A manager needs to manually provide a customer with a link that includes the key. The manager's key can be added to a link with the URL of any page of Storefront.

The key is case-sensitive, so it is important to specify it in a buy-link exactly as on the manager information page. For example, carter81 and Carter81 are different keys that will not work together for the same manager.

When a customer orders a new service via Storefront, it is possible to link the customer's account to a given manager. To perform this action, the following conditions should be met:

  • The manager has the Active status, the Sales person role, and the key is provided in the manager's information (see Adding a manager).
  • A customer visited any page of Storefront via a link with the &manager_key={manager_key} attribute where {manager_key} is the manager's key.
  • The customer's account is not yet linked to any manager, or it is a new account. 

For information about the linked manager for an account, see Viewing and updating account's details.

Linking the customer's account to a given manager has the following specifics:

  • On the customer side, the manager's key is stored in the browser cookies for one month. During this period, it is usually unnecessary to use the manager's key in the Storefront links for automatic linking an account to a manager: the cookies data will be used. A link that includes the manager's key should be used if the browser cookies were cleared.
  • After linking an account to a manager, the manager will receive notifications according to the Account created and the Account manager changed rotification events (see Creating an event handler).

Links with the attribute &manager_key={manager_key} can also be used for a referral program (see Configuring a referral program).

topup_amountOptional

The amount of a top-up payment in the reseller currency required to start the service provisioning. The attribute can only be used for ordering a prepaid subscription with the Pay as you go billing type (see Pay as you go. Charges generation) without any resource fees. When a customer orders a new service via Storefront, using a link with the attribute &shopping_cart_items[][type]=topup&shopping_cart_items[][amount]={topup_amount}, a sales order with 0 amount and a top-up payment for the given amount will be created and linked to the subscription.

The top-up payment is required to make sure that an ordered subscription will not be stopped almost right after its activation:

  1. A pay-as-you-go subscription within the Prepay model blocks funds on the account balance only for the quantity of resources consumed on the service side.
  2. Usually, the first consumption data from the service side is processed on the platform side one hour after the subscription activation.
  3. The top-up payment is used to cover this consumption.
skip_all_steps=1Optional

When a customer orders a new service via Storefront, using a link with the &skip_all_steps=1 attribute, the subscription configuration step in the Customer Control Panel is skipped. It is recommended to use this attribute for ordering subscriptions with the Pay as you go (internal) billing type because they do not have the resources to be changed and use quotas instead. See also Ordering a subscription with the Pay as you go (internal) billing type.

Examples

  1. A buy-link to order a subscription from the test.activeplatform.com reseller to a plan with the ID = 425 and a plan period with the ID = 1840:

    https://test.activeplatform.com/external_dispatcher/settle?shopping_cart_items[][plan_id]=425&shopping_cart_items[][plan_period_id]=1840&shopping_cart_items[][type]=application

  2. A buy-link to order a subscription from the test.activeplatform.com reseller to a plan with the ID = 425 and a plan period with the ID = 1840, the manager's key is carter81:

    https://test.activeplatform.com/external_dispatcher/settle?shopping_cart_items[][plan_id]=425&shopping_cart_items[][plan_period_id]=1840&shopping_cart_items[][type]=application&manager_key=carter81

  3. A buy-link to order a prepaid subscription with the Pay as you go (internal) billing type from the test.activeplatform.com reseller to a plan with the ID = 569 and a plan period with the ID = 2072, the top-up amount is 1000:

    https://test.activeplatform.com/external_dispatcher/settle?shopping_cart_items[][plan_id]=569&shopping_cart_items[][plan_period_id]=2072&shopping_cart_items[][type]=application&shopping_cart_items[][type]=topup&shopping_cart_items[][amount]={1000}&skip_all_steps=1