{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/stripe/main/json-schema/stripe-post-customers-customer-request-schema.json",
  "title": "PostCustomersCustomerRequest",
  "x-generated": "2026-10-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/stripe-customers-api-openapi.yml#/components/schemas/PostCustomersCustomerRequest",
  "type": "object",
  "properties": {
    "address": {
      "anyOf": [
        {
          "properties": {
            "city": {
              "maxLength": 5000,
              "type": "string"
            },
            "country": {
              "maxLength": 5000,
              "type": "string"
            },
            "line1": {
              "maxLength": 5000,
              "type": "string"
            },
            "line2": {
              "maxLength": 5000,
              "type": "string"
            },
            "postal_code": {
              "maxLength": 5000,
              "type": "string"
            },
            "state": {
              "maxLength": 5000,
              "type": "string"
            }
          },
          "title": "optional_fields_address",
          "type": "object"
        },
        {
          "enum": [
            ""
          ],
          "type": "string"
        }
      ],
      "description": "The customer's address."
    },
    "balance": {
      "description": "An integer amount in cents (or local equivalent) that represents the customer's current balance, which affect the customer's future invoices. A negative amount represents a credit that decreases the amount due on an invoice; a positive amount increases the amount due on an invoice.",
      "type": "integer"
    },
    "bank_account": {
      "anyOf": [
        {
          "properties": {
            "account_holder_name": {
              "maxLength": 5000,
              "type": "string"
            },
            "account_holder_type": {
              "enum": [
                "company",
                "individual"
              ],
              "maxLength": 5000,
              "type": "string"
            },
            "account_number": {
              "maxLength": 5000,
              "type": "string"
            },
            "country": {
              "maxLength": 5000,
              "type": "string"
            },
            "currency": {
              "type": "string"
            },
            "object": {
              "enum": [
                "bank_account"
              ],
              "maxLength": 5000,
              "type": "string"
            },
            "routing_number": {
              "maxLength": 5000,
              "type": "string"
            }
          },
          "required": [
            "account_number",
            "country"
          ],
          "title": "customer_payment_source_bank_account",
          "type": "object"
        },
        {
          "maxLength": 5000,
          "type": "string"
        }
      ],
      "description": "Either a token, like the ones returned by [Stripe.js](https://stripe.com/docs/js), or a dictionary containing a user's bank account details."
    },
    "card": {
      "anyOf": [
        {
          "properties": {
            "address_city": {
              "maxLength": 5000,
              "type": "string"
            },
            "address_country": {
              "maxLength": 5000,
              "type": "string"
            },
            "address_line1": {
              "maxLength": 5000,
              "type": "string"
            },
            "address_line2": {
              "maxLength": 5000,
              "type": "string"
            },
            "address_state": {
              "maxLength": 5000,
              "type": "string"
            },
            "address_zip": {
              "maxLength": 5000,
              "type": "string"
            },
            "cvc": {
              "maxLength": 5000,
              "type": "string"
            },
            "exp_month": {
              "type": "integer"
            },
            "exp_year": {
              "type": "integer"
            },
            "metadata": {
              "additionalProperties": {
                "type": "string"
              },
              "type": "object"
            },
            "name": {
              "maxLength": 5000,
              "type": "string"
            },
            "number": {
              "maxLength": 5000,
              "type": "string"
            },
            "object": {
              "enum": [
                "card"
              ],
              "maxLength": 5000,
              "type": "string"
            }
          },
          "required": [
            "exp_month",
            "exp_year",
            "number"
          ],
          "title": "customer_payment_source_card",
          "type": "object"
        },
        {
          "maxLength": 5000,
          "type": "string"
        }
      ],
      "description": "A token, like the ones returned by [Stripe.js](https://stripe.com/docs/js).",
      "x-stripeBypassValidation": true
    },
    "cash_balance": {
      "description": "Balance information and default balance settings for this customer.",
      "properties": {
        "settings": {
          "properties": {
            "reconciliation_mode": {
              "enum": [
                "automatic",
                "manual",
                "merchant_default"
              ],
              "type": "string"
            }
          },
          "title": "balance_settings_param",
          "type": "object"
        }
      },
      "title": "cash_balance_param",
      "type": "object"
    },
    "coupon": {
      "maxLength": 5000,
      "type": "string"
    },
    "default_alipay_account": {
      "description": "ID of Alipay account to make the customer's new default for invoice payments.",
      "maxLength": 500,
      "type": "string"
    },
    "default_bank_account": {
      "description": "ID of bank account to make the customer's new default for invoice payments.",
      "maxLength": 500,
      "type": "string"
    },
    "default_card": {
      "description": "ID of card to make the customer's new default for invoice payments.",
      "maxLength": 500,
      "type": "string"
    },
    "default_source": {
      "description": "If you are using payment methods created via the PaymentMethods API, see the [invoice_settings.default_payment_method](https://stripe.com/docs/api/customers/update#update_customer-invoice_settings-default_payment_method) parameter.\n\nProvide the ID of a payment source already attached to this customer to make it this customer's default payment source.\n\nIf you want to add a new payment source and make it the default, see the [source](https://stripe.com/docs/api/customers/update#update_customer-source) property.",
      "maxLength": 500,
      "type": "string"
    },
    "description": {
      "description": "An arbitrary string that you can attach to a customer object. It is displayed alongside the customer in the dashboard.",
      "maxLength": 5000,
      "type": "string"
    },
    "email": {
      "description": "Customer's email address. It's displayed alongside the customer in your dashboard and can be useful for searching and tracking. This may be up to *512 characters*.",
      "maxLength": 512,
      "type": "string"
    },
    "expand": {
      "description": "Specifies which fields in the response should be expanded.",
      "items": {
        "maxLength": 5000,
        "type": "string"
      },
      "type": "array"
    },
    "invoice_prefix": {
      "description": "The prefix for the customer used to generate unique invoice numbers. Must be 3–12 uppercase letters or numbers.",
      "maxLength": 5000,
      "type": "string"
    },
    "invoice_settings": {
      "description": "Default invoice settings for this customer.",
      "properties": {
        "custom_fields": {
          "anyOf": [
            {
              "items": {
                "properties": {
                  "name": {
                    "maxLength": 30,
                    "type": "string"
                  },
                  "value": {
                    "maxLength": 30,
                    "type": "string"
                  }
                },
                "required": [
                  "name",
                  "value"
                ],
                "title": "custom_field_params",
                "type": "object"
              },
              "type": "array"
            },
            {
              "enum": [
                ""
              ],
              "type": "string"
            }
          ]
        },
        "default_payment_method": {
          "maxLength": 5000,
          "type": "string"
        },
        "footer": {
          "maxLength": 5000,
          "type": "string"
        },
        "rendering_options": {
          "anyOf": [
            {
              "properties": {
                "amount_tax_display": {
                  "enum": [
                    "",
                    "exclude_tax",
                    "include_inclusive_tax"
                  ],
                  "type": "string"
                }
              },
              "title": "rendering_options_param",
              "type": "object"
            },
            {
              "enum": [
                ""
              ],
              "type": "string"
            }
          ]
        }
      },
      "title": "customer_param",
      "type": "object"
    },
    "metadata": {
      "anyOf": [
        {
          "additionalProperties": {
            "type": "string"
          },
          "type": "object"
        },
        {
          "enum": [
            ""
          ],
          "type": "string"
        }
      ],
      "description": "Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`."
    },
    "name": {
      "description": "The customer's full name or business name.",
      "maxLength": 256,
      "type": "string"
    },
    "next_invoice_sequence": {
      "description": "The sequence to be used on the customer's next invoice. Defaults to 1.",
      "type": "integer"
    },
    "phone": {
      "description": "The customer's phone number.",
      "maxLength": 20,
      "type": "string"
    },
    "preferred_locales": {
      "description": "Customer's preferred languages, ordered by preference.",
      "items": {
        "maxLength": 5000,
        "type": "string"
      },
      "type": "array"
    },
    "promotion_code": {
      "description": "The API ID of a promotion code to apply to the customer. The customer will have a discount applied on all recurring payments. Charges you create through the API will not have the discount.",
      "maxLength": 5000,
      "type": "string"
    },
    "shipping": {
      "anyOf": [
        {
          "properties": {
            "address": {
              "properties": {
                "city": {
                  "maxLength": 5000,
                  "type": "string"
                },
                "country": {
                  "maxLength": 5000,
                  "type": "string"
                },
                "line1": {
                  "maxLength": 5000,
                  "type": "string"
                },
                "line2": {
                  "maxLength": 5000,
                  "type": "string"
                },
                "postal_code": {
                  "maxLength": 5000,
                  "type": "string"
                },
                "state": {
                  "maxLength": 5000,
                  "type": "string"
                }
              },
              "title": "optional_fields_address",
              "type": "object"
            },
            "name": {
              "maxLength": 5000,
              "type": "string"
            },
            "phone": {
              "maxLength": 5000,
              "type": "string"
            }
          },
          "required": [
            "address",
            "name"
          ],
          "title": "customer_shipping",
          "type": "object"
        },
        {
          "enum": [
            ""
          ],
          "type": "string"
        }
      ],
      "description": "The customer's shipping information. Appears on invoices emailed to this customer."
    },
    "source": {
      "maxLength": 5000,
      "type": "string",
      "x-stripeBypassValidation": true
    },
    "tax": {
      "description": "Tax details about the customer.",
      "properties": {
        "ip_address": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "enum": [
                ""
              ],
              "type": "string"
            }
          ]
        },
        "validate_location": {
          "enum": [
            "deferred",
            "immediately"
          ],
          "type": "string"
        }
      },
      "title": "tax_param",
      "type": "object"
    },
    "tax_exempt": {
      "description": "The customer's tax exemption. One of `none`, `exempt`, or `reverse`.",
      "enum": [
        "",
        "exempt",
        "none",
        "reverse"
      ],
      "type": "string"
    }
  }
}