Code examples Download Postman collection

Introduction Authentication Balance Reports List Products Create Order - Travel Create Order - VPN Order Status Data Usage VPN Config Error codes

Partner API reference

All endpoints return JSON. You never send a price - you only say what you want to buy, and the server always calculates the price itself, so it can't be faked or tampered with.

Base URL:

Base URL

https://buyukesim.com/api/v1

Authentication

Send your API key as a Bearer token on every request below.

Note: adding balance is a website-only action (via your dashboard Magic Code), not part of this API - your API key cannot create or fund top-ups.

Header

Authorization: Bearer buk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Account

GET/api/v1/balance

Account Balance

What is left on your prepaid account. Every order already returns the same figure in its own balance block, so you never have to call this just to see what a purchase cost - this endpoint is for the checks that happen away from a purchase: a top-up alarm, a dashboard tile, a batch job that refuses to start what it cannot pay for.

Request

curl "https://buyukesim.com/api/v1/balance" \
  -H "Authorization: Bearer buk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response

{
  "success": true,
  "data": {
    "balance_usd": 477.5,
    "currency": "USD",
    "discount_pct": 10,
    "account": {
      "name": "Acme Telecom",
      "status": "active",
      "api_key_prefix": "buk_live_9f2a"
    }
  }
}

GET/api/v1/reports?from=2026-08-01&to=2026-08-31

Sales Report

What you bought over a date range and what it cost, broken down by product. Dates are UTC calendar days on the order date and inclusive at both ends; leaving them out reports the last 30 days. Paid orders only - an order that fails fulfilment is cancelled and refunded to your balance, so it never cost anything. The itemised orders array is capped at 100 rows by default (limit, max 500); narrow the dates to page through more.

Request

curl "https://buyukesim.com/api/v1/reports?from=2026-08-01&to=2026-08-31" \
  -H "Authorization: Bearer buk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response

{
  "success": true,
  "data": {
    "period": { "from": "2026-08-01", "to": "2026-08-31", "timezone": "UTC" },
    "totals": {
      "orders": 4,
      "units": 4,
      "spend_usd": 25.16,
      "currency": "USD"
    },
    "products": [
      { "type": "travel_data", "orders": 3, "units": 3, "spend_usd": 16.17 },
      { "type": "vpn",         "orders": 1, "units": 1, "spend_usd": 8.99 }
    ],
    "balance": { "remaining_usd": 477.5, "currency": "USD" },
    "orders": [
      {
        "order_id": 98423,
        "type": "vpn",
        "reference": "order-1236",
        "lookup_code": "K7M9-2XP4",
        "units": 1,
        "spend_usd": 8.99,
        "created_at": "2026-08-29 20:00:00",
        "plan": "30d"
      }
    ],
    "orders_truncated": false
  }
}

Products

GET/api/v1/products

List Products

Fetch all active Travel eSIM packages (with current package_code and price_usd) and the VPN access plans and servers, so you always know what's purchasable before calling Create Order. The travel_data array is the whole live catalogue (about 198 destinations - one entry is shown here); ?location_code=GB narrows it. Every price_usd is YOUR price: discount_pct is your own rate, not a fixed one, and the sample below just uses 10%.

Request

curl "https://buyukesim.com/api/v1/products" \
  -H "Authorization: Bearer buk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response

{
  "success": true,
  "data": {
    "discount_pct": 10,
    "travel_data": [
      {
        "package_code": "GB_1GB_7D",
        "name": "United Kingdom 1GB / 7 Days",
        "location_code": "GB",
        "retail_price_usd": 5.99,
        "price_usd": 5.39,
        "volume_label": "1 GB",
        "duration": 7,
        "duration_unit": "DAY"
      }
    ],
    "vpn": {
      "type": "vpn",
      "available": true,
      "currency": "USD",
      "plans": [
        { "plan": "30d", "days": 30, "label": "30 days", "retail_price_usd": 9.99, "price_usd": 8.99, "currency": "USD" }
      ],
      "protocols": ["wireguard", "openvpn", "vless"],
      "servers": [
        { "id": 42, "country_code": "NL", "city": "Amsterdam", "protocol": "wireguard" }
      ]
    }
  }
}

Orders

POST/api/v1/orders

Create Order - Travel eSIM

Creates and instantly fulfills a Travel eSIM order for the given package_code.

Request

curl -X POST "https://buyukesim.com/api/v1/orders" \
  -H "Authorization: Bearer buk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "product_type": "travel_data",
  "package_code": "GB_1GB_7D",
  "reference": "order-1235"
}'

Response

{
  "success": true,
  "data": {
    "order_id": 98422,
    "reference": "order-1235",
    "status": "paid",
    "product": {
      "type": "travel_data",
      "package_code": "GB_1GB_7D",
      "package_name": "United Kingdom 1GB / 7 Days",
      "location_code": "GB",
      "retail_price_usd": 5.99,
      "discount_pct": 10,
      "price_usd": 5.39
    },
    "lookup_code": null,
    "created_at": "2026-07-06T20:00:00+00:00",
    "balance": { "charged_usd": 5.39, "remaining_usd": 472.11, "currency": "USD" }
  }
}

POST/api/v1/orders

Create Order - VPN access

Creates and instantly provisions a VPN access order for the given vpn_plan, deducted from your prepaid balance. The response carries the username, password and expiry. If the VPN provider is unreachable the order is still paid and kept: you get HTTP 202 with status "provisioning_pending" and the order id, our team is alerted, and the credentials appear on GET /v1/orders/{id} once the account is created.

Request

curl -X POST "https://buyukesim.com/api/v1/orders" \
  -H "Authorization: Bearer buk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "product_type": "vpn",
  "vpn_plan": "30d",
  "reference": "order-1236"
}'

Response

{
  "success": true,
  "data": {
    "order_id": 98423,
    "reference": "order-1236",
    "status": "paid",
    "product": {
      "type": "vpn",
      "plan": { "key": "30d", "days": 30, "label": "30 days" },
      "retail_price_usd": 9.99,
      "discount_pct": 10,
      "price_usd": 8.99
    },
    "lookup_code": "K7M9-2XP4",
    "created_at": "2026-08-29T20:00:00+00:00",
    "vpn": {
      "provisioned": true,
      "expires_at": "2026-09-28 00:00:00",
      "username": "bk98423a1c3e",
      "password": "s7Kq2vXpLm4A",
      "protocols": ["wireguard", "openvpn", "vless"],
      "config_endpoint": "https://buyukesim.com/api/v1/orders/98423/vpn-config"
    },
    "success_url": "https://buyukesim.com/en/success?order_id=98423&access_token=...",
    "balance": { "charged_usd": 8.99, "remaining_usd": 463.12, "currency": "USD" }
  }
}

GET/api/v1/orders/98422

Order Status & Delivery

The delivery call: poll it until data.esim.ready is true and take the profile from data.esim.items. Each item carries both ways onto a phone - qr_code, and manual_install with the SM-DP+ address and activation code to type in by hand, for the very common case where your customer is reading your app on the same phone the profile has to install to and has no second screen to scan from. puk_code is null on travel eSIMs. Do not poll status: it reads "paid" the moment your balance is taken, which is a payment state, not a delivery one.

Request

curl "https://buyukesim.com/api/v1/orders/98422" \
  -H "Authorization: Bearer buk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response

{
  "success": true,
  "data": {
    "order_id": 98422,
    "reference": "order-1235",
    "status": "paid",
    "product": { "type": "travel_data", "package_code": "GB_1GB_7D", "retail_price_usd": 5.99, "price_usd": 5.39 },
    "lookup_code": "K7M9-2XP4",
    "esim": {
      "ready": true,
      "items": [
        {
          "_comment": "hosts below are placeholders - the real ones differ per profile",
          "qr_code": "https://qr.example-provider.net/8e2bba37e8b94ca49bf23be334a0a57f.png",
          "iccid": "8944...",
          "puk_code": null,
          "manual_install": {
            "activation_string": "LPA:1$rsp.example-provider.com$1173094A3D3A473D84695E0D6C404B34",
            "smdp_address": "rsp.example-provider.com",
            "activation_code": "1173094A3D3A473D84695E0D6C404B34",
            "confirmation_code_required": false
          }
        }
      ]
    }
  }
}

GET/api/v1/orders/98422/usage

Travel eSIM Data Usage

Live remaining/used data, activation and expiry status for a Travel eSIM order, pulled fresh from the provider each call.

Request

curl "https://buyukesim.com/api/v1/orders/98422/usage" \
  -H "Authorization: Bearer buk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response

{
  "success": true,
  "data": {
    "order_id": 98422,
    "status": "paid",
    "package": {
      "package_code": "GB_1GB_7D",
      "name": "United Kingdom 1GB / 7 Days",
      "location_code": "GB",
      "volume_label": "1 GB",
      "duration": 7,
      "duration_unit": "DAY"
    },
    "usage": {
      "iccid": "8944...",
      "apn": "cmlink",
      "esim_status": "IN_USE",
      "smdp_status": "ENABLED",
      "total_volume_bytes": 1073741824,
      "used_volume_bytes": 214748364,
      "remaining_volume_bytes": 858993459,
      "usage_percent": 20.0,
      "total_duration": 7,
      "duration_unit": "DAY",
      "expired_time": "2026-07-13T20:00:00+00:00"
    }
  }
}

GET/api/v1/orders/98423/vpn-config?protocol=wireguard&server_id=42

VPN Configuration

Fetch a WireGuard, OpenVPN or VLESS configuration for one server on a VPN order you created. Take server_id from the servers list in List Products. WireGuard servers also serve OpenVPN; VLESS servers only serve VLESS. Call it as often as you need, up to 20 times a minute.

Request

curl "https://buyukesim.com/api/v1/orders/98423/vpn-config?protocol=wireguard&server_id=42" \
  -H "Authorization: Bearer buk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

Response

{
  "success": true,
  "data": {
    "order_id": 98423,
    "protocol": "wireguard",
    "server": { "id": 42, "country_code": "NL", "city": "Amsterdam" },
    "name": "buyukesim-nl-amsterdam.conf",
    "content": "[Interface]\nPrivateKey = ...\nAddress = ...",
    "qr_payload": "[Interface]\nPrivateKey = ...\nAddress = ..."
  }
}

Error codes

Every error response has the same shape: a top-level success: false, plus an error object with a stable code field your code can check to know exactly what went wrong.

Error shape

{
  "success": false,
  "error": { "code": "insufficient_balance", "message": "..." }
}

HTTP	code	Meaning
401	unauthorized	Missing or invalid API key.
402	insufficient_balance	Insufficient prepaid balance for this order's price.
404	package_not_found	Travel package_code not found or no longer active.
409	provisioning_pending	The VPN account for this order is not created yet, or the plan has expired.
429	rate_limit	Rate limit exceeded - slow down requests.