Buy-link template for ordering a service via Storefront

When a customer orders a new subscription 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 subscription. 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 subscription 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 specified, the base path equals its value. Example: https://test.activeplatform.com/client/new_order where test.activeplatform.com is the reseller domain name (see Viewing and updating reseller domain information). This option is used with the Customer Control Panel.
  • 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 no longer supported.
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

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 subscription 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, 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):

  • 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.
  • Optional if External application URL is empty. In this case, order_type is not processed and can be absent.
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 to order a prepaid subscription with the 0 order amount (for example, for a subscription with the Pay as you go billing type, see Pay as you go. Charges generation), and when actions with the account balance are allowed by the reseller (see Managing financial settings).

When a customer orders a new subscription via Storefront, using a link with the attribute &shopping_cart_items[][type]=topup&shopping_cart_items[][amount]={topup_amount}, a sales order with the 0 amount and a top-up payment will be created and linked to the subscription. The topup_amount attribute works with the Prepayment for provisioning of subscriptions, amount in reseller currency setting in the plan's service term (see Creating a service term): the payment amount is defined by the greatest value among them.

More info

The top-up prepayment is required to make sure that an ordered subscription with the Pay as you go billing type 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 prepayment is used to cover this consumption.
skip_all_steps=1Optional

When a customer orders a new subscription 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/client/new_order?shopping_cart_items[][plan_id]=425&shopping_cart_items[][plan_period_id]=1840&shopping_cart_items[][type]=application&order_type=SalesOrder

  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/client/new_order?shopping_cart_items[][plan_id]=425&shopping_cart_items[][plan_period_id]=1840&shopping_cart_items[][type]=application&manager_key=ivanov22&order_type=SalesOrder

  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/client/new_order?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&order_type=SalesOrder