Calculate charges, fees, and discounts for product purchases with real-time pricing

Charges API

The Charges API calculates the total cost, discounts, taxes, and fees for purchasing products from the Starship catalog. It provides real-time pricing with multi-currency support and client-specific discount rates.

Overview

The Charges API processes complex pricing calculations including:

Base product costs
Volume discounts for bulk purchases
Client-specific discount rates based on agreements
Currency conversion with live forex rates
Tax calculations including GST where applicable
Handling fees and processing charges

All charge calculations are cached for 5 minutes to improve performance and ensure consistent pricing during the purchase flow.

Calculate Product Charges

Calculate the total charges, fees, and discounts for purchasing a specific product.

Endpoint

POST /api/v1/products/{id}/charges

Authentication: Bearer token required

Path Parameters

Parameter	Type	Required	Description
`id`	number	Yes	Product ID (must exist in catalog)

Request Body

{
  "denomination": 100.00,
  "quantity": 2,
  "wallet_id": 123
}

Field	Type	Required	Validation	Description
`denomination`	number	Yes	Min: 0.01, Max: 1,000,000,000	Purchase amount per unit
`quantity`	number	Yes	Min: 1	Number of units to purchase
`wallet_id`	number	No	Must exist for client	Specific wallet for payment (optional)

Response

Success Response (200 OK)

{
  "non_discounted_total": 200.00,
  "discount_amount": 5.00,
  "total_amount": 195.00,
  "discount": 2.5,
  "gst_amount": 35.10,
  "total_payable": 230.10,
  "max_quantity": 50,
  "net_amount": 195.00,
  "handling_fee_amount": 0.00,
  "charges_details": {
    "source_currency": "USD",
    "destination_currency": "USD",
    "forex_rate": null,
    "conversion_fee": null
  }
}

Response Fields

Field	Type	Description
`non_discounted_total`	number	Total cost before any discounts (denomination × quantity)
`discount_amount`	number	Total discount applied in currency units
`total_amount`	number	Amount after discount, before taxes and fees
`discount`	number	Discount percentage applied
`gst_amount`	number	Tax amount (GST/VAT where applicable)
`total_payable`	number	Final amount to be charged
`max_quantity`	number	Maximum allowed quantity for this product/client
`net_amount`	number	Net amount after all calculations
`handling_fee_amount`	number	Additional processing/handling fees
`charges_details`	object	Detailed breakdown of charge calculation

Charges Details Object

Field	Type	Description
`source_currency`	string	Product's base currency (e.g., "USD")
`destination_currency`	string	Wallet/payment currency (e.g., "EUR")
`forex_rate`	number	Exchange rate applied (null if same currency)
`conversion_fee`	number	Currency conversion fee (null if same currency)

Examples

# Basic charge calculation
curl -X POST "{{host}}/api/v1/products/1001/charges" \
  -H "Authorization: Bearer your_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "denomination": 100.00,
    "quantity": 2
  }'

# With specific wallet for multi-currency
curl -X POST "{{host}}/api/v1/products/1001/charges" \
  -H "Authorization: Bearer your_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "denomination": 50.00,
    "quantity": 5,
    "wallet_id": 123
  }'

# Bulk purchase calculation
curl -X POST "{{host}}/api/v1/products/1001/charges" \
  -H "Authorization: Bearer your_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "denomination": 25.00,
    "quantity": 20
  }'

Error Responses

Validation Errors

400 Bad Request - Invalid denomination

{
  "error": "invalid request body"
}

400 Bad Request - Validation failed

{
  "error": {
    "message": "validation failed",
    "details": "Denomination: must be at least 0.01"
  }
}

400 Bad Request - Quantity exceeds limit

{
  "error": "quantity exceeds maximum allowed (50)"
}

Product Errors

404 Not Found - Product not found

{
  "error": "product not found"
}

404 Not Found - Denomination not available

{
  "error": "denomination not found"
}

400 Bad Request - Wallet not found

{
  "error": "wallet not found"
}

Currency Conversion Errors

400 Bad Request - Exchange rate unavailable

{
  "error": "exchange rate not available for USD to EUR"
}

500 Internal Server Error - Forex service error

{
  "error": "failed to fetch exchange rate"
}

Rate Limits and Performance

Rate Limits

Charge Calculations: 50 requests per minute per client
Burst Limit: 10 requests per 10 seconds
Caching: Responses cached for 5 minutes with identical parameters

Performance Optimization

Cache Results: Identical requests return cached responses for 5 minutes
Batch Calculations: Group related calculations to minimize API calls
Validate Inputs: Check product availability and denomination ranges first
Handle Rate Limits: Implement exponential backoff for 429 responses
Monitor Forex Changes: Currency rates update frequently, cache appropriately

Best Practices

Pre-validate Denominations: Check product denomination ranges before calculating
Implement Client-side Caching: Cache calculation results for user sessions
Handle Currency Conversion: Always check for forex rates and conversion fees
Monitor Max Quantities: Respect client-specific and product-specific limits
Error Recovery: Implement fallback strategies for calculation failures

Next Steps

Learn about Products API to find products for charge calculation
Explore Wallet Management for multi-currency scenarios
Review Authentication for secure API access

Charges API

On this page