Browse the docs

Create account

POST /v2/api-gateway/accounts

Creates an account under organization_id (defaults to your top-level organization). account_currency defaults to USD. A new account starts with balance and available_balance of 0.

Request

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

Headers

Field	Type	Description
`Idempotency-Key`	string	A unique string you choose, up to 255 characters, that makes this request safe to retry. If a request times out or fails in transit, send it again with the same key: the status code and body of the first attempt are returned and the operation is not performed a second time. Stored replies — including failures — are replayed for 24 hours, after which the same key starts a fresh request. Reusing a key for a different request, or sending it while the first request is still running, returns 409. Omit the header and the request behaves exactly as before. Document upload endpoints do not accept it.

Body

Field	Type	Description
`organization_id`	string, uuid	Organization the account belongs to. Omit to use your top-level organization; a child organization must belong to you.
`name`	string	Display name for the account.
`account_currency`	string	ISO-4217 currency the account is denominated in. Defaults to `USD`.One of: `USD`, `MXN`
`metadata`	object	Your own key-value data to store on this account. It is returned verbatim on every read of the account and never affects how the account 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. This account has no update endpoint, so `metadata` is set once, at creation.

Example request

cURL

curl --request POST \
     --url 'https://api.themooncard.com/v2/api-gateway/accounts' \
     --header 'x-api-key: YOUR_API_KEY' \
     --header 'content-type: application/json' \
     --data '{
       "organization_id": "8d2cd518-5ef2-4280-91e8-63b1a0e672e7",
       "name": "string",
       "account_currency": "USD",
       "metadata": {
         "cost_center": "CC-204"
       }
     }'

Responses

201 Success

Field	Type	Description
`id` required	string	Account id.
`name` required	string, nullable
`organization_id` required	string
`ledger_account_id` required	string	Internal. May change or be removed without notice — do not rely on it.
`balance` required	number	Current balance as a number.
`available_balance` required	number	Spendable balance as a number.
`currency` required	string	ISO-4217 currency code, e.g. "USD".
`metadata` required	object	The key-value data you stored on this account, returned exactly as you sent it. An empty object when you never set any — it is never null.
`created_at` required	string	ISO-8601 timestamp.
`updated_at` required	string, nullable	ISO-8601 timestamp, or null.

JSON

{
  "id": "9b2e7d10-6c1f-4a3e-8f5d-2a4b6c8d0e1f",
  "name": "Operations",
  "organization_id": "5c1e2d3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "ledger_account_id": "0a1b2c3d-4e5f-4061-8273-8495a6b7c8d9",
  "balance": 1250.75,
  "available_balance": 1180.25,
  "currency": "USD",
  "metadata": {
    "cost_center": "CC-204"
  },
  "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 }).