User API (JS)

User API (JavaScript / Node.js)

These endpoints require client credentials and a valid user sub. The sub is the XWMS user id (stable number/id for that person). You get sub after a successful login in your app and store it in your own xwms_connections table. Use that stored sub here.

All responses use:

{
  "status": "success",
  "message": "Human readable message",
  "data": { "..." : "payload" }
}

Scenario (example flow)

1. User logs in via XWMS -> you store sub in xwms_connections.
2. You call User info to show the profile.
3. You call Address CRUD to list/create/update addresses.

Below you see the exact response structure.

1) User info

Endpoint: POST /api/get/user/info
Auth: client credentials
Scope: userinfo for extra fields

Request

{ "sub": 12345, "socials": true }

Expected response (shortened)

{
  "status": "success",
  "message": "User addresses retrieved successfully.",
  "data": {
    "user": {
      "sub": "12345",
      "name": "John Doe",
      "given_name": "John",
      "family_name": "Doe",
      "email": "john@example.com",
      "email_verified": true,
      "picture": "https://...",
      "birth_date": "2000-01-01",
      "gender": "male",
      "second_email": null,
      "country": "NL",
      "socials": [
        { "platform": "instagram", "username": "john", "url": "https://..." }
      ]
    }
  }
}

If your client does not have userinfo scope, the extra fields may be null.

Helper (npm)

const info = await xwms.getUserInfo(sub, { socials: true });

2) Address CRUD

Endpoint: POST /api/user/address
Auth: client credentials
Scope: useraddresses

Country format

• country is a country code, not an id.
• Use ISO‑2 (e.g. NL, DE) or ISO‑3 (e.g. NLD, DEU).
• The API looks up the country in the database and converts it to country_id.

Actions

• list
• create
• update
• delete

Create request example

{
  "sub": 12345,
  "action": "create",
  "address": {
    "type": "billing",
    "name": "Home",
    "company_name": null,
    "firstname": "John",
    "lastname": "Doe",
    "phone": "+31 612345678",
    "email": "john@example.com",
    "tax_nr": null,
    "registration_nr": null,
    "access_code": null,
    "postal_code": "1012AB",
    "house_number": "10A",
    "street": "Mainstreet",
    "city": "Amsterdam",
    "country": "NL"
  }
}

Expected response (shortened)

{
  "status": "success",
  "message": "Address created successfully.",
  "data": {
    "address": {
      "id": 55,
      "type": "billing",
      "name": "Home",
      "firstname": "John",
      "lastname": "Doe",
      "city": "Amsterdam",
      "country": {
        "id": 1,
        "short_name": "NL",
        "name": "Netherlands",
        "phonecode": "+31",
        "is_eu_member": true
      }
    }
  }
}

Helpers (npm)

const list = await xwms.userAddressCrud(sub, "list");
const created = await xwms.userAddressCrud(sub, "create", { address });
const updated = await xwms.userAddressCrud(sub, "update", { addressId: 55, address });
const removed = await xwms.userAddressCrud(sub, "delete", { addressId: 55 });

3) User payments

Endpoint: POST /api/get/user/payments
Auth: client credentials
Notes: Sensitive identifiers are masked in the response.

Request (example with filters)

{
  "sub": 12345,
  "filters": {
    "currency": "EUR",
    "session_id": "cs_test_123",
    "customer_id": "cus_123",
    "payment_intent": "pi_123",
    "subscription_id": "sub_123",
    "status": "paid",
    "method": "card",
    "mode": "subscription",
    "name": "Starter",
    "query": "starter"
  },
  "page": 1,
  "per_page": 25,
  "paid_only": true
}

Expected response (shortened)

{
  "status": "success",
  "message": "Payments retrieved successfully.",
  "data": {
    "payments": [
      {
        "id": 1,
        "name": "Starter Plan",
        "provider": "stripe",
        "payment_type": "subscription",
        "total": 12.34,
        "currency": "EUR",
        "method": "card",
        "mode": "subscription",
        "status": "paid",
        "paid": true,
        "products_count": 1,
        "identifiers": {
          "session_id": "******t_123",
          "customer_id": "****s_123",
          "payment_intent": "****i_123"
        },
        "created_at": "2026-01-23T12:00:00+00:00"
      }
    ],
    "meta": { "page": 1, "per_page": 25, "total": 1, "count": 1 }
  }
}

4) User purchased products

Endpoint: POST /api/get/user/products
Auth: client credentials
Notes: Returns products linked to user payments.

Request (example with filters)

{
  "sub": 12345,
  "filters": {
    "key": "client_starter",
    "name": "Starter",
    "type": "plan",
    "query": "starter",
    "currency": "EUR",
    "paid_only": true
  },
  "page": 1,
  "per_page": 25
}

Expected response (shortened)

{
  "status": "success",
  "message": "Products retrieved successfully.",
  "data": {
    "products": [
      {
        "payment_id": 1,
        "payment_status": "paid",
        "purchased_at": "2026-01-23T12:00:00+00:00",
        "product_id": 10,
        "product_type": "App\\\\Models\\\\Product",
        "name": "Client Starter Plan",
        "key": "client_starter",
        "type": "plan",
        "description": "Starter plan for developers...",
        "image": "https://...",
        "quantity": 1,
        "unit_price": 12,
        "subtotal": 12,
        "currency": "EUR",
        "is_xwms_product": true
      }
    ],
    "meta": { "page": 1, "per_page": 25, "total": 1, "count": 1 }
  }
}