Order Structure in Koncili
A marketplace order may seem simple—the customer buys, pays, and receives—but in practice, it involves multiple financial, fiscal, and operational elements.
Koncili consolidates and normalizes all data across different marketplaces, regardless of their varying levels of detail, ensuring a unified and standardized view for every order within the system.
Below are the core elements that compose an order:
Order Items
Each order consists of one or more products (SKUs - Stock Keeping Unit), which carry their own attributes:
- Product name and description
- SKU and internal code
- Quantity
- Unit price
- Applied discounts
- Linked campaign or promotion
📦 Product Structure Example
An order may contain several products with different commercial conditions, even if they belong to the same transaction.
The example below illustrates common scenarios such as order-level free shipping and item-level promotional discounts.
| Item | SKU | Product | Qty | Unit Price | Campaign | Discounts | Final Price |
|---|---|---|---|---|---|---|---|
| 1 | SKU-001 | White T-shirt | 1 | $ 59.90 | No discount | $ 0.0 | $ 59.90 |
| 2 | SKU-002 | Jeans | 2 | $ 129.90 | Free shipping | $ 0.0 | $ 259.80 |
| 3 | SKU-100 | Shampoo 300ml | 1 | $ 30.00 | "Buy One, Get One 50% Off" | $ 0.0 | $ 15.00 |
| 4 | SKU-100 | Shampoo 300ml | 1 | $ 30.00 | Regular price | $ 0.0 | $ 30.00 |
| 5 | SKU-156 | Soap | 1 | $ 2.00 | Discount | $ 0.50 | $ 1.50 |
Notes:
📌 The same SKU may appear more than once in an order with different conditions (e.g., one with a discount and another without).
📌 Some SKUs may be part of a campaign while others are not, such as free shipping on one specific SKU or a 50% discount on the second unit.
Campaigns and Discounts
Campaigns can be applied at the order level or the individual product level.
These promotions must be considered during reconciliation, as they directly impact the net settlement amount.
📘 Example - Item-level discount:
Order #5678 contains:
- 1x Shampoo (SKU-100) without discount
- 1x Shampoo (SKU-100) with "Buy One, Get One 50% Off" promotion
📘 Example - Order-level discount:
Order #9876 with 3 different products → the customer receives free shipping upon reaching a minimum purchase value.
📌 Koncili identifies whether discounts affect the entire order or only specific products, adjusting the value reconciliation accordingly.
Payment Methods
An order can have one or multiple payment methods, and any of them may involve installments.
During checkout, a payment attempt might fail (e.g., credit card declined), yet the order can still be completed using an alternative method.
📘 Example: Order #91011
- Credit Card (declined)
- Second Card (approved in 3 installments)
- Pix - Brazil's instant payment system (instant payment for the remaining balance)
📌 Koncili records the final approved method but maintains the attempt history if provided by the marketplace.
📌 It is important to distinguish payment method from settlement: a payment may be split into installments, but the settlement might be paid in full depending on the marketplace agreement.
Installments
Installments are linked to the payment method and represent one of the primary differences between the customer's payment and the settlement to the seller.
In Brazil, customers frequently pay for purchases in multiple interest-free installments (parcelas). Marketplaces may choose to settle these funds to the seller following the customer's payment schedule or offer an "anticipation" (early payout) for a fee.
📘 Example:
- Customer pays in 6 installments of $ 50.00
- The marketplace may:
- Settle in 6 installments of $ 50.00, mirroring the customer's payment, or
- Settle $ 280.00 upfront (lump sum), deducting an anticipation or "early liquidation" fee.
📌 In its reconciliations, Koncili considers what was effectively settled to the seller, regardless of how the customer paid.
Invoices (Notas Fiscais - NFs)
Invoices serve as the fiscal control points for an order.
A single order may involve one or multiple invoices, depending on the shipping logistics and the seller’s operational workflow.
Common scenarios:
- Multiple Invoices: Different parts of the same order shipped on separate dates.
- Incorrect Invoice (Canceled and Replaced): Tax, CFOP (Tax Operation Code), or valuation errors requiring the original invoice to be voided and re-issued.
- Supplementary Invoice: Used to provide missing fiscal information or adjust tax values.
- Reversal or Return Invoice: Issued for returns or cancellations occurring after the initial invoice (NF) was generated.
📌 For Koncili, the invoice is the definitive milestone that marks an order as invoiced (faturado) and eligible for reconciliation and ready for reconciliation.
Order Status
Despite minor variations between marketplaces, an order's lifecycle generally follows this sequence:
| Stage | Description |
|---|---|
| New | Order created in the marketplace. |
| Paid | Payment confirmed by the customer. |
| Invoiced | Invoice (NF) issued. |
| In Preparation | Products being picked and packed. |
| Shipped / In Transit | Order handed over to the carrier. |
| Delivered | Product received by the customer. |
📌 Koncili uses the order status to determine if it is ready for financial reconciliation.
An order marked as "Paid" but not "Invoiced" indicates that the operation has not yet triggered a settlement.
Cancellations
Cancellations directly impact invoices, payments, and reconciliations.
They can occur at two levels:
- Partial (item-level): Only one specific product is canceled.
- Total (order-level): The entire order is canceled.
- Late Cancellation: Occurs after the goods have been shipped, requiring a return invoice.
📘 Partial Example: Order #151617 - 1 Laptop + 1 Backpack → customer cancels only the backpack.
📘 Total Example: Order #202122 - 2 products → customer cancels the entire order before shipping; the seller does not issue an invoice, and the marketplace voids the payment.
📌 Cancellations generate entries such as RETURN_SALE or DEVOLUTION, which Koncili uses to adjust the financial balance.
Particularities of Installments and Settlements
In installment sales, the customer pays over time, but the settlement to the seller may be anticipated by the marketplace (minus an anticipation fee).
📘 Example: Sale: $ 1,000.00 in 10 installments → marketplace anticipates the payment and settles $ 950.00 upfront ($ 50.00 fee).
📌 Koncili always considers the actual amount settled, not the total installment value.
📌 The ERP should record the difference as a financial expense, classifying it according to the pre-aligned requirements between the finance and accounting departments.