Order Examples

The following contains a few common scenarios/examples for the ordering process. Unless otherwise stated, each of them presents the body for creating a new order using an order request like the following.

Create a new order
POST /Order/ HTTP/1.1
Host: https://api.info-subscription.com
Content-Type: application/json
S4-TenantId: SOMETENTANT
Authorization: Bearer RANDOMTOKEN
Content-Length: 42

Each example typically only shows properties relevant to the example and omits required elements for brevity.

It is possible to combine many of the examples, though not necessarily all of them.

Example: Choosing Products On A Plan

For organizations with many products to sell, it is often required to have the option to construct any product combination the subscriber desires. Consider an traditional cable TV provider, many of them offer extra channels, and even serves as an Internet Service Provider.

Instead of creating every combination of product selects as template plans, it is possible to provide one or two template plans that allows choosing between products. Continuing the example of a TV/ISP company, they may have the following products

  • Basic TV 00000000-0000-0000-0000-000000000001

  • Premium TV 00000000-0000-0000-0000-000000000002

  • Sports Channel 00000000-0000-0000-0000-000000000003

  • Movie Channel 00000000-0000-0000-0000-000000000004

  • Random Channel 00000000-0000-0000-0000-000000000005

  • Slow Internet 00000000-0000-0000-0000-000000000006

  • Fast Internet 00000000-0000-0000-0000-000000000007

  • Ultra Internet 00000000-0000-0000-0000-000000000008

An example template would look something like the following:

Template Plan/Package Body
{
    "id": "10000000-0000-0000-0000-000000000000",
    "products": [
        {
            "productId": "00000000-0000-0000-0000-000000000001",
            "fullPrice": 1000,
            "taxPercent": 25
        },
        {
            "productId": "00000000-0000-0000-0000-000000000002",
            "fullPrice": 2000,
            "taxPercent": 25
        },
        /* Omitted for brevity  */
        {
            "productId": "00000000-0000-0000-0000-000000000008",
            "fullPrice": 8000,
            "taxPercent": 25
        }
    ],
    "name": "TV and Internet",
    "description": "Internet and TV For All Yo!"
    /* Rest omitted for brevity */
}

If one were to subscribe to the above TV and Internet package, with no choices, it would contain 8 Products.

However, using choices, it is possible to construct and order for Basic TV and Slow Internet like the following

Order of Basic TV and Slow Internet using choices
{
    "subscriberId": "11111111-2222-3333-4444-000000000000",
    "templatePackageId": "10000000-0000-0000-0000-000000000000",
    "paymentAgreementId" : "44444444-5555-6666-7777-000000000000",
    "organizationId" : "20000000-0000-0000-0000-000000000000",
    "templatePackageChoices":
    {
        "products": ["00000000-0000-0000-0000-000000000001", "00000000-0000-0000-0000-000000000006"],
    }
}

Example: Overriding Pre-Defined Prices

Typically a template plan is setup with a specific set of products.

The price is either defined directly on the template plan, or as a function of the list price on the products.

In some scenarios it is desirable to override this price when creating the order.

For instance where an extra-ordinary discount should be given to a subscriber (for whatever reason), or in cases where each subscription is negotiated by a salesperson, which is typically for high-value enterprise and B2B susbscriptions.

It is possible to override the price during the order like the following

Price Override
{
    "subscriberId": "11111111-2222-3333-4444-000000000000",
    "templatePackageId": "10000000-0000-0000-0000-000000000000",
    "paymentAgreementId" : "44444444-5555-6666-7777-000000000000",
    "organizationId" : "20000000-0000-0000-0000-000000000000",
    "templatePackageChoices":
    {
        "priceOveride": 2000,
    }
}

Important

It is important to note that this is only possible if the template is configured to allow price overrides!

Example: Vipps or MobilePay as Payment Agreement

To use Vipps or MobilePay as the payment method, set the paymentAgreementParameters as follows:

Vipps Payment Agreement Parameters
{
  "paymentMethod": "Vipps",
  "vippsMobilePayParameters": {
    "customerPhoneNumber": "+4791234567",
    "merchantAgreementUrl": "https://yourdomain.com/selfservice/vipps-agreement-info",
    "merchantRedirectUrl": "https://yourdomain.com/order/complete",
    "accountId": "your-account-id"
    "profileScope": "name address email"
  }
}

  • paymentMethod must be set to Vipps or MobilePay.

  • vippsMobilePayParameters is an object with the following fields:

    • customerPhoneNumber (optional): The phone number to pre-fill in the Vipps dialog.

    • merchantAgreementUrl: URL to your self-service agreement page.

    • merchantRedirectUrl: URL to redirect the user after approval/rejection in the Vipps app.

    • profileScope (optional): Setting the profile scope will ask the user to share his/her contact details such as name, address, and email.

Example: SwedbankPay as Payment Agreement

To use SwedbankPay as the payment method, set the paymentAgreementParameters as follows:

SwedbankPay Payment Agreement Parameters
{
  "paymentMethod": "SwedbankPay",
  "payExEcommerceParameters": {
    "callbackUrl": "https://yourdomain.com/api/payment/callback",
    "cancelUrl": "https://yourdomain.com/order/cancel",
    "completeUrl": "https://yourdomain.com/order/complete",
    "payExAccountId": "your-payex-account-id",
    "culture": "nb-NO"
  }
}

  • paymentMethod must be set to SwedbankPay.

  • payExEcommerceParameters is an object with the following fields: - callbackUrl: URL for payment status callbacks from SwedbankPay. - cancelUrl: URL to redirect the user if the payment is cancelled. - completeUrl: URL to redirect the user after successful payment. - payExAccountId (optional): The SwedbankPay account to use. - culture (optional): Language/culture code for the payment window (e.g., nb-NO).

Refer to the API documentation for additional options and required fields for other payment methods.