Error

A valid request URL is required to generate request examples

{
  "accountId": "network",
  "smsCreditBalance": 500,
  "planTier": "starter",
  "planRenewsAt": "2026-08-28T00:00:00.000Z",
  "updatedAt": "2026-07-28T09:12:00.000Z"
}

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "<string>",
    "statusCode": 123,
    "fieldErrors": [
      {
        "field": "<string>",
        "message": "<string>"
      }
    ]
  }
}

{
  "error": {
    "message": "<string>",
    "statusCode": 123
  }
}

{
  "error": {
    "message": "<string>",
    "statusCode": 123
  }
}

{
  "error": {
    "message": "<string>",
    "statusCode": 123
  }
}

Billing

Grant SMS credits to the account wallet (crédit)

Adds amount SMS credits (a strictly positive integer) to the single account wallet and records them as an adjustment entry on the credit ledger, with the optional source kept as the operator note. This is the UNPAID path: no money changes hands and Stripe is not involved, so use it for pilots, goodwill and corrections only — a customer-funded top-up must go through the top-up checkout operation instead. There is no revoke verb; a correction is another grant (or a negative ledger movement made elsewhere). NOT IDEMPOTENT — there is no dedup key, so a retried call grants the credits a SECOND time and appends a second ledger entry; if a request times out, read the overview and check the ledger before retrying. Returns the wallet as it stands after the credits settled.

POST

credits

grant

Error

A valid request URL is required to generate request examples

{
  "accountId": "network",
  "smsCreditBalance": 500,
  "planTier": "starter",
  "planRenewsAt": "2026-08-28T00:00:00.000Z",
  "updatedAt": "2026-07-28T09:12:00.000Z"
}

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "<string>",
    "statusCode": 123,
    "fieldErrors": [
      {
        "field": "<string>",
        "message": "<string>"
      }
    ]
  }
}

{
  "error": {
    "message": "<string>",
    "statusCode": 123
  }
}

{
  "error": {
    "message": "<string>",
    "statusCode": 123
  }
}

{
  "error": {
    "message": "<string>",
    "statusCode": 123
  }
}

Authorizations

Authorization

string

header

required

Authorization: Bearer <token>. Accepts EITHER a Keycloak access token (scopes-in-token) OR an opaque POS session token; both resolve to the same pos.* scope vocabulary the route guards enforce.

Body

application/json

amount

integer

required

Required range: 0 < x <= 9007199254740991

source

string

Minimum string length: 1

Response

The account wallet at its new materialized balance.

accountId

string

required

Minimum string length: 1

smsCreditBalance

integer

required

Required range: -9007199254740991 <= x <= 9007199254740991

updatedAt

string<date-time>

required

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$

planTier

string

Minimum string length: 1

planRenewsAt

string<date-time>

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$

Read the billing catalogue and current plan Read the credit wallet, ledger and usage (crédit, recharge)

Ventes & encaissement

Catalogue & stock

Finance

Clients & fidélité

Marketing & promotions

Services

Système

Other

Grant SMS credits to the account wallet (crédit)

Authorizations

Body

Response