Product Guide

To get a foundation for how products are structured and their different features the product structure user guide is a good place to start. This section will handle how to work with products from the API and how products are constructed as entities or objects.

Product type and object structure

The product type defines how many charge plans and charges a product has but all products contain a list of at least one charge plan which in turn contains a list of at least one charge. The four product types consist of:

• Simple: Can have only one charge plan with one charge

• MultipleCharges: Can have only one charge plan with multiple charges

• MultipleChargePlans: Can have multiple charge plans with only one charge each

• Full: Can have multiple charge plans with multiple charges

Simplified JSON Example of the structure of a simple product response:

"product": {
    "productNumber": "P-000001",
    "chargePlans": [
        {
            "chargePlanNumber": "CP-000001",
            "charges": [
                {
                     "chargeNumber": "C-000001",
                     "priceDetails": [...]
                }
            ]
        }
    ]
}

Simplified JSON Example of the structure of a Full product response:

"product": {
    "productNumber": "P-000001",
    "chargePlans": [
        {
            "chargePlanNumber": "CP-000001",
            "charges": [
                {
                     "chargeNumber": "C-000001",
                     "priceDetails": [...]
                },
                {
                     "chargeNumber": "C-000002",
                     "priceDetails": [...]
                }
            ]
        },
        {
            "chargePlanNumber": "CP-000002",
            "charges": [
                {
                     "chargeNumber": "C-000003",
                     "priceDetails": [...]
                },
                {
                     "chargeNumber": "C-000004",
                     "priceDetails": [...]
                },
                {
                     "chargeNumber": "C-000005",
                     "priceDetails": [...]
                }
            ]
        },
    ]
}

Charge plans

The charge plan as an object mainly serves as a container for charges within the product structure and contains no specifically important fields other than general ones. Nonetheless, it is an important reference for order products (products on an order) linking the order products to its initial product and charges.

Charges

Charges are the most important part of the product and hold the most important information which makes them more complex with a number of important fields.
One way of looking at charges is by separating its fields into different categories.

“General fields”, “charge configuration fields”, and “financial fields”

In the following JSON example, the fields are sorted by each category.

{ 
    //"General fields" 
    "name": "string", 
    "customFields": {}, 
    "externalCRMId": "string", 
    "externalERPId": "string", 
     
    //charge configuration fields 
    "chargeType": "Recurring", 
    "model": "Quantity", 
    "unit": "units", 
    "pricePeriod": "Monthly, 
    "defaultQuantity": 0, 
    "usageRating": "Sum", 
    "measurementsRule": 0, 
    "PriceDetails": [ 
        { 
            "tier": 0, 
            "currency": "EUR", 
            "price": 10, 
            "customFields": {}, 
            "description": "string", 
            "isInfinite": false, 
            "priceBase": "Flat", 
            "toQuantity": 0 
        } 
    ], 
 
    //Financial fields 
    "billingPeriod": "Monthly", 
    "periodAlignment": "None", 
    "billingDay": "None", 
    "billingTiming" "InAdvance" 
    "specificBillingDay": 0, 
    "taxIncluded": false, 
    "revenueRecognition": "Recognized monthly over time", 
    "taxTemplate": "Sweden standard", 
    "deferredRevenueAccount": "2970", 
    "recognizedRevenueAccount": "3000" 
}

General fields

These are general fields and features for a charge. Read more about custom fields and external ids in the developer resources section

Charge configuration fields

These are fields that define what type of charge and model it is, as well as fields that are connected to the type or model and its price details.

The charge type will dictate what price model can be and the combination of what type and what model a charge has and dictates what values will define the charge. The matrixes below show the relationship between the fields and what type and model a charge has.

Most values can be set even if they have no importance for the type and model and will be ignored when the charge is used. If a value would be prohibited to be set in a specific case or required this will generally be stated in the documentation or throw a validation error on the request.

Financial fields

These fields are connected to how the charge will be billed on an order and act as default values for the order product charge (the charge of an order) when it’s created based on the charge.

Default charge values

In the Younium UI Settings > Products > Product settings default values for charges can be specified. If a field is left out or set to null in the request, will set it to the default value if one is defined. Noteworthy fields that can be null if no default value is present revenueRecognition, taxTemplate, deferredRevenueAccount, and recognizedRevenueAccount. In some use cases, this is preferred and these values are set when the order product charge is created.

Price details

At least one price detail is required on a charge (With the exception of a rated usage charge which should have none) and contains the information of the charge's price. The price model will dictate the price detail structure and relates primarily to two fields on the price detail object: tier and currency.

The tier field is a zero-bases-index for a specific currency and only one tier index can exist for each currency. If a charges model is flat or quantity there can only be one price detail per currency and the tier will always be 0. So the tier index is more important to consider if the model is volume or tiered where the price detail is grouped by currency and ordered by the tier.

When adding multiple price detail tiers to a charge there are some rules to consider to avoid validation errors:

• The tier index is required to start with 0 and increment by 1 for each tier. Skipping an index will cause a validation error.

• toQuantity must be larger than the toQuantityof the previous tier. fromQuantity (not settable) will be calculated based on this.

• toQuantity should be set for each tier with the exception of the last tier if isInfinite is true. if toQuantity is 0 or less or not set it will take the fromQuantity value or 0 if tier is 0.

• isInfinite will only affect the last tier and will override toQuantity

• If a currency is not specified the base currency of the legal entity will be applied by default.

Product category

Category for products to eg. simplify reports. also used if the product is a stock product. this field will reference the product categories found in settings > products > product categories where it’s possible to create new ones.