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

# Change requests and approval

> Propose content changes and get them approved by AllRide.

## Why changes need approval

Consumers only ever see **approved** content: the live revision of a voucher set, your provider profile and your listing branding. Every create or update of that content is a **change request** that AllRide reviews before it goes live. This protects consumers and their customers from misleading or unsafe content.

These do **not** need a change request and take effect at once: vouchers (batch, uploads, revocations), `internalName`, activation, schedules, stock alert rules and workspace branding.

Change requests exist for three subjects, with the same six operations each:

| Subject | Base path | Read / write permission |
| - | - | - |
| Voucher set | `/provider/v1/voucher-sets/{voucherSetId}/change-requests` | `view-provider-voucher-sets` / `submit-provider-voucher-sets` |
| Provider profile | `/provider/v1/provider-profile/change-requests` | `view-provider-profile` / `manage-provider-profile` |
| Listing branding | `/provider/v1/listing-branding/change-requests` | `view-provider-profile` / `manage-provider-profile` |

`GET /provider/v1/change-requests` lists them across subjects.

## Submit a change request

```bash theme={null}
curl -sS -X POST "$VOUCHER_API_BASE_URL/provider/v1/voucher-sets/2030/change-requests" \
  -H "Authorization: Bearer $VOUCHER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"providerNote": "Raise the value to €5.", "submit": true}'
```

* `proposedContent` is the full content you propose. For a voucher set you may leave it out: the set's `draftContent` is used, and the draft is cleared (the change request now holds your working copy).
* `submit: true` (the default) validates the complete content, runs the automated checks and sets `status: scanning`. The first change request of a set has `kind: create` and moves the set to `pending-approval`; later ones are `update` and leave the live set unchanged until approval.
* `submit: false` creates a `draft` change request that you can edit and submit later with `:submit`.
* One open change request per subject: a second → 409 `change-request-open` with `more.openChangeRequestId` naming the open change request.
* `diff` and `changedFields` show what changes against the live content; `warnings` lists non-blocking hints (for example `insufficient-contrast`).

**Edit** an open change request with `PATCH` (top-level fields merge). Every edit rebases it on the current live revision; outside `draft` the checks restart. **Withdraw** it with `:withdraw`; for a voucher set the proposed content goes back to `draftContent`, so nothing is lost.

If the live content changed underneath an open change request (AllRide can make corrections), `isStale` is `true`: any `PATCH`, even only `providerNote`, rebases it.

## Automated content checks

When you submit or edit, automated checks scan the content for unsafe links, hidden characters, markup, impersonation and similar problems, and then AllRide reviews **every** change request. You see the status, never check details:

| Status | Meaning | You can |
| - | - | - |
| `draft` | Not submitted | Edit, submit, withdraw |
| `submitted`, `scanning` | Automated checks running | Edit (restarts checks), withdraw |
| `awaiting-review` | Waiting for AllRide | Edit (restarts checks), withdraw |
| `approved` | Live as a new revision | — |
| `rejected` | Not approved; read `decisionReason` | — |
| `withdrawn` | Withdrawn by you | — |

Problems the schema can express (HTML in Markdown, bad URLs, missing fields) are refused immediately with 400 `data-failed-validation`. Everything else is decided in review. Follow the [content rules](https://docs-provider.voucher.allride.io/provider/content-rules.md) to avoid rejections. Removing an allowed link host or scheme that available vouchers still use → 422 `link-host-in-use`.

## Review outcomes

* **Approved**: a new revision becomes live (`appliedRevisionNo`). The first approval of a set makes it `inactive`, ready to [activate](https://docs-provider.voucher.allride.io/provider/activation-and-scheduling.md). AllRide may approve with small modifications: `modifiedByAdmin: true`, `approvedContent` and `modificationDiff` show them.
* **Rejected**: `decisionReason` explains why. The live content is unchanged; your proposed content returns to the set's draft, and a set that was never approved goes back to `draft`.

You are told through the webhooks [`change-request-approved`](https://docs-provider.voucher.allride.io/webhooks/events/change-request-approved) and [`change-request-rejected`](https://docs-provider.voucher.allride.io/webhooks/events/change-request-rejected) and by email. In the sandbox, change requests whose checks pass are approved automatically.

## Changelog

Each subject has a changelog of its approved change requests, newest first, with `diff`, `origin` (`provider` or `admin`) and `decisionReason`:

* `GET /provider/v1/voucher-sets/{voucherSetId}/changelog`
* `GET /provider/v1/provider-profile/changelog`
* `GET /provider/v1/listing-branding/changelog`

Corrections made by AllRide appear with `origin: admin` and the reviewer as "AllRide". Every approved revision of a set is also available under `…/revisions`.

## Related

* [Content rules](https://docs-provider.voucher.allride.io/provider/content-rules.md)
* [Voucher sets](https://docs-provider.voucher.allride.io/provider/voucher-sets.md)
* [Provider profile and branding](https://docs-provider.voucher.allride.io/provider/profile-and-branding.md)


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