Skip to main content
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.

​
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.
FieldsDescription
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
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

FieldsDescription
card_token

string

Required		Token of the card for which to retrieve transactions.

Allowable Values:

Existing card token

​
URL query parameters

FieldsDescription
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

FieldsDescription
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

FieldsDescription
card_token

string

Required		Token of the card on which to place the stop order.

Allowable Values:

Existing card token

​
Request body

FieldsDescription
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",
  "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

FieldsDescription
card_token

string

Required		Token of the card on which you have placed a stop order.

Allowable Values:

Existing card token

​
Response body

FieldsDescription
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",
      "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

FieldsDescription
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",
  "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

FieldsDescription
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

FieldsDescription
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",
  "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:
NetworkCode
VisaR1
Mastercard05
PulseST
DiscoverST
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

StatusDescription
ACTIVEStop order is in effect. Matching recurring transactions will be declined.
CANCELLEDStop order has been manually canceled via the update endpoint.
EXPIREDStop 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.

Related topics

Managing Cards in the Marqeta DashboardAbout Account Level ManagementManaging Physical CardsDigital Wallets ManagementCardholder and Card Management in Europe