List transitions for card - Marqeta Docs

Home

Getting Started

Testing

Card Issuing

Card Processing

Accounts & Money Movement

Risk, Fraud, and Disputes

Cardholder User Experience

GET///

Retrieves a list of the transitions for a specific card. This endpoint supports field filtering and pagination.

URL path parameters

Fields	Description
token string Required	Unique identifier of the card. Allowable Values: Existing card token

URL query parameters

Fields	Description
count integer Optional	Number of card transitions to retrieve. Allowable Values: 1-10 Default value: 5
start_index integer Optional	Sort order index of the first resource in the returned array. Allowable Values: Any integer Default value: 0
fields string Optional	Comma-delimited list of fields to return (`field_1,field_2`, and so on). Leave blank to return all fields. Allowable Values: Comma-delimited list of fields, or blank
sort_by string Optional	Field on which to sort. Use any field in the resource model, or one of the system fields `lastModifiedTime` or `createdTime`. Prefix the field name with a hyphen (`-`) to sort in descending order. Omit the hyphen to sort in ascending order. Allowable Values: `createdTime`, `lastModifiedTime`, or any field in the resource model Default value: `-createdTime`

Response body

Fields	Description
count integer Conditionally returned	Number of resources to retrieve. This field is returned if there are resources in your returned array. Allowable Values: 1-10
data array of objects Conditionally returned	Array of card transition objects. Objects are returned as appropriate to your query. Allowable Values: Valid array of one or more card transition objects
data[].barcode string Returned	The barcode printed on the card, expressed as digits. Allowable Values: 10-20 chars
data[].bulk_issuance_token string Conditionally returned	The unique identifier of the bulk card order. Allowable Values: 1-36 chars
data[].card object Conditionally returned	Associates customer-injected metadata with the card. Allowable Values: `metadata`
data[].card.metadata object Conditionally returned	Associates customer-injected metadata with the card. Allowable Values: You can define the names and values of up to 20 fields in the format `"my_name_1": "my_value_1"`.
data[].card_product_token string Returned	Unique identifier of the card product. Allowable Values: 36 char max
data[].card_token string Returned	Unique identifier of the card. Allowable Values: 1–36 chars
data[].channel string Returned	The mechanism by which the transition was initiated. - ADMIN - Indicates that the card transition was initiated through the Marqeta Dashboard. - API - Indicates that the card transition was initiated by you through the Core API. Use this value when creating a card transition with an API `POST` request. - FRAUD - Indicates that either Marqeta or the card network has determined that the card is fraudulent. - IVR - Indicates that the card transition was initiated through your Interactive Voice Response system. - SYSTEM - Indicates that the card transition was initiated by Marqeta. For example, Marqeta suspended the card due to excessive failed personal identification number (PIN) entries. Allowable Values: `API`, `IVR`, `FRAUD`, `ADMIN`, `SYSTEM`
data[].created_time datetime Conditionally returned	Date and time when the resource was created, in UTC. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
data[].created_timestamp datetime Conditionally returned	Date and time when the resource was created. Expressed in UTC, with millisecond precision. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ss:SSSZ
data[].expedite boolean Conditionally returned	A value of `true` indicates that you requested expedited processing of the card from your card fulfillment provider. Allowable Values: `true`, `false`
data[].expiration string Returned	Expiration date in `MMyy` format. Allowable Values: Format: MMyy
data[].expiration_time string Returned	Expiration date and time in UTC format. Allowable Values: datetime Format: yyyy-MM-ddThh:mm:ssZ
data[].fulfillment object Conditionally returned	Specifies certain physical characteristics of a card, as well as shipment information. Allowable Values: `card_fulfillment_reason`, `card_personalization`, `shipping`
data[].fulfillment.card_fulfillment_reason string Conditionally returned	Reason for card fulfillment. Allowable Values: `NEW`, `LOST_STOLEN`, `EXPIRED`
data[].fulfillment.card_personalization object Returned	Specifies personalized attributes to be added to the card. Allowable Values: `carrier`, `images`, `perso_type`, `text`
data[].fulfillment.card_personalization.carrier object Conditionally returned	Specifies attributes of the card carrier. Allowable Values: `logo_file`, `logo_thumbnail_file`, `message_file`, `message_line`, `template_id`
data[].fulfillment.card_personalization.carrier.logo_file string Conditionally returned	Specifies an image to display on the card carrier. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider.
data[].fulfillment.card_personalization.carrier.logo_thumbnail_file string Conditionally returned	Specifies a thumbnail-sized rendering of the image specified in the `logo_file` field. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider.
data[].fulfillment.card_personalization.carrier.message_file string Conditionally returned	Specifies a text file containing a custom message to print on the card carrier. Allowable Values: Contains the name of the text file and must match the name of the file you send to your fulfillment provider.
data[].fulfillment.card_personalization.carrier.message_line string Conditionally returned	Specifies a custom message that appears on the card carrier. Allowable Values: 60 char max
data[].fulfillment.card_personalization.carrier.message_line_2 string Conditionally returned	Specifies the second line of a custom message that appears on the card carrier. Allowable Values: 60 char max
data[].fulfillment.card_personalization.carrier.template_id string Conditionally returned	Specifies the card carrier template to use. Allowable Values: Card carrier template ID
data[].fulfillment.card_personalization.images object Conditionally returned	Specifies personalized images that appear on the card. Allowable Values: `card`, `carrier`, `carrier_return_window`, `signature`
data[].fulfillment.card_personalization.images.card object Conditionally returned	Specifies personalized images that appear on the card. Allowable Values: `name`, `thermal_color`
data[].fulfillment.card_personalization.images.card.name string Conditionally returned	Specifies a PNG image to display on the card. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider.
data[].fulfillment.card_personalization.images.card.thermal_color string Conditionally returned	Specifies the color of the image displayed on the card. Allowable Values: Contains the name of the color and must match one of the provider’s predefined colors.
data[].fulfillment.card_personalization.images.carrier object Conditionally returned	Specifies personalized images that appear on the card carrier. Allowable Values: `message_1`, `name`
data[].fulfillment.card_personalization.images.carrier.message_1 string Conditionally returned	Specifies a custom message that appears on the card carrier. Allowable Values: 60 char max
data[].fulfillment.card_personalization.images.carrier.name string Conditionally returned	Specifies a PNG image to display on the card carrier. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider.
data[].fulfillment.card_personalization.images.carrier_return_window object Conditionally returned	Specifies a PNG image to display in the return address window of envelopes used for sending cards to cardholders. Allowable Values: `name`
data[].fulfillment.card_personalization.images.carrier_return_window.name string Conditionally returned	Specifies a PNG image to display in the return address window of envelopes used for sending cards to cardholders. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider.
data[].fulfillment.card_personalization.images.signature object Conditionally returned	Specifies a PNG image of the cardholder’s signature. Allowable Values: `name`
data[].fulfillment.card_personalization.images.signature.name string Conditionally returned	Specifies a PNG image of the cardholder’s signature. Allowable Values: Contains the name of the image file and must match the name of the file you send to your fulfillment provider.
data[].fulfillment.card_personalization.perso_type string Conditionally returned	Specifies the type of card personalization. Allowable Values: `EMBOSS`, `LASER`, `FLAT`
data[].fulfillment.card_personalization.text object Returned	Specifies personalized text that appears on the card. Allowable Values: `name_line_1`, `name_line_2`, `name_line_3`
data[].fulfillment.card_personalization.text.name_line_1 object Returned	Specifies the first line of personalized text that appears on the card. Allowable Values: `name_line_1.value` 21 char max; if `name_line_1_numeric_postfix` is `true`, 14 char max. Strings longer than the character limit are truncated.
data[].fulfillment.card_personalization.text.name_line_1.value string Conditionally returned	Line of personalized text printed on the card. Allowable Values: 21 char max
data[].fulfillment.card_personalization.text.name_line_2 object Conditionally returned	Specifies the second line of personalized text that appears on the card. Allowable Values: `name_line_2.value`
data[].fulfillment.card_personalization.text.name_line_2.value string Conditionally returned	Line of personalized text printed on the card. Allowable Values: 21 char max
data[].fulfillment.card_personalization.text.name_line_3 object Conditionally returned	Specifies the third line of personalized text that appears on the card. Allowable Values: `name_line_3.value`
data[].fulfillment.card_personalization.text.name_line_3.value string Conditionally returned	Line of personalized text printed on the card. Allowable Values: 21 char max
data[].fulfillment.shipping object Conditionally returned	Specifies shipping details for the order. Allowable Values: `care_of_line`, `method`, `recipient_address`, `return_address`
data[].fulfillment.shipping.care_of_line string Conditionally returned	Adds the specified value as a care of (C/O) line to the mailing carrier. NOTE: This field can be specified on cards, card products, and bulk card orders. If you specify this field at multiple levels, the order of precedence is: card, bulk card order, card product. Allowable Values: 255 char max
data[].fulfillment.shipping.method string Conditionally returned	Specifies the shipping service. Allowable Values: `LOCAL_MAIL`, `LOCAL_MAIL_PACKAGE`, `GROUND`, `TWO_DAY`, `OVERNIGHT`, `INTERNATIONAL`, `INTERNATIONAL_PRIORITY`, `LOCAL_PRIORITY`, `FEDEX_EXPEDITED`, `FEDEX_REGULAR`, `UPS_EXPEDITED`, `UPS_REGULAR`, `USPS_EXPEDITED`, `USPS_REGULAR` Shipping options vary by card provider. For details on the specific shipping companies and services offered by your card provider, contact your Marqeta representative.
data[].fulfillment.shipping.recipient_address object Conditionally returned	Address to which the order will be shipped. In order to generate cards, a valid shipping address must be provided by one of these: - The card or bulk card order’s `fulfillment.shipping.recipient_address` field - The users’ `address` fields - The card product’s `config.fulfillment.shipping.recipient_address` field The order of precedence from highest to lowest is card, user, card product. To be valid, an address must have the `address1`, `city`, `state`, and `postal_code` or `zip` fields populated. The `country` field defaults to USA if unpopulated. Allowable Values: Valid `recipient_address` object
data[].fulfillment.shipping.recipient_address.address1 string Conditionally returned	Number and street of the address. Allowable Values: 255 char max Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA have a limit of 100 characters, and Arroweye Solutions has a limit of 50 characters.
data[].fulfillment.shipping.recipient_address.address2 string Conditionally returned	Additional address information. Allowable Values: 255 char max Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA have a limit of 100 characters, and Arroweye Solutions has a limit of 50 characters.
data[].fulfillment.shipping.recipient_address.city string Conditionally returned	City of the address. Allowable Values: 40 char max
data[].fulfillment.shipping.recipient_address.country string Conditionally returned	Country of the address. Allowable Values: 40 char max English short name. For example, for the Kingdom of Spain, use the English short name “Spain”. The ISO maintains the full list of country codes.
data[].fulfillment.shipping.recipient_address.first_name string Conditionally returned	First name of the addressee. Allowable Values: 40 char max
data[].fulfillment.shipping.recipient_address.last_name string Conditionally returned	Last name of the addressee. Allowable Values: 40 char max
data[].fulfillment.shipping.recipient_address.middle_name string Conditionally returned	Middle name of the addressee. Allowable Values: 40 char max
data[].fulfillment.shipping.recipient_address.phone string Conditionally returned	Telephone number of the addressee. Allowable Values: 20 char max
data[].fulfillment.shipping.recipient_address.postal_code string Conditionally returned	Postal code of the address. Allowable Values: 10 char max
data[].fulfillment.shipping.recipient_address.state string Conditionally returned	State of the address. Allowable Values: 32 char max
data[].fulfillment.shipping.recipient_address.zip string Conditionally returned	United States ZIP code of the address. Allowable Values: 10 char max
data[].fulfillment.shipping.return_address object Conditionally returned	Address to which the order will be returned if shipping fails. Allowable Values: `address1`, `address2`, `city`, `country`, `first_name`, `last_name`, `middle_name`, `phone`, `postal_code`, `state`, `zip`
data[].fulfillment.shipping.return_address.address1 string Conditionally returned	Number and street of the address. Allowable Values: 255 char max Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA have a limit of 100 characters, and Arroweye Solutions has a limit of 50 characters.
data[].fulfillment.shipping.return_address.address2 string Conditionally returned	Additional address information. Allowable Values: 255 char max Limits lower than 255 characters may be imposed by providers. Perfect Plastic Printing and IDEMIA have a limit of 100 characters, and Arroweye Solutions has a limit of 50 characters.
data[].fulfillment.shipping.return_address.city string Conditionally returned	City of the address. Allowable Values: 40 char max
data[].fulfillment.shipping.return_address.country string Conditionally returned	Country of the address. Allowable Values: 40 char max English short name. For example, for the Kingdom of Spain, use the English short name “Spain”. The ISO maintains the full list of country codes.
data[].fulfillment.shipping.return_address.first_name string Conditionally returned	First name of the addressee. Allowable Values: 40 char max
data[].fulfillment.shipping.return_address.last_name string Conditionally returned	Last name of the addressee. Allowable Values: 40 char max
data[].fulfillment.shipping.return_address.middle_name string Conditionally returned	Middle name of the addressee. Allowable Values: 40 char max
data[].fulfillment.shipping.return_address.phone string Conditionally returned	Telephone number of the addressee. Allowable Values: 20 char max
data[].fulfillment.shipping.return_address.postal_code string Conditionally returned	Postal code of the address. Allowable Values: 10 char max
data[].fulfillment.shipping.return_address.state string Conditionally returned	State of the address. Allowable Values: 32 char max
data[].fulfillment.shipping.return_address.zip string Conditionally returned	United States ZIP code of the address. Allowable Values: 10 char max
data[].fulfillment_status string Returned	Provides status information about the card related to order and delivery. The possible fulfillment states are: - ISSUED: Initial state of all newly created/issued cards - ORDERED: Card ordered through card fulfillment provider - REJECTED: Card rejected by card fulfillment provider - SHIPPED: Card shipped by card fulfillment provider - DELIVERED: Card delivered by the card fulfillment provider. - DIGITALLY_PRESENTED: Card digitally presented using the `/cards/{token}/showpan` endpoint; does not affect the delivery of physical cards Allowable Values: `ISSUED`, `ORDERED`, `REJECTED`, `SHIPPED`, `DELIVERED`, `DIGITALLY_PRESENTED`
data[].last_four string Returned	Last four digits of the card primary account number (PAN). Allowable Values: 4 chars
data[].pan string Returned	Primary account number (PAN) of the card. Allowable Values: 16 char max
data[].pin_is_set boolean Returned	Specifies if the personal identification number (PIN) has been set for the card. Allowable Values: 4 chars
data[].reason string Conditionally returned	Additional information about the state change. Allowable Values: 255 char max
data[].reason_code string Conditionally returned	A standard code describing the reason for the transition: - 00: Object activated for the first time - 01: Requested by you - 02: Inactivity over time - 03: This address cannot accept mail or the addressee is unknown - 04: Negative account balance - 05: Account under review - 06: Suspicious activity was identified - 07: Activity outside the program parameters was identified - 08: Confirmed fraud was identified - 09: Matched with an Office of Foreign Assets Control list - 10: Card was reported lost - 11: Card information was cloned - 12: Account or card information was compromised - 13: Temporary status change while on hold/leave - 14: Initiated by Marqeta - 15: Initiated by issuer - 16: Card expired - 17: Failed KYC - 18: Changed to `ACTIVE` because information was properly validated - 19: Changed to `ACTIVE` because account activity was properly validated - 20: Change occurred prior to the normalization of reason codes - 21: Initiated by a third party, often a digital wallet provider - 22: PIN retry limit reached - 23: Card was reported stolen - 24: Address issue - 25: Name issue - 26: SSN issue - 27: DOB issue - 28: Email issue - 29: Phone issue - 30: Account/fulfillment mismatch - 31: Other reason - 32: Unblock request - 86: Notification of death Allowable Values: `00`, `01`, `02`, `03`, `04`, `05`, `06`, `07`, `08`, `09`, `10`, `11`, `12`, `13`, `14`, `15`, `16`, `17`, `18`, `19`, `20`, `21`, `22`, `23`, `24`, `25`, `26`, `27`, `28`, `29`, `30`, `31`, `32`, `86`
data[].reissue_pan_from_card_token string Conditionally returned	Reissues the specified (“source”) card. Allowable Values: Existing card token
data[].new_pan_from_card_token string Conditionally returned	Reissues the specified (“source”) card with a new primary account number (PAN). Allowable Values: Existing card token
data[].state string Returned	Indicates the state of the card. Allowable Values: `ACTIVE`, `SUSPENDED`, `TERMINATED`, `UNACTIVATED`
data[].token string Returned	Unique identifier of the card transition. Allowable Values: 1–36 chars
data[].type string Returned	This field cannot be set directly using the `/cardtransitions` endpoint. A card transition’s `type` is managed by the Marqeta platform, based on the before and after state of the transition, as specified in the request’s `state` field. This field appears only when populated by the card fulfillment provider. The `type` field’s possible values are: - fulfillment.delivered: Card was delivered by the card fulfillment provider - fulfillment.digitally_presented: Card was digitally presented using the `/cards/{token}/showpan` endpoint; does not affect the delivery of physical cards - fulfillment.issued: Card was created/issued - fulfillment.ordered: Card was ordered from the card fulfillment provider - fulfillment.rejected: Card was rejected by the card fulfillment provider - fulfillment.shipped: Card was shipped by the card fulfillment provider - state.activated: Card was activated - state.limited: Card was limited - state.reinstated: Card was reinstated from a suspended state - state.suspended: Card was suspended - state.terminated: Card was terminated Allowable Values: `fulfillment.delivered`, `fulfillment.digitally_presented`, `fulfillment.issued`, `fulfillment.ordered`, `fulfillment.rejected`, `fulfillment.shipped`, `state.activated`, `state.limited`, `state.reinstated`, `state.suspended`, `state.terminated`
data[].user object Conditionally returned	Associates customer-injected metadata with the cardholder. Allowable Values: `metadata`
data[].user.metadata object Conditionally returned	Associates customer-injected metadata with the cardholder. Allowable Values: You can define the names and values of up to 20 fields in the format `"my_name_1": "my_value_1"`.
data[].user_token string Returned	Unique identifier of the cardholder. Allowable Values: 1–36 chars
data[].validations object Conditionally returned	Contains information about the user. Allowable Values: Existing `validations` object
data[].validations.user object Returned	Contains information about the user. Allowable Values: `birth_date`, `phone`, `random_name_line1_postfix`, `ssn`
data[].validations.user.birth_date boolean Returned	Indicates whether the `birth_date` field in the request was validated. Allowable Values: `true`, `false`
data[].validations.user.phone boolean Returned	Indicates whether the `phone` field in the request was validated. Allowable Values: `true`, `false`
data[].validations.user.random_name_line1_postfix boolean Returned	Indicates whether the `random_name_line1_postfix` field in the request was validated. Allowable Values: `true`, `false`
data[].validations.user.ssn boolean Returned	Indicates whether the `ssn` field in the request was validated. Allowable Values: `true`, `false`
end_index integer Conditionally returned	Sort order index of the last resource in the returned array. This field is returned if there are resources in your returned array. Allowable Values: Any integer
is_more boolean Conditionally returned	A value of `true` indicates that more unreturned resources exist. A value of `false` indicates that no more unreturned resources exist. This field is returned if there are resources in your returned array. Allowable Values: `true`, `false`
start_index integer Conditionally returned	Sort order index of the first resource in the returned array. This field is returned if there are resources in your returned array. Allowable Values: Any integer

Sample response body

JSON

{
  "count": 2,
  "start_index": 0,
  "end_index": 1,
  "is_more": false,
  "data": [
    {
      "token": "suspend_01",
      "card_token": "my_user_01_card_01",
      "user_token": "my_user_01",
      "state": "SUSPENDED",
      "reason": "I do not want to use this card, so suspend it.",
      "reason_code": "01",
      "channel": "API",
      "expedite": false,
      "fulfillment_status": "ISSUED",
      "validations": {
        "user": {
          "birth_date": true,
          "phone": false,
          "random_name_line1_postfix": false,
          "ssn": false
        }
      },
      "type": "state.suspended",
      "created_time": "2021-01-12T19:54:12Z",
      "card_product_token": "my_cardproduct_01",
      "last_four": "2160",
      "pan": "1111115454542160",
      "expiration": "1026",
      "expiration_time": "2026-10-31T23:59:59Z",
      "barcode": "11379418395311581864",
      "pin_is_set": false,
      "user": {
        "metadata": {
          "my_name_1": "my_value_1",
          "my_name_2": "my_value_2"
        }
      }
    },
    {
      "token": "activate_05",
      "card_token": "my_user_01_card_01",
      "user_token": "my_user_01",
      "state": "ACTIVE",
      "reason": "I want to use this card, so activate it.",
      "reason_code": "00",
      "channel": "API",
      "expedite": false,
      "fulfillment_status": "ISSUED",
      "validations": {
        "user": {
          "birth_date": true,
          "phone": false,
          "random_name_line1_postfix": false,
          "ssn": false
        }
      },
      "type": "state.activated",
      "created_time": "2022-02-23T23:28:39Z",
      "card_product_token": "my_cardproduct_01",
      "last_four": "2160",
      "pan": "1111115454542160",
      "expiration": "1026",
      "expiration_time": "2027-10-31T23:59:59Z",
      "barcode": "11379418395311581864",
      "pin_is_set": false,
      "user": {
        "metadata": {
          "my_name_1": "my_value_1",
          "my_name_2": "my_value_2"
        }
      }
    }
  ]
}