Describes how we work with shipping costs

Calculating shipping costs can be a real headache. Complicated agreements
with tons of exceptions, added fees and penalty conditions.

Cost API

In order to understand the way cost calculations work, you should be aware of the following
points:
Rules of Transport Agreements

  - The cost from a price interval is the `baseCost`
  - `baseCost` = `fixedCost` + `variableCost`
  - `variableCost` = `unitCost` x `costUnit` (points to value in freight object) 



Within each addedFeeGroup, only one fee can be matched
Within each penaltyFeeGroup only one fee can be matched
This means that declaring fees within the same group is mainly intended for the same fee but at different levels, such
as a different fuel surcharge for different countries.




Each fee group (both penalty and added) is required to have descriptions in both Swedish and English.
Each fee inside a group is required to have descriptions in both Swedish and English.




Each price group, added fee group and penalty fee group is responsible for its own
geographical conditions
This means that you need to explicitly specify that DestinationCountryCode should be one of ["SE", "FI"] if a price group
can be used for shipments to Sweden and Finland
Not specifying a country condition is the same as allowing all countries




Actual Golang errors are reserved to functional errors, such as our LESS comparison not working properly
Any error due to that a freight object simply cannot be used with an agreement are returned using the result.Status




Both added and penalty fees are able to be of the type MULTIPLY which means that the fee amount is interpreted as a percentage to multiply the base cost with
The only place where the amount in the fee object is converted from a percentage to the resulting amount is in the function CombineCostAndFees




In order to minimize the insertion of invalid transport agreements, the validation function is intended to serve as a final check
Despite this, it is always best to try the agreement for real in limited scale before rolling it out to large-scale production




No UUID value may appear twice in the same agreement
No code value may appear twice in the same agreement



Creating a Digital Transport Agreement
These are the steps you should follow when creating a digital transport agreement.

Receive agreement file: First you need to receive the agreement file from the
user. They have the ability to upload the agreement to Scope (which we should add a Slack notification for).
Find references to additional content: Read through the agreement and look for any loose mentions of
penalty or added fees. Very often they are defined in other documents that are not part of the actual agreement.
Outline structure: Create the 'shell' of the agreement by structuring the top layers - price groups, added fee groups and penalty fee groups.
Fill in content: Now translate the data in the agreement to the structure required by us. The easiest way to do this is to first just get one price group done correctly, and
then use that as a base for future ones.
Clean up identifiers: Now you should use a function for ensuring you have clean identifiers and codes, as this is a requirement for the agreement. To do this, you can use transportation.HarmonizeAgreement function which checks and, if needed, updates the identifies and/or codes in the agreement and returns the 'cleaned' version.
Validate agreement: Before inserting, it is always good to see if the agreement is correctly formatted. For this purpose, you can use the transportation.Validation endpoint. It is also built in to transportation.InsertDigitalTransportAgreement.
View agreement: Now you should try to have the agreement inserted for a retailer locally or in a preview environment
and make sure it is displayed properly by going to the agreement page. To do this, navigate to tms/transportAgreement/[id], replacing [id] with the specific Agreement ID. Once you have successfully inserted the agreement, you can interact with it through the Digital Transport Agreement Explorer.
Test agreement: Before marking the creation of the agreement as completed, you should try a few cases where you
know what the cost should be, and calculate them using the cost calculator form on the agreement page to ensure it is performing
as expected.


Inserting Digital Transport Agreements
When inserting a digital transport agreement, you should be aware of the following:

Set ValidFrom and ValidTo: These fields are required and defines the time period the agreement is valid for. By definition, there should not be any overlap between agreements for the same transport method.
These fields are used when calculating costs for Invoice Control by mapping to the valid agreement for the specific invoice date.
One Active agreement per transport method: The Active flag indicates which agreement out of many that should be used for a specific transport method.
By definition, an active agreement should be the agreement that is valid for the current date. The Checkout will always use the active agreement for the transport method to calculate the cost,
whereas Invoice Control does not care about the active flag and will instead use the agreement that is valid for the specific invoice date.


<MermaidChart
heading="Anatomy of cost"
chart={`graph TD
A(Total Cost) --> B(Base Cost)
A --> C(Added Fee Sum)
A --> D(Penalty Fee Sum)
B --> E(Fixed Cost)
B --> F(Variable Cost)
F --> M(Unit Cost x Cost Unit Value)
C --- G(Added Fee)
G --- H(Added Fee)
H --- I(Added Fee)

D --- J(Penalty Fee)
J --- K(Penalty Fee)
K --- L(Penalty Fee)

style A stroke-width:3px,fill:transparent,color:inherit,stroke:text;
style B stroke-width:2px,fill:transparent,color:inherit,stroke:#24D583;
style C stroke-width:2px,fill:transparent,color:inherit,stroke:#269fd7;
style D stroke-width:2px,fill:transparent,color:inherit,stroke:#E52E44;
style E stroke-width:1px,fill:transparent,color:inherit,stroke:#24D58399;
style F stroke-width:1px,fill:transparent,color:inherit,stroke:#24D58399;
style M stroke-width:1px,fill:transparent,color:inherit,stroke:#24D58399;
style G stroke-width:1px,fill:transparent,color:inherit,stroke:#269fd799;
style H stroke-width:1px,fill:transparent,color:inherit,stroke:#269fd799;
style I stroke-width:1px,fill:transparent,color:inherit,stroke:#269fd799;
style J stroke-width:1px,fill:transparent,color:inherit,stroke:#E52E4499;
style K stroke-width:1px,fill:transparent,color:inherit,stroke:#E52E4499;
style L stroke-width:1px,fill:transparent,color:inherit,stroke:#E52E4499;

`}
/>
Noteworthy about the cost anatomy

The Base Cost, the Added Fee Sum and the Penalty Fee Sum should always add up to the Total Cost

This means that in the case of a penalty fee having the operation REPLACE, the Base Cost and the Added Fee Sum will be set to 0.
In this case, we will still include the matched fees and cost from the price group in the more detailed parts of the struct




Which endpoint to use?
Follow this guide to find out which endpoint you should use.
<Quiz
Questions={
[
{
Key: "ext1",
Text: "Is the call made from an external system?",
Options: ["Yes", "No"]
},
{
Key: "freightobj",
Text: "How many freight objects?",
Options: ["One", "Many"]
},
{
Key: "transportmetho",
Text: "How many transport methods should be calculated for?",
Options: ["One", "Many"]
},
{
Key: "noAgree",
Text: "How should agreements be used?",
Options: ["Should be fetched", "Provided in call"]
},
]
}>
<Result RequiredAnswers={["No","One","One","Provided in call"]}>
You should use 

<Result RequiredAnswers={["Yes",["One","","Many"],"",""]}>
You should use 

<Result RequiredAnswers={["No","One","Many","Should be fetched"]}>
Use 

<Result RequiredAnswers={["No","One","Many","Provided in call"]}>
Use 

<Result RequiredAnswers={["No","Many","One","Should be fetched"]}>
If using from Scope, use .
From SkrymR, you should instead iterate over the freight objects and call 

<Result RequiredAnswers={["No","Many","One","Provided in call"]}>
Iterate over the freight objects and call 

<Result RequiredAnswers={["No","Many","Many","Should be fetched"]}>
If using from Scope, use .
From SkrymR, you should instead iterate over the freight objects and call 

<Result RequiredAnswers={["No","Many","Many","Provided in call"]}>
Iterate over the freight objects and call 


Iterate over the freight objects and call 

