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

# Grace

> Ask Grace, the AI assistant in the dashboard, about your payments, your orchestration configuration, and how Gr4vy works.

> [!NOTE]
>
> Grace is in early access and available to selected accounts. To request access, contact your Gr4vy account manager.

Grace is an AI assistant built into the Gr4vy dashboard. You ask it questions in plain language and it answers from your own payment data, your current Gr4vy configuration, and the Gr4vy documentation.

Use Grace to find out what happened to your payments, work out why, and decide what to change. For example:

* "What was my authorization rate last month, by scheme?"
* "Why did declines go up last week?"
* "Which Flow rules declined anything this week?"
* "How often does a second attempt succeed?"
* "What is network tokenization, and should I turn it on?"

During early access, Grace is a page of its own in the dashboard's navigation, shown only to users who have been given access.

## What Grace knows about

Grace grounds its responses in three connected data sources.

| Source | What it answers | Example question |
| - | - | - |
| Your payment data | Counts, volumes, and rates over a period, broken down and filtered the way you ask. Grace can also look up individual transactions and search for them. | "Declines last week by country and method." |
| Your current configuration | What's set up right now: your connections, your [Flow](https://docs.gr4vy.com/guides/dashboard/flow/overview.md) rules and their change history, and the payment options offered to buyers at checkout. | "What would checkout offer a buyer in Germany paying 50 EUR?" |
| Gr4vy documentation | What a feature does, what a term means, and how Gr4vy behaves. | "What's the difference between a decline and a failure?" |

Because Grace runs on its own page, it can't see the filters or period set on other dashboard pages. Include the period and filters you want in your question.

### What you can break down and filter by

Grace can group or filter your payment data by most transaction attributes, alone or in combination. These include:

* **Routing:** the connection a payment went to, the provider behind it, and the Flow rule that routed it.
* **Outcome:** the transaction status, whether a payment was ever authorized, declined, failed, captured, voided, or refunded, the Gr4vy error code, and the raw response code from the payment service.
* **Card:** scheme, issuer, card type (credit, debit, or prepaid), bank identification number (BIN), and issuing country.
* **Payment:** method, how the payment details arrived (for example a card number, a stored card, or a network token), country, currency, and amount bands.
* **Repeat payments:** payment source (such as e-commerce, recurring, or card on file), whether the merchant initiated it, and whether it reused a stored credential.
* **3-D Secure:** whether it was attempted, how far it got, whether the buyer was challenged, the authentication outcome, and whether liability shifted.

You can also ask for a figure over time, by minute, hour, day, week, or month.

## How Grace answers

Grace keeps answers short because they appear in a narrow panel. A typical answer has these parts:

1. **The answer itself**, with the period and filters it used folded into the sentence.
2. **A table or chart** when the result has more than a figure or two. Charts are drawn from the same results as the tables, so a value read off a chart always matches its table.
3. **Grace's interpretation**, in a separate paragraph that starts with **My read:** in bold. Everything above that line is data. Everything after it is Grace's judgment, which can draw on general payments knowledge.

While Grace works, it shows a short line describing what it's checking. A complex question can take several queries, so expect some answers to take longer than others.

### Every rate states its basis

A rate depends on what it's divided by. Grace always tells you. If you ask for your authorization rate with no qualifier, Grace gives two figures:

* **Every processed payment.** Authorized payments out of every payment that was processed.
* **Payments that reached a payment service.** Authorized payments out of only those payments that reached a payment service. This leaves out payments your own Flow decline rules stopped first.

The two figures show how the denominator affects the reported authorization rate. Grace also distinguishes between a *payment* and an *attempt*. A payment that Gr4vy retried across three connections is one payment and three attempts, and Grace says which one it counted.

### Estimates are labeled

When you ask what a change might do, Grace can give an estimate based on figures from the same answer. An estimate always names its inputs and its assumption, and is called an estimate. For example: "Estimate: roughly 400 more approved payments a week, if the 1,200 soft declines above recover at the 34% retry success rate above."

Estimates never appear in a table or chart.

### Recommendations

Grace can recommend configuration changes, such as a routing rule or a retry setting. Before it does, it reads your current configuration so it doesn't suggest something you already have. It names the Gr4vy feature and the documentation page that describes it.

Grace recommends, but it never changes your configuration. You make any change yourself in the dashboard.

## Get the most out of Grace

**Name the period.** Grace reads phrases like "last week," "this month," and "yesterday" as calendar periods in UTC, with weeks starting on Monday. For a rolling window, ask for "the last 7 days" instead. If your question leaves the period open and it matters, Grace asks, usually with a suggestion.

**Start broad, then drill in.** Grace remembers the conversation, so follow-ups like "and by issuer?" or "only for Visa" build on the previous answer. A good investigation often goes from a total, to a breakdown, to a filtered breakdown.

**Ask why.** "Why did my authorization rate drop last week compared to the week before?" makes Grace compare the two periods and show which connection, scheme, country, or other attribute accounts for the change.

**Specify the filters.** Grace doesn't pick up filters from other dashboard pages. Include the period and filters you want Grace to use in your question.

**Check whether a rule change explains a shift.** Ask "did my authorization rate move when my routing rules changed last month?" and Grace lines up the weekly rate against the dates your Flow rules were edited.

**Ask about a single transaction.** Give Grace a transaction ID and ask "why did this decline?" to see its details and the reason.

**Ask what to do next.** Once Grace has shown you a problem, ask what it recommends. Its recommendations are better when it has already pulled the relevant figures in the same conversation.

**Ask how a figure was calculated.** If you're unsure what a number counts, ask. Grace can explain the basis, window, and filters behind any figure it reported.

## Comparing Grace with the dashboard

Grace computes its figures independently, so a number from Grace can differ from the number on an [insights](https://docs.gr4vy.com/guides/dashboard/insights/homepage.md) page. When you ask Grace about a difference, it explains it from the basis, period, and filters it used. Common causes are:

* **The basis.** The [Authorizations](https://docs.gr4vy.com/guides/dashboard/insights/authorizations.md) page excludes payments declined by Flow rules and payments that failed. Grace's "every processed payment" figure includes them.
* **The period.** Grace treats "last week" as a calendar week in UTC, where a dashboard page may show a rolling window.
* **Recent data.** Grace's data covers up to the start of the current hour. Early in an hour, some dashboard pages can include up to 30 minutes of payments that Grace can't see yet.
* **Rounding.** Grace reports rates to one decimal place.

## Conversations

Grace answers within one conversation at a time. A conversation resets, with a divider in the panel, when:

* You select **Start a new conversation**.
* You've been idle for 30 minutes.
* You switch to a different merchant account.
* Your dashboard access is reduced.

After a reset, Grace no longer remembers what came before the divider, though you can still scroll up and read it.

You can stop an answer while it's arriving. A stopped answer disappears from the panel, because a partial answer can contain a figure without the sentence that explains it.

Grace doesn't keep a history of past conversations that you can reopen.

## Limitations

Grace can be wrong. Check any figure you plan to act on, and ask Grace how it calculated anything that looks off.

Grace can't:

* **Change anything.** Grace reads your data and configuration and makes recommendations. It can't create rules, edit connections, refund payments, or take any other action.
* **Report on the current, incomplete hour.** Grace's payment data runs up to the start of the current hour, so it can't tell you about the last few minutes.
* **Report on chargebacks or disputes.** This data isn't available to Grace.
* **Report anti-fraud decisions.** Grace can't break figures down by anti-fraud outcome.
* **Analyze buyers.** Grace can't identify repeat buyers, compare new and returning buyers, or build cohorts.
* **Break refunded amounts down.** Grace can give a total refund volume, a refund rate, and how many payments were refunded by any attribute, but not refunded amounts by attribute.
* **Add up different currencies.** Grace reports each currency separately rather than combining them.
* **Answer across several merchant accounts at once.** Grace answers for the merchant account you have open.
* **Show past connection settings.** Grace reads your connections and checkout options as they are now. For Flow rules it can also list every saved change over a period, but not past versions of other settings.
* **Help with topics unrelated to payments.** Grace declines these and says what it can help with.

When Grace can't answer a payments question, it says what's missing and what it can answer instead. Gr4vy uses these refusal logs to decide what Grace learns next.

## Data and privacy

**Grace sees only what you can see.** Grace acts as you, using your own dashboard sign-in and [permissions](https://docs.gr4vy.com/guides/dashboard/roles-and-permissions/overview.md). It can't read data from a merchant account you don't have access to, and it can't show buyer details your role doesn't allow you to see. If Grace needs a permission you don't have, it tells you.

**Card numbers are blocked.** If your message looks like it contains a card number, Grace doesn't send it. Remove the number and ask again, for example by using the transaction ID instead.

**Your data isn't used to train AI models.** Your questions, Grace's answers, and your payment data aren't used for model training.

**Questions and answers are kept for 30 days.** Gr4vy keeps a record of each question, the queries Grace ran, and the answer, so that Gr4vy support can investigate problems. These records stay in your own Gr4vy instance and region, don't include copies of your transaction data, and are deleted after 30 days. Access to them is limited to Gr4vy staff and every read is logged.

> [!NOTE]
>
> In a sandbox environment, Grace answers from your sandbox test data. Those figures say nothing about your real payments.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.