Localization choices

Read country choices

GET /api/v1/countries

Read configured country/state records, or a conditional collection of country text from users. No pagination, save or location-precision guarantee.

Before you call

Guest ACL permits this action; it has no required member/resource guard. Header resource is optional and can select grouped behavior. Without a resource it reads country records. With a resource, real=true or use_group_users_country enables grouping of all users’ country values, with no resource/user membership filter. That output can expose country text collected across resources; use it only when this is intended.

Default selection uses optional server GeoIP lookup of resolved request IP, falling back to US on unknown/unavailable result. IP resolver allows existing admin context to override ip via JSON/query; otherwise takes the last entry of plugin-forwarded header, then forwarded-for, then remote address. It is not a physical-location or trusted-client provenance guarantee.

Request

Bodyless; examples omit resource and use country-record branch.

Result

HTTP 200 items array; empty [] possible. Country-record branch orders sort DESC, title ASC; grouped branch has no explicit order.

curl "${WALLKIT_API_BASE}/api/v1/countries"

const response = await fetch(`${process.env.WALLKIT_API_BASE}/api/v1/countries`);
console.log(response.status, await response.json());

import os, json
from urllib.request import Request, urlopen
from urllib.error import HTTPError

request = Request(os.environ["WALLKIT_API_BASE"] + "/api/v1/countries", method="GET")
try:
    with urlopen(request) as response:
        print(response.status, json.load(response))
except HTTPError as error:
    print(error.code, json.load(error))

{
  "items": [
    {
      "id": 1,
      "code": "US",
      "title": "United States",
      "sort": 1,
      "selected": true,
      "states": [
        {
          "id": 10,
          "code": "CA",
          "title": "California",
          "county_id": 1
        }
      ]
    }
  ]
}

{"items":[{"code":null,"title":"Country not set"},{"code":null,"title":"France"}]}

Read an IP location suggestion

GET /api/v1/geoinfo

Read approximate country/state/city information for a supplied IP or request-resolved IP. This can perform external lookup and cache writes; it is not proof of residence or tax location.

Before you call

Guest access follows the shared read context.

Any caller can supply query ip (string filter, no IP-format validation); falsey/omitted uses the request IP resolver. The resolver’s forwarded/admin override behavior is described under countries. The GeoIP service initializes with resolved request IP as well, so supplied-query lookup may also cause a lookup of the request IP. Cache miss sends host IP to tools.keycdn.com geo lookup; response is logged and cached. Exceptions can fall back to installed GeoIP data; failures/unknown fields return null where getters lack data. No guarantee of one provider call, fresh data, lookup privacy or accuracy.

Request

Bodyless.

Result

HTTP 200 data object, no items/paginator.

curl "${WALLKIT_API_BASE}/api/v1/geoinfo?ip=192.0.2.1"

const response = await fetch(`${process.env.WALLKIT_API_BASE}/api/v1/geoinfo?ip=192.0.2.1`);
console.log(response.status, await response.json());

import os, json
from urllib.request import Request, urlopen
from urllib.error import HTTPError

request = Request(os.environ["WALLKIT_API_BASE"] + "/api/v1/geoinfo?ip=192.0.2.1", method="GET")
try:
    with urlopen(request) as response:
        print(response.status, json.load(response))
except HTTPError as error:
    print(error.code, json.load(error))

{
  "data": {
    "ip": "192.0.2.1",
    "country": null,
    "country_code": null,
    "state": null,
    "city": null
  }
}

Read configured currency labels

GET /api/v1/currency

Read available labels for display/selection; this does not convert money or guarantee a selected provider accepts a currency.

Before you call

Guest access follows the shared read context.

Request

Bodyless; no supported pagination/filter/mode/currency query. Reads global configured currencies, not resource/member-specific selection.

Result

HTTP 200 uses the following currency-label projection. There is no currency model/detail, exchange rate, precision, symbol, paginator or active filter. Config order is preserved; no complete ISO coverage promised.

curl "${WALLKIT_API_BASE}/api/v1/currency"

const response = await fetch(`${process.env.WALLKIT_API_BASE}/api/v1/currency`);
console.log(response.status, await response.json());

import os, json
from urllib.request import Request, urlopen
from urllib.error import HTTPError

request = Request(os.environ["WALLKIT_API_BASE"] + "/api/v1/currency", method="GET")
try:
    with urlopen(request) as response:
        print(response.status, json.load(response))
except HTTPError as error:
    print(error.code, json.load(error))

{
  "items": [
    {
      "title": "USD"
    },
    {
      "title": "EUR"
    }
  ]
}

List language records

GET /api/v1/languages

Read paginated configured languages. Inactive/non-default records are included unless your filter excludes them.

Before you call

Guest access follows the shared read context.

Request

Bodyless.

Result

HTTP 200 items array of language records, plus paginator. Empty items [] is explicitly returned when no rows match. Default ordering id DESC; no resource scope/active restriction.

curl "${WALLKIT_API_BASE}/api/v1/languages?page=1&limit=10"

const response = await fetch(`${process.env.WALLKIT_API_BASE}/api/v1/languages?page=1&limit=10`);
console.log(response.status, await response.json());

import os, json
from urllib.request import Request, urlopen
from urllib.error import HTTPError

request = Request(os.environ["WALLKIT_API_BASE"] + "/api/v1/languages?page=1&limit=10", method="GET")
try:
    with urlopen(request) as response:
        print(response.status, json.load(response))
except HTTPError as error:
    print(error.code, json.load(error))

{
  "items": [
    {
      "id": 10,
      "slug": "en",
      "title": "English"
    }
  ],
  "paginator": {
    "current_page": 1,
    "page": 1,
    "total_pages": 1,
    "total_items": 1,
    "limit": 10
  }
}

Read one language record

GET /api/v1/languages/{id}

Read a configured language by its sanitized local numeric ID, without resource/active restriction.

Before you call

Guest access follows the shared read context.

Request

Bodyless; id path required, integer-sanitized. Registered path is not digit-restricted; use the local integer from list. No slug lookup/filter/pagination.

Result

HTTP 200 top-level language record, not items/data wrapper.

curl "${WALLKIT_API_BASE}/api/v1/languages/10"

const response = await fetch(`${process.env.WALLKIT_API_BASE}/api/v1/languages/10`);
console.log(response.status, await response.json());

import os, json
from urllib.request import Request, urlopen
from urllib.error import HTTPError

request = Request(os.environ["WALLKIT_API_BASE"] + "/api/v1/languages/10", method="GET")
try:
    with urlopen(request) as response:
        print(response.status, json.load(response))
except HTTPError as error:
    print(error.code, json.load(error))

{
  "id": 10,
  "slug": "en",
  "title": "English"
}

{"error":"language_not_found","error_description":"Language not found"}

Read currency labels through the admin-prefixed route

GET /api/v1/admin/currency

Read the same global configured labels as the unprefixed currency action.

Before you call

The admin-prefixed registration targets the same api controller/action as its unprefixed counterpart, with guest ACL and no required user/resource guard. No admin credential is required solely because of this prefix. If credentials are supplied, shared admin-path session resolution can differ; guest examples omit them. The collection is not restricted to an admin account.

Request

Bodyless; no supported pagination/filter/mode/currency query. Reads global configured currencies, not resource/member-specific selection.

Result

HTTP 200 uses the exact currency-label collection, including conditional items omission. Global configuration order is preserved; no currency conversion or paginator is returned.

curl "${WALLKIT_API_BASE}/api/v1/admin/currency"

const response = await fetch(`${process.env.WALLKIT_API_BASE}/api/v1/admin/currency`);
console.log(response.status, await response.json());

import os, json
from urllib.request import Request, urlopen
from urllib.error import HTTPError

request = Request(os.environ["WALLKIT_API_BASE"] + "/api/v1/admin/currency", method="GET")
try:
    with urlopen(request) as response:
        print(response.status, json.load(response))
except HTTPError as error:
    print(error.code, json.load(error))

{
  "items": [
    {
      "title": "USD"
    },
    {
      "title": "EUR"
    }
  ]
}

Read countries through the admin-prefixed route

GET /api/v1/admin/countries

Read country/state choices or conditional global grouped country text using the same action as the unprefixed route.

Before you call

The admin-prefixed registration targets the same api controller/action as its unprefixed counterpart, with guest ACL and no required user/resource guard. No admin credential is required solely because of this prefix. If credentials are supplied, shared admin-path session resolution can differ; guest examples omit them. The collection is not restricted to an admin account.

Optional valid resource and real=true/use_group_users_country can select the global user-country branch, with the same privacy/scope limits. Existing admin credentials can affect IP resolver override; omission in this example uses default request-resolution/fallback.

Request

Bodyless; optional resource header, real query Boolean-filter flag and admin-only resolver ip override follow the countries request contract. No member/resource guard or extra admin-account filter.

Result

HTTP 200 items with the exact country/grouped projection. No paginator. Country sort DESC/title ASC; grouped order unspecified.

curl "${WALLKIT_API_BASE}/api/v1/admin/countries"

const response = await fetch(`${process.env.WALLKIT_API_BASE}/api/v1/admin/countries`);
console.log(response.status, await response.json());

import os, json
from urllib.request import Request, urlopen
from urllib.error import HTTPError

request = Request(os.environ["WALLKIT_API_BASE"] + "/api/v1/admin/countries", method="GET")
try:
    with urlopen(request) as response:
        print(response.status, json.load(response))
except HTTPError as error:
    print(error.code, json.load(error))

{
  "items": [
    {
      "id": 1,
      "code": "US",
      "title": "United States",
      "selected": true,
      "states": []
    }
  ]
}