Implementation of the External Pricing Endpoint

External Pricing Use Cases

The external pricing configuration and consumption of the related endpoint is triggered during the following use cases to retrieve prices:

  • Storefront → Basket Items List
    A call to retrieve an external price is made for every end-customer (select customer, create new customer, select personal usage, select affiliate account, create new affiliate account). When deleting an item from the basket, external pricing is called again to retrieve prices for all basket items.
  • Storefront → Subscription/Subscription Addon Partial Cancellation
    The latest external price is requested so that it can be applied to the invoices and to the subscription after quantity decrease.
  • BSS → Sales → Offers
    The latest external price is requested when Adding or Editing an offer item.
  • BSS → Sales → Orders
    The latest external price is requested during the following actions:
    • Adding or Editing of an order item
    • Executing an Order
  • BSS → Billing → Subscriptions
    Latest external price is requested during the following actions:
    • Create New
    • Change Quantity
    • Renew
    • Upgrade/Downgrade
    • Upgrade Trial to Paid
    • AddonsAdd New Addon
    • AddonsChange Quantity

External Pricing Endpoint Request

The request sent to an external pricing endpoint is an HTTP Post request following the request headers and authorization/authentication details of other Service Management API endpoints.

The request is triggered every time retrieval of prices is required, based on the use cases described in the previous section.

An example of the body of the HTTP Post request is shown below.

{
    "ContractType": 1,
    "Currency": "USD",
    "Items": [
        {
            "Id": "0cc7362f-ff3b-4b0f-b845-4ed552202eb1",
            "ExternalId": null,
            "Quantity": 1,
            "Unit": {
                "Id": "062ac5fb-60fd-483d-8636-d6e6126ff91f",
                "Value": 1,
                "Type": "month"
            },
            "IsBackordering": true,
            "BillingPlan": {
                "Installments": 12,
                "InstallmentsFrequency": 1
            },
            "ItemCharacteristics": [
                {
                    "Id": "03884248-9cec-476e-876a-5b879fc7b3f2",
                    "Name": "status",
                    "Value": "scheduled",
                    "ExternalId": "501",
                    "ExternalValue": "processing"
                }
            ],
            "Product": {
                "Id": "80632336-efc3-4d74-b81d-6fd2eecefa1f",
                "Name": "Basic Product",
                "ExternalId": "Product_1_basic",
                "Code": "Product_1",
                "IsAddon": false,
                "ProductCharacteristics": [
                    {
                        "Id": "03884248-9cec-476e-876a-5b879fc7b3f3",
                        "Name": "edition",
                        "Value": "home",
                        "ExternalId": "400",
                        "ExternalValue": "w_home"
                    }
                ]
            },
            "ExtraDetails": null,
            "EffectiveDate": "2022-10-17T00:00:00"
        }
    ],
    "Account": {
        "Id": 10615,
        "ExternalId": "customer_322348234",
        "Country": {
            "Name": "United   States",
            "Code": "US"
        },
        "Region": {
            "Name": "New York",
            "Code": "NY"
        }
    },
    "BillToAccount": {
        "Id": 10614,
        "ExternalId": "reseller_23938293",
        "Country": {
            "Name": "United   States",
            "Code": "US"
        },
        "Region": {
            "Name": "Arkansas",
            "Code": "AR"
        }
    }
}

Schema Details

  • ContractType – The value of this field varies depending on how the external pricing request was triggered. The available values are 0-9 and are defined as follows:
    • 0: Public API → Product
    • 1: Order Item or Basket Item
    • 2: Offer Item
    • 3: Subscription Create or Recalculate
    • 4: Subscription Add New Addon or Recalculate
    • 5: Subscription Renewal
    • 6: Subscription Change Quantity
    • 7: Subscription Addon Change Quantity
    • 8: Subscription Upgrade
    • 9: Subscription Downgrade
  • Currency -The currency in its 3-letter mnemonic (EUR, USD, etc). This is the expected currency of the price.
  • Account – End-Customer details
    • Id – interworks.cloud Platform account unique identifier
    • ExternalId – Unique identifier of the account/customer entity as provided on the response of Account Synchronization endpoint
    • Country – Contains the following fields:
      • Name – The name of the country
      • Code – The two-letter country code
    • Region – Contains the following fields:
      • Name – The name of the State/Region
      • Code – The two-letter region code
  • BillToAccount -Reseller / Bill To Account details
    • Id – interworks.cloud Platform account unique identifier
    • ExternalId – Unique identifier of the account/customer entity as provided on the response of Account Synchronization endpoint
    • Country – Contains the following fields:
      • Name – The name of the country
      • Code – The two-letter country code
    • Region
      • Name – The name of the State/Region
      • Code – The two-letter region code
  • Items -The pricing request details related to the service (Product, Unit, Quantity, etc). The request contains multiple items if the Order/Basket, Offer or Subscription/Subscription Addons entities are related.
    • Id -Unique identifier for current item. This value should be used on the response to return the calculated price for the item.
    • ExternalId -Unique identifier of the service entity as provided on the response of Subscription Create endpoint.
    • Quantity -The final quantity of the service that the price is requested for.
    • Unit – The unit details of the service that the price is requested for.
      • Id – The identifier of the unit
      • Value – 1
      • Type – The time period, e.g. “month”
    • IsBackordering – Indicates whether the lease/addon is from backordering
    • BillingPlan – Contains the billing plan details:
      • Installments – The total number of installments
      • InstallmentsFrequency – The number of installments per month
      • ItemCharacteristics – The characteristics of the order item:
        • Id – The internal identifier of the characteristic
        • Name – The name of the characteristic, e.g. “status”
        • Value – The internal value of the characteristic, e.g. “scheduled”
        • ExternalId – The identifier of the characteristic in the 3rd party system
        • ExternalValue – The value of the characteristic in the 3rd party system
  • Product -The product details of the service as provided during Get Service Definition
    • Id – The unique identifier of the product
    • Name – The name of the product
    • ExternalId – The identifier of the product in the third party system
    • Code – A code used to identify the product
    • IsAddon – Indicates whether the product is an add-on to another product
    • ProductCharacteristics – Contains a list of product characteristics:
      • Id – The internal identifier of the product characteristic
      • Name – The name of the product characteristic, e.g. “edition”
      • Value – The internal value of the product characteristic, e.g. “home”
      • ExternalId – The identifier of the characteristic in the 3rd party system
      • ExternalValue – The value of the characteristic in the 3rd party system
  • ExtraDetails -Extra details of the service entity as provided in the response of Subscription Create endpoint.
  • EffectiveDate -The effective date the price is requested for.

External Pricing Endpoint Response

The response should return the calculated Cost Price and Sell Price of the requested service in the requested currency. If price calculation fails, the status shows the reason for failure.

The exchange rate used in the calculation can be returned, but this is optional and only used for display reasons by the interworks.cloud Platform. The exchange rate is not used in any calculations performed by the interworks.cloud Platform.

The body of the response is described below.

{
   "Currency": "USD",
   "Items": [
      {
         "Id": "0cc7362f-ff3b-4b0f-b845-4ed552202eb1",
         "CostPrice": 20.92,
         "SellPrice": 24.06,
         "GeneratedAt": "2022-10-17T12:47:30.1163543+03:00",
         "Status": {
            "Code": 0,
            "Message": "Prices   Retrieved"
         }
      }
   ],
   "ExchangeRate": {
      "Currency": "EUR",
      "Rate": 1.17,
      "GeneratedAt": "2022-10-17T12:47:30.1153273+03:00"
   }
}

Schema Details

  • Currency -The currency in 3-letter mnemonic that calculated prices are given. In case requested currency is different by the response currency, the external pricing request will be treated as failed by interworks.cloud Platform.
  • Items -Every item in the request body should also be contained in the response body.
    • Id – the unique identifier value of the item as provided in response body
    • CostPrice – the calculated Cost price for the requested service
    • SellPrice – the calculated Sell price for the requested service
    • GeneratedAt – Date and time of performed calculation in ISO 8601 format
    • Status
      • Message – any message describing the success or failure of pricing calculation for current item
      • Code (type: numeric) – the code value indicates success or failure of pricing calculation. The following ranges should be used:
        • >=0 : Successful calculation
        • -1 to -79.999 : Unexpected failure during price calculation. The status message is not user friendly and should be replaced by “Unable to retrieve unit price for product” in the response.
        • -80.000 to -89.999 : Failure during price calculation. The status message is user friendly and can be used in the response.
  • ExchangeRate – Optional. The exchange rate information used for price calculation
    • Currency – The exchange rate currency in 3-letter mnemonic
    • Rate – The exchange rate
    • GeneratedAt – Date and time of exchange rate retrieval