{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/nmi/json-schema/nmi-update-customer-request-schema.json",
  "title": "Update Customer Request",
  "description": "Request schema for updating a customer. Supports bulk updates of billing and shipping addresses. All provided billing and shipping addresses will be updated.",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/nmi-customers-api-openapi.yml#/components/schemas/UpdateCustomerRequest",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "maxLength": 36,
      "description": "Customer vault identifier. Max 36 characters."
    },
    "billing": {
      "type": "array",
      "description": "Array of billing addresses to update. Each billing address can be partially updated by providing only the fields that need to change.",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "maxLength": 32,
            "description": "Billing address ID to update. If not provided, the billing address with priority '1' will be updated, or a new one will be created. Max 32 characters."
          },
          "first_name": {
            "type": "string",
            "maxLength": 50,
            "description": "First name"
          },
          "last_name": {
            "type": "string",
            "maxLength": 50,
            "description": "Last name"
          },
          "company": {
            "type": "string",
            "maxLength": 100,
            "description": "Company name"
          },
          "address1": {
            "type": "string",
            "maxLength": 100,
            "description": "Address line 1"
          },
          "address2": {
            "type": "string",
            "maxLength": 100,
            "description": "Address line 2"
          },
          "city": {
            "type": "string",
            "maxLength": 50,
            "description": "City"
          },
          "state": {
            "type": "string",
            "maxLength": 50,
            "description": "State or province. Format: `CC`"
          },
          "zip": {
            "type": "string",
            "maxLength": 20,
            "description": "ZIP or postal code"
          },
          "country": {
            "type": "string",
            "maxLength": 2,
            "description": "Country code (ISO 3166-1 alpha-2). Format: `CC`"
          },
          "phone": {
            "type": "string",
            "description": "Phone number"
          },
          "email": {
            "type": "string",
            "format": "email",
            "description": "Email address"
          },
          "fax": {
            "type": "string",
            "maxLength": 50,
            "description": "Fax number"
          },
          "priority": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Priority of the billing address"
          },
          "currency": {
            "type": "string",
            "minLength": 3,
            "maxLength": 3,
            "description": "ISO 4217 currency code used for payment validation. Defaults to `USD` when omitted."
          },
          "payment_details": {
            "$ref": "#/$defs/CustomerVaultPaymentDetails"
          },
          "cardholder_auth": {
            "$ref": "#/$defs/CardholderAuth"
          }
        }
      }
    },
    "shipping": {
      "type": "array",
      "description": "Array of shipping addresses to update. Each shipping address can be partially updated by providing only the fields that need to change.",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "maxLength": 32,
            "description": "Shipping address ID to update. If not provided, the shipping address with priority '1' will be updated, or a new one will be created. Max 32 characters."
          },
          "first_name": {
            "type": "string",
            "maxLength": 50,
            "description": "First name"
          },
          "last_name": {
            "type": "string",
            "maxLength": 50,
            "description": "Last name"
          },
          "company": {
            "type": "string",
            "maxLength": 100,
            "description": "Company name"
          },
          "address1": {
            "type": "string",
            "maxLength": 100,
            "description": "Address line 1"
          },
          "address2": {
            "type": "string",
            "maxLength": 100,
            "description": "Address line 2"
          },
          "city": {
            "type": "string",
            "maxLength": 50,
            "description": "City"
          },
          "state": {
            "type": "string",
            "maxLength": 50,
            "description": "State or province. Format: `CC`"
          },
          "zip": {
            "type": "string",
            "maxLength": 20,
            "description": "ZIP or postal code"
          },
          "country": {
            "type": "string",
            "maxLength": 2,
            "description": "Country code (ISO 3166-1 alpha-2). Format: `CC`"
          },
          "phone": {
            "type": "string",
            "description": "Phone number"
          },
          "email": {
            "type": "string",
            "format": "email",
            "description": "Email address"
          },
          "fax": {
            "type": "string",
            "maxLength": 50,
            "description": "Fax number"
          },
          "priority": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Priority of the shipping address"
          }
        }
      }
    },
    "merchant_defined_fields": {
      "$ref": "#/$defs/MerchantDefinedFields"
    }
  },
  "$defs": {
    "CardholderAuth": {
      "type": "object",
      "title": "Cardholder Authentication",
      "description": "Cardholder authentication data. Use the 3-D Secure variant for EMV authentication results. Use the Decrypted wallet variant for merchant-decrypted Apple Pay or Google Pay, which relays the cryptogram and ECI to the 3-D Secure fields.",
      "oneOf": [
        {
          "type": "object",
          "title": "3-D Secure",
          "description": "EMV 3-D Secure authentication result fields.",
          "additionalProperties": false,
          "required": [
            "status",
            "cavv"
          ],
          "properties": {
            "status": {
              "type": "string",
              "enum": [
                "verified",
                "attempted"
              ],
              "description": "Set 3D Secure condition. Value used to determine E-commerce indicator (ECI)."
            },
            "cavv": {
              "type": "string",
              "maxLength": 50,
              "description": "Cardholder authentication verification value from the 3-D Secure authentication response. Format: base64 encoded."
            },
            "xid": {
              "type": "string",
              "maxLength": 50,
              "description": "Cardholder authentication transaction id. Format: base64 encoded."
            },
            "three_ds_version": {
              "type": "string",
              "maxLength": 10,
              "description": "3DSecure version (for example `2.1.0` or `2.2.0`)."
            },
            "directory_server_id": {
              "type": "string",
              "maxLength": 50,
              "description": "Directory Server Transaction ID from 3DSecure 2.0 authentication. Format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
            }
          }
        },
        {
          "type": "object",
          "title": "Decrypted wallet (Apple Pay / Google Pay)",
          "description": "Wallet authentication for decrypted Apple Pay or Google Pay payments.",
          "additionalProperties": false,
          "required": [
            "cavv"
          ],
          "properties": {
            "cavv": {
              "type": "string",
              "maxLength": 50,
              "description": "Wallet payment cryptogram (submitted in the repurposed 3-D Secure `cavv` field)."
            },
            "eci": {
              "type": "string",
              "maxLength": 10,
              "description": "Electronic Commerce Indicator from the wallet payment data (submitted in the repurposed 3-D Secure `eci` field)."
            }
          }
        }
      ]
    },
    "CustomerVaultPaymentDetails": {
      "title": "Customer Vault Payment Details",
      "description": "Payment method for a customer vault billing record. Supports the same retail card-present variants as payment transactions.",
      "oneOf": [
        {
          "type": "object",
          "title": "Credit card",
          "additionalProperties": false,
          "required": [
            "card_number",
            "card_exp"
          ],
          "properties": {
            "card_number": {
              "type": "string",
              "description": "Credit card number"
            },
            "card_exp": {
              "type": "string",
              "description": "Credit card expiration date. Format: `MMYY`"
            }
          }
        },
        {
          "$ref": "#/$defs/RetailUnencryptedMagneticStripe"
        },
        {
          "$ref": "#/$defs/RetailMagTekMagensaEncryptedSwipe"
        },
        {
          "$ref": "#/$defs/RetailIdTechEncryptedSwipe"
        },
        {
          "$ref": "#/$defs/RetailIdTechEncryptedKeyed"
        },
        {
          "$ref": "#/$defs/RetailIngenicoChip"
        },
        {
          "$ref": "#/$defs/RetailIngenicoSwipe"
        },
        {
          "$ref": "#/$defs/RetailIngenicoNfc"
        },
        {
          "$ref": "#/$defs/RetailIngenicoKeyed"
        },
        {
          "$ref": "#/$defs/RetailMobileSdkEncryptedPayment"
        },
        {
          "type": "object",
          "title": "ACH / check",
          "additionalProperties": false,
          "required": [
            "check_name",
            "check_aba",
            "check_account"
          ],
          "properties": {
            "check_name": {
              "type": "string",
              "maxLength": 50,
              "description": "The name on the customer's ACH account"
            },
            "check_aba": {
              "type": "number",
              "description": "The customer's bank routing number"
            },
            "check_account": {
              "type": "number",
              "description": "The customer's bank account number"
            },
            "account_type": {
              "type": "string",
              "enum": [
                "checking",
                "savings"
              ],
              "description": "The type of ACH account the customer has"
            },
            "account_holder_type": {
              "type": "string",
              "enum": [
                "personal",
                "business"
              ],
              "description": "Whether the ACH account is personal or business"
            },
            "sec_code": {
              "type": "string",
              "enum": [
                "PPD",
                "WEB",
                "TEL",
                "CCD",
                "POP",
                "RCK"
              ],
              "description": "The Standard Entry Class code of the ACH transaction"
            }
          }
        },
        {
          "type": "object",
          "title": "Payment token",
          "additionalProperties": false,
          "required": [
            "payment_token"
          ],
          "properties": {
            "payment_token": {
              "type": "string",
              "description": "The tokenized version of the customer's card or check information"
            },
            "payment": {
              "type": "string",
              "enum": [
                "check",
                "creditcard"
              ],
              "description": "Selects card vs check when a [Payment Component](../docs/payment-component) (or [Collect.js](https://secure.networkmerchants.com/merchants/resources/integration/integration_portal.php#cjs_methodology)) `payment_token` contains both card and ACH data."
            }
          }
        },
        {
          "type": "object",
          "title": "Apple Pay",
          "additionalProperties": false,
          "required": [
            "applepay_payment_data"
          ],
          "properties": {
            "applepay_payment_data": {
              "type": "string",
              "maxLength": 10000,
              "description": "Encrypted payment data from the Apple Pay SDK."
            }
          }
        },
        {
          "type": "object",
          "title": "Google Pay",
          "additionalProperties": false,
          "required": [
            "googlepay_payment_data"
          ],
          "properties": {
            "googlepay_payment_data": {
              "type": "string",
              "maxLength": 10000,
              "description": "Encrypted payment data from the Google Pay SDK."
            }
          }
        },
        {
          "type": "object",
          "title": "Decrypted Apple Pay",
          "additionalProperties": false,
          "required": [
            "decrypted_applepay_data",
            "card_number",
            "card_exp"
          ],
          "properties": {
            "decrypted_applepay_data": {
              "type": "boolean",
              "enum": [
                true
              ],
              "description": "Set to `true` when submitting merchant-decrypted Apple Pay data."
            },
            "card_number": {
              "type": "string",
              "description": "Device primary account number (dPAN) from the decrypted Apple Pay payload."
            },
            "card_exp": {
              "type": "string",
              "description": "Credit card expiration date from the decrypted Apple Pay payload. Format: `MMYY`"
            }
          }
        },
        {
          "type": "object",
          "title": "Decrypted Google Pay",
          "additionalProperties": false,
          "required": [
            "decrypted_googlepay_data",
            "card_number",
            "card_exp"
          ],
          "properties": {
            "decrypted_googlepay_data": {
              "type": "boolean",
              "enum": [
                true
              ],
              "description": "Set to `true` when submitting merchant-decrypted Google Pay data."
            },
            "card_number": {
              "type": "string",
              "description": "Device primary account number (dPAN) from the decrypted Google Pay payload."
            },
            "card_exp": {
              "type": "string",
              "description": "Credit card expiration date from the decrypted Google Pay payload. Format: `MMYY`"
            }
          }
        }
      ]
    },
    "MerchantDefinedFields": {
      "type": "object",
      "title": "Merchant Defined Fields",
      "description": "Custom fields configured in the merchant control panel under Settings → Merchant Defined Fields (`field_1` through `field_20`).",
      "properties": {
        "field_1": {
          "type": "string",
          "maxLength": 255,
          "description": "Merchant defined field 1"
        },
        "field_2": {
          "type": "string",
          "maxLength": 255,
          "description": "Merchant defined field 2"
        },
        "field_3": {
          "type": "string",
          "maxLength": 255,
          "description": "Merchant defined field 3"
        },
        "field_4": {
          "type": "string",
          "maxLength": 255,
          "description": "Merchant defined field 4"
        },
        "field_5": {
          "type": "string",
          "maxLength": 255,
          "description": "Merchant defined field 5"
        },
        "field_6": {
          "type": "string",
          "maxLength": 255,
          "description": "Merchant defined field 6"
        },
        "field_7": {
          "type": "string",
          "maxLength": 255,
          "description": "Merchant defined field 7"
        },
        "field_8": {
          "type": "string",
          "maxLength": 255,
          "description": "Merchant defined field 8"
        },
        "field_9": {
          "type": "string",
          "maxLength": 255,
          "description": "Merchant defined field 9"
        },
        "field_10": {
          "type": "string",
          "maxLength": 255,
          "description": "Merchant defined field 10"
        },
        "field_11": {
          "type": "string",
          "maxLength": 255,
          "description": "Merchant defined field 11"
        },
        "field_12": {
          "type": "string",
          "maxLength": 255,
          "description": "Merchant defined field 12"
        },
        "field_13": {
          "type": "string",
          "maxLength": 255,
          "description": "Merchant defined field 13"
        },
        "field_14": {
          "type": "string",
          "maxLength": 255,
          "description": "Merchant defined field 14"
        },
        "field_15": {
          "type": "string",
          "maxLength": 255,
          "description": "Merchant defined field 15"
        },
        "field_16": {
          "type": "string",
          "maxLength": 255,
          "description": "Merchant defined field 16"
        },
        "field_17": {
          "type": "string",
          "maxLength": 255,
          "description": "Merchant defined field 17"
        },
        "field_18": {
          "type": "string",
          "maxLength": 255,
          "description": "Merchant defined field 18"
        },
        "field_19": {
          "type": "string",
          "maxLength": 255,
          "description": "Merchant defined field 19"
        },
        "field_20": {
          "type": "string",
          "maxLength": 255,
          "description": "Merchant defined field 20"
        }
      }
    },
    "RetailIdTechEncryptedKeyed": {
      "type": "object",
      "title": "Retail ID Tech M130 encrypted keyed",
      "description": "Card-present encrypted keyed entry data from an ID Tech M130 reader. Set `industry` to `retail` on the payment request.",
      "additionalProperties": false,
      "required": [
        "encrypted_data"
      ],
      "properties": {
        "encrypted_data": {
          "type": "string",
          "description": "Raw encrypted data."
        }
      }
    },
    "RetailIdTechEncryptedSwipe": {
      "type": "object",
      "title": "Retail ID Tech M130 encrypted swipe",
      "description": "Card-present encrypted swipe data from an ID Tech M130 reader. Set `industry` to `retail` on the payment request.",
      "additionalProperties": false,
      "required": [
        "encrypted_track_1",
        "encrypted_track_2"
      ],
      "properties": {
        "encrypted_track_1": {
          "type": "string",
          "description": "Raw encrypted data."
        },
        "encrypted_track_2": {
          "type": "string",
          "description": "Raw encrypted data."
        },
        "encrypted_track_3": {
          "type": "string",
          "description": "Raw encrypted data."
        },
        "encrypted_ksn": {
          "type": "string",
          "description": "Raw encrypted data."
        }
      }
    },
    "RetailIngenicoChip": {
      "type": "object",
      "title": "Retail Ingenico Telium 2 chip (EMV)",
      "description": "Card-present EMV chip payment from an Ingenico Telium 2 reader. Set `industry` to `retail` on the payment request.",
      "additionalProperties": false,
      "required": [
        "entry_mode",
        "emv_auth_request_data",
        "emv_device",
        "verification_method",
        "encrypted_ksn",
        "encrypted_track_2"
      ],
      "properties": {
        "entry_mode": {
          "type": "string",
          "enum": [
            "emv_icc"
          ],
          "description": "The type of transaction data to be processed."
        },
        "emv_auth_request_data": {
          "type": "string",
          "description": "EMV data for the transaction as received from the EMV chip card SDK."
        },
        "emv_device": {
          "type": "string",
          "enum": [
            "ingenico_rba"
          ],
          "description": "The EMV-capable card reader."
        },
        "verification_method": {
          "type": "string",
          "enum": [
            "signature",
            "offline_pin",
            "offline_pin_signature",
            "none"
          ],
          "description": "Method used to verify the EMV transaction."
        },
        "encrypted_ksn": {
          "type": "string",
          "description": "Raw encrypted data."
        },
        "encrypted_track_2": {
          "type": "string",
          "description": "Raw encrypted data."
        }
      }
    },
    "RetailIngenicoKeyed": {
      "type": "object",
      "title": "Retail Ingenico Telium 2 keyed",
      "description": "Card-present encrypted keyed entry from an Ingenico Telium 2 reader. Set `industry` to `retail` on the payment request.",
      "additionalProperties": false,
      "required": [
        "entry_mode",
        "emv_device",
        "encrypted_ksn",
        "encrypted_track_2"
      ],
      "properties": {
        "entry_mode": {
          "type": "string",
          "enum": [
            "keyed"
          ],
          "description": "The type of transaction data to be processed."
        },
        "emv_device": {
          "type": "string",
          "enum": [
            "ingenico_rba"
          ],
          "description": "The EMV-capable card reader."
        },
        "encrypted_ksn": {
          "type": "string",
          "description": "Raw encrypted data."
        },
        "encrypted_track_2": {
          "type": "string",
          "description": "Raw encrypted data."
        }
      }
    },
    "RetailIngenicoNfc": {
      "type": "object",
      "title": "Retail Ingenico Telium 2 NFC",
      "description": "Card-present NFC payment from an Ingenico Telium 2 reader. Set `industry` to `retail` on the payment request.",
      "additionalProperties": false,
      "required": [
        "entry_mode",
        "emv_device",
        "encrypted_ksn",
        "encrypted_track_2"
      ],
      "properties": {
        "entry_mode": {
          "type": "string",
          "enum": [
            "nfc_msd"
          ],
          "description": "The type of transaction data to be processed."
        },
        "emv_device": {
          "type": "string",
          "enum": [
            "ingenico_rba"
          ],
          "description": "The EMV-capable card reader."
        },
        "encrypted_ksn": {
          "type": "string",
          "description": "Raw encrypted data."
        },
        "encrypted_track_2": {
          "type": "string",
          "description": "Raw encrypted data."
        }
      }
    },
    "RetailIngenicoSwipe": {
      "type": "object",
      "title": "Retail Ingenico Telium 2 swipe",
      "description": "Card-present encrypted swipe from an Ingenico Telium 2 reader. Set `industry` to `retail` on the payment request.",
      "additionalProperties": false,
      "required": [
        "entry_mode",
        "emv_device",
        "encrypted_ksn",
        "encrypted_track_1",
        "encrypted_track_2"
      ],
      "properties": {
        "entry_mode": {
          "type": "string",
          "enum": [
            "swiped",
            "swiped_emv_fallback"
          ],
          "description": "The type of transaction data to be processed."
        },
        "emv_device": {
          "type": "string",
          "enum": [
            "ingenico_rba"
          ],
          "description": "The EMV-capable card reader."
        },
        "encrypted_ksn": {
          "type": "string",
          "description": "Raw encrypted data."
        },
        "encrypted_track_1": {
          "type": "string",
          "description": "Raw encrypted data."
        },
        "encrypted_track_2": {
          "type": "string",
          "description": "Raw encrypted data."
        }
      }
    },
    "RetailMagTekMagensaEncryptedSwipe": {
      "type": "object",
      "title": "Retail MagTek Magensa encrypted swipe",
      "description": "Card-present payment using encrypted magnetic stripe data from a MagTek Magensa reader. Set `industry` to `retail` on the payment request.",
      "additionalProperties": false,
      "required": [
        "magnesafe_track_1",
        "magnesafe_track_2"
      ],
      "properties": {
        "magnesafe_track_1": {
          "type": "string",
          "description": "Raw MagTek Magensa data."
        },
        "magnesafe_track_2": {
          "type": "string",
          "description": "Raw MagTek Magensa data."
        },
        "magnesafe_magneprint": {
          "type": "string",
          "description": "Raw MagTek Magensa data."
        },
        "magnesafe_ksn": {
          "type": "string",
          "description": "Raw MagTek Magensa data."
        },
        "magnesafe_magneprint_status": {
          "type": "string",
          "description": "Raw MagTek Magensa data."
        }
      }
    },
    "RetailMobileSdkEncryptedPayment": {
      "type": "object",
      "title": "Mobile SDK encrypted payment",
      "description": "RSA-encrypted card data from the NMI Mobile SDK (iOS/Android). Use in place of raw card number, expiration, and CVV. Set `industry` to `retail` on the payment request when processing as a card-present transaction.",
      "additionalProperties": false,
      "required": [
        "encrypted_payment"
      ],
      "properties": {
        "encrypted_payment": {
          "type": "string",
          "description": "Encrypted payment blob returned by the Mobile SDK."
        }
      }
    },
    "RetailUnencryptedMagneticStripe": {
      "type": "object",
      "title": "Retail unencrypted magnetic stripe",
      "description": "Card-present payment using raw magnetic stripe data from a card reader. Set `industry` to `retail` on the payment request.",
      "additionalProperties": false,
      "required": [
        "track_1",
        "track_2"
      ],
      "properties": {
        "track_1": {
          "type": "string",
          "description": "Raw magnetic stripe data."
        },
        "track_2": {
          "type": "string",
          "description": "Raw magnetic stripe data."
        },
        "track_3": {
          "type": "string",
          "description": "Raw magnetic stripe data."
        }
      }
    }
  }
}