---
title: "Update a token status"
method: POST
path: "/v1/issuing/tokens/{token}"
---

# Update a token status

`POST /v1/issuing/tokens/{token}`

Attempts to update the specified Issuing `Token` object to the status specified.

## Path parameters

- `token` string, required

## Response `200`

Successful response.

- IssuingToken — An issuing token object is created when an issued card is added to a digital wallet. As a [card issuer](https://docs.stripe.com/issuing), you can [view and manage these tokens](https://docs.stripe.com/issuing/controls/token-management) through Stripe.
  - `card` union, required — Card associated with this token.
    - string
    - IssuingCard — You can [create physical or virtual cards](https://docs.stripe.com/issuing) that are issued to cardholders.
      - `brand` string, required — The brand of the card.
      - `cancellation_reason` 'design_rejected' | 'fulfillment_error' | 'lost' | 'stolen', nullable — The reason why the card was canceled.
      - `cardholder` IssuingCardholder, required — An Issuing `Cardholder` object represents an individual or business entity who is [issued](https://docs.stripe.com/issuing) cards. Related guide: [How to create a cardholder](https://docs.stripe.com/issuing/cards/virtual/issue-cards#create-cardholder)
        - `billing` IssuingCardholderAddress, required
          - `address` Address, required
            - `city` string, nullable — City, district, suburb, town, or village.
            - `country` string, nullable — Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)).
            - `line1` string, nullable — Address line 1, such as the street, PO Box, or company name.
            - `line2` string, nullable — Address line 2, such as the apartment, suite, unit, or building.
            - `postal_code` string, nullable — ZIP or postal code.
            - `state` string, nullable — State, county, province, or region ([ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2)).
        - `company` IssuingCardholderCompany
          - `tax_id_provided` boolean, required — Whether the company's business ID number was provided.
        - `created` integer, required — Time at which the object was created. Measured in seconds since the Unix epoch.
        - `email` string, nullable — The cardholder's email address.
        - `id` string, required — Unique identifier for the object.
        - `individual` IssuingCardholderIndividual
          - `card_issuing` IssuingCardholderCardIssuing
            - `user_terms_acceptance` IssuingCardholderUserTermsAcceptance
              - …
          - `dob` IssuingCardholderIndividualDob
            - `day` integer, nullable — The day of birth, between 1 and 31.
            - `month` integer, nullable — The month of birth, between 1 and 12.
            - `year` integer, nullable — The four-digit year of birth.
          - `first_name` string, nullable — The first name of this cardholder. Required before activating Cards. This field cannot contain any numbers, special characters (except periods, commas, hyphens, spaces and apostrophes) or non-latin letters.
          - `last_name` string, nullable — The last name of this cardholder. Required before activating Cards. This field cannot contain any numbers, special characters (except periods, commas, hyphens, spaces and apostrophes) or non-latin letters.
          - `verification` IssuingCardholderVerification
            - `document` IssuingCardholderIdDocument
              - …
        - `livemode` boolean, required — If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
        - `metadata` object, required — Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
        - `name` string, required — The cardholder's name. This will be printed on cards issued to them.
        - `object` 'issuing.cardholder', required — String representing the object's type. Objects of the same type share the same value.
        - `phone_number` string, nullable — The cardholder's phone number. This is required for all cardholders who will be creating EU cards. See the [3D Secure documentation](https://docs.stripe.com/issuing/3d-secure#when-is-3d-secure-applied) for more details.
        - `preferred_locales` string[], nullable — The cardholder’s preferred locales (languages), ordered by preference. Locales can be `da`, `de`, `en`, `es`, `fr`, `it`, `pl`, or `sv`. This changes the language of the [3D Secure flow](https://docs.stripe.com/issuing/3d-secure) and one-time password messages sent to the cardholder.
        - `requirements` IssuingCardholderRequirements, required
          - `disabled_reason` 'listed' | 'rejected.listed' | 'requirements.past_due' | 'under_review', nullable — If `disabled_reason` is present, all cards will decline authorizations with `cardholder_verification_required` reason.
          - `past_due` string[], nullable — Array of fields that need to be collected in order to verify and re-enable the cardholder.
        - `spending_controls` IssuingCardholderAuthorizationControls
          - `allowed_card_presences` string[], nullable — Array of card presence statuses from which authorizations will be allowed. Possible options are `present`, `not_present`. All other statuses will be blocked. Cannot be set with `blocked_card_presences`. Provide an empty value to unset this control.
          - `allowed_categories` string[], nullable — Array of strings containing [categories](https://docs.stripe.com/api#issuing_authorization_object-merchant_data-category) of authorizations to allow. All other categories will be blocked. Cannot be set with `blocked_categories`.
          - `allowed_merchant_countries` string[], nullable — Array of strings containing representing countries from which authorizations will be allowed. Authorizations from merchants in all other countries will be declined. Country codes should be ISO 3166 alpha-2 country codes (e.g. `US`). Cannot be set with `blocked_merchant_countries`. Provide an empty value to unset this control.
          - `blocked_card_presences` string[], nullable — Array of card presence statuses from which authorizations will be declined. Possible options are `present`, `not_present`. Cannot be set with `allowed_card_presences`. Provide an empty value to unset this control.
          - `blocked_categories` string[], nullable — Array of strings containing [categories](https://docs.stripe.com/api#issuing_authorization_object-merchant_data-category) of authorizations to decline. All other categories will be allowed. Cannot be set with `allowed_categories`.
          - `blocked_merchant_countries` string[], nullable — Array of strings containing representing countries from which authorizations will be declined. Country codes should be ISO 3166 alpha-2 country codes (e.g. `US`). Cannot be set with `allowed_merchant_countries`. Provide an empty value to unset this control.
          - `spending_limits` IssuingCardholderSpendingLimit[], nullable — Limit spending with amount-based rules that apply across this cardholder's cards.
            - `amount` integer, required — Maximum amount allowed to spend per interval. This amount is in the card's currency and in the [smallest currency unit](https://docs.stripe.com/currencies#zero-decimal).
            - `categories` string[], nullable — Array of strings containing [categories](https://docs.stripe.com/api#issuing_authorization_object-merchant_data-category) this limit applies to. Omitting this field will apply the limit to all categories.
            - `interval` 'all_time' | 'daily' | 'monthly' | 'per_authorization' | 'weekly' | 'yearly', required — Interval (or event) to which the amount applies.
          - `spending_limits_currency` string, currency, nullable — Currency of the amounts within `spending_limits`.
        - `status` 'active' | 'blocked' | 'inactive', required — Specifies whether to permit authorizations on this cardholder's cards.
        - `type` 'company' | 'individual', required — One of `individual` or `company`. See [Choose a cardholder type](https://docs.stripe.com/issuing/other/choose-cardholder) for more details.
      - `created` integer, required — Time at which the object was created. Measured in seconds since the Unix epoch.
      - `currency` string, currency, required — Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Supported currencies are `usd` in the US, `eur` in the EU, and `gbp` in the UK.
      - `cvc` string — The card's CVC. For security reasons, this is only available for virtual cards, and will be omitted unless you explicitly request it with [the `expand` parameter](https://docs.stripe.com/api/expanding_objects). Additionally, it's only available via the ["Retrieve a card" endpoint](https://docs.stripe.com/api/issuing/cards/retrieve), not via "List all cards" or any other endpoint.
      - `exp_month` integer, required — The expiration month of the card.
      - `exp_year` integer, required — The expiration year of the card.
      - `financial_account` string, nullable — The financial account this card is attached to.
      - `id` string, required — Unique identifier for the object.
      - `last4` string, required — The last 4 digits of the card number.
      - `latest_fraud_warning` IssuingCardFraudWarning
        - `started_at` integer, nullable — Timestamp of the most recent fraud warning.
        - `type` 'card_testing_exposure' | 'fraud_dispute_filed' | 'third_party_reported' | 'user_indicated_fraud', nullable — The type of fraud warning that most recently took place on this card. This field updates with every new fraud warning, so the value changes over time. If populated, cancel and reissue the card.
      - `lifecycle_controls` IssuingCardLifecycleControls
        - `cancel_after` IssuingCardLifecycleConditions, required
          - `payment_count` integer, required — The card is automatically cancelled when it makes this number of non-zero payment authorizations and transactions. The count includes penny authorizations, but doesn't include non-payment actions, such as authorization advice.
      - `livemode` boolean, required — If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
      - `metadata` object, required — Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
      - `number` string — The full unredacted card number. For security reasons, this is only available for virtual cards, and will be omitted unless you explicitly request it with [the `expand` parameter](https://docs.stripe.com/api/expanding_objects). Additionally, it's only available via the ["Retrieve a card" endpoint](https://docs.stripe.com/api/issuing/cards/retrieve), not via "List all cards" or any other endpoint.
      - `object` 'issuing.card', required — String representing the object's type. Objects of the same type share the same value.
      - `personalization_design` union — The personalization design object belonging to this card.
        - string
        - IssuingPersonalizationDesign — A Personalization Design is a logical grouping of a Physical Bundle, card logo, and carrier text that represents a product line.
          - `card_logo` union — The file for the card logo to use with physical bundles that support card logos. Must have a `purpose` value of `issuing_logo`. Image must be in PNG format with dimensions of 1000px by 200px. It must be a binary (black and white) image containing a black logo on a white background. We don't accept grayscale.
            - string
            - File — This object represents files hosted on Stripe's servers. You can upload files with the [create file](https://api.stripe.com#create_file) request (for example, when uploading dispute evidence). Stripe also creates files independently (for example, the results of a [Sigma scheduled query](#scheduled_queries)). Related guide: [File upload guide](https://docs.stripe.com/file-upload)
              - …
          - `carrier_text` IssuingPersonalizationDesignCarrierText
            - `footer_body` string, nullable — The footer body text of the carrier letter.
            - `footer_title` string, nullable — The footer title text of the carrier letter.
            - `header_body` string, nullable — The header body text of the carrier letter.
            - `header_title` string, nullable — The header title text of the carrier letter.
          - `created` integer, required — Time at which the object was created. Measured in seconds since the Unix epoch.
          - `id` string, required — Unique identifier for the object.
          - `livemode` boolean, required — If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
          - `lookup_key` string, nullable — A lookup key used to retrieve personalization designs dynamically from a static string. This may be up to 200 characters.
          - `metadata` object, required — Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
          - `name` string, nullable — Friendly display name.
          - `object` 'issuing.personalization_design', required — String representing the object's type. Objects of the same type share the same value.
          - `physical_bundle` union, required — The physical bundle object belonging to this personalization design.
            - string
            - IssuingPhysicalBundle — A Physical Bundle represents the bundle of physical items - card stock, carrier letter, and envelope - that is shipped to a cardholder when you create a physical card.
              - …
          - `preferences` IssuingPersonalizationDesignPreferences, required
            - `is_default` boolean, required — Whether we use this personalization design to create cards when one isn't specified. A connected account uses the Connect platform's default design if no personalization design is set as the default design.
            - `is_platform_default` boolean, nullable — Whether this personalization design is used to create cards when one is not specified and a default for this connected account does not exist.
          - `rejection_reasons` IssuingPersonalizationDesignRejectionReasons, required
            - `card_logo` string[], nullable — The reason(s) the card logo was rejected.
            - `carrier_text` string[], nullable — The reason(s) the carrier text was rejected.
          - `status` 'active' | 'inactive' | 'rejected' | 'review', required — Whether this personalization design can be used to create cards.
      - `replaced_by` union — The latest card that replaces this card, if any.
        - string
        - IssuingCard — recursive
      - `replacement_for` union — The card this card replaces, if any.
        - string
        - IssuingCard — recursive
      - `replacement_reason` 'damaged' | 'expired' | 'fulfillment_error' | 'lost' | 'stolen', nullable — The reason why the previous card needed to be replaced.
      - `second_line` string, nullable — Text separate from cardholder name, printed on the card.
      - `shipping` IssuingCardShipping
        - `address` Address, required
          - `city` string, nullable — City, district, suburb, town, or village.
          - `country` string, nullable — Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)).
          - `line1` string, nullable — Address line 1, such as the street, PO Box, or company name.
          - `line2` string, nullable — Address line 2, such as the apartment, suite, unit, or building.
          - `postal_code` string, nullable — ZIP or postal code.
          - `state` string, nullable — State, county, province, or region ([ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2)).
        - `address_validation` IssuingCardShippingAddressValidation
          - `mode` 'disabled' | 'normalization_only' | 'validation_and_normalization', required — The address validation capabilities to use.
          - `normalized_address` Address
            - `city` string, nullable — City, district, suburb, town, or village.
            - `country` string, nullable — Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)).
            - `line1` string, nullable — Address line 1, such as the street, PO Box, or company name.
            - `line2` string, nullable — Address line 2, such as the apartment, suite, unit, or building.
            - `postal_code` string, nullable — ZIP or postal code.
            - `state` string, nullable — State, county, province, or region ([ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2)).
          - `result` 'indeterminate' | 'likely_deliverable' | 'likely_undeliverable', nullable — The validation result for the shipping address.
        - `business_name` string, nullable — The name of the business at the shipping address, used on the shipping label to ensure delivery when the card is shipped to a cardholder's workplace.
        - `carrier` 'correos' | 'dhl' | 'fedex' | 'royal_mail' | 'usps', nullable — The delivery company that shipped a card.
        - `customs` IssuingCardShippingCustoms
          - `eori_number` string, nullable — A registration number used for customs in Europe. See [https://www.gov.uk/eori](https://www.gov.uk/eori) for the UK and [https://ec.europa.eu/taxation_customs/business/customs-procedures-import-and-export/customs-procedures/economic-operators-registration-and-identification-number-eori_en](https://ec.europa.eu/taxation_customs/business/customs-procedures-import-and-export/customs-procedures/economic-operators-registration-and-identification-number-eori_en) for the EU.
        - `eta` integer, nullable — A unix timestamp representing a best estimate of when the card will be delivered.
        - `name` string, required — Recipient name.
        - `phone_number` string, nullable — The phone number of the receiver of the shipment. Our courier partners will use this number to contact you in the event of card delivery issues. For individual shipments to the EU/UK, if this field is empty, we will provide them with the phone number provided when the cardholder was initially created.
        - `require_signature` boolean, nullable — Whether a signature is required for card delivery. This feature is only supported for US users. Standard shipping service does not support signature on delivery. The default value for standard shipping service is false and for express and priority services is true.
        - `service` 'express' | 'priority' | 'standard', required — Shipment service, such as `standard` or `express`.
        - `status` 'canceled' | 'delivered' | 'failure' | 'pending' | 'returned' | 'shipped' | 'submitted', nullable — The delivery status of the card.
        - `tracking_number` string, nullable — A tracking number for a card shipment.
        - `tracking_url` string, nullable — A link to the shipping carrier's site where you can view detailed information about a card shipment.
        - `type` 'bulk' | 'individual', required — Packaging options.
      - `spending_controls` IssuingCardAuthorizationControls, required
        - `allowed_card_presences` string[], nullable — Array of card presence statuses from which authorizations will be allowed. Possible options are `present`, `not_present`. All other statuses will be blocked. Cannot be set with `blocked_card_presences`. Provide an empty value to unset this control.
        - `allowed_categories` string[], nullable — Array of strings containing [categories](https://docs.stripe.com/api#issuing_authorization_object-merchant_data-category) of authorizations to allow. All other categories will be blocked. Cannot be set with `blocked_categories`.
        - `allowed_merchant_countries` string[], nullable — Array of strings containing representing countries from which authorizations will be allowed. Authorizations from merchants in all other countries will be declined. Country codes should be ISO 3166 alpha-2 country codes (e.g. `US`). Cannot be set with `blocked_merchant_countries`. Provide an empty value to unset this control.
        - `blocked_card_presences` string[], nullable — Array of card presence statuses from which authorizations will be declined. Possible options are `present`, `not_present`. Cannot be set with `allowed_card_presences`. Provide an empty value to unset this control.
        - `blocked_categories` string[], nullable — Array of strings containing [categories](https://docs.stripe.com/api#issuing_authorization_object-merchant_data-category) of authorizations to decline. All other categories will be allowed. Cannot be set with `allowed_categories`.
        - `blocked_merchant_countries` string[], nullable — Array of strings containing representing countries from which authorizations will be declined. Country codes should be ISO 3166 alpha-2 country codes (e.g. `US`). Cannot be set with `allowed_merchant_countries`. Provide an empty value to unset this control.
        - `spending_limits` IssuingCardSpendingLimit[], nullable — Limit spending with amount-based rules that apply across any cards this card replaced (i.e., its `replacement_for` card and _that_ card's `replacement_for` card, up the chain).
          - `amount` integer, required — Maximum amount allowed to spend per interval. This amount is in the card's currency and in the [smallest currency unit](https://docs.stripe.com/currencies#zero-decimal).
          - `categories` string[], nullable — Array of strings containing [categories](https://docs.stripe.com/api#issuing_authorization_object-merchant_data-category) this limit applies to. Omitting this field will apply the limit to all categories.
          - `interval` 'all_time' | 'daily' | 'monthly' | 'per_authorization' | 'weekly' | 'yearly', required — Interval (or event) to which the amount applies.
        - `spending_limits_currency` string, currency, nullable — Currency of the amounts within `spending_limits`. Always the same as the currency of the card.
      - `status` 'active' | 'canceled' | 'inactive', required — Whether authorizations can be approved on this card. May be blocked from activating cards depending on past-due Cardholder requirements. Defaults to `inactive`.
      - `type` 'physical' | 'virtual', required — The type of the card.
      - `wallets` IssuingCardWallets
        - `apple_pay` IssuingCardApplePay, required
          - `eligible` boolean, required — Apple Pay Eligibility
          - `ineligible_reason` 'missing_agreement' | 'missing_cardholder_contact' | 'unsupported_region', nullable — Reason the card is ineligible for Apple Pay
        - `google_pay` IssuingCardGooglePay, required
          - `eligible` boolean, required — Google Pay Eligibility
          - `ineligible_reason` 'missing_agreement' | 'missing_cardholder_contact' | 'unsupported_region', nullable — Reason the card is ineligible for Google Pay
        - `primary_account_identifier` string, nullable — Unique identifier for a card used with digital wallets
  - `created` integer, required — Time at which the object was created. Measured in seconds since the Unix epoch.
  - `device_fingerprint` string, nullable — The hashed ID derived from the device ID from the card network associated with the token.
  - `id` string, required — Unique identifier for the object.
  - `last4` string — The last four digits of the token.
  - `livemode` boolean, required — If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
  - `network` 'mastercard' | 'visa', required — The token service provider / card network associated with the token.
  - `network_data` IssuingNetworkTokenNetworkData
    - `device` IssuingNetworkTokenDevice
      - `device_fingerprint` string — An obfuscated ID derived from the device ID.
      - `ip_address` string — The IP address of the device at provisioning time.
      - `location` string — The geographic latitude/longitude coordinates of the device at provisioning time. The format is [+-]decimal/[+-]decimal.
      - `name` string — The name of the device used for tokenization.
      - `phone_number` string — The phone number of the device used for tokenization.
      - `type` 'other' | 'phone' | 'watch' — The type of device used for tokenization.
    - `mastercard` IssuingNetworkTokenMastercard
      - `card_reference_id` string — A unique reference ID from MasterCard to represent the card account number.
      - `token_reference_id` string, required — The network-unique identifier for the token.
      - `token_requestor_id` string, required — The ID of the entity requesting tokenization, specific to MasterCard.
      - `token_requestor_name` string — The name of the entity requesting tokenization, if known. This is directly provided from MasterCard.
    - `type` 'mastercard' | 'visa', required — The network that the token is associated with. An additional hash is included with a name matching this value, containing tokenization data specific to the card network.
    - `visa` IssuingNetworkTokenVisa
      - `card_reference_id` string, nullable — A unique reference ID from Visa to represent the card account number.
      - `token_reference_id` string, required — The network-unique identifier for the token.
      - `token_requestor_id` string, required — The ID of the entity requesting tokenization, specific to Visa.
      - `token_risk_score` string — Degree of risk associated with the token between `01` and `99`, with higher number indicating higher risk. A `00` value indicates the token was not scored by Visa.
    - `wallet_provider` IssuingNetworkTokenWalletProvider
      - `account_id` string — The wallet provider-given account ID of the digital wallet the token belongs to.
      - `account_trust_score` integer — An evaluation on the trustworthiness of the wallet account between 1 and 5. A higher score indicates more trustworthy.
      - `card_number_source` 'app' | 'manual' | 'on_file' | 'other' — The method used for tokenizing a card.
      - `cardholder_address` IssuingNetworkTokenAddress
        - `line1` string, required — The street address of the cardholder tokenizing the card.
        - `postal_code` string, required — The postal code of the cardholder tokenizing the card.
      - `cardholder_name` string — The name of the cardholder tokenizing the card.
      - `device_trust_score` integer — An evaluation on the trustworthiness of the device. A higher score indicates more trustworthy.
      - `hashed_account_email_address` string — The hashed email address of the cardholder's account with the wallet provider.
      - `reason_codes` string[] — The reasons for suggested tokenization given by the card network.
      - `suggested_decision` 'approve' | 'decline' | 'require_auth' — The recommendation on responding to the tokenization request.
      - `suggested_decision_version` string — The version of the standard for mapping reason codes followed by the wallet provider.
  - `network_updated_at` integer, required — Time at which the token was last updated by the card network. Measured in seconds since the Unix epoch.
  - `object` 'issuing.token', required — String representing the object's type. Objects of the same type share the same value.
  - `status` 'active' | 'deleted' | 'requested' | 'suspended', required — The usage state of the token.
  - `wallet_provider` 'apple_pay' | 'google_pay' | 'samsung_pay' — The digital wallet for this token, if one was used.

## Other responses

- `default` — Error response.

---

[API](https://skmtc.net/stripe/apis/spec3.md) · [All operations](https://skmtc.net/stripe/apis/spec3/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/stripe/spec3/revisions/3653ad45bbec/schema)