Fresim Public API

Build your own storefront, app, or integration on top of your Fresim account. The public API exposes your brand, your catalog, paid checkout, and top-ups — the same services that power Fresim-hosted storefronts. Every request is scoped to the creator account that owns the API key: you can only ever see and sell your own data.

Base URL

https://fresim.com

All endpoints live under /api/public/ and speak JSON. Successful responses carry { "success": true, ... }; failures carry { "success": false, "error": "..." } with a matching HTTP status.

Authentication

Create an API key from Dashboard → Settings → API Keys (available on the Business tier and up). Keys start with fsk_ and are shown once at creation — store them like passwords. Send the key on every request in either header form:

# Option A — Authorization header
curl https://fresim.com/api/public/brand \
  -H "Authorization: Bearer fsk_your_key_here"

# Option B — X-API-Key header
curl https://fresim.com/api/public/brand \
  -H "X-API-Key: fsk_your_key_here"

Keys carry permissions (currently just checkout, granted by default) and can be revoked at any time from the same Settings section. A revoked or malformed key returns 401; a key missing the endpoint's permission returns 403.

Rate limits

Each key has its own rate limit — 100 requests per minute by default — enforced across all four endpoints together. Exceeding it returns 429:

{ "success": false, "error": "Rate limit exceeded: 100 requests per minute" }

Need a higher limit for a production integration? Email us.

Endpoints

GET/api/public/brandrequires: checkout

Get your brand

Your storefront's brand identity — name, colors, description, logo, and tier. Use it to theme your own frontend so brand edits in the Fresim dashboard propagate automatically.

curl https://fresim.com/api/public/brand \
  -H "X-API-Key: fsk_your_key_here"

Response

{
  "success": true,
  "brandName": "NomadConnect",
  "slug": "nomadconnect",
  "primaryColor": "#22d3ee",
  "secondaryColor": "#818cf8",
  "description": "Stay connected in 180+ countries.",
  "logo": null,
  "tier": "business",
  "customDomain": null
}

GET/api/public/catalogrequires: checkout

List your offers

Every active offer on your storefront, in your configured sort order. The id of each offer is what you pass to checkout and top-up below. Prices are the retail prices you set in the dashboard.

curl https://fresim.com/api/public/catalog \
  -H "X-API-Key: fsk_your_key_here"

Response

{
  "success": true,
  "offers": [
    {
      "id": "cmoffer123",
      "name": "United States — 5GB / 30 days",
      "description": "5GB of data in the United States for 30 days.",
      "price": 14.99,
      "currency": "usd",
      "offerId": "CKH140",
      "provider": "esimaccess"
    }
  ]
}

POST/api/public/checkoutrequires: checkout

Start a paid checkout

Creates a Stripe Checkout session for one of your offers and returns the hosted payment URL — redirect your customer there. Fulfillment (eSIM provisioning + confirmation email) happens automatically after payment, exactly like a Fresim-hosted storefront sale, with the Stripe Connect split applied at the moment of purchase.

curl -X POST https://fresim.com/api/public/checkout \
  -H "X-API-Key: fsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "creatorOfferId": "cmoffer123", "email": "customer@example.com" }'

Response

{
  "success": true,
  "url": "https://checkout.stripe.com/c/pay/cs_live_…"
}

POST/api/public/topuprequires: checkout

Top up an existing eSIM

Same flow as checkout, for refilling an eSIM your customer already has — pass the eSIM's iccid along with the offer to apply. Returns a Stripe Checkout URL; the top-up is applied automatically after payment.

curl -X POST https://fresim.com/api/public/topup \
  -H "X-API-Key: fsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "creatorOfferId": "cmoffer123",
    "email": "customer@example.com",
    "iccid": "89852240400012345678"
  }'

Response

{
  "success": true,
  "url": "https://checkout.stripe.com/c/pay/cs_live_…"
}

Error reference

Status	Meaning
401	Missing, malformed, invalid, or revoked API key.
403	Key lacks the endpoint's permission (checkout).
404	Referenced resource not found (e.g. unknown offer).
429	Per-key rate limit exceeded.
500	Something failed on our side — safe to retry idempotent GETs.

Every error body has the same shape: { "success": false, "error": "human-readable message" }.

Starter template

Dedicated-tier partners get a fully deployable Next.js storefront template wired to these four endpoints (typed API client, plan cards, top-up flow, brand-color theming) as part of provisioning. On any tier, the endpoints above are all you need — the template is a head start, not a requirement. Questions or a missing endpoint for your use case? Email us.