braintree · Schema

Braintree Customer

Represents a customer record stored in the Braintree Vault. Customer records serve as containers for vaulted payment methods, billing addresses, and associated transaction history. They enable returning customer checkout flows and are required for managing subscriptions and recurring billing.

Properties

Name	Type	Description
id	string	Unique identifier for the customer. Auto-generated by Braintree if not specified at creation.
first_name	string	Customer's first name.
last_name	string	Customer's last name.
email	string	Customer's email address. Must use ASCII characters only.
phone	string	Customer's primary phone number.
company	string	Name of the company or organization associated with this customer.
website	string	Customer's website URL. Must be a well-formed URL.
fax	string	Customer's fax number.
payment_methods	array	Collection of vaulted payment methods associated with this customer.
addresses	array	Collection of stored billing and shipping addresses associated with this customer.
custom_fields	object	Custom key-value pairs associated with this customer. Keys must be pre-configured as custom fields in the Braintree Control Panel.
created_at	string	Timestamp when the customer record was created, in ISO 8601 format.
updated_at	string	Timestamp when the customer record was last updated, in ISO 8601 format.

View JSON Schema on GitHub

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://api-evangelist.github.io/braintree/schemas/customer.json",
  "title": "Braintree Customer",
  "description": "Represents a customer record stored in the Braintree Vault. Customer records serve as containers for vaulted payment methods, billing addresses, and associated transaction history. They enable returning customer checkout flows and are required for managing subscriptions and recurring billing.",
  "type": "object",
  "required": ["id"],
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the customer. Auto-generated by Braintree if not specified at creation.",
      "maxLength": 36,
      "pattern": "^[a-zA-Z0-9_-]+$"
    },
    "first_name": {
      "type": "string",
      "description": "Customer's first name.",
      "maxLength": 255
    },
    "last_name": {
      "type": "string",
      "description": "Customer's last name.",
      "maxLength": 255
    },
    "email": {
      "type": "string",
      "format": "email",
      "description": "Customer's email address. Must use ASCII characters only.",
      "maxLength": 255
    },
    "phone": {
      "type": "string",
      "description": "Customer's primary phone number.",
      "maxLength": 255
    },
    "company": {
      "type": "string",
      "description": "Name of the company or organization associated with this customer.",
      "maxLength": 255
    },
    "website": {
      "type": "string",
      "format": "uri",
      "description": "Customer's website URL. Must be a well-formed URL.",
      "maxLength": 255
    },
    "fax": {
      "type": "string",
      "description": "Customer's fax number.",
      "maxLength": 255
    },
    "payment_methods": {
      "type": "array",
      "description": "Collection of vaulted payment methods associated with this customer.",
      "items": {
        "$ref": "#/$defs/PaymentMethod"
      }
    },
    "addresses": {
      "type": "array",
      "description": "Collection of stored billing and shipping addresses associated with this customer.",
      "items": {
        "$ref": "#/$defs/Address"
      }
    },
    "custom_fields": {
      "type": "object",
      "description": "Custom key-value pairs associated with this customer. Keys must be pre-configured as custom fields in the Braintree Control Panel.",
      "additionalProperties": {
        "type": "string"
      }
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "Timestamp when the customer record was created, in ISO 8601 format."
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "description": "Timestamp when the customer record was last updated, in ISO 8601 format."
    }
  },
  "$defs": {
    "PaymentMethod": {
      "type": "object",
      "description": "A payment method stored in the Braintree Vault for a customer. This is a polymorphic object representing credit cards, PayPal accounts, Venmo accounts, or other supported payment types.",
      "required": ["token"],
      "properties": {
        "token": {
          "type": "string",
          "description": "Unique token identifying this vaulted payment method. Used to reference the payment method in transactions and subscriptions.",
          "maxLength": 36
        },
        "customer_id": {
          "type": "string",
          "description": "Identifier of the customer who owns this payment method.",
          "maxLength": 36
        },
        "default": {
          "type": "boolean",
          "description": "Indicates whether this is the customer's default payment method used when no specific token is specified."
        },
        "image_url": {
          "type": "string",
          "format": "uri",
          "description": "URL of an image representing the payment method type, such as a card brand logo."
        },
        "subscriptions": {
          "type": "array",
          "description": "Active subscriptions using this payment method.",
          "items": {
            "type": "object",
            "description": "Brief summary of a subscription using this payment method.",
            "properties": {
              "id": {
                "type": "string",
                "description": "Subscription identifier."
              },
              "plan_id": {
                "type": "string",
                "description": "Billing plan identifier for this subscription."
              },
              "status": {
                "type": "string",
                "description": "Current status of the subscription.",
                "enum": ["Active", "Canceled", "Expired", "Past Due", "Pending"]
              }
            }
          }
        },
        "created_at": {
          "type": "string",
          "format": "date-time",
          "description": "Timestamp when this payment method was vaulted, in ISO 8601 format."
        },
        "updated_at": {
          "type": "string",
          "format": "date-time",
          "description": "Timestamp when this payment method was last updated, in ISO 8601 format."
        }
      }
    },
    "Address": {
      "type": "object",
      "description": "A billing or shipping address stored in the Braintree Vault for a customer.",
      "required": ["id"],
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique identifier for this stored address.",
          "maxLength": 36
        },
        "customer_id": {
          "type": "string",
          "description": "Identifier of the customer this address belongs to.",
          "maxLength": 36
        },
        "first_name": {
          "type": "string",
          "description": "First name of the address holder.",
          "maxLength": 255
        },
        "last_name": {
          "type": "string",
          "description": "Last name of the address holder.",
          "maxLength": 255
        },
        "company": {
          "type": "string",
          "description": "Company or organization name at this address.",
          "maxLength": 255
        },
        "street_address": {
          "type": "string",
          "description": "Primary street address line.",
          "maxLength": 255
        },
        "extended_address": {
          "type": "string",
          "description": "Secondary address line such as apartment or suite number.",
          "maxLength": 255
        },
        "locality": {
          "type": "string",
          "description": "City or locality of the address.",
          "maxLength": 255
        },
        "region": {
          "type": "string",
          "description": "State, province, or region code.",
          "maxLength": 255
        },
        "postal_code": {
          "type": "string",
          "description": "Postal or ZIP code.",
          "maxLength": 9
        },
        "country_code_alpha2": {
          "type": "string",
          "description": "Two-letter ISO 3166-1 alpha-2 country code.",
          "pattern": "^[A-Z]{2}$"
        },
        "country_code_alpha3": {
          "type": "string",
          "description": "Three-letter ISO 3166-1 alpha-3 country code.",
          "pattern": "^[A-Z]{3}$"
        },
        "country_name": {
          "type": "string",
          "description": "Full country name.",
          "maxLength": 255
        },
        "created_at": {
          "type": "string",
          "format": "date-time",
          "description": "Timestamp when this address was created, in ISO 8601 format."
        },
        "updated_at": {
          "type": "string",
          "format": "date-time",
          "description": "Timestamp when this address was last updated, in ISO 8601 format."
        }
      }
    }
  }
}