Customers
CRUD for customers and their payment stats.
Newest first, as { data, total, take, skip } with take up to 100 (default 100). Each customer carries payments, succeeded and the gross settled total (amounts added as numbers, whatever the asset) of the payment intents paid from its wallets, on the key's network only. The payer of a settled payment whose wallet no customer holds is added automatically (reference: auto).
Requires the customers:read scope.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
take?numberPage size: how many items to return (1 to 100).
value <= 100100skip?numberHow many items to skip before this page (offset).
0OK
The body, query or path failed validation. message is an array of the individual failures.
Routes that reject a valid request for a reason of their own (an amount, a memo, a state) document the code for it on their own 400.
no_authenticated_consumer: The gateway forwarded no API key identity
insufficient_scope: the API key does not hold the scope this route requires. The shared public API key also gets this on every route that is not marked x-cosmos-public-key, with a message saying so; more scopes will not help, the key is the wrong one.
gateway_required: the request did not arrive through APISIX.
Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.
curl -X GET 'https://api.cosmospay.lat/cosmos-api/v1/customers'{ "data": [ { "id": "clz9xcust00001", "name": "Ada Lovelace", "alias": "Acme (billing)", "email": "ada@example.com", "wallets": [ { "id": "cw4f0c2a9d1b7e83c5a6f9d2e1b0c3a7f8", "chain": "stellar", "address": "GCALNQQBXAPZ2WIRSDDBMSTAKCUH5SG6U76YBFLQLIXJTF7FE5AX7AOO", "label": "Treasury", "createdAt": "2026-06-21T12:34:56.000Z" } ], "account": "GCALNQQBXAPZ2WIRSDDBMSTAKCUH5SG6U76YBFLQLIXJTF7FE5AX7AOO", "note": "Prefers wire settlement", "reference": "ext_4821", "createdAt": "2026-06-21T12:34:56.000Z", "updatedAt": "2026-06-21T12:34:57.000Z", "payments": 12, "succeeded": 11, "total": "1042.5" } ], "total": 137, "take": 100, "skip": 0}A customer holds up to 20 wallets on Stellar, Solana or Monad (the deprecated account counts as one of them), and a wallet named twice counts once. Payments settled from any of them count toward the customer. A wallet another of your customers already holds is 409 customer_wallet_taken.
Requires the customers:write scope.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
application/json- body
A customer to create: a merchant-managed record whose wallets' payments count toward it.
name*stringCustomer name (1 to 120 characters).
alias?stringAn alternative display name (at most 120 characters).
note?stringFree-text note about the customer (at most 500 characters).
email?stringContact email address (at most 160 characters).
account?stringDeprecatedDeprecated: use wallets. One wallet, its chain read from its shape: a Stellar account (G..., checksum verified), a Solana address (base58, 32 bytes) or a Monad address (0x + 40 hex, any case; stored EIP-55 checksummed). It is added to wallets.
wallets?array<>The customer's wallets, on any chain payments settle on, up to 20. Payment intents paid from any of them count toward the customer. A wallet belongs to one customer: one that another customer of yours already holds answers 409 customer_wallet_taken.
reference?stringYour own reference for the customer (at most 120 characters).
Created
The body, query or path failed validation. message is an array of the individual failures.
Routes that reject a valid request for a reason of their own (an amount, a memo, a state) document the code for it on their own 400.
no_authenticated_consumer: The gateway forwarded no API key identity
insufficient_scope: the API key does not hold the scope this route requires. The shared public API key also gets this on every route that is not marked x-cosmos-public-key, with a message saying so; more scopes will not help, the key is the wrong one.
gateway_required: the request did not arrive through APISIX.
customer_wallet_taken: Another of your customers already holds that wallet
Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.
curl -X POST 'https://api.cosmospay.lat/cosmos-api/v1/customers' \ -H 'Content-Type: application/json' \ -d '{ "name": "Acme Inc."}'{ "id": "clz9xcust00001", "name": "Ada Lovelace", "alias": "Acme (billing)", "email": "ada@example.com", "wallets": [ { "id": "cw4f0c2a9d1b7e83c5a6f9d2e1b0c3a7f8", "chain": "stellar", "address": "GCALNQQBXAPZ2WIRSDDBMSTAKCUH5SG6U76YBFLQLIXJTF7FE5AX7AOO", "label": "Treasury", "createdAt": "2026-06-21T12:34:56.000Z" } ], "account": "GCALNQQBXAPZ2WIRSDDBMSTAKCUH5SG6U76YBFLQLIXJTF7FE5AX7AOO", "note": "Prefers wire settlement", "reference": "ext_4821", "createdAt": "2026-06-21T12:34:56.000Z", "updatedAt": "2026-06-21T12:34:57.000Z"}The customer with its wallets, oldest first, and account, the deprecated first wallet's address. Payment stats are on the list only.
Requires the customers:read scope.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
id*stringOK
The body, query or path failed validation. message is an array of the individual failures.
Routes that reject a valid request for a reason of their own (an amount, a memo, a state) document the code for it on their own 400.
no_authenticated_consumer: The gateway forwarded no API key identity
insufficient_scope: the API key does not hold the scope this route requires. The shared public API key also gets this on every route that is not marked x-cosmos-public-key, with a message saying so; more scopes will not help, the key is the wrong one.
gateway_required: the request did not arrive through APISIX.
No such resource, or it exists and belongs to another consumer. The two are deliberately the same answer: "exists but not yours" is an ownership oracle.
Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.
curl -X GET 'https://api.cosmospay.lat/cosmos-api/v1/customers/string'{ "id": "clz9xcust00001", "name": "Ada Lovelace", "alias": "Acme (billing)", "email": "ada@example.com", "wallets": [ { "id": "cw4f0c2a9d1b7e83c5a6f9d2e1b0c3a7f8", "chain": "stellar", "address": "GCALNQQBXAPZ2WIRSDDBMSTAKCUH5SG6U76YBFLQLIXJTF7FE5AX7AOO", "label": "Treasury", "createdAt": "2026-06-21T12:34:56.000Z" } ], "account": "GCALNQQBXAPZ2WIRSDDBMSTAKCUH5SG6U76YBFLQLIXJTF7FE5AX7AOO", "note": "Prefers wire settlement", "reference": "ext_4821", "createdAt": "2026-06-21T12:34:56.000Z", "updatedAt": "2026-06-21T12:34:57.000Z"}Changes only the fields sent (name, alias, note, email, reference). The deprecated account edits the first wallet only: an address replaces or adds it, null removes it; other wallets change through /v1/customers/{id}/wallets. An address another of your customers holds is 409 customer_wallet_taken.
Requires the customers:write scope.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
id*stringapplication/json- body
Changes to a customer's own fields; only the fields sent change. Wallets change through /v1/customers/{id}/wallets.
name?stringCustomer name (1 to 120 characters).
alias?stringAn alternative display name (at most 120 characters).
note?stringFree-text note about the customer (at most 500 characters).
email?stringContact email address (at most 160 characters).
reference?stringYour own reference for the customer (at most 120 characters).
account?|DeprecatedDeprecated: manage wallets with POST and DELETE /v1/customers/{id}/wallets. The customer's first wallet: an address replaces it (or adds one), its chain read from its shape; null removes it.
OK
The body, query or path failed validation. message is an array of the individual failures.
Routes that reject a valid request for a reason of their own (an amount, a memo, a state) document the code for it on their own 400.
no_authenticated_consumer: The gateway forwarded no API key identity
insufficient_scope: the API key does not hold the scope this route requires. The shared public API key also gets this on every route that is not marked x-cosmos-public-key, with a message saying so; more scopes will not help, the key is the wrong one.
gateway_required: the request did not arrive through APISIX.
No such resource, or it exists and belongs to another consumer. The two are deliberately the same answer: "exists but not yours" is an ownership oracle.
customer_wallet_taken: Another of your customers already holds that wallet
Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.
curl -X PATCH 'https://api.cosmospay.lat/cosmos-api/v1/customers/string' \ -H 'Content-Type: application/json' \ -d '{}'{ "id": "clz9xcust00001", "name": "Ada Lovelace", "alias": "Acme (billing)", "email": "ada@example.com", "wallets": [ { "id": "cw4f0c2a9d1b7e83c5a6f9d2e1b0c3a7f8", "chain": "stellar", "address": "GCALNQQBXAPZ2WIRSDDBMSTAKCUH5SG6U76YBFLQLIXJTF7FE5AX7AOO", "label": "Treasury", "createdAt": "2026-06-21T12:34:56.000Z" } ], "account": "GCALNQQBXAPZ2WIRSDDBMSTAKCUH5SG6U76YBFLQLIXJTF7FE5AX7AOO", "note": "Prefers wire settlement", "reference": "ext_4821", "createdAt": "2026-06-21T12:34:56.000Z", "updatedAt": "2026-06-21T12:34:57.000Z"}Deletes the customer and its wallets. Payment intents are kept; a later settled payment from one of those wallets adds its payer back as an automatic customer.
Requires the customers:write scope.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
id*stringOK
The body, query or path failed validation. message is an array of the individual failures.
Routes that reject a valid request for a reason of their own (an amount, a memo, a state) document the code for it on their own 400.
no_authenticated_consumer: The gateway forwarded no API key identity
insufficient_scope: the API key does not hold the scope this route requires. The shared public API key also gets this on every route that is not marked x-cosmos-public-key, with a message saying so; more scopes will not help, the key is the wrong one.
gateway_required: the request did not arrive through APISIX.
No such resource, or it exists and belongs to another consumer. The two are deliberately the same answer: "exists but not yours" is an ownership oracle.
Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.
curl -X DELETE 'https://api.cosmospay.lat/cosmos-api/v1/customers/string'{ "id": "clz9xcust00001", "deleted": true}A customer holds any number of wallets (up to 20), on Stellar, Solana or Monad; payments paid from any of them count toward it. A wallet the customer already holds answers as it is.
Requires the customers:write scope.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
id*stringapplication/json- body
One wallet of a customer: the chain it is on and its address there.
chain*stringThe chain the wallet is on.
"stellar""solana""monad"address*stringThe address on that chain: a Stellar account (G..., checksum verified), a Solana address (base58, 32 bytes) or a Monad address (0x + 40 hex, any case; stored EIP-55 checksummed). Payment intents whose payer (source) is this address count toward the customer.
label?stringA name for the wallet, shown beside the address.
Created
The body, query or path failed validation. message is an array of the individual failures.
Routes that reject a valid request for a reason of their own (an amount, a memo, a state) document the code for it on their own 400.
no_authenticated_consumer: The gateway forwarded no API key identity
insufficient_scope: the API key does not hold the scope this route requires. The shared public API key also gets this on every route that is not marked x-cosmos-public-key, with a message saying so; more scopes will not help, the key is the wrong one.
gateway_required: the request did not arrive through APISIX.
No such resource, or it exists and belongs to another consumer. The two are deliberately the same answer: "exists but not yours" is an ownership oracle.
customer_wallet_taken: Another of your customers already holds that wallet
Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.
curl -X POST 'https://api.cosmospay.lat/cosmos-api/v1/customers/string/wallets' \ -H 'Content-Type: application/json' \ -d '{ "chain": "solana", "address": "7EcDhSYGxXyscszYEp35KHN8vvw3svAuLKTzXwCFLtV"}'{ "id": "cw4f0c2a9d1b7e83c5a6f9d2e1b0c3a7f8", "chain": "stellar", "address": "GCALNQQBXAPZ2WIRSDDBMSTAKCUH5SG6U76YBFLQLIXJTF7FE5AX7AOO", "label": "Treasury", "createdAt": "2026-06-21T12:34:56.000Z"}Payments from that address stop counting toward this customer, and a later settled payment from it adds it as a new automatic customer. A walletId that is not one of this customer's wallets is 404.
Requires the customers:write scope.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
id*stringwalletId*stringOK
The body, query or path failed validation. message is an array of the individual failures.
Routes that reject a valid request for a reason of their own (an amount, a memo, a state) document the code for it on their own 400.
no_authenticated_consumer: The gateway forwarded no API key identity
insufficient_scope: the API key does not hold the scope this route requires. The shared public API key also gets this on every route that is not marked x-cosmos-public-key, with a message saying so; more scopes will not help, the key is the wrong one.
gateway_required: the request did not arrive through APISIX.
No such resource, or it exists and belongs to another consumer. The two are deliberately the same answer: "exists but not yours" is an ownership oracle.
Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.
curl -X DELETE 'https://api.cosmospay.lat/cosmos-api/v1/customers/string/wallets/string'{ "id": "cw4f0c2a9d1b7e83c5a6f9d2e1b0c3a7f8", "deleted": true}