Order Invoice
The invoicing system is designed to dynamically generate invoices for orders made within Gifthub ecosystem. It accounts for various complexities such as discounts, fees, currency exchanges, and groupi
Components
1. Order Shop Product
Defines the structure of the product involved in the transaction, including details like SKU, pricing, quantity, and any customer-specific deals.
Attributes:
SKU: Unique identifier for the product.
Quote: The requestd quote of the product.
Quantity: The requested quanity for the product.
2. Exchange Rates
Stores information about currency exchange rates, including the base currency, target currency, rate, and the date when the rate was last modified.
3. Invoice Items
Generated for each line item in the invoice, including these types:
main-productdiscountsfeeexchange-base-currencyexchange-target-currencyorder-commissionitem-total
4. Invoice Records
Aggregates invoice items by SKU, facilitating group-specific operations like total calculation.
5. Order Invoice
The final structure representing the complete invoice, including status, payment method, grouped items, and the total amount.
We use the structure above in two invoices per order.
Wallet Invoice: is the breakdown of the amount that is to be reduced from customer wallet in the system. (
invoicefield)Retail Invoice: is the breakdown of the amount that is used when calculating the retail invoice to be paid by the customer. (
retailInvoicefield)
Invoices Shared Structures
InvoiceRecord
sku
string
items
InvoiceItem[]
total
Map<CurrencyCode, Number>
InvoiceItem
description
string
metaData
object
type
main-productdiscountsfeeexchange-base-currencyexchange-target-currencyorder-commissionitem-total
effect
object
{
currency: CurrencyCodes,
amount: number,
}Wallet Invoice
Everything in the wallet invoice is exchanged to wallet currency. Here is the workflow of generating the wallet invoice per order:
Main product: For each product in the order, we generate invoice item for the main product.
Generate Exchange Invoices: If the wallet currency differs from the product base currency, generate additional invoice items to account for currency exchange.
Apply Customer Wallet Deal : We add all the related adjustments based on the customer’s wallet deal for each specific product to the invoice.
Group products: We then group all added items to the invoice per specific product.
Generate Invoice: Compile the final invoice, summarizing the totals of all groups (products).
If there is a percentage mode in the adjustment amounts it’ll get applied to the Main product after exchange
Wallet Invoice Structure
records
InvoiceRecord[]
status
pendingpaid
paymentMethod
bank-transferbalance
wallet
CurrencyCode
total
number
Retail Invoice
Everything in the retail invoice is exchanged to retail currency. Here is the workflow of generating the retail invoice per order:
Product Total: For each product in the order, we generate invoice item for the total amount of that product calculated in the wallet invoice in wallet currency
Generate Exchange Invoices: If the retail currency differs from the wallet currency, generate additional invoice items to account for currency exchange.
Apply Customer Retail Deal : We add all the related adjustments based on the customer’s retail deal for each specific product to the invoice.
Group products: We then group all added items to the invoice per specific product.
Generate Invoice: Compile the final invoice, summarizing the totals of all groups (products).
If there is a percentage mode in the adjustment amounts it’ll get applied to the product total after exchange
records
InvoiceRecord[]
paymentMethod
bank-transferbalance
currency
CurrencyCode
total
number
Example
Given a single product order:
CustomerA has the below table as its deal with Gifthub for Product1.
retailCurrency → IRT
walletCurrency → EUR
039-208-range
2
50
DKK
Wallet Deal
Type
Mode
Amount
discount
percentage
-2
fee
fixed
1
commission
percentage
6
Retail Deal - deal items
fee
fixed
45,000
commission
percentage
6
Generated Wallet Invoice
Product1
main-product
DKK
100
Exchange DKK to EUR
EXCHANGE_TARGET_CURRENCY
DKK
-100
Exchange DKK to EUR
EXCHANGE_BASE_CURRENCY
EUR
13.39
Discount (2%)
DISCOUNT
EUR
-0.26
Fee
FEE
EUR
2
Commission
COMMISSION
EUR
0.8
Total
EUR
15.93
Generated Retail Invoice
Product1 Total
product-total
EUR
15.93
Exchange EUR to IRT
EXCHANGE_TARGET_CURRENCY
EUR
-15.93
Exchange EUR to IRT
EXCHANGE_BASE_CURRENCY
IRT
998,811
Fee
FEE
IRT
90,000
Commission
COMMISSION
IRT
59,928
Total
IRT
1,148,739
JSON Response
{
// ... rest of order
"invoice": {
"status": "pending",
"paymentMethod": "balance",
"records": [
{
"sku": "039-208-range",
"items": [
{
"description": "SUPER_GEVEKORTET_DK",
"metaData": {
"quantity": 2,
"quote": 50
},
"type": "main-product",
"effect": {
"currency": "DKK",
"amount": 100
}
},
{
"description": "Even out target currency: DKK",
"metaData": {
"targetCurrency": "DKK",
"rate": 7.464285714285714,
"modifiedDate": {
"_seconds": 1716120001,
"_nanoseconds": 188000000
},
"baseCurrency": "EUR"
},
"type": "exchange-target-currency",
"effect": {
"currency": "DKK",
"amount": -100
}
},
{
"description": "Payment in base currency: EUR",
"metaData": {
"targetCurrency": "DKK",
"rate": 7.464285714285714,
"modifiedDate": {
"_seconds": 1716120001,
"_nanoseconds": 188000000
},
"baseCurrency": "EUR"
},
"type": "exchange-base-currency",
"effect": {
"currency": "EUR",
"amount": 13.39
}
},
{
"description": "Discount",
"metaData": {
"amount": -2,
"adjustmentMode": "percentage"
},
"type": "discount",
"effect": {
"currency": "EUR",
"amount": -0.26
}
},
{
"description": "Fee",
"metaData": {
"amount": 1,
"adjustmentMode": "fixed"
},
"type": "fee",
"effect": {
"currency": "EUR",
"amount": 2
}
},
{
"description": "Commission",
"metaData": {
"amount": 6,
"adjustmentMode": "percentage"
},
"type": "order-commission",
"effect": {
"currency": "EUR",
"amount": 0.8
}
}
],
"total": {
"DKK": 0,
"EUR": 15.93
}
}
],
"wallet": "EUR",
"total": 15.93
},
"retailInvoice": {
"paymentMethod": "bank-transfer",
"records": [
{
"sku": "039-208-range",
"items": [
{
"description": "Product item total",
"metaData": {
"sku": "039-208-range"
},
"type": "product-total",
"effect": {
"currency": "EUR",
"amount": 15.93
}
},
{
"description": "Even out target currency: EUR",
"metaData": {
"targetCurrency": "EUR",
"rate": 0.00001594896331738437,
"modifiedDate": {
"_seconds": 1716120001,
"_nanoseconds": 187000000
},
"baseCurrency": "IRT"
},
"type": "exchange-target-currency",
"effect": {
"currency": "EUR",
"amount": -15.93
}
},
{
"description": "Payment in base currency: IRT",
"metaData": {
"targetCurrency": "EUR",
"rate": 0.00001594896331738437,
"modifiedDate": {
"_seconds": 1716120001,
"_nanoseconds": 187000000
},
"baseCurrency": "IRT"
},
"type": "exchange-base-currency",
"effect": {
"currency": "IRT",
"amount": 998811
}
},
{
"description": "Commission",
"metaData": {
"amount": 6,
"adjustmentMode": "percentage"
},
"type": "order-commission",
"effect": {
"currency": "IRT",
"amount": 59928
}
},
{
"description": "Fee",
"metaData": {
"amount": 45000,
"adjustmentMode": "fixed"
},
"type": "fee",
"effect": {
"currency": "IRT",
"amount": 90000
}
}
],
"total": {
"EUR": 0,
"IRT": 1148739
}
}
],
"currency": "IRT",
"total": 1148739
}
// ... rest of order
}Last updated