Docs

API or SDK: which one, and when?

Short answer: the API runs on your server, the SDK runs in your app. They are two ends of the same system, not alternatives.

Your server uses the API

With a secret key. Anything that involves trust.

Credit coins after your own payment system confirms a purchase.
Debit coins, reverse a gift, look up or delete a user.
Create and edit your gift catalog.
Receive webhooks, for example to reward the user who got a gift.
Create a client token for the signed-in user.

Your app uses the SDK

With a client token. Everything the user sees and does.

Show the gift tray, the catalog and the user's balance.
Send a gift, always as the user the token belongs to.
Show the gifts a user has received.
Play the gift effects, the combo counter and the notice.

How they fit together

1. The user buys coins.        Your server confirms the payment,
                               then calls the API:  POST /v1/users/{id}/credit
2. The app opens.              Your server calls:   POST /v1/client-tokens
                               and hands the token (gs_ct_…) to the app.
3. The user opens the tray.    The SDK uses the token: gifts, balance, send.
4. A gift is sent.             The SDK plays the effect. Your server gets a
                               webhook (gift.sent) and can react.

Why it is split

The secret key can credit coins to anyone. If it were inside an app, anyone could take it out and give themselves free coins. A client token is different: it belongs to one user, expires (one hour by default), can read the catalog and that user's own balance, read the gifts any user has received (gift walls, leaderboards, the "while you were away" summary for itself), join the gift rooms you allowed, and send gifts as that user. It cannot credit or debit coins and it cannot act for anyone else.

You can skip the SDK

If a server sends the gifts (a bot, a batch job, a web backend) or you draw your own screens, the API is enough. It does everything the SDK does. The SDK only saves you the interface: the tray, the effects and the combo counter.

What the SDKs cover today

Five platforms: web, React Native, Flutter, Android and iOS. Each has the gift tray, the effects and a client that refreshes the token and retries safely. Details per platform: SDKs. Live gifts for everyone watching: Gift rooms.

You always do two things yourself

Sell coins and take the money. GiftingStack never handles real money.
Call credit from your server when a purchase is confirmed. Optionally, to make sure the purchase is real and used once, check it first with Receipt validation.

Ready to try it? Quickstart: send your first gift. Deciding how gifts appear in your app? Integration patterns.

Questions or something unclear? support@giftingstack.com.