FN SHOP developer docs

Base URL: https://fnitem.shop/api/v3/service/ · Your API key is on the API Key page.

Authentication

Send your API key as a header or query param:

• header X-Api-Key: <key>, or
• query ?api_key=<key>

The API detects your site’s domain from the request and locks your key to it on first use — no domain parameter needed. Your key only sees that owner’s accounts, categories and orders.

Plan limits

Each key is on a plan with a number of requests per term. A term is the period you paid for — a month, or the three, six or twelve you bought at once — and the count starts over when you renew. verify_license is never counted, so checking your key costs nothing.

Doubling the price quadruples the requests, so the bigger plan is cheaper per call.

A call past the plan is refused before it does anything, and is not counted:

{
    "result": false,
    "code": "plan_limit_reached",
    "description": "The standard plan allows 20,000 requests per term, and this key has used them. Renew to start a new term.",
    "plan": "standard",
    "limit": 20000,
    "used": 20000,
    "resets_at": 1790794897,
    "resets_in": 432000
}

resets_at is when the term ends — the key’s expiry. Renewing before then starts a new term at once. groups_status returns plan with used, remaining and resets_at, so a storefront can see how close it is before a call is refused, and your API key page shows the same.

Request & response

Call https://fnitem.shop/api/v3/service/{action} (GET or POST). Every response is JSON with at least:

{ "result": true, "code": "ok_code", "description": "", ... }

Gift lifecycle

Shop

Categories (per owner)

Accounts

Dashboards

Orders

category

For gift_check/gift_send, category is one of your category slugs, or all (any account), or omitted (default). Only accounts whose group matches are used; an empty pool returns no_accounts_in_group.

Identifying the buyer

Every gifting call takes receiver, an Epic username. That works until the buyer renames — then the stored value stops resolving, and they are told their username is wrong for an account that is perfectly fine.

gift_check, gift_send and friend_add therefore also return receiver_id, the resolved Epic account id, and accept it back on the next call. An account id never changes, so a shop that stores one keeps working across a rename — and skips the lookup, so the call is slightly faster too.

Returned on refusals as well as on success, so a shop can capture the id from the first call it makes even when that call says no. friend_add also returns it as receiver for callers written before this existed; both fields carry the same value.

friend_add

Fortnite only allows a gift once both accounts have been friends for 48 hours. Call friend_add as soon as a buyer enters their name — at the top of checkout, or when they add to cart — so the wait is already running by the time they pay. Calling it again is safe: accounts that are already friends are skipped rather than sent a second request.

Leave category out and the request goes from every account you have. That is usually what you want: any account might end up being the one that gifts, and befriending only one leaves the rest unable to deliver. Pass a category to restrict it to that pool.

The reply summarises the whole pool, then breaks it down per account:

A pending request has giftable_at: null: Epic starts the 48 hours when the buyer accepts, not when you send. Tell them to accept, then poll this or gift_check. One account failing doesn't stop the others — check accounts[] for the detail.

friend_status

Where a buyer stands with each of your accounts, without sending anything. Call it before offering checkout, or to show a returning buyer how long is left.

Takes receiver and receiver_id like friend_add, and reads the pool of the same category. A buyer with ready above zero can be gifted right now.

shop

Returns the items currently in the shop, ready to list in a storefront. Filter with offerId, giftable=1|0, search (name substring) or limit.

Also returned: uid (changes when the shop rotates, so you can skip a refresh), count and total. shop_unavailable means shop data could not be read.

groups_status

Every category with its accounts, in the order gifts actually use them — the drag order you set on the Accounts page. A gift goes out from the first eligible account in the list, so this is the order to show if you display a pool anywhere.

position can be null, and the list then falls back to name order. Treat null as "no priority to show" rather than implying one. In the (ungrouped) bucket position is cosmetic: those accounts aren't in any category, so they never gift.

order_history

Every order placed against your accounts, whatever placed it. Alias: orders.

type says what kind of order a row is:

gift and api_gift are both gifts and differ only in how they were placed, so the filter takes a list: type=gift,api_gift gives every gift and nothing you bought for yourself.

Orders record what kind they were, not which app placed them, so there is no filter for that.

Filters are optional and combine. Send all, or leave a filter out, to ignore it — so you can pass the same parameter every time and vary only its value.

Alongside orders[] the reply carries total and spent for the whole filter rather than the page you asked for, so a summary can stay on screen while you page through. types counts each kind under that same filter, so you can see the mix at once instead of asking once per kind.

{
  "result": true, "code": "order_history",
  "total": 1284, "spent": 1027200, "limit": 50, "offset": 0,
  "types": { "api_gift": 900, "gift": 350, "purchase": 34 },
  "orders": [
    { "id": "trk1", "date": 1755534240, "type": "api_gift", "status": "completed",
      "receiver": "990e78dd\u2026", "sender": "acc1", "offer": "offer1",
      "price": 800, "order_id": "1042", "category": "vip" }
  ]
}

You only ever see your own orders.

Linking an account

Log into the Epic account, open this URL, and copy authorizationCode:

https://www.epicgames.com/id/api/redirect?clientId=3f69e56c7649492c8cc29f1af08a8a12&responseType=code

Then POST it to account_link with a category. Codes are single-use and expire quickly.

Code examples

Pick a language; every endpoint below updates. Replace YOUR_KEY and the sample values.