Docs

How your fee is measured

GiftingStack's service fee is measured from the coins you sell on your live environment: store sales we can verify, web sales you declare, the free coins above a small allowance, and coins spent on gifts that no recorded sale accounts for. No money moves through GiftingStack.

Checked against the API on 2026-10-23.

Three kinds of credit

Every credit must say what it is, on live and test alike: send exactly one of the three kinds below. A credit with none of them is refused with 400 sale_kind_required, and bonus: true next to a receipt_id or a price is 400 invalid_request. There is no product list to define. Use a new reference (your order or store transaction id) and a new Idempotency-Key for each credit.

A verified store sale

Verify the receipt first, then credit with the receipt_id it returned. The price and currency come from the store. On live, sending price or currency next to receipt_id is 400 invalid_request, even if they match.

curl -X POST https://api.giftingstack.com/v1/users/ava/credit \
  -H "Authorization: Bearer $GS_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(node -e "console.log(crypto.randomUUID())")" \
  -d '{"amount": 500, "reason": "purchase", "reference": "appstore_2000000123",
       "receipt_id": "rcp_01JA0Q8X2M4N6P8R0T2V4W6Y8Z"}'

A declared web sale

curl -X POST https://api.giftingstack.com/v1/users/ava/credit \
  -H "Authorization: Bearer $GS_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(node -e "console.log(crypto.randomUUID())")" \
  -d '{"amount": 500, "reason": "purchase", "reference": "web_order_1002",
       "price": "4.99", "currency": "USD"}'

The credit is recorded with price_source: "declared". Declare what your user really paid: it is compared with your verified store sales (see "Checks" below).

A bonus credit

curl -X POST https://api.giftingstack.com/v1/users/ava/credit \
  -H "Authorization: Bearer $GS_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(node -e "console.log(crypto.randomUUID())")" \
  -d '{"amount": 100, "reason": "welcome_bonus", "reference": "welcome_ava", "bonus": true}'

Coins added from the dashboard (Users, Adjust balance) are bonus credits too.

Fiat amounts are information only

A price on a credit records what your user paid your store. It never changes a balance, is never converted into coins, and no endpoint pays out, refunds or charges money based on it. Coins cannot be cashed out. The only conversion we make is a USD figure for our own invoice, described below.

How the fee is measured

The fee is measured per calendar month (UTC), from live credits only. Test credits are never counted. The base of the month is:

verified store sales
- refunds of those sales
+ declared web sales
+ bonus coins above the 20% allowance
+ web spending floor

Verified store sales

A credit with a receipt_id is a store sale priced by the store: the Apple transaction carries its own price; for Google Play we read the order's total with the Play Developer API (orders.get), which includes the quantity. For that, the service account you upload needs the View financial data permission in Play Console (Receipt validation). On live, a Google Play receipt whose price could not be read is not credited (422 price_missing); the dashboard's Purchases page says why ("Price not available: …"). Fix the permission and verify the purchase again: the price is filled in and the credit goes through. A purchase the store gives no price for at all (a promo code) is credited without a price and not counted.

Declared web sales

Credits with a price and currency and no receipt count in full at the price you declared. Declared sales are not verified by the stores, so they are compared with your verified sales and with the coin prices shown publicly on your website or web shop (see "Checks").

Bonus coins and the 20% rule

Coins credited with bonus: true (no receipt, no price) are not a sale. Giving some away is normal, so every month up to 20% of the coins you sold (store and web) can be given away without counting. Coins above that allowance are valued at the month's median verified price per coin and added to the base. If you had no verified store sale in the month, they are valued at the month's median declared web price per coin instead (a web-only shop works the same way); with neither in the month, at the price of the last three months. With no price at all there is nothing to value them with: nothing is added, and the month is flagged for review.

Median price. Each day and currency of your priced sales is one vote, and the median of the votes is the price per coin, so one large sale at a token price does not set it. Coins counted as sold. Only sales with a price we can convert to USD count as sold coins (for the allowance and for the floor below), and of each kind (store, web) at most twice the coins their amount buys at that kind's median price.

Example. In a month you sold 10,000 coins through the stores for 100 USD (0.01 USD per coin) and 2,000 coins on your web shop for 24 USD. You credited 3,000 bonus coins. The allowance is 20% of the 12,000 sold coins, 2,400 coins; the excess is 600 coins, worth 600 × 0.01 = 6 USD. A store refund of 5 USD was reported in the month. The base is 100 − 5 + 24 + 6 = 125 USD.

Web spending floor

Coins your users spend should come from coins you credited: sold, or given within the allowance. Each month we look at the last three months (this one included): the coins spent on gifts and taken by debits (without allow_negative), minus the coins counted as sold (store and web), the 20% allowance and the bonus excess already valued, minus the coins earlier months of the same window already counted this way. If 10,000 or more coins are left, they are valued at the window's median declared web price per coin (or, with no declared web sale, its median verified store price) and added to the base as the web spending floor. A coin is never counted twice. With no sale at all to price them, nothing is added and the month is flagged for review.

There is no floor in your first three live months (balances you carried over from before) or in the month you move from the free plan to a paid one for the first time, or after three months without a paid plan. Billing shows the floor on its own line.

Example. Over three months you sold 9,000 coins on your web shop for 900 USD (0.10 USD per coin), gave no bonus coins, and your users spent 40,000 coins on gifts. Covered: 9,000 sold + 1,800 allowance = 10,800 coins. The floor is 29,200 coins × 0.10 = 2,920 USD.

Refunds

When a store refunds a purchase that backed a live credit (reported by store notifications or a later receipt verification), its price is subtracted at the rate of the credit's day, in the month the refund was reported, or in the credit's month if that is later. A reversed refund adds it back. A partial refund subtracts the full price. If a month's base is negative, it counts as 0. Coins you already credited are not taken back by GiftingStack.

Currencies

Prices in other currencies are converted to USD with the European Central Bank (ECB) daily reference rate of the day of the sale (UTC); if the ECB published none that day, the latest rate of the 14 days before is used. On live, a web sale must be declared in USD, EUR or a currency the ECB publishes (400 currency_not_supported otherwise). A store sale in a currency the ECB does not publish is listed as unconverted on Billing, left out of the base and not counted as sold. The USD figure only drives our invoice; your users and your balances are not affected.

What the plans charge

The current prices are on Pricing. They are for Starter, Growth and Scale, which you buy in the dashboard. Enterprise is arranged with us (write to support@giftingstack.com): it has its own agreement for the price, the limits and, where needed, rooms beyond 20,000 viewers, and is billed outside the checkout. The rules below are the standard ones:

The dashboard shows the month's verified sales, refunds, declared web sales, bonus excess, the web spending floor, the fee estimate in USD and the exchange-rate note on Billing, and on Usage the coins sold and given.

Checks

Declared web sales and bonus coins are compared with your verified store data and with the coins spent on gifts in your project: for example a declared share of live sales that is unusually high, a large bonus excess, bonus coins with no sale in the month to price them, coins spent on gifts far above the coins you sold over the last months, a web spending floor, credits refused for a missing sale kind, or declared prices far below your store prices are flagged for review. A flag changes no balance and no charge; it means we may ask how your sales are reported. We also check the coin prices shown publicly on your website or web shop against the prices you declare. Reporting sales incorrectly (for example declaring a price below what your user paid, or crediting store sales without their receipt) can lead to corrections of past months and to a suspension of the live environment, with 7 days to correct it first: see the Terms (sections 8 and 11) and Go live.

Questions or something unclear? support@giftingstack.com.