Browse the docs

Update velocity control

PATCH /v1/api-gateway/controls/velocity/{id}

Partial update; every field is optional (an empty body only bumps updated_at). Same operation as V2 PATCH /controls/velocity/{id}.

Request

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

Path parameters

Field	Type	Description
`id` required	string	Velocity control id.

Body

Field	Type	Description
`limit_amount`	number	New cap for the window: an amount in major units of the card's own currency on a `SPEND` control, a whole number of approved authorizations (integer >= 1) on a `COUNT` one.
`type`	string	`SPEND` or `COUNT`.One of: `SPEND`, `COUNT`
`velocity_window`	string	`MONTH`, `DAY`, `WEEK` or `TOTAL`. All windows are UTC.One of: `MONTH`, `DAY`, `WEEK`, `TOTAL`
`mode`	string	`STRICT` declines a breach; `WATCH` only reports it.One of: `STRICT`, `WATCH`
`only_merchants`	array of object	Replace the merchant allowlist. Omit to leave it unchanged; send `[]` or `null` to clear it.
`only_merchants[].name`	string	Case-insensitive substring of the acquirer merchant name, e.g. "TRAIN TICKETS". Trimmed before matching.
`only_merchants[].mcc`	string	Exact four-digit merchant category code, e.g. "5734".
`enabled`	boolean	Enable or disable the control without deleting it.
`metadata`	object	Your own key-value data to store on this velocity control. It is returned verbatim on every read of the velocity control and never affects how the velocity control 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/v1/api-gateway/controls/velocity/{id}' \
     --header 'x-api-key: YOUR_API_KEY' \
     --header 'content-type: application/json' \
     --data '{
       "limit_amount": 0,
       "type": "SPEND",
       "velocity_window": "MONTH",
       "mode": "STRICT",
       "only_merchants": [
         {
           "name": "string",
           "mcc": "string"
         }
       ],
       "enabled": false,
       "metadata": {
         "team": "field-ops"
       }
     }'

Responses

200 Success

Field	Type	Description
`id` required	string	Velocity control id.
`card_id` required	string, nullable	Card this control applies to, or null for cardholder-level controls.
`cardholder_id` required	string, nullable	Cardholder this control applies to, or null for card-level controls.
`limit_amount` required	number	The cap for the window: an amount in the card's own currency on a `SPEND` control, a whole number of approved authorizations on a `COUNT` one.
`type` required	string	Control type: `SPEND` or `COUNT`.
`velocity_window` required	string	Window the limit applies to: `MONTH`, `DAY`, `WEEK` or `TOTAL`, all UTC.
`mode` required	string	`STRICT` declines a breach; `WATCH` only reports it over the webhook.
`only_merchants` required	array of object	Merchant allowlist, or null when the card is not locked to any merchant.
`only_merchants[].name`	string
`only_merchants[].mcc`	string
`fixed` required	integer	1 when Moon fixed this control to the card it belongs to: the control that makes a card single-use, or the one that locks it to a merchant. A fixed control is read like any other but cannot be updated or deleted here (`CONTROL_IS_FIXED`). What to do instead depends on which one it is: a merchant lock is changed or removed through the card merchant-lock endpoints, while a single-use limit cannot be lifted at all — it ends with the card, so terminate the card to stop it being used. Otherwise 0.One of: `0`, `1`
`enabled` required	integer	1 when enabled, otherwise 0.One of: `0`, `1`
`metadata` required	object	The key-value data you stored on this velocity control, returned exactly as you sent it. An empty object when you never set any — it is never null.
`created_at` required	string
`updated_at` required	string

JSON

{
  "id": "e2c4a6b8-0d1f-4a2b-8c3d-4e5f6a7b8c9d",
  "card_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "cardholder_id": null,
  "limit_amount": 500,
  "type": "SPEND",
  "velocity_window": "MONTH",
  "mode": "STRICT",
  "only_merchants": null,
  "fixed": 0,
  "enabled": 1,
  "metadata": {
    "team": "field-ops"
  },
  "created_at": "2026-08-01T09:12:44.000Z",
  "updated_at": "2026-08-16T17:51:01.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

Velocity control not found (VELOCITY_CONTROL_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 August 16, 2026