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.
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
| Action | Method | Params | Purpose |
|---|---|---|---|
verify_license | GET/POST | — | Validate the API key; returns user_id + plan. |
resolve_account | GET/POST | username, mode | Resolve a Fortnite username (or psn:/xb:/ns: prefixed) to an Epic account id. |
friend_add | GET/POST | receiver, category?, account_id?, limit? | Friend the buyer from every account (or one category) and report when gifting becomes possible. |
gift_check | GET/POST | offerId, receiver, category | Check whether a gift can be sent from the category's pool. |
gift_send | GET/POST | offerId, receiver, order_id, category | Send the gift from the category's pool. Records the order. |
Shop
| Action | Method | Params | Purpose |
|---|---|---|---|
shop | GET/POST | offerId?, giftable?, search?, limit? | The live item shop: name, image, price, rarity and both ids for every item. |
Categories (per owner)
| Action | Method | Params | Purpose |
|---|---|---|---|
category_list | GET/POST | — | List your categories with account counts + the default. |
category_create | POST | slug, name | Create a category. slug: 2-40 chars of a-z 0-9 _ ; "all" reserved. |
category_delete | POST | slug, reassign_to? | Delete a category; if it holds accounts, pass reassign_to=<slug>. |
Accounts
| Action | Method | Params | Purpose |
|---|---|---|---|
accounts_list | GET/POST | category? | List your accounts (id, name, category, cached V-Bucks/gifts). |
accounts_data | GET/POST | — | Live per-account V-Bucks + gifts (queries Epic). |
account_assign | POST | account_id | account_ids, category | Move existing account(s) into a category. |
account_link | POST | code, category | Link a new Epic account (Android authorization code) into a category. |
account_remove | POST | account_id | Unlink an account (DB row only). |
Dashboards
| Action | Method | Params | Purpose |
|---|---|---|---|
inventory | GET/POST | — | Aggregate per category: counts, V-Bucks, free gift slots. No identifiers. |
groups_status | GET/POST | live? | Per-account detail per category, in gifting priority order. live=1 refreshes first. |
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.
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.
| Field | Notes |
|---|---|
receiver | Required. Epic username, or psn:/xbl:/ns: prefixed, or an account id. |
category | Optional. Restrict to one pool. Omitted → every account. |
account_id | Optional. Pin a single sender, so a returning buyer stays with the account that already befriended them. |
limit | Optional, default 25. Caps how many accounts are contacted in one call, so a large pool can't exceed the request timeout. |
The reply summarises the whole pool, then breaks it down per account:
| Field | Notes |
|---|---|
code | friend_request_sent, already_friends, partially_sent (some accounts failed) or friend_request_failed (all did). |
sent, already_friends, failed | Counts across the accounts contacted. |
can_gift_now | true if any account can gift right now — check this before offering checkout. |
giftable_at | Soonest unix time any account becomes able to gift. null while every request is still unaccepted. |
giftable_in | Seconds until that moment, for a countdown. |
accounts_total, accounts_tried, truncated | truncated is true when the pool was bigger than limit; the rest are picked up on the next call. |
accounts[] | Per account: account_id, displayName, status (sent / already_friends / failed), friends_since, giftable_at, can_gift_now, and error when it failed. |
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.
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.
| Field | Notes |
|---|---|
offerId | Pass this to gift_check / gift_send. It changes every time the shop rotates, so don't use it to identify an item. |
mainId | The item's permanent id (CID_…, EID_…). Use this one to recognise the same item across rotations. |
name, description | For a bundle, the bundle's own name and blurb. |
kind | What the entry is: bundle, jam_track, instrument, car, lego_kit or item. Use this to include or exclude a whole class of item — type is null for jam tracks, cars, LEGO kits, instruments and V-Bucks packs, so it can't be filtered on. A bundle stays bundle even when it is made of music. |
type, rarity, series | e.g. outfit / Epic / Icon Series. series is null for ordinary items. |
price, regularPrice | V-Bucks. They differ when the item is discounted. |
giftable | false for items Epic won't allow as a gift (Battle Passes, V-Bucks packs). |
image | Item artwork URL. |
colors | The item's colour pair, for matching the in-game card background. |
inDate, outDate | How long the item stays in the shop (ISO-8601). |
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.
| Field | Notes |
|---|---|
position | 1-based place in the gifting queue. Label rows with this, not with sort_order. |
sort_order | The raw stored value. It repeats freely and is 0 for every account never dragged, so it means nothing on its own. |
position is null when the install hasn't run the ordering migration yet — 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.
Linking an account
Log into the Epic account, open this URL, and copy authorizationCode:
https://www.epicgames.com/id/api/redirect?clientId=3f69e56c7649492c8cc29f1af08a8a12&responseType=codeThen 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.
WordPress plugin (fnitemshop-auto-gift)
A WooCommerce plugin that calls this API on order completion: it maps a product to a Fortnite item and one of your categories, then sends the gift from that category’s accounts.
Setup
- Link your Epic accounts and create your categories in the panel.
- Install and activate
fnitemshop-auto-gifton your WordPress site. - Paste your API key (from the API Key page) in the plugin settings. It binds to your site domain on first use.
- Per product: set the Fortnite item, the category to gift from, and the price.
The plugin uses the same endpoints documented under REST API — gift_check then gift_send against the mapped category. Epic requires 48 hours of friendship before a gift is allowed, so an order may complete after that wait. Sent gifts appear under Orders.