Update Vault Form (tag pair)

{exp:cartthrob:update_vault_form} outputs an HTML form for updating an existing saved payment method (vault record) owned by the current member.

This is a form tag (tag pair), and it is commonly used in checkout-related account flows.

See also:

• add_vault_form
• delete_vault_form
• checkout_form
• gateway_fields
• selected_gateway_fields
• gateway_fields_url
• global_form_settings

Parameters

In addition to the tag-specific parameters below, this tag supports shared form parameters from global_form_settings (for example error_handling, show_errors, id, class, name, onsubmit, enctype, action, and validation rules).

vault_id

Required vault record identifier to update.

If vault_id is missing, invalid, or not owned by the current member, the tag returns no output.

vault_id="{segment_3}"

return

Return path used after action completion.

return="store/edit_vault/{segment_3}"

secure_return

If truthy, return URLs are forced to HTTPS.

secure_return="yes"

language

Optional language value passed into action processing.

language="english"

logged_out_redirect

Used by logged-out guard behavior for this form.

logged_out_redirect="account/login"

gateway_method

Optional gateway method value (gateway-specific).

gateway_method="ideal"

required

Pipe-delimited required fields for this form.

required="first_name|name"

required="not ..." is also supported and is converted internally to a not_required list:

required="not first_name|last_name"

authorized_redirect

Optional success-status redirect.

authorized_redirect="store/vaults/updated"

failed_redirect

Optional failed-status redirect.

failed_redirect="store/vaults/failed"

declined_redirect

Optional declined-status redirect.

declined_redirect="store/vaults/declined"

processing_redirect

Optional processing-status redirect.

processing_redirect="store/vaults/processing"

Variables

This form includes global tag/form variables plus vault record values ($vault->toArray()).

Commonly used values include:

• {name}
• {primary}
• {token}
• Customer/billing/shipping fields saved with the vault record

{vault_fields}

If {vault_fields} is present in tag body content, CartThrob replaces it with gateway-generated vault fields HTML (gateway_fields(..., 'vault_fields')).

Inline error variables

When inline error handling is used, form error variables are available (for example errors_exist, {errors}, error:field_name).

Form Fields

1. A hidden vault_id field is automatically injected by the tag.
2. Typical editable fields from real template usage include:
   1. name
   2. primary
   3. customer/billing/shipping fields (for example first_name, address, shipping_city, email_address)
3. Gateway-specific editable fields can be rendered with {vault_fields} when needed by the selected gateway flow.

Behavior and Constraints

1. Logged-out guard behavior is applied.
2. vault_id must resolve to a member-owned vault record; otherwise no form output is returned.
3. If no id parameter is provided, it defaults to update_vault_form.
4. Gateway is forced from the existing vault record (not selected from a gateway parameter).
5. required="not ..." is converted to an exclusion list for gateway-required field validation.
6. Submit action flow (update_vault_action) validates required fields, updates the vault record, and returns form-builder completion/errors.

Examples

Segment-driven vault update form:

{exp:cartthrob:update_vault_form
  error_handling="inline"
  class="form-horizontal"
  vault_id="{segment_3}"
  required="first_name"
  return="store/edit_vault/{segment_3}"}

  <input type="text" name="name" value="{name}" />
  <input type="checkbox" name="primary" value="1" {if primary == 1}checked="checked"{/if} />
  <input type="text" name="first_name" value="{first_name}" />
  <input type="text" name="last_name" value="{last_name}" />
  <input type="text" name="email_address" value="{email_address}" />

  <input type="submit" value="Update Payment Method" />
{/exp:cartthrob:update_vault_form}

With {vault_fields}:

{exp:cartthrob:update_vault_form vault_id="{segment_3}" return="store/vaults"}
  {vault_fields}
  <input type="submit" value="Update" />
{/exp:cartthrob:update_vault_form}