Browse the docs

Update cardholder

PATCH /v2/api-gateway/cardholders/{id}

Partial update. Every field is optional; an empty body makes no changes and returns the current cardholder. organization_id must be one of your organizations.

Request

Authentication: your API key in the x-api-key header.

Path parameters

Field	Type	Description
`id` required	string, uuid	The Moon cardholder id (`id`, a UUID), not your `external_id`.

Body

Field	Type	Description
`external_id`	string	New value for your identifier of the cardholder. Must not be empty when sent. Canonical name for the value this route also accepts as `end_customer_id`. Send one or the other; sending both with different values is rejected.
`end_customer_id`	string	Deprecated alias of `external_id`, kept working for existing integrations. Send one or the other; sending both with different values is rejected.
`organization_id`	string, uuid	UUID of one of your organizations to move the cardholder to. 404 `ORGANIZATION_NOT_FOUND` if it is not one of yours.
`delegated_kyc_completed`	boolean	Whether you have verified this cardholder yourself. `true` sets `delegated_kyc_completed_at` to now; `false` clears it.
`metadata`	object	Your own key-value data to store on this cardholder. It is returned verbatim on every read of the cardholder and never affects how the cardholder is processed — use it to carry your order or customer identifier so you do not have to keep a separate mapping. Up to 50 keys, keys up to 40 characters and values up to 500 characters. Values must be strings — nested objects, arrays, numbers and booleans are rejected. On update the map you send replaces the stored map in full: omit the field to leave it unchanged, send `{}` to clear it, and send a key with an empty string value to remove just that key.

Example request

cURL

curl --request PATCH \
     --url 'https://api.themooncard.com/v2/api-gateway/cardholders/3f5b1c2e-8d4a-4b6f-9e2a-1c7d8e9f0a1b' \
     --header 'x-api-key: YOUR_API_KEY' \
     --header 'content-type: application/json' \
     --data '{
       "external_id": "customer_123",
       "end_customer_id": "customer_123",
       "organization_id": "5c1e2d3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
       "delegated_kyc_completed": true,
       "metadata": {
         "crm_id": "CRM-4821"
       }
     }'

Responses

200 Success

Field	Type	Description
`id` required	string	Cardholder id (Moon-assigned).
`external_id` required	string, nullable	Your identifier for this cardholder (the `end_customer_id` you supplied), or null.
`organization_id` required	string	Owning organization.
`email` required	string, nullable
`delegated_kyc_completed_at` required	string, nullable	When delegated KYC was marked complete, or null.
`banned_at` required	string, nullable	When the cardholder was banned, or null.
`auth_enabled_at` required	string, nullable	When cardholder authentication was enabled, or null.
`last_login_at` required	string, nullable	When the cardholder last logged in, or null.
`metadata` required	object	The key-value data you stored on this cardholder, returned exactly as you sent it. An empty object when you never set any — it is never null.
`created_at` required	string, nullable
`updated_at` required	string, nullable

JSON

{
  "id": "3f5b1c2e-8d4a-4b6f-9e2a-1c7d8e9f0a1b",
  "external_id": "customer_123",
  "organization_id": "5c1e2d3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "email": "jane@example.com",
  "delegated_kyc_completed_at": "2026-08-02T14:20:05.000Z",
  "banned_at": null,
  "auth_enabled_at": "2026-08-02T14:21:00.000Z",
  "last_login_at": "2026-08-15T09:03:44.000Z",
  "metadata": {
    "crm_id": "CRM-4821"
  },
  "created_at": "2026-08-01T09:12:44.000Z",
  "updated_at": "2026-08-15T09:03:44.000Z"
}

400 Error

Validation failed (errors[] lists each offending field) or a domain rule rejected the request ({ message, code }).

The body is the standard error object: see Errors.

401 Error

Missing or invalid credentials, e.g. { "message": "Invalid API Key", "code": "UNAUTHORIZED" }.

The body is the standard error object: see Errors.

404 Error

Cardholder not found (CARDHOLDER_NOT_FOUND) or target organization not owned by you (ORGANIZATION_NOT_FOUND).

The body is the standard error object: see Errors.

500 Error

Unexpected server error. Body is { message: "Internal server error", code: "INTERNAL_SERVER_ERROR" }.

The body is the standard error object: see Errors.

Last updated June 5, 2026