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 to create a sales order.

In this article:

Template

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

{base_path}?shopping_cart_items[][plan_id]={plan_id}&shopping_cart_items[][plan_period_id]={plan_period_id}&shopping_cart_items[][resources][][id]={resource_id}&shopping_cart_items[][resources][][quantity]={resource_quantity}&shopping_cart_items[][type]=application&manager_key={manager_key}&order_type={order_type}&shopping_cart_items[][type]=topup&shopping_cart_items[][amount]={topup_amount}&skip_all_steps=1&_ga={ga_values}

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 must always be specified as is.

Attributes

AttributeRequired/OptionalDescription
base_pathRequired

The base path of a buy-link. It depends on the External application URL value (see External application URL settings in Customer Store general settings):

  • If External application URL is empty, the base path equals https://{base_url}/external_dispatcher/settle where base_url is the domain name of the reseller linked to the Customer Store (see Viewing and updating reseller domain information). This option is used with the classic Customer Control Panel.
  • If External application URL is specified, the base path equals its value. Example: https://test.activeplatform.com/client/new_order where test.activeplatform.com is the domain name of the reseller linked to the Customer Store (see Viewing and updating reseller domain information). This option is used with the new Customer Control Panel.
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.

resource_idOptional

The ID of a resource to include in a subscription with the specified amount. To add several resources in a subscription, specify resource_id and resource_quantity in pairs

The classic Customer Control Panel does not support processing the resource_id attribute.

resource_quantityOptionalThe quantity of a resource with the specified ID to include in a subscription. Required for every resource_id
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 notification 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).

order_typeOptional

Defines the type of order a customer creates by following a buy-link:

  • SalesOrder — purchase a new subscription.
  • RenewalOrder — renew an existing subscription.
  • ProlongOrder — prolong an existing subscription.
  • ChangeOrder — change the resource quantity in an existing subscription.
  • SwitchPlanOrder — switch the plan of an existing subscription.

Mandatory depends on the External application URL value (see External application URL settings in Customer Store general settings):

  • Optional if External application URL is empty. In this case, order_type is not processed and can be absent.
  • Required if External application URL is specified. In this case, &order_type=SalesOrder is automatically added to a link attached to the Buy now (or Try it) button on the product page.

The classic Customer Control Panel does not support processing the order_type attribute.

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.

ga_valuesOptionalThe values of a Google Analytics tag

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