Overview

Every Authorization Rule follows the same lifecycle. You draft a rule, which runs in shadow mode so you can observe its impact without affecting live transactions. You promote the draft to make it active. You disable or delete the rule when it is no longer needed. This page covers creating, retrieving, and managing rules through that lifecycle.

The same lifecycle applies to every rule type and event stream, including Conditional Action Rules, Velocity Limit Rules, Tokenization Rules, 3DS Authentication Rules, and Custom Code Rules.

Rule States

A rule has a top-level state that is either ACTIVE or INACTIVE. Draft status is conveyed separately by the draft_version object on the rule, not by the rule's state:

• Rule state: ACTIVE (affecting live transactions) or INACTIVE (not affecting transactions)
• draft_version.state: PENDING (the draft is compiling, for Custom Code Rules only), SHADOWING (the draft is evaluating in shadow mode alongside the current active version), or ERROR (the draft failed to compile)
• Version state (from version history): ACTIVE (the live version), SHADOW (a version that ran in shadow mode), or INACTIVE (a superseded or disabled version)

Drafting a New Rule

To draft a new rule, use the POST /v2/auth_rules endpoint. Specify the rule type, event stream, parameters, and the entities the rule applies to. The rule is created with no active version and a draft_version that runs in shadow mode.

For most rule types the draft begins running in shadow mode immediately. For Custom Code Rules (TYPESCRIPT_CODE), the code compiles asynchronously first: the draft_version.state is PENDING during compilation, then transitions to SHADOWING once it succeeds, or ERROR if compilation fails.

Scoping a Rule

A rule's entities parameter sets which transactions the rule applies to. It has an include list of entities the rule applies to, and an optional exclude list of entities the rule skips. Each entity has a type:

The card event streams are AUTHORIZATION, THREE_DS_AUTHENTICATION, TOKENIZATION, and CARD_TRANSACTION_UPDATE. Rules on every other event stream accept PROGRAM, ACCOUNT, and BUSINESS_ACCOUNT entities only.

Including and Excluding Entities

Exclusions override inclusions. A rule skips a transaction when its card, its account, its business account, or one of the card's tags is excluded, even when another of those entities is included. A rule's entities must also meet these constraints:

• include contains at least one entity
• PROGRAM, when included, is the only included entity, and it cannot be excluded
• An entity appears at most once, and never in both include and exclude
• A rule references at most 1,000 entities across both lists, not counting PROGRAM

Scoping by Card Tag

Tags are key-value pairs that you set on a card through the Cards API, such as a risk tier or a program segment. A CARD_TAG entity matches every card whose tags contain the entity's key with exactly the entity's value. A single tag entity lets a rule target a cohort of cards, with no list of card tokens to maintain on the rule.

Lithic checks the card's current tags each time it evaluates an event. To move a card into or out of a tag-scoped rule, update the card's tags with PATCH /v1/cards/{card_token}. The rule does not need to change.

A tag entity works in either list. Include a tag to apply a rule to a cohort, or exclude a tag to exempt a cohort from a program-wide rule.

Example: Risk Tiers

A program tags each card with a risk-level of high or low, and wants a stricter transaction amount limit on high-risk cards. It creates two rules:

• A rule with a low amount limit, scoped to cards tagged risk-level: high
• A rule with a higher amount limit, scoped to cards tagged risk-level: low

The first rule's entities parameter includes one CARD_TAG entity:

{
  "entities": {
    "include": [{ "type": "CARD_TAG", "key": "risk-level", "value": "high" }]
  }
}

The second rule is the same, with value set to low.

To move a card from the high-risk tier to the low-risk tier, send this request body to PATCH /v1/cards/{card_token}:

{
  "tags": {
    "risk-level": "low"
  }
}

The update overwrites the card's risk-level value and keeps its other tags. From the card's next event, the low-risk rule applies to it and the high-risk rule does not. Neither rule changes.

Updating a Rule's Entities

• To replace both lists, send entities to PATCH /v2/auth_rules/{auth_rule_token}. A missing list is treated as empty, so always send include
• To add or remove individual entities, send add and remove objects to PATCH /v2/auth_rules/{auth_rule_token}/entities. Each object has its own include and exclude lists

Example Request

{
  "name": "Block gambling MCCs",
  "entities": {
    "include": [{ "type": "PROGRAM" }],
    "exclude": [{ "type": "CARD_TAG", "key": "risk-level", "value": "low" }]
  },
  "type": "CONDITIONAL_ACTION",
  "event_stream": "AUTHORIZATION",
  "parameters": {
    "action": "DECLINE",
    "conditions": [
      {
        "attribute": "MCC",
        "operation": "IS_ONE_OF",
        "value": ["7801", "7802", "7995"]
      }
    ]
  }
}

Once the rule is created, it runs in shadow mode. To learn how shadow mode works and how to measure a draft rule's impact before promoting it, see Analytics and Observability.

Promoting a Rule

When you are confident in a draft rule, promote it with the POST /v2/auth_rules/{auth_rule_token}/promote endpoint. The request takes no body parameters.

Promotion makes the draft the new active version, replacing any existing active version, and the draft_version returns to null. Once promoted, the rule begins affecting authorizations in real time.

The previously active version is set to inactive but is not destroyed. It remains visible in the rule's version history. There is no endpoint to re-activate a prior version directly. To restore an earlier configuration, create a new draft with those parameters and promote it.

Disabling a Rule

To disable a rule, use the PATCH /v2/auth_rules/{auth_rule_token} endpoint and set the rule's state to INACTIVE. The rule stops affecting authorizations.

{
  "state": "INACTIVE"
}

The previously active configuration is preserved in version history, even though the current_version parameter is cleared from the rule response.

Clearing a Draft

To clear a draft without affecting the active rule, call the POST /v2/auth_rules/{auth_rule_token}/draft endpoint with parameters set to null:

{
  "parameters": null
}

This stops the draft from running in shadow mode. The active version, if any, is unchanged.

Deleting a Rule

To permanently remove a rule, use the DELETE /v2/auth_rules/{auth_rule_token} endpoint. A successful deletion returns a 204 No Content response. Unlike disabling, deletion cannot be undone and the rule is no longer retrievable. If you may need the rule again, disable it instead of deleting it.

Retrieving Rules

Listing Rules

Use the GET /v2/auth_rules endpoint to list all rules under your program. Filter the response with:

• account_token / card_token / business_account_token: rules associated with a specific entity
• scope: filter by rule scope (PROGRAM, ACCOUNT, BUSINESS_ACCOUNT, CARD, or ANY)
• event_streams: one or more event streams (for example, AUTHORIZATION, TOKENIZATION, THREE_DS_AUTHENTICATION, ACH_DEBIT_RECEIPT, ACH_CREDIT_RECEIPT). The singular event_stream parameter still works but is deprecated in favor of event_streams
• page_size: results per page (1–100, default 50)

Fetching a Rule by Token

Use the GET /v2/auth_rules/{auth_rule_token} endpoint to retrieve a single rule, including its state, current_version, and any draft_version.

Viewing Version History

Use the GET /v2/auth_rules/{auth_rule_token}/versions endpoint to retrieve every version of a rule, newest first. Each version includes its parameters and its state (ACTIVE, SHADOW, or INACTIVE). This is how previously active configurations remain available after a promotion or a disable.

Lithic-Managed Rules

Some rules in your program may be flagged as lithic_managed. These rules are managed by Lithic and cannot be modified or deleted through the API or Dashboard. They appear in rule listings and in rule results but are not editable.

Next Steps

• Analytics and Observability: measure rules in shadow mode and interpret decline results
• Conditional Action Rules and Velocity Limit Rules: the rule types you will manage through this lifecycle