Pricing Engine, Market Indices & Offers in Jules

Product documentation — How Jules models commodity pricing from raw market indices through formula-based contracts to commercial offers, price intelligence, and portal-shared documents.

Table of Contents

1. Overview

2. Price Indices

3. Price Formulas

4. Price Index Prompts

5. Offers & Offered Prices

6. Offer Lifecycle

7. Price Suggestions

8. The Suggestion System (Price Lists)

9. Portal Sharing

10. Shared Suggestions

11. Unexpected Costs

12. Questions (Form Configuration)

13. Key Business Rules

14. Glossary

Overview

Recyclable commodity trading is inherently price-volatile. A tonne of HMS 1&2 purchased in Rotterdam may be priced against the LME Steel Scrap index average for the week of shipment, minus a differential, times a recovery rate. A bale of OCC may be priced against the RISI Paper index for the previous month. Jules is built to handle this complexity natively.

The pricing engine in Jules connects four distinct layers:

Price Indices

A price index is a named market reference value used to determine the base price in formula-based deals. Jules stores indices internally, allowing them to be referenced in price formulas and operation qualities.

What is a price index?

Indices are unique per (value, period) combination — Jules will silently ignore duplicate entries for the same index in the same period.

Common market indices in recyclable commodities trading

Admin note: Price index values must be entered or imported manually per period. There is no automatic market data feed in the current version. Creating a new index via createPriceIndex is idempotent — duplicate (value, period) entries are ignored.

Price Formulas

A price formula is a reusable template that defines how to calculate the final price from one or two market indices. Formulas are selected at the operation quality or offer level, replacing the need to re-enter the calculation logic for each deal.

Formula structure

Every formula follows a mathematical pattern combining:

• Index 1 — the primary market reference

• Index 2 (optional) — a secondary index for blended formulas

• Differential — a fixed premium or discount applied to the index

• Recovery rate — a percentage of the index value applied (e.g., 80% recovery)

• Other costs — additional deductions or additions

• Contango — forward premium for future delivery

Supported formula codes

Index configuration options

When a formula references an index, each index slot has additional configuration:

Practical example

A typical ferrous scrap purchase formula might be:

Price = (LME Steel Scrap — Average M-1, Official) × 78% Recovery — 15 USD/T Other Costs

This formula code would be INDEX_TIMES_RECOVERY_MINUS_OTHER_COSTS, configured with:

• Index 1 = LME Steel Scrap

• Price mode = AVERAGE_M_1

• Price type = OFFICIAL

• Recovery = 78%

• Other costs = 15 USD/T

Price Index Prompts

A price index prompt is a scheduled reference point associated with a specific index. When an operation or offer uses a formula with a CUSTOM_RANGE or specific-day price mode, the prompt defines which exact period or settlement date is used to fix the price.

Prompts are stored in the price_index_to_prompts table, linked to a PriceIndex by indexId. The prompt field contains a human-readable label (e.g., "March 2025 average", "Week 12 settlement") that traders can select from a dropdown when configuring a quality line.

Business meaning: In commodity trading, agreeing on the "quotational period" — the specific window over which index values are averaged to determine the final price — is a critical commercial term. Price index prompts allow your team to pre-configure common quotational periods and reference them consistently across deals, reducing errors and disputes.

Offers & Offered Prices

An offer is a formal commercial proposal sent to a potential counterparty (customer or supplier) before a deal is confirmed as an operation. Offers list the materials you are willing to trade, at what prices, with what logistics terms.

Offer fields

Offered price fields

Each material line within an offer is an offered price:

Note: A single offered price can span multiple incoterms and multiple destination sites. Jules flattens these combinations into separate rows when generating the PDF document, so the counterparty sees a full price matrix per quality, destination, and incoterm.

Offer Lifecycle

Every offer moves through four maturity stages:

Generating a shared offer PDF

Jules can generate a professional PDF of the offer and produce a pre-filled email body for sending to the counterparty. This is triggered by:

• generateSharedOffer — generates the PDF for an existing offer

• createAndGenerateSharedOffer — creates the offer and immediately generates the PDF in one step

• updateAndGenerateSharedOffer — updates the offer and regenerates the PDF

The generated document:

• Uses a configured PDF template (SHARED_OFFER document type)

• Groups offered prices by destination or quality depending on configuration

• Applies rounding rules for quantities and prices

• Triggers any configured outbound webhooks (ON_SHARE_OFFER trigger)

• Returns a url (downloadable PDF link), mailTitle, and mailBody for the email

Renewing offers

The generateUpdatedOffers mutation allows bulk renewal of offers — useful at the start of a new trading period when the same price structure needs to be refreshed with updated dates. Offers are cloned with new dates while preserving their material lines and pricing.

Price Suggestions

When creating an offer or configuring an operation, Jules provides price suggestions — historically derived reference prices to help traders fill in values quickly and consistently.

There are two types of granular price suggestions:

Equipment price suggestions

Equipment price suggestions (EquipmentPriceSuggestion) provide reference prices for specific container equipment types and material grades:

Filtering supports combinations of equipment type, quality, and modalities. Queries using null equipment or quality match all — the system returns suggestions for all equipment types or all grades when no filter is specified.

Service price suggestions

Service price suggestions (ServicePriceSuggestion) provide reference prices for specific services (e.g., inspection, pre-carriage, port handling) by equipment type and material grade:

Business meaning: Service price suggestions help operations teams quickly recall what an inspection costs for a 40' container of HMS at a given port, based on what was actually invoiced in previous deals — reducing the risk of underestimating costs when creating new operations or offers.

The Suggestion System (Price Lists)

Beyond equipment and service-level suggestions, Jules has a broader Suggestion system that generates full price list views — structured grids of target prices per site, quality, incoterm, and destination.

There are three suggestion types:

What a suggestion contains

Each suggestion (whether LocalSuggestion or ExportSuggestion) carries:

For export suggestions, the destination is expressed as a portOfDestination. For local suggestions, it is expressed as a destinationArea.

Business meaning: The price list suggestion view is the trader's starting point before sending an offer or creating a purchase operation. It shows every site they work with, for a given material, with the most up-to-date target prices and capacity context — so they can quickly decide which suppliers to contact, at what price, and how much volume to request.

Portal Sharing

Jules allows internal documents and data to be shared with external counterparties through a client portal. The ShareOnPortal mechanism handles this.

How portal sharing works

Input structure

The shareOnClientPortal mutation takes:

• docType — the type of document being shared (e.g., offer, shipment document)

• associatedObjectType — the object category (LinkedEntityEnum)

• associatedObjectId — the ID of the object being shared

• linkedEntities — a list of { linkedEntity, linkedEntityId } objects defining which companies gain visibility

One shareOnClientPortal call can share a document with multiple companies simultaneously.

Access control note: Portal users are external users with restricted access. They see only the documents explicitly shared with their company. Prices, margins, and internal costs are hidden from portal views.

Shared Suggestions

Shared suggestions are price intelligence packets sent by traders to suppliers via email — a lightweight workflow for sharing buying price targets with a supplier before a formal offer is created.

What is shared

Each shared suggestion includes:

Multiple suggestions can be bundled into a single message, along with a free-text message and a contact recipient at the supplier site.

Tracking shared suggestions

The filteredSharedSuggestions query returns SharedSuggestionsWithTracking records — a full audit trail of every suggestion bundle sent, showing:

Business meaning: Shared suggestions give traders a fast way to "test the market" by sending informal price targets to multiple suppliers simultaneously, track who received what, and then formalize the best responses into actual purchase operations.

Unexpected Costs

Unexpected costs are cost items that arise during or after a shipment that were not part of the original deal structure — things like demurrage, port surcharges, contamination penalties, re-sorting fees, or any other unplanned expense.

Unexpected cost fields

Third-party impact tracking

The thirdPartyImpacts field records which parties ultimately bear this unexpected cost:

A single unexpected cost can have multiple third-party impacts — for example, a demurrage charge may be split between the supplier and the logistics provider.

This tracking feeds directly into margin calculations, ensuring that the profitability of a deal reflects the true economics including post-shipment surprises.

Filtering unexpected costs

Unexpected costs can be filtered by:

• shipmentId — all unexpected costs on a specific shipment

• otherProductIds — filter by cost category

• dateOfCreation date range — costs recognized within a time window

Questions (Form Configuration)

The Questions module manages configurable question fields that appear on various forms throughout Jules. These are not end-user survey questions — they are form field metadata that allows organizations to configure which fields are shown, required, hidden, or reordered on key forms.

What forms can be configured?

Question field properties

Business meaning: The Question module allows operations administrators to tailor Jules forms to their organization's workflows without development work. A company trading only export scrap may hide the domestic-only fields on purchase operations. A company with strict quality inspection requirements may mark certain loading form fields as mandatory that other organizations leave optional.

Key Business Rules

1. Price index uniqueness

A price index is unique per (value, period) combination. Attempting to create a duplicate index for the same name and period is silently ignored — Jules uses an ON CONFLICT DO NOTHING strategy.

2. Formula selection is per quality line

Price formulas are not set at the operation level — they are selected on each individual operation quality or offered price line. This means a single operation can have one quality at a fixed spot price and another quality on an LME-linked formula.

3. Dual-index formulas

Jules supports formulas with two indices (Index 1 and Index 2), each with its own recovery rate, price mode, price type, and prompt. This is used in trades where the final price blends two market benchmarks — for example, a copper-bearing alloy priced partly against LME Copper and partly against LME Lead.

4. Offer PDF generation triggers webhooks

When a shared offer PDF is generated, Jules fires any configured ON_SHARE_OFFER webhooks. This allows integrations with CRM systems, messaging platforms, or custom notification flows to be triggered automatically at the point of sharing.

5. Local offers update goal sale prices

When an offer with marketType = LOCAL is created or updated, Jules automatically creates or updates goal sale prices in the Goals module. This keeps commercial targets in sync with market price discoveries made through the offer workflow.

6. Unexpected costs feed margin calculations

Unexpected costs attached to a shipment are included in margin calculations for the operations on that shipment. The thirdPartyImpacts field determines whether the cost reduces the buy-side margin, the sell-side margin, or is recorded as a provider cost outside the trade margin.

7. Offer bulk renewal

The generateUpdatedOffers mutation supports bulk renewal of offers by date range — useful at the end of a trading month when all offers need to be refreshed. The system clones existing offers with updated dates, preserving all material lines and pricing terms.

8. Shared suggestions are delivered asynchronously

The shareSuggestionsToSupplier mutation does not send the email synchronously. It publishes a message to the shareSuggestions RabbitMQ queue, and the worker processes it asynchronously. This means the API call returns immediately, and the email is delivered in the background. The delivery status is tracked in SharedSuggestionsWithTracking.

9. Question configuration is per organization and per form

Each organization can independently configure which questions appear on which forms, what order they appear in, which are mandatory, and which are hidden. This configuration is resolved per formId + formType combination, giving granular control at the form-instance level.

10. Equipment and service suggestions support null-wildcard matching

When querying equipment or service price suggestions without specifying a filter, Jules returns records where the filtered field is null (i.e., applies to all). This means a suggestion with equipment = null matches all equipment types, serving as a generic fallback.

Glossary