Customer Discounts Guide

Understanding how customer-specific discounts work in the Attivita API.

Overview

The Attivita API automatically applies customer-specific discounts based on your account's discount package. This means:

• 💰 Prices shown in API responses reflect your final price
• 🔄 Discounts are applied automatically during order creation
• 📊 No manual calculation needed
• 🏷️ Transparent pricing across all endpoints

How Discounts Work

Discount Package Structure

Each customer account may have an associated discount package that defines:

{
  "discountPackage": {
    "name": "Premium Partner 2024",
    "discounts": [
      {
        "category": "Microsoft",
        "percentage": 15
      },
      {
        "category": "Adobe",
        "percentage": 10
      },
      {
        "category": "Default",
        "percentage": 5
      }
    ],
    "validFrom": "2024-01-01",
    "validUntil": "2024-12-31"
  }
}

Automatic Application

When you request products or create orders, discounts are applied automatically:

Products Endpoint

// Request
GET /api/products

// Response shows discounted prices
[
  {
    "name": "Microsoft Office 2021",
    "price": 212.49,        // ← Your discounted price (15% off)
    "listPrice": 249.99,    // ← Original price
    "discount": 15,         // ← Your discount percentage
    ...
  }
]

Orders Endpoint

// Request
POST /api/orders
{
  "products": [
    {
      "productId": "507f1f77bcf86cd799439011",
      "amount": 2
    }
  ]
}

// Response
{
  "items": [
    {
      "product": "Microsoft Office 2021",
      "quantity": 2,
      "price": 212.49,      // ← Discounted unit price
      "subtotal": 424.98    // ← Calculated with discount
    }
  ],
  "subTotal": 424.98,
  "discountTotal": 75.00,   // ← Total discount amount
  "grandTotal": 424.98
}

Understanding Price Fields

In Product Responses

Field	Description	Example
price	Your final price after discounts	212.49
oldPrice	Previous price (if changed)	229.99
listPrice	Original price before discounts	249.99

In Order Responses

Field	Description	Example
items[].price	Discounted unit price	212.49
items[].subtotal	Line total with discount	424.98
subTotal	Order total before taxes	424.98
discountTotal	Total discount amount	75.00
grandTotal	Final total (may include VAT)	505.73

Discount Calculation Examples

Example 1: Single Product Order

// Product list price: €100.00
// Your discount: 20%
// Quantity: 3

const calculation = {
  listPrice: 100.00,
  discount: 0.20,
  quantity: 3,
  
  unitPrice: 100.00 * (1 - 0.20),        // €80.00
  subtotal: 80.00 * 3,                   // €240.00
  discountAmount: (100.00 - 80.00) * 3,  // €60.00
  
  // For German customers (19% VAT)
  vat: 240.00 * 0.19,                    // €45.60
  grandTotal: 240.00 + 45.60             // €285.60
};

Example 2: Mixed Category Order

// Your discounts:
// - Microsoft: 15%
// - Adobe: 10%
// - Others: 5%

const order = {
  items: [
    {
      product: "Microsoft Office",
      listPrice: 249.99,
      discount: 0.15,
      quantity: 1,
      finalPrice: 212.49  // 249.99 * 0.85
    },
    {
      product: "Adobe Creative Cloud",
      listPrice: 599.99,
      discount: 0.10,
      quantity: 1,
      finalPrice: 539.99  // 599.99 * 0.90
    },
    {
      product: "Antivirus Software",
      listPrice: 49.99,
      discount: 0.05,
      quantity: 2,
      finalPrice: 94.98   // (49.99 * 0.95) * 2
    }
  ],
  
  subTotal: 847.46,      // Sum of final prices
  discountTotal: 107.50, // Total saved
  grandTotal: 847.46     // Before VAT
};

VAT Handling

German Customers

19% VAT is automatically added to orders for German customers:

{
  "subTotal": 100.00,
  "vatAmount": 19.00,
  "grandTotal": 119.00
}

International Customers

VAT handling depends on your location and business status. Contact support for details.

Checking Your Discount Status

While there's no direct endpoint to check your discount package, you can:

1. Compare Prices: Check product prices against known list prices
2. Review Orders: The discountTotal field shows applied discounts
3. Contact Support: For detailed discount package information

Special Considerations

Volume Discounts

Some products may have additional volume-based discounts:

// Standard discount: 10%
// Volume discount: Additional 5% for 10+ units

{
  "quantity": 15,
  "baseDiscount": 0.10,
  "volumeDiscount": 0.05,
  "totalDiscount": 0.15,  // Combined discount
  "finalPrice": listPrice * 0.85 * quantity
}

Promotional Pricing

During promotions, you receive the better of:

• Your customer discount
• The promotional discount

// Your discount: 10%
// Promotion: 15% off
// You get: 15% (the better deal)

Subscription Products

Subscription products may have different discount structures:

{
  "product": "Microsoft 365",
  "billingCycle": "annual",
  "listPrice": 99.99,
  "yourPrice": 84.99,  // With discount
  "monthlyEquivalent": 7.08
}

Best Practices

1. Don't Cache Prices Too Long

Prices and discounts can change:

const PRICE_CACHE_TTL = 3600000; // 1 hour max

async function getProductPrice(productId) {
  const cached = priceCache.get(productId);
  
  if (cached && Date.now() - cached.time < PRICE_CACHE_TTL) {
    return cached.price;
  }
  
  const product = await api.getProduct(productId);
  priceCache.set(productId, {
    price: product.price,
    time: Date.now()
  });
  
  return product.price;
}

2. Verify Prices at Order Time

Always use current prices when creating orders:

async function createOrderWithPriceCheck(items) {
  // Get current prices
  const products = await api.getProducts();
  const priceMap = new Map(products.map(p => [p._id, p.price]));
  
  // Verify prices haven't changed significantly
  for (const item of items) {
    const currentPrice = priceMap.get(item.productId);
    const expectedPrice = item.expectedPrice;
    
    if (Math.abs(currentPrice - expectedPrice) > 0.01) {
      throw new Error(`Price changed for ${item.productId}`);
    }
  }
  
  // Create order
  return api.createOrder(items);
}

3. Display Savings to Users

Show customers how much they're saving:

function formatPriceDisplay(product) {
  const savings = product.listPrice - product.price;
  const savingsPercent = (savings / product.listPrice) * 100;
  
  return {
    listPrice: `€${product.listPrice.toFixed(2)}`,
    yourPrice: `€${product.price.toFixed(2)}`,
    savings: `€${savings.toFixed(2)}`,
    savingsPercent: `${savingsPercent.toFixed(0)}%`,
    display: `€${product.price.toFixed(2)} (Save ${savingsPercent.toFixed(0)}%)`
  };
}

Troubleshooting

Prices Seem Wrong?

1. Check Product Categories: Different categories may have different discounts
2. Verify Account Status: Ensure your account is active
3. Review Order Dates: Discounts may have expiration dates
4. Contact Support: For discount package verification

No Discount Applied?

Possible reasons:

• Product not eligible for discounts
• Discount package expired
• Account status issue
• Special pricing already applied

FAQ

Q: Can I see my discount percentage via API?

A: Not directly, but you can calculate it by comparing the price field with known list prices.

Q: Do discounts stack?

A: No, only one discount package applies per customer. You get either your negotiated discount or promotional pricing, whichever is better.

Q: Are discounts guaranteed?

A: Discounts are subject to your agreement with Attivita GmbH and may change with notice.

Q: How are multi-currency orders handled?

A: All prices in the API are in EUR. Currency conversion is handled separately.

Next Steps

• Review Order Creation documentation
• Implement Best Practices
• Set up Webhook Notifications for price changes