> ## Documentation Index
> Fetch the complete documentation index at: https://www.marqeta.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Subscription Management

> Subscription Management feature

export const EndpointCard = ({method = "API", title, children, href, arrow = true}) => {
  const METHOD_STYLES = {
    GET: {
      bg: "mint-bg-green-400/20 dark:mint-bg-green-400/20",
      text: "mint-text-green-700 dark:mint-text-green-400",
      border: "mint-border-green-300 dark:mint-border-green-700"
    },
    POST: {
      bg: "mint-bg-blue-400/20 dark:mint-bg-blue-400/20",
      text: "mint-text-blue-700 dark:mint-text-blue-400"
    },
    PUT: {
      bg: "mint-bg-yellow-400/20 dark:mint-bg-yellow-400/20",
      text: "mint-text-yellow-700 dark:mint-text-yellow-400"
    },
    PATCH: {
      bg: "mint-bg-orange-400/20 dark:mint-bg-orange-400/20",
      text: "mint-text-orange-700 dark:mint-text-orange-400"
    },
    DELETE: {
      bg: "mint-bg-red-400/20 dark:mint-bg-red-400/20",
      text: "mint-text-red-700 dark:mint-text-red-400"
    },
    API: {
      bg: "mint-bg-black",
      text: "mint-text-white"
    }
  };
  const MethodBadge = ({method}) => {
    const style = METHOD_STYLES[method?.toUpperCase()] ?? METHOD_STYLES.GET;
    return <span className={`
          method-pill rounded-lg font-semibold px-1.5 py-0.5 text-xs leading-5 ${style.bg} ${style.text}`}>
        {method?.toUpperCase()}
      </span>;
  };
  const content = <div className="group flex items-center gap-4 border border-gray-200 dark:border-gray-700 rounded-xl p-5 hover:border-gray-400 dark:hover:border-gray-500 hover:shadow-md transition-all cursor-pointer">
      {}
      <div className="shrink-0">
        <MethodBadge method={method} />
      </div>
      {}
      <div className="flex-1 min-w-0">
        <p className="font-semibold text-gray-900 dark:text-white text-sm leading-snug">{title}</p>
        {children && <p className="mt-1 text-sm text-gray-500 dark:text-gray-400 line-clamp-2">{children}</p>}
      </div>
    </div>;
  if (!href) return content;
  return <a href={href} className="block no-underline border-b-0 mb-2">
      {content}
    </a>;
};

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.

<h2 id="_prerequisites">
  Prerequisites
</h2>

<h3 id="_enable_the_subscription_management_feature">
  Enable the subscription management feature
</h3>

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>
  **Note**
  Cards in a `TERMINATED` state or cards that have reached their expiration date cannot have stop orders placed against them.
</Note>

* Confirm that a recurring transaction exists for the card. You can use the value in the `transaction_token` field in [Retrieve recurring transactions](#retrieve_recurring_transactions) to identify the recurring transaction. Use [Retrieve recurring transactions](#retrieve_recurring_transactions) to find recurring transactions associated with a card.

<h3 id="_about_merchant_id_continuity">
  About merchant ID continuity
</h3>

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](#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.

<h2 id="stop_order_object">
  Stop order object
</h2>

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

| Fields                                                                  | Description                                                                                                                                                                                                                                                                                                                                                                                          |
| ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| stop\_order\_token<br /><br />string<br /><br />Returned                | Marqeta-assigned unique identifier for the stop order.<br /><br />**Allowable Values:**<br /><br />Existing stop order token                                                                                                                                                                                                                                                                         |
| card\_token<br /><br />string<br /><br />Returned                       | Token of the card on which you have placed the stop order.<br /><br />**Allowable Values:**<br /><br />Existing card token                                                                                                                                                                                                                                                                           |
| transaction\_token<br /><br />string<br /><br />Returned                | Marqeta-assigned token of the original recurring transaction used to create the stop order.<br /><br />**Allowable Values:**<br /><br />Existing transaction token                                                                                                                                                                                                                                   |
| merchant\_id<br /><br />string<br /><br />Returned                      | Merchant ID (MID) as defined by the card network, derived from the original recurring transaction.<br /><br />**Allowable Values:**<br /><br />Existing MID                                                                                                                                                                                                                                          |
| merchant\_name<br /><br />string<br /><br />Conditionally returned      | Name of the merchant.<br /><br />**Allowable Values:**<br /><br />255 char max                                                                                                                                                                                                                                                                                                                       |
| original\_amount<br /><br />decimal<br /><br />Returned                 | Amount of the original recurring transaction used to create the stop order, derived automatically from the transaction.<br /><br />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.<br /><br />**Allowable Values:**<br /><br />decimal<br /><br />**Format:**<br />0.00     |
| stop\_reason<br /><br />string<br /><br />Returned                      | Reason the stop order was created.<br /><br />**Allowable Values:**<br /><br />`CANCELLED_SUBSCRIPTION`, `TRIAL_ENDED`, `UNRECOGNIZED_CHARGE`, `BILLING_ISSUE`, `MERCHANT_UNRESPONSIVE`, `PRICE_CHANGE`, `SUSPECTED_FRAUD`, `CARD_LOST_OR_REPLACED`, `OTHER`                                                                                                                                         |
| update\_reason<br /><br />string<br /><br />Conditionally returned      | Reason for the most recent update.<br /><br />**Allowable Values:**<br /><br />`DURATION_CHANGED`, `ISSUED_IN_ERROR`, `CARDHOLDER_REQUEST`, `MERCHANT_RESOLVED`                                                                                                                                                                                                                                      |
| reason\_description<br /><br />string<br /><br />Conditionally returned | Free-text description of the reason for the stop order or update.<br /><br />**Allowable Values:**<br /><br />255 char max                                                                                                                                                                                                                                                                           |
| user\_token<br /><br />string<br /><br />Returned                       | Token of the cardholder associated with the card.<br /><br />**Allowable Values:**<br /><br />Existing user token                                                                                                                                                                                                                                                                                    |
| duration<br /><br />integer<br /><br />Returned                         | Duration of the stop order. Defaults to `13` if a value is not specified when the stop order is created.<br /><br />Max: `60`<br /><br />**Allowable Values:**<br /><br />Integer between `1` and `60`                                                                                                                                                                                               |
| duration\_unit<br /><br />string<br /><br />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`.<br /><br />If a value for `duration_unit` is provided without also providing a value for the `duration` field, the endpoint returns a validation error.<br /><br />**Allowable Values:**<br /><br />`MONTH`, `YEAR` |
| status<br /><br />string<br /><br />Returned                            | Current status of the stop order. The value for this field defaults to `ACTIVE` upon creation of the stop order.<br /><br />**Allowable Values:**<br /><br />`ACTIVE`, `CANCELLED`, `EXPIRED`                                                                                                                                                                                                        |
| created\_time<br /><br />datetime<br /><br />Returned                   | Date and time when the resource was created, in UTC.<br /><br />**Allowable Values:**<br /><br />Format: `yyyy-MM-ddThh:mm:ssZ`                                                                                                                                                                                                                                                                      |
| last\_modified\_time<br /><br />datetime<br /><br />Returned            | Date and time when the resource was last updated, in UTC.<br /><br />**Allowable Values:**<br /><br />Format: `yyyy-MM-ddThh:mm:ssZ`                                                                                                                                                                                                                                                                 |
| expiry\_time<br /><br />datetime<br /><br />Returned                    | Date and time when the stop order expires, in UTC.<br /><br />**Allowable Values:**<br /><br />Format: `yyyy-MM-ddThh:mm:ssZ`                                                                                                                                                                                                                                                                        |

<h2 id="retrieve_recurring_transactions">
  Retrieve recurring transactions
</h2>

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`

<h3 id="_path_parameters">
  Path parameters
</h3>

| Fields                                            | Description                                                                                                           |
| ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| card\_token<br /><br />string<br /><br />Required | Token of the card for which to retrieve transactions.<br /><br />**Allowable Values:**<br /><br />Existing card token |

<h3 id="_url_query_parameters">
  URL query parameters
</h3>

| Fields                                               | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| is\_recurring<br /><br />boolean<br /><br />Required | Set to `true` to filter only recurring transactions.<br /><br />**Allowable Values:**<br /><br />`true`, `false`<br /><br />**Default:** `false`                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| start\_date<br /><br />string<br /><br />Optional    | Start of the date range filter. If a value for this field is provided, a value for `end_date` must also be specified.<br /><br />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.<br /><br />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`.<br /><br />**Allowable Values:**<br /><br />Date in `yyyy-MM-dd` or `yyyy-MM-ddThh:mm:ssZ` format                   |
| end\_date<br /><br />string<br /><br />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.<br /><br />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.<br /><br />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`.<br /><br />**Allowable Values:**<br /><br />Date in `yyyy-MM-dd` or `yyyy-MM-ddThh:mm:ssZ` format |

<h3 id="_response_body">
  Response body
</h3>

| Fields                                                             | Description                                                                                                                                                                                                                                                                                                                    |
| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| count<br /><br />integer<br /><br />Conditionally returned         | Number of resources to retrieve.<br /><br />This field is returned if there are resources in your returned array.<br /><br />**Allowable Values:**<br /><br />1-10                                                                                                                                                             |
| data<br /><br />array of objects<br /><br />Conditionally returned | Valid array of transaction objects. For more information, see the description of the [transaction object](/core-api/transactions/#transaction_model) on the Transactions page.<br /><br />Objects are returned based on your query.<br /><br />**Allowable Values:**<br /><br />Valid array of one or more transaction objects |
| end\_index<br /><br />integer<br /><br />Conditionally returned    | Sort order index of the last resource in the returned array.<br /><br />This field is returned if there are resources in your returned array.<br /><br />**Allowable Values:**<br /><br />Any integer                                                                                                                          |
| is\_more<br /><br />boolean<br /><br />Conditionally returned      | A value of `true` indicates that more unreturned resources exist. A value of `false` indicates that all resources have been returned.<br /><br />This field is returned if there are resources in your returned array.<br /><br />**Allowable Values:**<br /><br />`true`, `false`                                             |
| start\_index<br /><br />integer<br /><br />Conditionally returned  | Sort order index of the first resource in the returned array.<br /><br />This field is returned if there are resources in your returned array.<br /><br />**Allowable Values:**<br /><br />Any integer                                                                                                                         |

<h3 id="_sample_response">
  Sample response
</h3>

```json JSON lines wrap theme={null}
{
  "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
      }
    }
  ]
}
```

<h2 id="create_a_stop_order">
  Create a stop order
</h2>

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

<Note>
  **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.
</Note>

For errors associated with the creation of a stop order, see the [Errors](/core-api/errors/) page.

**Action:** `POST`
**Endpoint:** `/v3/cards/{card_token}/stoporders`

<h3 id="_path_parameters_2">
  Path parameters
</h3>

| Fields                                            | Description                                                                                                         |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| card\_token<br /><br />string<br /><br />Required | Token of the card on which to place the stop order.<br /><br />**Allowable Values:**<br /><br />Existing card token |

<h3 id="_request_body">
  Request body
</h3>

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

<h3 id="_response_body_2">
  Response body
</h3>

See [Stop order object](#stop_order_object).

<h3 id="_sample_request">
  Sample request
</h3>

```json JSON lines wrap theme={null}
{
  "transaction_token": "15254919",
  "stop_reason": "OTHER",
  "reason_description": "other reasons",
  "duration": 2,
  "duration_unit": "MONTH"
}
```

<h3 id="_sample_response_2">
  Sample response
</h3>

```json JSON lines wrap theme={null}
{
  "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"
}
```

<h2 id="list_stop_orders_for_a_card">
  List stop orders for a card
</h2>

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](/core-api/errors/) page.

**Action:** `GET`
**Endpoint:** `/v3/cards/{card_token}/stoporders`

<h3 id="_path_parameters_3">
  Path parameters
</h3>

| Fields                                            | Description                                                                                                              |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| card\_token<br /><br />string<br /><br />Required | Token of the card on which you have placed a stop order.<br /><br />**Allowable Values:**<br /><br />Existing card token |

<h3 id="_response_body_3">
  Response body
</h3>

| Fields                                                             | Description                                                                                                                                                                                                                                                                        |
| ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| count<br /><br />integer<br /><br />Conditionally returned         | Number of resources to retrieve.<br /><br />This field is returned if there are resources in your returned array.<br /><br />**Allowable Values:**<br /><br />1-10                                                                                                                 |
| data<br /><br />array of objects<br /><br />Conditionally returned | Array of stop order objects.<br /><br />**Allowable Values:**<br /><br />Valid array of one or more stop order objects                                                                                                                                                             |
| end\_index<br /><br />integer<br /><br />Conditionally returned    | Sort order index of the last resource in the returned array.<br /><br />This field is returned if there are resources in your returned array.<br /><br />**Allowable Values:**<br /><br />Any integer                                                                              |
| is\_more<br /><br />boolean<br /><br />Conditionally returned      | A value of `true` indicates that more unreturned resources exist. A value of `false` indicates that all resources have been returned.<br /><br />This field is returned if there are resources in your returned array.<br /><br />**Allowable Values:**<br /><br />`true`, `false` |
| start\_index<br /><br />integer<br /><br />Conditionally returned  | Sort order index of the first resource in the returned array.<br /><br />This field is returned if there are resources in your returned array.<br /><br />**Allowable Values:**<br /><br />Any integer                                                                             |
| data\[].\*<br /><br />object<br /><br />Conditionally returned     | See [Stop order object](#stop_order_object).                                                                                                                                                                                                                                       |

<h3 id="_sample_response_3">
  Sample response
</h3>

```json JSON lines wrap theme={null}
{
  "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"
    }
  ]
}
```

<h2 id="retrieve_a_specific_stop_order">
  Retrieve a specific stop order
</h2>

Returns the details of a single stop order.

**Action:** `GET`
**Endpoint:** `/v3/cards/{card_token}/stoporders/{stop_order_token}`

<h3 id="_path_parameters_4">
  Path parameters
</h3>

| Fields                                                   | Description                                                                                                                  |
| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| card\_token<br /><br />string<br /><br />Required        | Token of the card on which you have placed a stop order.<br /><br />**Allowable Values:**<br /><br />Existing card token     |
| stop\_order\_token<br /><br />string<br /><br />Required | Marqeta-assigned unique identifier for the stop order.<br /><br />**Allowable Values:**<br /><br />Existing stop order token |

<h3 id="_response_body_4">
  Response body
</h3>

See [Stop order object](#stop_order_object).

<h3 id="_sample_response_4">
  Sample response
</h3>

```json JSON lines wrap theme={null}
{
  "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"
}
```

<h2 id="update_stop_order">
  Update stop order
</h2>

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}`

<h3 id="_path_parameters_5">
  Path parameters
</h3>

| Fields                                                   | Description                                                                                                                  |
| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| card\_token<br /><br />string<br /><br />Required        | Token of the card on which you have placed a stop order.<br /><br />**Allowable Values:**<br /><br />Existing card token     |
| stop\_order\_token<br /><br />string<br /><br />Required | Marqeta-assigned unique identifier for the stop order.<br /><br />**Allowable Values:**<br /><br />Existing stop order token |

<h3 id="_request_body_2">
  Request body
</h3>

| Fields                                                    | Description                                                                                                                                                                                                                                                                                                                                                                                                    |
| --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| status<br /><br />string<br /><br />Required              | New status for the stop order.<br /><br />**Allowable Values:**<br /><br />`ACTIVE`, `CANCELLED`                                                                                                                                                                                                                                                                                                               |
| update\_reason<br /><br />string<br /><br />Required      | Reason for the update.<br /><br />**Allowable Values:**<br /><br />`DURATION_CHANGED` - The stop order duration has been modified.<br />`ISSUED_IN_ERROR` - The stop order was placed by mistake.<br />`CARDHOLDER_REQUEST` - The cardholder requested the change.<br />`MERCHANT_RESOLVED` - The issue with the merchant has been resolved.                                                                   |
| reason\_description<br /><br />string<br /><br />Optional | Free-text description of the update reason.<br /><br />**Allowable Values:**<br /><br />255 char max                                                                                                                                                                                                                                                                                                           |
| duration<br /><br />integer<br /><br />Optional           | New duration of the stop order.<br /><br />Max: `60`.<br /><br />**Allowable Values:**<br /><br />Integer between `1` and `60`                                                                                                                                                                                                                                                                                 |
| duration\_unit<br /><br />string<br /><br />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`.<br /><br />If a value for `duration_unit` is provided without also providing a value for the `duration` field, then the endpoint returns a validation error.<br /><br />**Allowable Values:**<br /><br />`MONTH`, `YEAR` |

<h3 id="_response_body_5">
  Response body
</h3>

See [Stop order object](#stop_order_object).

<h3 id="_sample_request_2">
  Sample request
</h3>

```json JSON lines wrap theme={null}
{
  "status": "CANCELLED",
  "update_reason": "CARDHOLDER_REQUEST",
  "reason_description": "Customer request"
}
```

<h3 id="_sample_response_5">
  Sample response
</h3>

```json JSON lines wrap theme={null}
{
  "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"
}
```

<Warning>
  **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).
</Warning>

<h2 id="_stop_order_declines">
  Stop order declines
</h2>

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>
  **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.
</Note>

<h2 id="_stop_order_statuses">
  Stop order statuses
</h2>

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

<h3 id="_status_lifecycle">
  Status lifecycle
</h3>

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](#update_stop_order) endpoint. If you do not cancel the stop order, it automatically transitions to `EXPIRED` when the `expiry_time` is reached.

<Note>
  **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.
</Note>