Pricing & Charges

The amount Starship debits from your wallet on a successful order is not just face_value × quantity. It is the result of a fixed pricing calculation: your client discount, then FX conversion when the product and wallet currencies differ, then a handling fee. Understanding it matters for two reasons:

1. 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.
2. 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. The Charges API and POST /orders run the same calculation. Call it before POST /orders and display the result; never compute the discounted price yourself on the client.

The Cascade

Step by Step

1. Face value

The starting number is 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. The Charges API returns it as non_discounted_total.

2. Client discount

The discount field is a percentage applied to the face value:

• Positive discount = a discount. You pay less than face value. discount: 4 on $50.00 gives total_amount: 48.00.
• Negative discount = a markup. You pay more than face value. discount: -4 on $50.00 gives total_amount: 52.00.

total_amount = non_discounted_total × (1 − discount / 100), and discount_amount is non_discounted_total × discount / 100 (negative for a markup).

The rate comes from your configuration for that product: a client-specific rate if your account manager has set one, otherwise the standard rate for the supplying vendor product. Rates are set per product. Do not assume a flat rate across your catalog.

3. FX conversion

If the product's currency differs from your wallet currency, the post-discount total_amount is converted into the wallet currency. The response reports the rate as charges_details.forex_rate and the converted amount as net_amount. charges_details.source_currency and charges_details.destination_currency name the two currencies. In a same-currency quote, net_amount and forex_rate are absent.

4. Handling fee

A handling fee is reported as two fields, handling_fee_pct and handling_fee_amount. Both are present on every quote; when no fee applies they are 0. The fee is handling_fee_pct percent of the amount after step 2 (same currency) or after step 3 (cross-currency), so it is always computed in your wallet currency. A negative handling_fee_pct is a credit that reduces the total.

There is no itemized charges array; the handling fee is the only fee line.

5. Final wallet debit

total_payable is the amount debited from your wallet:

• Same currency: total_payable = total_amount + handling_fee_amount
• Cross-currency: total_payable = net_amount + handling_fee_amount

Use this exact number in your checkout UI. Any other source of truth will drift.

Example — $50 Amazon US → INR wallet, 4% discount

The same order with discount: -4 (a markup) would give total_amount: 52.00 and total_payable: 4326.40. With handling_fee_pct: 2.5 on top of the 4% discount, handling_fee_amount would be 99.84 and total_payable 4093.44.

Your UI should display the subtotal, the discount line, any handling fee, and the total — not just the total.

When Does the Price Change?

• Between quote and order: a quote is not a price lock. POST /orders recalculates the price when the order is created, using your discount, handling fee and FX rate at that moment. If any of them changed after you quoted, the order is charged the new price. Quote immediately before ordering.
• After the order is created: the wallet debit is recorded at creation and does not move afterwards.

What You Should Build

Next

• Charges API reference — the endpoint shape
• Wallets Overview — how the wallet ledger works
• Create an Order — passing the quoted total