---
title: "Update customer by ID"
method: PATCH
path: "/customers/{customerId}"
tags: ["Customers"]
---

# Update customer by ID

`PATCH /customers/{customerId}`

Update a customer's metadata by their system-generated ID.

Most customer updates complete synchronously and return `200` with the updated customer. If the request changes `email` for a customer that has one or more tied Embedded Wallet internal accounts with `EMAIL_OTP` credentials, the email change uses the two-step signed-retry flow so the customer's wallet session authorizes the authentication credential update. On the signed retry, Grid updates the customer email and every tied `EMAIL_OTP` credential across all tied Embedded Wallets as one logical operation. If any tied credential cannot be updated, the customer email is not changed.

For an Embedded Wallet email update:

1. Call `PATCH /customers/{customerId}` with the full update body and no signature headers. Grid returns `202` with `payloadToSign`, `requestId`, and `expiresAt`. The pending challenge binds the submitted update fields and the set of tied Embedded Wallet email OTP credentials that must be updated.

2. Use the session API keypair of a verified authentication credential on one of the customer's tied Embedded Wallets to build an API-key stamp over `payloadToSign`, then retry the same request with that full stamp as the `Grid-Wallet-Signature` header and the `requestId` echoed back as the `Request-Id` header. The retry body must carry the same update fields submitted in step 1. The signed retry returns `200` with the updated customer.

## Headers

- `Grid-Wallet-Signature` string
- `Request-Id` string

## Request body

- union
  - IndividualCustomerUpdateRequest — Request body for `PATCH /customers/{customerId}`. When `email` changes for a customer with tied Embedded Wallet internal accounts, Grid updates the customer email and every tied `EMAIL_OTP` credential across all tied Embedded Wallets through the endpoint's signed-retry flow.
    - `currencies` string[] — Updated list of currency codes the customer will use (ISO 4217 for fiat, e.g. "USD", "EUR"; tickers for crypto, e.g. "BTC", "USDC"). Replaces the existing list. Some currency combinations may require separate customers — if so, the request will be rejected with details.
    - `email` string, email — Email address for the customer. For customers with tied Embedded Wallet internal accounts, changing this value also updates every tied `EMAIL_OTP` credential across all tied Embedded Wallets.
    - `umaAddress` string — Optional UMA address identifier. If provided, the customer's UMA address will be updated. This is an optional identifier to route payments to the customer.
    - `customerType` 'INDIVIDUAL', required
    - `kycStatus` 'UNVERIFIED' | 'PENDING' | 'APPROVED' | 'REJECTED' — The current KYC status of a customer
    - `fullName` string — Individual's full name
    - `birthDate` string, date — Date of birth in ISO 8601 format (YYYY-MM-DD)
    - `nationality` string — Country code (ISO 3166-1 alpha-2)
    - `address` Address
      - `line1` string, required — Street address line 1
      - `line2` string — Street address line 2
      - `city` string — City
      - `state` string — State/Province/Region
      - `postalCode` string, required — Postal/ZIP code
      - `country` string, required — Country code (ISO 3166-1 alpha-2)
  - BusinessCustomerUpdateRequest — Request body for `PATCH /customers/{customerId}`. When `email` changes for a customer with tied Embedded Wallet internal accounts, Grid updates the customer email and every tied `EMAIL_OTP` credential across all tied Embedded Wallets through the endpoint's signed-retry flow.
    - `currencies` string[] — Updated list of currency codes the customer will use (ISO 4217 for fiat, e.g. "USD", "EUR"; tickers for crypto, e.g. "BTC", "USDC"). Replaces the existing list. Some currency combinations may require separate customers — if so, the request will be rejected with details.
    - `email` string, email — Email address for the customer. For customers with tied Embedded Wallet internal accounts, changing this value also updates every tied `EMAIL_OTP` credential across all tied Embedded Wallets.
    - `umaAddress` string — Optional UMA address identifier. If provided, the customer's UMA address will be updated. This is an optional identifier to route payments to the customer.
    - `customerType` 'BUSINESS', required
    - `kybStatus` 'UNVERIFIED' | 'PENDING' | 'APPROVED' | 'REJECTED' — The current KYB status of a business customer
    - `address` Address
      - `line1` string, required — Street address line 1
      - `line2` string — Street address line 2
      - `city` string — City
      - `state` string — State/Province/Region
      - `postalCode` string, required — Postal/ZIP code
      - `country` string, required — Country code (ISO 3166-1 alpha-2)
    - `businessInfo` BusinessInfoUpdate — Additional information for business entities
      - `legalName` string — Legal name of the business
      - `doingBusinessAs` string — Trade name or DBA name of the business, if different from the legal name
      - `country` string — Country of incorporation or registration (ISO 3166-1 alpha-2)
      - `registrationNumber` string — Business registration number
      - `incorporatedOn` string, date — Date of incorporation in ISO 8601 format (YYYY-MM-DD)
      - `entityType` 'SOLE_PROPRIETORSHIP' | 'PARTNERSHIP' | 'LLC' | 'CORPORATION' | 'S_CORPORATION' | 'NON_PROFIT' | 'OTHER' — Legal entity type of the business
      - `taxId` string — Tax identification number
      - `countriesOfOperation` string[] — List of countries where the business operates (ISO 3166-1 alpha-2)
      - `businessType` 'AGRICULTURE_FORESTRY_FISHING_AND_HUNTING' | 'MINING_QUARRYING_AND_OIL_AND_GAS_EXTRACTION' | 'UTILITIES' | 'CONSTRUCTION' | 'MANUFACTURING' | 'WHOLESALE_TRADE' | 'RETAIL_TRADE' | 'TRANSPORTATION_AND_WAREHOUSING' | 'INFORMATION' | 'FINANCE_AND_INSURANCE' | 'REAL_ESTATE_AND_RENTAL_AND_LEASING' | 'PROFESSIONAL_SCIENTIFIC_AND_TECHNICAL_SERVICES' | 'MANAGEMENT_OF_COMPANIES_AND_ENTERPRISES' | 'ADMINISTRATIVE_AND_SUPPORT_AND_WASTE_MANAGEMENT_AND_REMEDIATION_SERVICES' | 'EDUCATIONAL_SERVICES' | 'HEALTH_CARE_AND_SOCIAL_ASSISTANCE' | 'ARTS_ENTERTAINMENT_AND_RECREATION' | 'ACCOMMODATION_AND_FOOD_SERVICES' | 'OTHER_SERVICES' | 'PUBLIC_ADMINISTRATION' — The high-level industry category of the business
      - `purposeOfAccount` 'CONTRACTOR_PAYOUTS' | 'CREATOR_PAYOUTS' | 'EMPLOYEE_PAYOUTS' | 'MARKETPLACE_SELLER_PAYOUTS' | 'SUPPLIER_PAYMENTS' | 'CROSS_BORDER_B2B' | 'AR_AUTOMATION' | 'AP_AUTOMATION' | 'EMBEDDED_PAYMENTS' | 'PLATFORM_FEE_COLLECTION' | 'P2P_TRANSFERS' | 'CHARITABLE_DONATIONS' | 'OTHER' — The intended purpose for using the Grid account
      - `sourceOfFunds` string — The primary source of funds for the business
      - `expectedMonthlyTransactionCount` 'COUNT_UNDER_10' | 'COUNT_10_TO_100' | 'COUNT_100_TO_500' | 'COUNT_500_TO_1000' | 'COUNT_OVER_1000' — Expected number of transactions per month
      - `expectedMonthlyTransactionVolume` 'VOLUME_UNDER_10K' | 'VOLUME_10K_TO_100K' | 'VOLUME_100K_TO_1M' | 'VOLUME_1M_TO_10M' | 'VOLUME_OVER_10M' — Expected total transaction volume per month in USD equivalent
      - `expectedRecipientJurisdictions` string[] — List of countries where the business expects to send payments (ISO 3166-1 alpha-2)

## Response `200`

Customer updated successfully. For Embedded Wallet email updates, this is returned only on the signed retry after the customer email and all tied email OTP credentials have been updated.

- union
  - IndividualCustomer
    - `id` string — System-generated unique identifier
    - `platformCustomerId` string, required — Platform-specific customer identifier
    - `region` string — Country code (ISO 3166-1 alpha-2) representing the customer's regional identity and regulatory jurisdiction.
    - `currencies` string[] — List of currency codes enabled for this customer.
    - `email` string, email — Email address for the customer.
    - `umaAddress` string, required — Full UMA address (always present in responses, even if system-generated). This is an optional identifier to route payments to the customer.
    - `createdAt` string, date-time — Creation timestamp
    - `updatedAt` string, date-time — Last update timestamp
    - `isDeleted` boolean — Whether the customer is marked as deleted
    - `customerType` 'INDIVIDUAL', required
    - `kycStatus` 'UNVERIFIED' | 'PENDING' | 'APPROVED' | 'REJECTED' — The current KYC status of a customer
    - `fullName` string — Individual's full name
    - `birthDate` string, date — Date of birth in ISO 8601 format (YYYY-MM-DD)
    - `nationality` string — Country code (ISO 3166-1 alpha-2)
    - `address` Address
      - `line1` string, required — Street address line 1
      - `line2` string — Street address line 2
      - `city` string — City
      - `state` string — State/Province/Region
      - `postalCode` string, required — Postal/ZIP code
      - `country` string, required — Country code (ISO 3166-1 alpha-2)
  - BusinessCustomer
    - `id` string — System-generated unique identifier
    - `platformCustomerId` string, required — Platform-specific customer identifier
    - `region` string — Country code (ISO 3166-1 alpha-2) representing the customer's regional identity and regulatory jurisdiction.
    - `currencies` string[] — List of currency codes enabled for this customer.
    - `email` string, email — Email address for the customer.
    - `umaAddress` string, required — Full UMA address (always present in responses, even if system-generated). This is an optional identifier to route payments to the customer.
    - `createdAt` string, date-time — Creation timestamp
    - `updatedAt` string, date-time — Last update timestamp
    - `isDeleted` boolean — Whether the customer is marked as deleted
    - `customerType` 'BUSINESS', required
    - `kybStatus` 'UNVERIFIED' | 'PENDING' | 'APPROVED' | 'REJECTED' — The current KYB status of a business customer
    - `address` Address
      - `line1` string, required — Street address line 1
      - `line2` string — Street address line 2
      - `city` string — City
      - `state` string — State/Province/Region
      - `postalCode` string, required — Postal/ZIP code
      - `country` string, required — Country code (ISO 3166-1 alpha-2)
    - `businessInfo` object — Business information returned on a customer. `taxId` and `incorporatedOn` are required on creation but may be absent on legacy customers that pre-date the requirement, so both are optional in responses.
      - `legalName` string, required — Legal name of the business
      - `doingBusinessAs` string — Trade name or DBA name of the business, if different from the legal name
      - `country` string — Country of incorporation or registration (ISO 3166-1 alpha-2)
      - `registrationNumber` string — Business registration number
      - `incorporatedOn` string, date — Date of incorporation in ISO 8601 format (YYYY-MM-DD)
      - `entityType` 'SOLE_PROPRIETORSHIP' | 'PARTNERSHIP' | 'LLC' | 'CORPORATION' | 'S_CORPORATION' | 'NON_PROFIT' | 'OTHER' — Legal entity type of the business
      - `taxId` string — Tax identification number
      - `countriesOfOperation` string[] — List of countries where the business operates (ISO 3166-1 alpha-2)
      - `businessType` 'AGRICULTURE_FORESTRY_FISHING_AND_HUNTING' | 'MINING_QUARRYING_AND_OIL_AND_GAS_EXTRACTION' | 'UTILITIES' | 'CONSTRUCTION' | 'MANUFACTURING' | 'WHOLESALE_TRADE' | 'RETAIL_TRADE' | 'TRANSPORTATION_AND_WAREHOUSING' | 'INFORMATION' | 'FINANCE_AND_INSURANCE' | 'REAL_ESTATE_AND_RENTAL_AND_LEASING' | 'PROFESSIONAL_SCIENTIFIC_AND_TECHNICAL_SERVICES' | 'MANAGEMENT_OF_COMPANIES_AND_ENTERPRISES' | 'ADMINISTRATIVE_AND_SUPPORT_AND_WASTE_MANAGEMENT_AND_REMEDIATION_SERVICES' | 'EDUCATIONAL_SERVICES' | 'HEALTH_CARE_AND_SOCIAL_ASSISTANCE' | 'ARTS_ENTERTAINMENT_AND_RECREATION' | 'ACCOMMODATION_AND_FOOD_SERVICES' | 'OTHER_SERVICES' | 'PUBLIC_ADMINISTRATION' — The high-level industry category of the business
      - `purposeOfAccount` 'CONTRACTOR_PAYOUTS' | 'CREATOR_PAYOUTS' | 'EMPLOYEE_PAYOUTS' | 'MARKETPLACE_SELLER_PAYOUTS' | 'SUPPLIER_PAYMENTS' | 'CROSS_BORDER_B2B' | 'AR_AUTOMATION' | 'AP_AUTOMATION' | 'EMBEDDED_PAYMENTS' | 'PLATFORM_FEE_COLLECTION' | 'P2P_TRANSFERS' | 'CHARITABLE_DONATIONS' | 'OTHER' — The intended purpose for using the Grid account
      - `sourceOfFunds` string — The primary source of funds for the business
      - `expectedMonthlyTransactionCount` 'COUNT_UNDER_10' | 'COUNT_10_TO_100' | 'COUNT_100_TO_500' | 'COUNT_500_TO_1000' | 'COUNT_OVER_1000' — Expected number of transactions per month
      - `expectedMonthlyTransactionVolume` 'VOLUME_UNDER_10K' | 'VOLUME_10K_TO_100K' | 'VOLUME_100K_TO_1M' | 'VOLUME_1M_TO_10M' | 'VOLUME_OVER_10M' — Expected total transaction volume per month in USD equivalent
      - `expectedRecipientJurisdictions` string[] — List of countries where the business expects to send payments (ISO 3166-1 alpha-2)
    - `beneficialOwners` BeneficialOwner[]
      - `id` string, required — Unique identifier for this beneficial owner
      - `customerId` string, required — The ID of the business customer this beneficial owner is associated with
      - `roles` BeneficialOwnerRole[], required — Roles of this person within the business
      - `ownershipPercentage` integer, required — Percentage of ownership in the business (0-100)
      - `personalInfo` BeneficialOwnerPersonalInfo, required
        - `firstName` string, required — First name of the individual
        - `middleName` string — Middle name of the individual
        - `lastName` string, required — Last name of the individual
        - `birthDate` string, date, required — Date of birth in ISO 8601 format (YYYY-MM-DD)
        - `nationality` string, required — Country of nationality (ISO 3166-1 alpha-2)
        - `email` string, email — Email address of the individual
        - `phoneNumber` string — Phone number in E.164 format
        - `address` Address, required
          - `line1` string, required — Street address line 1
          - `line2` string — Street address line 2
          - `city` string — City
          - `state` string — State/Province/Region
          - `postalCode` string, required — Postal/ZIP code
          - `country` string, required — Country code (ISO 3166-1 alpha-2)
        - `idType` 'SSN' | 'ITIN' | 'EIN' | 'NON_US_TAX_ID', required — Type of tax identification
        - `identifier` string, required — The identification number or value
        - `countryOfIssuance` string — Country that issued the identification (ISO 3166-1 alpha-2)
      - `kycStatus` 'UNVERIFIED' | 'PENDING' | 'APPROVED' | 'REJECTED', required — The current KYC status of a customer
      - `createdAt` string, date-time, required — When this beneficial owner was created
      - `updatedAt` string, date-time — When this beneficial owner was last updated

## Other responses

- `202` — Challenge issued for an Embedded Wallet email update. The response contains `payloadToSign` plus a `requestId`. Build an API-key stamp over `payloadToSign` with the session API keypair from a verified authentication credential on one of the customer's tied Embedded Wallets, then retry the same request with `Grid-Wallet-Signature` and `Request-Id`.
- `400` — Bad request
- `401` — Unauthorized. Also returned for Embedded Wallet email update retries when the provided `Grid-Wallet-Signature` is missing, malformed, or does not match the pending customer update challenge, when the `Request-Id` does not match an unexpired pending challenge, or when the retry body does not match the update fields bound into `payloadToSign` on the initial call.
- `404` — Customer not found
- `409` — Conflict. Returned when the supplied email address is already associated with an `EMAIL_OTP` credential on this or another internal account, or when the tied Embedded Wallet email OTP credential set changed between the initial `202` challenge and the signed retry.
- `424` — Failed dependency. Returned when Grid cannot update one or more tied Embedded Wallet email OTP credentials. The customer email is not changed unless all tied credentials are updated successfully.
- `500` — Internal service error

## Changes

- **2026-05-28** `d0bce562bffd` — 6 warning, 5 info
  - added the new `REQUEST_ID_MISSING` enum value to the `code` response property for the response status `401`
  - added the new `UMA_NOT_FOUND` enum value to the `code` response property for the response status `404`
  - added the new `WALLET_SIGNATURE_BODY_MISMATCH` enum value to the `code` response property for the response status `401`
  - added the new `WALLET_SIGNATURE_INVALID` enum value to the `code` response property for the response status `401`
  - …7 more
- **2026-04-27** `5b8a8161eeb3` — 12 warning, 48 info
  - removed the request property `oneOf[subschema #2: Business Customer Update Request]/allOf[#/components/schemas/BusinessCustomerFields]/beneficialOwners`
  - removed the optional property `oneOf[subschema #1: Individual Customer]/allOf[#/components/schemas/Customer]/kycStatus` from the response with the `200` status
  - removed the optional property `oneOf[subschema #2: Business Customer]/allOf[#/components/schemas/BusinessCustomerFields]/beneficialOwners` from the response with the `200` status
  - removed the optional property `oneOf[subschema #2: Business Customer]/allOf[#/components/schemas/Customer]/kycStatus` from the response with the `200` status
  - …56 more
- …earlier changes not shown

[Full history](https://skmtc.dev/lightsparkdev/apis/grid-api/changes/customers/:customerId/patch.md)

---

[API](https://skmtc.dev/lightsparkdev/apis/grid-api.md) · [All operations](https://skmtc.dev/lightsparkdev/apis/grid-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/lightsparkdev/grid-api/revisions/d0bce562bffd/schema)