User API (Laravel)

User API (Laravel)

Requires client credentials and a valid sub. The sub is the XWMS user id (stable id/number for that person).
You receive it after login and store it in xwms_connections.

Scenario (example flow)

1. User logs in via XWMS -> you store sub.
2. You call User info to display profile.
3. You call Address CRUD to manage addresses.

1) User info

Endpoint: POST /api/get/user/info
Scope: userinfo

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

$info = XwmsApiHelper::getUserInfo($sub, ['socials' => true]);

2) Address CRUD

Endpoint: POST /api/user/address
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.

Create request example

{
  "sub": 12345,
  "action": "create",
  "address": {
    "type": "billing",
    "name": "Home",
    "firstname": "John",
    "lastname": "Doe",
    "email": "john@example.com",
    "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",
      "city": "Amsterdam",
      "country": { "id": 1, "name": "Netherlands" }
    }
  }
}

Helpers

$list = XwmsApiHelper::userAddressCrud($sub, 'list');
$create = XwmsApiHelper::userAddressCrud($sub, 'create', ['address' => $address]);
$update = XwmsApiHelper::userAddressCrud($sub, 'update', [
    'address_id' => 55,
    'address' => $address,
]);
$delete = XwmsApiHelper::userAddressCrud($sub, 'delete', ['address_id' => 55]);

3) User payments

Endpoint: POST /api/get/user/payments
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
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 }
  }
}