Pricing & Charges
How the final amount debited from your wallet is computed — base price, FX, client discount, vendor discount, fees — and how to quote it before placing an order
Pricing & Charges
The amount Starship debits from your wallet on a successful order is never just face_value × quantity. It's the result of a deterministic pricing cascade that applies FX conversion, a client-level discount (negotiated with your account manager), and — when relevant — a vendor-level discount. Understanding this cascade matters for two reasons:
- Your pre-order quote must match what gets charged. If you show an end-user "Pay ₹500" and the wallet actually gets debited ₹487.20, you've created an accounting gap.
- Your reconciliation logic must agree with Starship's ledger. A 0.05 rounding difference per order compounds to a real number across a week of traffic.
The authoritative pre-order quote always comes from the Charges API. Call it before POST /orders and display the result; never compute the discounted price yourself on the client.
The Cascade
The cascade is strictly ordered. Changing the order changes the result — e.g., applying discount before FX yields a different rounded number.
Step by Step
1. Face value
The starting number is straightforward: denomination × quantity, expressed in the product's currency (not your wallet currency). A $50 Amazon US gift card has face value $50 regardless of where you're billed.
2. FX conversion
If the product's currency differs from your wallet currency, Starship converts at the current rate from its fx_rates table. The rate is updated daily and snapshot on the order; the amount you're quoted is the amount you're billed — later rate moves do not retroactively change the order.
3. Client discount (CPD — "Client Product Discount")
Your account manager negotiates a per-product discount percentage. When the cascade reaches this step, it looks up the CPD row for (client, product). CPD is additive to the client's benefit — typical values are in the -1 % to -15 % range (negative = discount).
CPD is a hand-tuned, per-product table. Do not assume a flat rate across your catalog.
4. Vendor discount (fallback)
If no CPD row exists for this (client, product), the cascade falls back to a vendor-level margin. This is a global discount Starship carries for the vendor (e.g., VoucherKart gives Starship X% off face value on gift cards), and Starship passes a portion of that through to you.
The default margin when neither CPD nor vendor-specific applies is 2% in your favor. Treat this as a floor, not a guarantee.
Protective cap. If your CPD asks for a discount larger than the vendor's own margin for that product, Starship silently caps the discount at the vendor margin. You'll see this in the Charges API response, not as an error — just as a smaller effective discount than your CPD row implies. This prevents Starship from taking a loss on your orders.
5. Fees
Some products carry handling fees, convenience charges, or FX surcharges. The Charges API itemizes these under the charges array so you can display them to end-users transparently.
6. Final wallet debit
The debited amount is face_value × fx_rate × (1 + discount) + fees. The Charges API returns this pre-rounded in your wallet currency. Use this exact number in your checkout UI — any other source of truth will drift.
Example — $50 Amazon US → INR wallet, 4% CPD
| Step | Computation | Running total |
|---|---|---|
| Face value | $50 × 1 | USD 50.00 |
| FX (USD → INR at 83.20) | 50 × 83.20 | INR 4,160.00 |
| CPD applied (-4%) | 4,160 × 0.96 | INR 3,993.60 |
| Fees | + 0 | INR 3,993.60 |
| Wallet debit | INR 3,993.60 |
The Charges API would return this breakdown itemized. Your UI should display the subtotal, the discount line, and the total — not just the total.
When Does the Price Change?
- Between quote and order: FX rates refresh daily, not per request, so a quote held for hours is usually still accurate. A quote held across an FX refresh may drift by the daily rate move — typically less than 0.5 %. If this matters to you, quote immediately before ordering.
- Between order and fulfillment: never. Once an order is
PLACED, the price is snapshot. Rate moves after that point do not change the order. - On refund: the wallet is credited back the exact debit amount — FX movements between debit and refund do not benefit or hurt you.
What You Should Build
Always quote before ordering
Call the Charges API with the exact { product_id, denomination, quantity } you're about to order. Use its total as your UI's "Pay now" amount.
Display the breakdown, not just the total
End-users trust itemized receipts. Show the face value, discount, and final total as separate lines.
Reconcile daily against the ledger
A GET /wallets/:id/transactions run over yesterday's window should match the sum of your successfully-delivered orders, debit-for-debit. If they differ, investigate — typically the culprit is a refund you missed or a partial delivery that hasn't closed out.
Don't precompute discount % client-side
CPD rows change without notice (your account manager negotiates new rates). Always trust the Charges API. Never hardcode a discount percentage in your frontend.
Next
- Charges API reference — the endpoint shape
- Wallets Overview — how the wallet ledger works
- Create an Order — passing the quoted total