Subscription Management

The Subscription Management API allows you to place, retrieve, and update stop orders against a series of recurring transactions associated with specific merchants. Stop orders prevent future recurring debit transactions from being authorized for a given card, but do not stop force-posted clearing transactions. Subscription management is network agnostic.

Prerequisites

Enable the subscription management feature

Before using the Subscription Management API, ensure that you perform the following actions:

Connect with your Marqeta representative to enable the subscription management feature for your program.
Confirm that a card exists that is in an ACTIVE, SUSPENDED, or LIMITED state.

Note Cards in a TERMINATED state or cards that have reached their expiration date cannot have stop orders placed against them.

Confirm that a recurring transaction exists for the card. You can use the value in the transaction_token field in Retrieve recurring transactions to identify the recurring transaction. Use Retrieve recurring transactions to find recurring transactions associated with a card.

About merchant ID continuity

In order to effectively block future recurring transactions for a specific merchant, the merchant ID must match the value in the merchant_id field in the original Create a stop order response. Merchant IDs are not static and can change if, for example, a merchant starts using a different acquirer or changes the location of their business. As Marqeta does not generate or assign the values for merchant IDs, changes to merchant ID values are not within Marqeta’s control.

Stop order object

The following fields are returned for stop order resources across the Subscription Management API.

Fields	Description
stop_order_token string Returned	Marqeta-assigned unique identifier for the stop order. Allowable Values: Existing stop order token
card_token string Returned	Token of the card on which you have placed the stop order. Allowable Values: Existing card token
transaction_token string Returned	Marqeta-assigned token of the original recurring transaction used to create the stop order. Allowable Values: Existing transaction token
merchant_id string Returned	Merchant ID (MID) as defined by the card network, derived from the original recurring transaction. Allowable Values: Existing MID
merchant_name string Conditionally returned	Name of the merchant. Allowable Values: 255 char max
original_amount decimal Returned	Amount of the original recurring transaction used to create the stop order, derived automatically from the transaction. Marqeta includes this value, along with the card and merchant ID, as part of the matching key that determines which future recurring transactions the stop order blocks. Allowable Values: decimal Format: 0.00
stop_reason string Returned	Reason the stop order was created. Allowable Values: `CANCELLED_SUBSCRIPTION`, `TRIAL_ENDED`, `UNRECOGNIZED_CHARGE`, `BILLING_ISSUE`, `MERCHANT_UNRESPONSIVE`, `PRICE_CHANGE`, `SUSPECTED_FRAUD`, `CARD_LOST_OR_REPLACED`, `OTHER`
update_reason string Conditionally returned	Reason for the most recent update. Allowable Values: `DURATION_CHANGED`, `ISSUED_IN_ERROR`, `CARDHOLDER_REQUEST`, `MERCHANT_RESOLVED`
reason_description string Conditionally returned	Free-text description of the reason for the stop order or update. Allowable Values: 255 char max
user_token string Returned	Token of the cardholder associated with the card. Allowable Values: Existing user token
duration integer Returned	Duration of the stop order. Defaults to `13` if a value is not specified when the stop order is created. Max: `60` Allowable Values: Integer between `1` and `60`
duration_unit string Returned	Unit of the duration of the stop order. Currently the only values supported for this field are `MONTH` and `YEAR`. If no value is provided, `duration_unit` defaults to `MONTH`. If a value for `duration_unit` is provided without also providing a value for the `duration` field, the endpoint returns a validation error. Allowable Values: `MONTH`, `YEAR`
status string Returned	Current status of the stop order. The value for this field defaults to `ACTIVE` upon creation of the stop order. Allowable Values: `ACTIVE`, `CANCELLED`, `EXPIRED`
created_time datetime Returned	Date and time when the resource was created, in UTC. Allowable Values: Format: `yyyy-MM-ddThh:mm:ssZ`
last_modified_time datetime Returned	Date and time when the resource was last updated, in UTC. Allowable Values: Format: `yyyy-MM-ddThh:mm:ssZ`
expiry_time datetime Returned	Date and time when the stop order expires, in UTC. Allowable Values: Format: `yyyy-MM-ddThh:mm:ssZ`

Retrieve recurring transactions

The /v3/cards/{card_token}/transactions endpoint allows you to retrieve recurring transactions from the last six months using the is_recurring query parameter. Action: GET Endpoint: /v3/cards/{card_token}/transactions

Path parameters

Fields	Description
card_token string Required	Token of the card for which to retrieve transactions. Allowable Values: Existing card token

URL query parameters

Fields	Description
is_recurring boolean Required	Set to `true` to filter only recurring transactions. Allowable Values: `true`, `false` Default: `false`
start_date string Optional	Start of the date range filter. If a value for this field is provided, a value for `end_date` must also be specified. If there are no values provided for both `start_date` and `end_date`, then the endpoint retrieves results for the six months prior to the current date. The maximum window allowed between `start_date` and `end_date` is six months. If the date range exceeds six months, the endpoint returns `400 Bad Request`. Allowable Values: Date in `yyyy-MM-dd` or `yyyy-MM-ddThh:mm:ssZ` format
end_date string Optional	Ending date of the range provided for the filter. If a value for `end_date` is provided, then `start_date` must also be specified. If there are no values provided for both `start_date` and `end_date`, then the endpoint retrieves results for the six months prior to the current date. The maximum window allowed between `start_date` and `end_date` is six months. If the date range exceeds six months, then the endpoint returns `400 Bad Request`. Allowable Values: Date in `yyyy-MM-dd` or `yyyy-MM-ddThh:mm:ssZ` format

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	Valid array of transaction objects. For more information, see the description of the transaction object on the Transactions page. Objects are returned based on your query. Allowable Values: Valid array of one or more transaction objects
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 all resources have been returned. 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

JSON

{
  "count": 2,
  "start_index": 0,
  "end_index": 1,
  "is_more": false,
  "data": [
    {
      "type": "authorization",
      "state": "PENDING",
      "identifier": "14814131",
      "token": "019c58db-b18f-76c3-8977-ac7a073f9571",
      "user_token": "my-user-new-pan",
      "acting_user_token": "my-user-new-pan",
      "card_token": "my-card-test-14",
      "card_product_token": "4d4183e1-957c-45fd-b028-438ab39e9570",
      "is_recurring": true,
      "created_time": "2026-02-13T21:15:18Z",
      "user_transaction_time": "2026-02-13T21:15:18Z",
      "settlement_date": "2026-02-13T00:00:00Z",
      "request_amount": 20.00,
      "amount": 20.00,
      "currency_code": "USD",
      "approval_code": "816315",
      "response": {
        "code": "0000",
        "memo": "Approved or completed successfully"
      },
      "network": "VISA",
      "subnetwork": "VISANET",
      "card_acceptor": {
        "mid": "000696875727497",
        "mcc": "6411",
        "name": "Marqeta Storefront",
        "street_address": "1000 Main St",
        "city": "St. Petersburg",
        "state": "FL",
        "postal_code": "33705",
        "country_code": "USA"
      },
      "pos": {
        "pan_entry_mode": "CARD_ON_FILE",
        "card_holder_presence": true,
        "card_presence": false,
        "is_recurring": true,
        "is_installment": false
      }
    },
    {
      "type": "authorization.clearing",
      "state": "COMPLETION",
      "identifier": "14814132",
      "token": "019c58e1-085d-7b16-9608-d40413fd7ba7",
      "user_token": "my-user-new-pan",
      "acting_user_token": "my-user-new-pan",
      "card_token": "my-card-test-14",
      "card_product_token": "4d4183e1-957c-45fd-b028-438ab39e9570",
      "is_recurring": true,
      "preceding_related_transaction_token": "019c58db-b18f-76c3-8977-ac7a073f9571",
      "original_transaction_token": "019c58db-b18f-76c3-8977-ac7a073f9571",
      "created_time": "2026-02-13T21:21:08Z",
      "user_transaction_time": "2026-02-13T21:15:18Z",
      "settlement_date": "2026-02-13T00:00:00Z",
      "request_amount": 20.00,
      "amount": 20.00,
      "currency_code": "USD",
      "approval_code": "639534",
      "response": {
        "code": "0000",
        "memo": "Approved or completed successfully"
      },
      "network": "VISA",
      "subnetwork": "VISANET",
      "card_acceptor": {
        "mid": "000696875727497",
        "mcc": "6411",
        "name": "Marqeta Storefront",
        "street_address": "1000 Main St",
        "city": "St. Petersburg",
        "state": "FL",
        "postal_code": "33705",
        "country_code": "USA"
      },
      "pos": {
        "card_presence": false,
        "is_recurring": true,
        "is_installment": false
      }
    }
  ]
}

Create a stop order

Places a new stop order to block future recurring transactions from a specific merchant for a given card.

Note If you reissue a card whose source card had a stop order on it, the stop order will not carry over to the reissued card. You must create a new stop order for the reissued card if you would like to continue blocking future recurring transactions.

For errors associated with the creation of a stop order, see the Errors page. Action: POST Endpoint: /v3/cards/{card_token}/stoporders

Path parameters

Fields	Description
card_token string Required	Token of the card on which to place the stop order. Allowable Values: Existing card token

Request body

Fields	Description
transaction_token string Required	Marqeta-assigned token identifying the recurring transaction series. Allowable Values: Existing transaction token
stop_reason string Required	Reason for the stop order. Allowable Values: `CANCELLED_SUBSCRIPTION` - Cardholder canceled the subscription. `TRIAL_ENDED` - Free trial period has ended. `UNRECOGNIZED_CHARGE` - Cardholder does not recognize the charge. `BILLING_ISSUE` - Billing dispute or problem. `MERCHANT_UNRESPONSIVE` - Merchant is not responding to cancellation requests. `PRICE_CHANGE` - Subscription price changed unexpectedly. `SUSPECTED_FRAUD` - Potential fraudulent activity. `CARD_LOST_OR_REPLACED` - Card was lost, stolen, or replaced. `OTHER` - Other reason. Use the `reason_description` field for details.
reason_description string Optional	Free-text description of the reason. Allowable Values: 255 char max
duration integer Optional	Duration of the stop order. Defaults to `13` if a value for this field is not provided. Max: `60`. Allowable Values: Integer between `1` and `60`
duration_unit string Optional	Unit of the duration of the stop order. Currently the only values supported for this field are `MONTH` and `YEAR`. If no value is provided, `duration_unit` defaults to `MONTH`. If a value for `duration_unit` is provided without also providing a value for the `duration` field, then the endpoint returns a validation error. Allowable Values: `MONTH`, `YEAR`

Response body

See Stop order object.

Sample request

JSON

{
  "transaction_token": "15254919",
  "stop_reason": "OTHER",
  "reason_description": "other reasons",
  "duration": 2,
  "duration_unit": "MONTH"
}

Sample response

JSON

{
  "stop_order_token": "so_12345",
  "card_token": "card_token_123",
  "transaction_token": "15254919",
  "merchant_id": "mid",
  "merchant_name": "merchant_name",
  "original_amount": 20.00,
  "stop_reason": "OTHER",
  "reason_description": "other reasons",
  "user_token": "cardholder_124",
  "duration": 2,
  "duration_unit": "MONTH",
  "status": "ACTIVE",
  "created_time": "2025-01-28T19:24:43Z",
  "last_modified_time": "2025-01-28T19:24:43Z",
  "expiry_time": "2025-03-28T23:59:59Z"
}

List stop orders for a card

Returns a paginated list of all stop orders for the given card token, sorted by last modified time. For errors associated with listing a stop order for a card, see the Errors page. Action: GET Endpoint: /v3/cards/{card_token}/stoporders

Path parameters

Fields	Description
card_token string Required	Token of the card on which you have placed a stop order. Allowable Values: Existing card token

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 stop order objects. Allowable Values: Valid array of one or more stop order objects
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 all resources have been returned. 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
data[].* object Conditionally returned	See Stop order object.

Sample response

JSON

{
  "count": 3,
  "start_index": 0,
  "end_index": 2,
  "is_more": false,
  "data": [
    {
      "stop_order_token": "so_12345",
      "card_token": "card_token_123",
      "transaction_token": "txn_abc",
      "merchant_id": "mid_001",
      "merchant_name": "merchant_name_001",
      "original_amount": 20.00,
      "stop_reason": "CANCELLED_SUBSCRIPTION",
      "reason_description": "Customer request",
      "duration": 13,
      "duration_unit": "MONTH",
      "status": "ACTIVE",
      "created_time": "2025-01-28T19:24:43Z",
      "last_modified_time": "2025-01-28T19:24:43Z",
      "expiry_time": "2026-02-28T23:59:59Z"
    }
  ]
}

Retrieve a specific stop order

Returns the details of a single stop order. Action: GET Endpoint: /v3/cards/{card_token}/stoporders/{stop_order_token}

Path parameters

Fields	Description
card_token string Required	Token of the card on which you have placed a stop order. Allowable Values: Existing card token
stop_order_token string Required	Marqeta-assigned unique identifier for the stop order. Allowable Values: Existing stop order token

Response body

See Stop order object.

Sample response

JSON

{
  "stop_order_token": "so_12345",
  "card_token": "card_token_123",
  "transaction_token": "token",
  "merchant_id": "mid",
  "merchant_name": "merchant_name",
  "original_amount": 20.00,
  "stop_reason": "CANCELLED_SUBSCRIPTION",
  "reason_description": "Customer request",
  "duration": 13,
  "duration_unit": "MONTH",
  "status": "ACTIVE",
  "created_time": "2025-09-23T19:24:43Z",
  "last_modified_time": "2025-09-23T19:24:43Z",
  "expiry_time": "2026-10-23T23:59:59Z"
}

Update stop order

Updates an existing stop order. Use this endpoint to cancel a stop order or change its duration. Action: PUT Endpoint: /v3/cards/{card_token}/stoporders/{stop_order_token}

Path parameters

Fields	Description
card_token string Required	Token of the card on which you have placed a stop order. Allowable Values: Existing card token
stop_order_token string Required	Marqeta-assigned unique identifier for the stop order. Allowable Values: Existing stop order token

Request body

Fields	Description
status string Required	New status for the stop order. Allowable Values: `ACTIVE`, `CANCELLED`
update_reason string Required	Reason for the update. Allowable Values: `DURATION_CHANGED` - The stop order duration has been modified. `ISSUED_IN_ERROR` - The stop order was placed by mistake. `CARDHOLDER_REQUEST` - The cardholder requested the change. `MERCHANT_RESOLVED` - The issue with the merchant has been resolved.
reason_description string Optional	Free-text description of the update reason. Allowable Values: 255 char max
duration integer Optional	New duration of the stop order. Max: `60`. Allowable Values: Integer between `1` and `60`
duration_unit string Optional	Unit for the new duration of the stop order. Currently the only values supported for this field are `MONTH` and `YEAR`. If no value is provided, `duration_unit` defaults to `MONTH`. If a value for `duration_unit` is provided without also providing a value for the `duration` field, then the endpoint returns a validation error. Allowable Values: `MONTH`, `YEAR`

Response body

See Stop order object.

Sample request

JSON

{
  "status": "CANCELLED",
  "update_reason": "CARDHOLDER_REQUEST",
  "reason_description": "Customer request"
}

Sample response

JSON

{
  "stop_order_token": "so_12345",
  "card_token": "card_token_123",
  "transaction_token": "token",
  "merchant_id": "mid",
  "merchant_name": "merchant_name",
  "original_amount": 20.00,
  "stop_reason": "CANCELLED_SUBSCRIPTION",
  "update_reason": "CARDHOLDER_REQUEST",
  "reason_description": "Customer request",
  "duration": 13,
  "duration_unit": "MONTH",
  "status": "CANCELLED",
  "created_time": "2025-09-23T19:24:43Z",
  "last_modified_time": "2025-11-23T19:24:43Z",
  "expiry_time": "2026-10-23T23:59:59Z"
}

Important When you change the value for the duration field, the new expiry date is calculated from the original stop order creation date, not from the update date.For example, if a stop order was created on 2025-09-23 and you submit an update request on 2025-11-23 that changes the duration to three months, the new expiry will be 2025-12-23 (three months from the creation date).

Stop order declines

After placing a stop order on a recurring transaction for a specific merchant, Marqeta will automatically decline any subsequent occurrences of that transaction with the response code 1949 (Decline recurring transaction by cardholder) during the authorization process. This decline reason code is mapped to card networks with the following values:

Network	Code
Visa	`R1`
Mastercard	`05`
Pulse	`ST`
Discover	`ST`

Note If you are a JIT Gateway program, you can choose to perform authorization decisioning internally and decline JIT requests with the REVOCATION_AUTHORIZATION_ORDER reason code. Marqeta will then translate this reason code to the associated card network decline reason code and send it to the card network.

Stop order statuses

Status	Description
`ACTIVE`	Stop order is in effect. Matching recurring transactions will be declined.
`CANCELLED`	Stop order has been manually canceled via the `update` endpoint.
`EXPIRED`	Stop order has passed its expiry date.

Status lifecycle

When you create a stop order, its default status is ACTIVE. After creation, you can transition the stop order to CANCELLED via the Update stop order endpoint. If you do not cancel the stop order, it automatically transitions to EXPIRED when the expiry_time is reached.

Note Only orders in an ACTIVE state transition to an EXPIRED state when the expiry date is reached.Canceled orders remain in CANCELLED state when the expiry date is reached.

​Prerequisites

​Enable the subscription management feature

​About merchant ID continuity

​Stop order object

​Retrieve recurring transactions

​Path parameters

​URL query parameters

​Response body

​Sample response

​Create a stop order

​Path parameters

​Request body

​Response body

​Sample request

​Sample response

​List stop orders for a card

​Path parameters

​Response body

​Sample response

​Retrieve a specific stop order

​Path parameters

​Response body

​Sample response

​Update stop order

​Path parameters

​Request body

​Response body

​Sample request

​Sample response

​Stop order declines

​Stop order statuses

​Status lifecycle

Prerequisites

Enable the subscription management feature

About merchant ID continuity

Stop order object

Retrieve recurring transactions

Path parameters

URL query parameters

Response body

Sample response

Create a stop order

Path parameters

Request body

Response body

Sample request

Sample response

List stop orders for a card

Path parameters

Response body

Sample response

Retrieve a specific stop order

Path parameters

Response body

Sample response

Update stop order

Path parameters

Request body

Response body

Sample request

Sample response

Stop order declines

Stop order statuses

Status lifecycle