---
updatedAt: 2026-06-12T17:02:44.000Z
agentTools:
  projectIndex: https://developer.spreedly.com/llms.txt
---

# Update gratis payment method

Update a payment method's management state and some specific payment method parameters associated with Advanced Vault.
For further details, see [Advanced Vault](https://developer.spreedly.com/docs/advanced-vault).

Please note, that this API call is only available to merchants who are currently enrolled in Advanced Vault.


# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Spreedly API V1",
    "version": "v1",
    "description": "An OpenAPI specification file for V1 of the Spreedly Core Transactional API"
  },
  "x-explorer-enabled": false,
  "components": {
    "securitySchemes": {
      "basic_auth": {
        "type": "http",
        "scheme": "basic",
        "description": "Unless otherwise noted, all calls to the Spreedly API use [HTTP basic authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) over HTTPS.\n            Use the [environment key](https://developer.spreedly.com/docs/the-spreedly-app#environment-key) of the Spreedly environment you wish to execute against as the HTTP basic user, and one of your organization's [access secrets](https://developer.spreedly.com/docs/the-spreedly-app#access-secrets) as the HTTP basic password."
      }
    },
    "schemas": {
      "errors": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "description": "Which attribute(s) have an error"
            },
            "key": {
              "type": "string",
              "description": "Error Key"
            },
            "message": {
              "type": "string",
              "description": "Error Message"
            }
          },
          "required": [
            "key",
            "message"
          ]
        }
      },
      "payment_method": {
        "type": "object",
        "properties": {
          "token": {
            "type": "string",
            "description": "The token identifying the payment method in the Spreedly vault"
          },
          "created_at": {
            "type": "string",
            "description": "The time the payment method token was created"
          },
          "updated_at": {
            "type": "string",
            "description": "The time the payment method token was last updated"
          },
          "email": {
            "type": "string",
            "description": "The email address of the customer associated with this credit card"
          },
          "storage_state": {
            "type": "string",
            "description": "The `storage_state` (retained, redacted, cached, used) of the payment method"
          },
          "test": {
            "type": "boolean",
            "description": "`true` if this payment method is a test payment method and cannot be used against real gateways or receivers"
          },
          "metadata": {
            "type": "object",
            "description": "metadata key-value pairs (limit 25). Keys are limited to 50 characters. Values are limited to 500 characters and cannot contain compounding data types"
          },
          "callback_url": {
            "type": "string",
            "description": "The URL where Spreedly will attempt delivery of asynchronous results for 3DS and offsite transactions. Transaction results are posted in the format specified by `callback_format` if provided or XML if `callback_format` is not present or null. (default: `null`)"
          },
          "last_four_digits": {
            "type": "string",
            "description": "The last four digits of the credit card number. This can be displayed to the user."
          },
          "first_six_digits": {
            "type": "string",
            "description": "The first six digits of the credit card number. This can be displayed to the user."
          },
          "card_type": {
            "type": "string",
            "description": "The [type](https://developer.spreedly.com/docs/supported-payment-methods), or brand, of the card. Please see the `card_type_mapping` function below for more detail."
          },
          "first_name": {
            "type": "string",
            "description": "The first name of the cardholder"
          },
          "last_name": {
            "type": "string",
            "description": "The last name of the cardholder"
          },
          "month": {
            "type": "string",
            "description": "The expiration month"
          },
          "year": {
            "type": "string",
            "description": "The expiration year"
          },
          "address1": {
            "type": "string",
            "description": "The first line of the billing address"
          },
          "address2": {
            "type": "string",
            "description": "The second line of the billing address"
          },
          "city": {
            "type": "string",
            "description": "The city of the billing address"
          },
          "state": {
            "type": "string",
            "description": "The state of the billing address"
          },
          "zip": {
            "type": "string",
            "description": "The zip code of the billing address"
          },
          "country": {
            "type": "string",
            "description": "The country code of the billing address"
          },
          "phone_number": {
            "type": "string",
            "description": "The phone number of the billing address"
          },
          "house_number_or_name": {
            "type": "string",
            "description": "The house number or building name of the billing address. When `house_number_or_name` and/or `street` are provided, `address1` is composed from them and any separately supplied `address1` is overridden."
          },
          "street": {
            "type": "string",
            "description": "The street name of the billing address. When `house_number_or_name` and/or `street` are provided, `address1` is composed from them and any separately supplied `address1` is overridden."
          },
          "street_line2": {
            "type": "string",
            "description": "The second line of the billing address, such as an apartment, suite, or unit number. Canonical equivalent of `address2`; when provided, it overrides `address2`."
          },
          "phone_number_country_code": {
            "type": "string",
            "description": "The country (international dialing) code of the billing phone number (for example, `1` for the US and Canada)."
          },
          "phone_number_area_code": {
            "type": "string",
            "description": "The area code of the billing phone number (for example, `415`)."
          },
          "company": {
            "type": "string",
            "description": "The company of the cardholder"
          },
          "full_name": {
            "type": "string",
            "description": "The full name of the cardholder."
          },
          "eligible_for_card_updater": {
            "type": "string",
            "description": "`true` if this payment method should be included in Account Updater"
          },
          "shipping_address1": {
            "type": "string",
            "description": "The first line of the shipping address"
          },
          "shipping_address2": {
            "type": "string",
            "description": "The second line of the shipping address"
          },
          "shipping_city": {
            "type": "string",
            "description": "The city of the shipping address"
          },
          "shipping_state": {
            "type": "string",
            "description": "The state of the shipping address"
          },
          "shipping_zip": {
            "type": "string",
            "description": "The zip code of the shipping address"
          },
          "shipping_country": {
            "type": "string",
            "description": "The country code of the shipping address"
          },
          "shipping_house_number_or_name": {
            "type": "string",
            "description": "The house number or building name of the shipping address. When `shipping_house_number_or_name` and/or `shipping_street` are provided, `shipping_address1` is composed from them and any separately supplied `shipping_address1` is overridden."
          },
          "shipping_street": {
            "type": "string",
            "description": "The street name of the shipping address. When `shipping_house_number_or_name` and/or `shipping_street` are provided, `shipping_address1` is composed from them and any separately supplied `shipping_address1` is overridden."
          },
          "shipping_street_line2": {
            "type": "string",
            "description": "The second line of the shipping address, such as an apartment, suite, or unit number. Canonical equivalent of `shipping_address2`; when provided, it overrides `shipping_address2`."
          },
          "shipping_phone_number_country_code": {
            "type": "string",
            "description": "The country (international dialing) code of the shipping phone number (for example, `1` for the US and Canada)."
          },
          "shipping_phone_number_area_code": {
            "type": "string",
            "description": "The area code of the shipping phone number (for example, `415`)."
          },
          "issuer_identification_number": {
            "type": "string",
            "description": "Displays the first 8 digits of the PAN when allowed. Currently allowed for Visa, Mastercard, and Discover cards, otherwise displays the first 6 digits."
          },
          "click_to_pay": {
            "type": "string",
            "description": "`true` if the card was tokenized using Click to Pay"
          },
          "managed": {
            "type": "string",
            "description": "The value indicating the payment method's management status."
          },
          "payment_method_type": {
            "type": "string",
            "description": "The type of this payment method, e.g., `credit_card`, `bank_account`, `apple_pay`, `google_pay`, `third_party_token`, etc…"
          },
          "errors": {
            "type": "string",
            "description": "If the payment method is invalid (missing required fields, etc…), there will be associated error messages here"
          },
          "fingerprint": {
            "type": "string",
            "description": "An identifying string that will match all cards in the environment with the same PAN"
          },
          "verification_value": {
            "type": "string",
            "description": "The obscured verification value (CVV), e.g., XXX or XXXX"
          },
          "number": {
            "type": "string",
            "description": "The obscured credit card number, e.g., XXXX-XXXX-XXXX-4444"
          },
          "bin_metadata": {
            "type": "object",
            "description": "BIN metadata is available in the response if the card is enrolled in Advanced Vault. See [BIN metadata](https://developer.spreedly.com/docs/bin-metadata) for more information.",
            "properties": {
              "card_brand": {
                "type": "string"
              },
              "card_category": {
                "type": "string"
              },
              "card_type": {
                "type": "string"
              },
              "issuing_bank": {
                "type": "string"
              },
              "issuing_country_iso_number": {
                "type": "string"
              },
              "issuing_country_iso_a2_code": {
                "type": "string"
              },
              "issuing_country_iso_a3_code": {
                "type": "string"
              },
              "issuing_country_iso_name": {
                "type": "string"
              },
              "issuing_bank_phone_number": {
                "type": "string"
              },
              "issuing_bank_website": {
                "type": "string"
              },
              "bin_type": {
                "type": "string"
              },
              "regulated": {
                "type": "string"
              },
              "max_pan_length": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            }
          },
          "subscribed_to_mastercard_abu": {
            "type": "boolean",
            "example": false,
            "description": "`true` if this payment method is subscribed to Mastercard ABU updating service"
          },
          "last_successfully_used": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "The time (UTC) the payment method was last successfully transacted with. The following transaction types are considered: Authorization, Purchase, Verification, GeneralCredit, OffsiteVerification, or OffsitePurchase"
          }
        }
      },
      "payment_method_update_gratis": {
        "type": "object",
        "properties": {
          "payment_method": {
            "type": "object",
            "properties": {
              "managed": {
                "type": "boolean",
                "description": "`true` or `false`"
              },
              "allow_blank_name": {
                "type": "boolean",
                "description": "`true` if this payment method should skip the name validation requirement"
              },
              "allow_expired_date": {
                "type": "boolean",
                "description": "`true` if this payment method should skip the expired date validation requirement"
              },
              "allow_blank_date": {
                "type": "boolean",
                "description": "`true` if this payment method should skip the expiration date validation requirement"
              },
              "eligible_for_card_updater": {
                "type": "boolean",
                "description": "`true` if this payment method should be included in Account Updater"
              },
              "callback_url": {
                "type": "string",
                "description": "The URL where Spreedly will attempt delivery of asynchronous results for Advanced Vault, 3DS, and offsite transactions. Transaction results are posted in the format specified by `callback_format` if provided or XML if `callback_format` is not present or null. (default: `null`)"
              }
            }
          }
        }
      },
      "payment_method_response": {
        "type": "object",
        "properties": {
          "payment_method": {
            "$ref": "#/components/schemas/payment_method"
          }
        }
      }
    }
  },
  "servers": [
    {
      "url": "https://core.spreedly.com/v1"
    }
  ],
  "paths": {
    "/payment_methods/{payment_method_token}/update_gratis": {
      "parameters": [
        {
          "name": "payment_method_token",
          "in": "path",
          "description": "The token of the payment method",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "put": {
        "summary": "Update gratis payment method",
        "tags": [
          "payment_methods"
        ],
        "security": [
          {
            "basic_auth": []
          }
        ],
        "operationId": "update-gratis-payment-method",
        "description": "Update a payment method's management state and some specific payment method parameters associated with Advanced Vault.\nFor further details, see [Advanced Vault](https://developer.spreedly.com/docs/advanced-vault).\n\nPlease note, that this API call is only available to merchants who are currently enrolled in Advanced Vault.\n",
        "parameters": [],
        "responses": {
          "200": {
            "description": "successful",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/payment_method_response"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/payment_method_response"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/errors"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/errors"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/errors"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/errors"
                }
              }
            }
          },
          "422": {
            "description": "Unprocessable Entity",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/errors"
                }
              },
              "application/xml": {
                "schema": {
                  "$ref": "#/components/schemas/errors"
                }
              }
            }
          }
        },
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/payment_method_update_gratis"
              },
              "examples": {
                "Update managed status": {
                  "summary": "Update managed status",
                  "value": "{\"payment_method\":{\"managed\":true}}"
                }
              }
            },
            "application/xml": {
              "schema": {
                "$ref": "#/components/schemas/payment_method_update_gratis"
              },
              "examples": {
                "Update managed status": {
                  "summary": "Update managed status",
                  "value": "{\"payment_method\":{\"managed\":true}}"
                }
              }
            }
          }
        }
      }
    }
  }
}
```