> ## Documentation Index
> Fetch the complete documentation index at: https://alguna.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Amendment and Renewal Approvals
> How amendment and renewal quotes wait for approval before the customer can sign: the proposal card, what is locked while a quote waits, edits after sending, signing, renewals, automations and the API
An amendment or renewal quote changes a subscription that is already live, so a discount or term your rules forbid could otherwise reach the customer for signature with no review. When a ruleset covers **Amendment quote** or **Renewal quote** and the proposed terms match one of its rules, Alguna prepares the proposal but does not issue it: the quote waits in **Pending approval**, the customer has nothing to sign, and the quote goes out only after approvers sign off. Use this page to understand what reps and approvers see at each step, what is locked while a quote waits, and how signing, automations and the API behave. For the rules themselves see [Approval Rules](/docs/approvals/approval-rules#quote-types); for how quotes relate to subscriptions see [How Alguna Works](/docs/concepts/how-alguna-works).
Rulesets are configured in the dashboard under **Settings → Workflows → Quotes → Approvals**. Quotes can be created and sent from the dashboard or through the [public API](#public-api).
***
## How it differs from a new-business quote
| | New-business quote | Amendment quote | Renewal quote |
| - | - | - | - |
| **Evaluated terms** | All proposed terms | Only terms the amendment adds or makes worse | All terms of the new commitment, unchanged ones included |
| **Example: rule "any product discount above 20%"** | A 25% discount matches | Raising Product A from 25% to 35% matches; lowering it to 15% does not | Renewing Product A at an unchanged 25% matches |
| **Subscription while the quote waits** | Draft subscription, not live | Live subscription stays active and billing | Live subscription stays active and billing |
A ruleset applies only to the quote types selected on it. A rule that covers amendments and renewals does not affect new-business quotes, and the reverse.
***
## Lifecycle
```mermaid theme={null}
stateDiagram-v2
[*] --> Draft: proposal prepared
Draft --> OutForSignature: no rule matches, issued at once
Draft --> AwaitingApproval: Request approval
AwaitingApproval --> Draft: Return to draft
AwaitingApproval --> NeedsReview: subscription changed while waiting
NeedsReview --> Draft: Return to draft
AwaitingApproval --> Rejected: an approver rejects
Rejected --> AwaitingApproval: Request approval again
Rejected --> Draft: Return to draft
AwaitingApproval --> Approved: approved, held for a person to send
AwaitingApproval --> OutForSignature: approved, sent automatically
Approved --> OutForSignature: Send for signature
OutForSignature --> Signed: customer signs
Signed --> [*]
```
**Discard proposal** on the card of an unsent quote withdraws the quote and its staged change. The subscription stays active on its current terms.
***
## The proposal card
The top of the quote shows a card with the proposal's state, what happens next, and the actions available to you.
| Card label | What it means | Actions |
| - | - | - |
| **Draft** | The proposal is prepared and not sent. If its terms match a rule, the card says so and shows why | **Request approval** when a rule matches, otherwise **Send for signature**; **Discard proposal** |
| **Awaiting approval** | Approvers are reviewing the proposal. Nothing is issued and the customer cannot sign | **Return to draft**, **Discard proposal** |
| **Needs review** | The subscription changed while approval was pending, so the approval no longer applies | **Return to draft**, **Discard proposal** |
| **Rejected** | An approver rejected the proposal. The proposed terms are kept | **Request approval again**, **Return to draft**, **Discard proposal** |
| **Approved** | Approved, and held for a person to send | **Send for signature**, **Return to draft**, **Discard proposal** |
| **Approved, sending** | Approved, and the quote is being sent for signature automatically | — |
| **Send failed** | Approved, but the automatic send failed. Alguna tries again automatically | **Send again**, **Return to draft**, **Discard proposal** |
| **Out for signature** | The quote is issued and waits for the customer's signature | — |
The subscription page of a quote that waits also says that an open amendment or renewal quote holds the subscription, and links to it.
***
## Requesting approval
1. Open the draft amendment or renewal quote. When its terms match a rule, the card shows **Request approval** instead of **Send for signature**.
2. Review why. Each product row that triggers a rule is highlighted with the rule name and the reason, for example *Discount above 20%: Product A: discount 25% → 35%; above 20% and worsens*. Rows that changed but trigger nothing are shown without the highlight. On a renewal the reason names the level rather than the change, for example *Product A: discount 25%; above 20%*.
3. Select **Request approval**. The dialog repeats the reason and the comparison, asks for a justification when the ruleset requires one, and, when the ruleset lets the requester choose, asks what should happen after approval.
The quote moves to **Awaiting approval** and approvers are notified as for any [approval flow](/docs/approvals/approval-flows#notifications).
An amendment that matches no rule skips this step and is issued for signature at once.
***
## While a quote waits
A quote in **Awaiting approval** holds its subscription. Until the quote is sent or discarded:
* **No document is issued.** There is no signing link and no PDF for the customer. A shared link to the quote says it still needs approval and offers no signing.
* **The terms are locked.** Changing prices, discounts, quantities or products is refused with a prompt to return the quote to draft first. Delivery details such as the quote's name can still change, and the request stays pending.
* **The subscription stays active.** It keeps billing on its current terms.
* **Other changes to the subscription wait.** A second amendment quote, a new draft version of the subscription, a self-service plan change by the customer and a scheduled price escalation are all refused while the quote holds the subscription, with a message that names the open quote.
* **A change to the live terms still goes through, and makes the approval stale.** If someone edits the subscription's current terms while the request waits, the approval no longer matches what the customer would sign. When the approver decides, the quote shows **Needs review** instead of being sent, and the comparison is shown against the new terms. Return it to draft and request approval again.
**Return to draft** cancels the pending request and keeps the proposed terms, so you can edit them and request approval again. The earlier request stays in the quote's approval history.
***
## Reviewing a request
Approvers find the request under **Approvals**, with the quote, the rule and the requester's justification. Opening it shows the captured proposal: every changed product row with its own product name, the proposed and current values side by side, and the highlight and reason on the rows that triggered the rule. Approve or reject as described in [Making a decision](/docs/approvals/approval-flows#making-a-decision).
***
## After a decision
### Approved
What happens next follows the ruleset's **After approval** setting:
* **Automatic** — the quote is sent for signature as soon as the flow is approved.
* **Manual** — the quote shows **Approved** and waits. A rep selects **Send for signature** when ready.
If the automatic send fails, the card shows **Send failed**. Alguna retries on its own; **Send again** runs it immediately. The quote is issued once either way.
### Rejected
The quote shows **Rejected** and keeps its proposal, so the rep can see exactly what was turned down. A rejected quote cannot be sent or signed, and a plain approval request does not reopen it: the rep either selects **Request approval again** to ask for the same terms, or returns it to draft to change them first.
***
## Editing a quote that is out for signature
An edit to an amendment or renewal quote that is already out for signature is checked against the same rules.
| Situation | Card label | What the customer can do |
| - | - | - |
| The edited terms need no approval | **Out for signature** | The quote is reissued with the edits at once, and the customer signs the new terms |
| The edited terms need approval | **Edit awaiting approval** | Nothing. The customer cannot sign until the edits are approved and reissued |
| The edit is approved and is being reissued | **Edit approved, reissuing** | Nothing until the reissue completes |
| The edit is approved and held for a person | **Edit approved** | Nothing until someone sends the quote to reissue it |
| The automatic reissue failed | **Reissue failed** | Nothing. Alguna retries on its own; **Reissue again** runs it immediately |
| The edit is rejected | **Edit rejected** | Nothing. Select **Request approval again**, edit the terms again, or withdraw the quote |
| The subscription changed while the edit waited | **Edit needs review** | Nothing. Edit the terms again to request approval, or withdraw the quote |
While an edit waits, a signature on the previously issued document is refused, both on the hosted signing page and when the quote is marked signed offline. This keeps the customer from signing terms that are about to change. When the edit is approved and reissued, the customer signs the new revision.
***
## Signing
A signature is accepted only for terms that were issued with the approval they needed, or that needed none. In practice:
* A quote in **Awaiting approval**, **Rejected** or **Needs review** cannot be signed, whether through the hosted signing page or by marking it signed offline.
* When the customer signs an approved, issued quote, the change is applied to the subscription as for any [amendment quote](/docs/subscriptions/amendments#getting-an-amendment-signed).
* Signing or applying the same quote twice is refused; the change is applied once.
***
## Renewals and automations
A renewal quote is evaluated under **Renewal quote**, whether a rep creates it or an automation does. The [`create_quote`](/docs/automations/actions#create_quote) action with `kind` set to `renewal` creates a renewal of the subscription you name. The renewal waits for approval like a rep's quote, the current subscription stays active, and signing the approved renewal takes effect for the next term.
When an automation creates a quote that needs approval:
* The quote is kept in **Pending approval** with an approval request, and waits for the approvers' decision.
* The automation step reports the pending approval as its failure and is not retried. Running the same automation run again returns the same quote and the same approval request rather than creating another.
* An [`activate_quote`](/docs/automations/actions#activate_quote) step on a quote that is waiting for approval fails and changes nothing.
A user who can manage quotes but not subscriptions can still request approval of a renewal from the quote.
***
## When rules change
* **Editing a rule** re-evaluates requests that are still waiting. Each is replaced by a new version of the request, evaluated against the edited rule, and stays pending. The request's `generation` in the API increases.
* **Disabling a rule or ruleset** releases the requests that only it required.
When you disable a rule or ruleset, every pending request that no other enabled rule requires is approved immediately, without a person's decision. This applies to new-business, amendment and renewal quotes alike. If you only want to pause new requests, review what is pending under **Approvals** before you disable the rule.
***
## Public API
The `2026-04-01` API reports approval on every quote and refuses operations that an approval blocks.
* **Quote status.** A quote waiting for approval has `status` `pending_approval`. [List quotes](/docs/api-reference/v2/2026-04-01/quotes/list-quotes) filters by `status`, `kind` and `subscription_id`.
* **The `approval` object.** [Get a quote](/docs/api-reference/v2/2026-04-01/quotes/get-a-quote) returns `approval` with the request's `status`, `operation`, `flow_id`, `generation`, `requested_at` and `decided_at`. On an amendment or renewal quote it describes the approval of the quote's own issuance. Its `status` is one of `none`, `pending`, `approved_manual_hold`, `approved_awaiting_execution`, `executed`, `failed`, `stale`, `rejected` or `canceled`; `stale` is the API's name for **Needs review**.
* **Refusals.** [Create a quote](/docs/api-reference/v2/2026-04-01/quotes/create-a-quote) for an amendment, [Send a quote for signature](/docs/api-reference/v2/2026-04-01/quotes/send-a-quote-for-signature) and [Mark a quote as signed offline](/docs/api-reference/v2/2026-04-01/quotes/mark-a-quote-as-signed-offline) fail when issuing needs approval. The error's `approval` object names the pending flow in `approval.flow_id` and why the call was refused in `approval.reason`. Repeating the call while the approval is pending returns the same flow.
To find every amendment quote that is waiting for approval:
```bash cURL theme={null}
curl "https://api.alguna.io/quotes?kind=amendment&status=pending_approval" \
-H "Authorization: Bearer $ALGUNA_API_KEY" \
-H "Alguna-Version: 2026-04-01"
```
```python Python theme={null}
import os
import requests
response = requests.get(
"https://api.alguna.io/quotes",
params={"kind": "amendment", "status": "pending_approval"},
headers={
"Authorization": f"Bearer {os.environ['ALGUNA_API_KEY']}",
"Alguna-Version": "2026-04-01",
},
)
response.raise_for_status()
for quote in response.json()["data"]:
print(quote["id"], quote["approval"]["status"])
```
To react to decisions as they happen instead of polling, subscribe to the [approval webhooks](/docs/approvals/approval-flows#webhooks).
***
## Troubleshooting
**The card shows Request approval, but I expected the quote to send.** A rule in an enabled ruleset that covers this quote type matched. The highlighted rows and the reason on the card name the rule. On an amendment, only added or worsened terms count; on a renewal, every term counts, so an unchanged discount can match.
**I can't create a second amendment or change the subscription.** An unissued amendment or renewal quote holds the subscription. Send or discard that quote first; the subscription page links to it.
**The approver approved, but the quote shows Needs review.** The subscription's live terms changed while the request waited. Return the quote to draft, check the comparison against the new terms, and request approval again.
**The customer says the signing link doesn't work.** The quote has an edit waiting for approval or its reissue. The customer can sign once the edit is approved and the quote is reissued.
**Send failed or Reissue failed.** Alguna retries automatically. Select **Send again** or **Reissue again** to run it now; the quote is issued once.
***
## Next steps
Choose the quote types a ruleset covers.
Stage and apply mid-term changes.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.