> ## 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. # Submit a listing branding change request > Submits a `draft` change request: complete validation, automated checks, status `scanning`. **Required permissions:** `manage-provider-profile` · **API keys:** allowed ## OpenAPI ````yaml /openapi/provider.v1.json post /provider/v1/listing-branding/change-requests/{changeRequestId}:submit openapi: 3.1.1 info: title: AllRide Voucher Provider API version: 1.0.0 description: >- The Provider API (`/provider/v1`) and the shared workspace API (`/partner/v1`) of the AllRide Voucher Platform for Partner Providers. Start with the [quickstart](/quickstart). This reference lists only the sandbox server; production is `https://api.voucher.allride.io`. contact: name: AllRide API support url: https://docs-provider.voucher.allride.io servers: - url: https://api.voucher-staging.allride.io description: Sandbox security: - apiKey: [] tags: - name: Provider profile description: Your consumer-visible general information and general terms. - name: Listing branding description: How you look in consumer catalogs, and the images it uses. - name: Categories description: AllRide-managed categories for voucher sets. - name: Voucher sets description: Voucher sets, their lifecycle, revisions and link templates. - name: Change requests description: Proposed content changes that AllRide approves. - name: Vouchers description: 'Codes and links: batch create, reveal, revoke.' - name: Voucher uploads description: Asynchronous CSV and XLSX imports. - name: Stock alerts description: Threshold alerts on voucher set stock. - name: Redemptions description: Redemptions of your vouchers (provider projection). - name: Analytics description: Statistics without consumer dimension. - name: Partner description: Your partner record, settings, API access and reference values. - name: Members description: People in your partner. - name: Groups description: Groups of members and the permission catalog. - name: API keys description: Credentials for your backend. - name: Webhook endpoints description: Where AllRide sends events. - name: Webhook deliveries description: Delivery log, replays. - name: IP allowlist description: Addresses allowed to call the API. - name: Workspace branding description: Your dashboard theme and its images. - name: Single sign-on description: SAML and OIDC connections. - name: Audit log description: Who changed what. - name: Webhooks description: Events AllRide sends to your endpoints. paths: /provider/v1/listing-branding/change-requests/{changeRequestId}:submit: post: tags: - Change requests summary: Submit a listing branding change request description: >- Submits a `draft` change request: complete validation, automated checks, status `scanning`. **Required permissions:** `manage-provider-profile` · **API keys:** allowed operationId: provider.listing-branding-change-requests.submit parameters: - name: changeRequestId in: path required: true description: >- Numeric id (changeRequestId). A non-numeric id is a 400 data-failed-validation; an unknown id or one of another partner is a 404. schema: $ref: '#/components/schemas/ULong' example: 10030 - $ref: '#/components/parameters/IdempotencyKey' responses: '200': description: Success. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' Idempotent-Replayed: $ref: '#/components/headers/IdempotentReplayed' content: application/json: schema: $ref: '#/components/schemas/ChangeRequestResponse' examples: example: summary: Example value: data: id: 10030 resource: change-request partnerId: 42 subjectType: voucher-set subjectId: 2030 kind: update origin: provider status: approved baseRevisionNo: 1 proposedContent: name: de: 5 € Fahrguthaben en: €5 ride credit summary: de: Für alle E-Scooter en: For all e-scooters bullets: - de: Einmal einlösbar en: Single use description: null howToRedeem: - de: App öffnen und Code unter Wallet eingeben en: Open the app and enter the code under Wallet termsText: de: Einmal pro Konto einlösbar. en: Redeemable once per account. valueLabel: de: 5 € Rabatt en: €5 off faceValue: value: 500 label: 5,00 € categoryId: 7017 linkTemplate: https://acme-scooters.example.com/r?c={{code}} allowedLinkHosts: - acme-scooters.example.com allowedLinkSchemes: [] brandingOverride: null countries: - DE extensions: null metadata: null diff: - path: /faceValue/value before: 300 after: 500 - path: /linkTemplate before: null after: https://acme-scooters.example.com/r?c={{code}} changedFields: - faceValue - linkTemplate warnings: [] providerNote: Raise the value to €5 and add the deep link. approvedContent: null modifiedByAdmin: false modificationDiff: null appliedRevisionNo: 2 isStale: false decisionReason: null submittedBy: type: partner-user id: 4043 label: ops@example.com reviewedBy: type: admin-user id: null label: AllRide submittedAt: '2026-10-21T10:02:00Z' reviewedAt: '2026-10-21T16:20:00Z' createdAt: '2026-10-21T09:58:41.002Z' updatedAt: '2026-10-21T16:20:00Z' _links: self: href: >- https://api.voucher-staging.allride.io/provider/v1/voucher-sets/2030/change-requests/10030 type: application/json subject: href: >- https://api.voucher-staging.allride.io/provider/v1/voucher-sets/2030 type: application/json appliedRevision: href: >- https://api.voucher-staging.allride.io/provider/v1/voucher-sets/2030/revisions/22017 type: application/json '400': $ref: '#/components/responses/BadRequestPost' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': description: 'Not found: `change-request-not-found`, `route-not-found`.' x-error-codes: - change-request-not-found - route-not-found headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: change-request-not-found: summary: Change request not found value: errors: - message: >- No change request with this id exists for this subject. statusCode: 404 errorCode: change-request-not-found '409': description: 'Conflict: `invalid-state-transition`, `idempotency-key-in-use`.' x-error-codes: - invalid-state-transition - idempotency-key-in-use headers: X-Request-Id: $ref: '#/components/headers/XRequestId' Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid-state-transition: summary: Invalid state transition value: errors: - message: >- The command is not allowed in the resource's current status; the message names the from and to states. This is also the answer when another change moved the resource first: the status is checked when the command runs. statusCode: 409 errorCode: invalid-state-transition '422': description: 'Unprocessable content: `idempotency-key-reused`.' x-error-codes: - idempotency-key-reused headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: idempotency-key-reused: summary: Idempotency-Key reused value: errors: - message: >- The Idempotency-Key was already used for a different request. statusCode: 422 errorCode: idempotency-key-reused '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailable' components: schemas: ULong: type: integer format: uint64 minimum: 0 maximum: 18446744073709552000 x-bigint: true description: >- Unsigned 64-bit integer. May exceed 2^53; parse with a BigInt-safe JSON parser in JavaScript. ChangeRequestResponse: type: object properties: data: $ref: '#/components/schemas/ChangeRequest' required: - data description: Single-object envelope around ChangeRequest. additionalProperties: false ErrorResponse: type: object properties: errors: type: array items: $ref: '#/components/schemas/ErrorEntry' description: The errors; in v1 always exactly one. minItems: 1 required: - errors description: >- Error body of every 4xx and 5xx response (Content-Type: application/json). additionalProperties: false ChangeRequest: type: object properties: id: $ref: '#/components/schemas/ULong' description: Change request id. resource: type: string enum: - change-request description: Always change-request. partnerId: $ref: '#/components/schemas/ULong' description: Your partner id. subjectType: type: string enum: - voucher-set - provider-profile - listing-branding description: >- What the change request changes. Treat as an open set: new values may be added. subjectId: $ref: '#/components/schemas/ULong' description: Id of the subject. kind: type: string enum: - create - update description: >- create for the first revision, else update. Treat as an open set: new values may be added. origin: type: string enum: - provider - admin description: 'Who proposed it. Treat as an open set: new values may be added.' status: type: string enum: - draft - submitted - scanning - awaiting-review - approved - rejected - withdrawn description: >- Change request status. Treat as an open set: new values may be added. baseRevisionNo: type: integer description: Live revision the diff is computed against. proposedContent: type: object additionalProperties: true description: >- Full proposed content of the subject (VoucherSetContent, ProviderProfileContent or ListingBrandingContent). diff: type: array items: $ref: '#/components/schemas/DiffEntry' description: Changes against the live content. changedFields: type: array items: type: string description: Field. description: Top-level fields in diff. warnings: type: array items: $ref: '#/components/schemas/ContentWarning' description: Non-blocking warnings. providerNote: type: - string - 'null' description: Your note to the reviewer. approvedContent: type: - object - 'null' additionalProperties: true description: Set only when AllRide approved with modifications. modifiedByAdmin: type: boolean description: AllRide changed the content when approving. modificationDiff: type: - array - 'null' items: $ref: '#/components/schemas/DiffEntry' description: Proposed → approved changes. appliedRevisionNo: type: - integer - 'null' description: Revision created on approval. isStale: type: boolean description: The live revision changed since the base; any edit rebases it. decisionReason: type: - string - 'null' description: Reason given by AllRide. submittedBy: oneOf: - $ref: '#/components/schemas/Actor' - type: 'null' description: Who submitted. reviewedBy: oneOf: - $ref: '#/components/schemas/Actor' - type: 'null' description: Reviewer (AllRide). submittedAt: oneOf: - $ref: '#/components/schemas/Instant' - type: 'null' description: Submission time. reviewedAt: oneOf: - $ref: '#/components/schemas/Instant' - type: 'null' description: Decision time. createdAt: $ref: '#/components/schemas/Instant' description: Creation time. updatedAt: $ref: '#/components/schemas/Instant' description: Last change. _links: type: object description: Links to related resources (self, subject, appliedRevision). additionalProperties: $ref: '#/components/schemas/Link' required: - id - resource - partnerId - subjectType - subjectId - kind - origin - status - baseRevisionNo - proposedContent - diff - changedFields - warnings - providerNote - approvedContent - modifiedByAdmin - modificationDiff - appliedRevisionNo - isStale - decisionReason - submittedBy - reviewedBy - submittedAt - reviewedAt - createdAt - updatedAt - _links description: A proposed change of consumer-visible content that AllRide reviews. additionalProperties: false ErrorEntry: type: object properties: message: type: string description: >- Human-readable message. Do not parse it; it can change. For 5xx errors it is always the generic `Something went wrong on our side`. statusCode: type: integer description: The HTTP status. errorCode: type: string description: >- Stable kebab-case error code, listed in the error catalog. Branch on this field. requestId: type: string description: >- 5xx only: the request id (also in the `X-Request-Id` header). Quote it when you contact support. more: type: object additionalProperties: true description: >- Additional details for some codes, for example `validationErrors` (array of `ValidationError`) or `requiredPermissions`. The members per code are listed in the error catalog. properties: validationErrors: type: array items: $ref: '#/components/schemas/ValidationError' description: Invalid properties or parameters. required: - message - statusCode - errorCode description: One error. Branch on `errorCode`; ignore members you do not know. DiffEntry: type: object properties: path: type: string description: JSON Pointer of the changed field. before: description: Value before. after: description: Value after. required: - path - before - after description: One changed field. additionalProperties: false ContentWarning: type: object properties: code: type: string description: Warning code, for example insufficient-contrast. pointer: type: string description: JSON Pointer into proposedContent. required: - code - pointer description: A non-blocking validation warning. additionalProperties: false Actor: type: object properties: type: type: string enum: - admin-user - partner-user - api-key - redemption-session - system description: 'Kind of actor. Treat as an open set: new values may be added.' id: oneOf: - $ref: '#/components/schemas/ULong' - type: 'null' description: Id of the user or API key; null for AllRide staff. label: type: string description: >- Display snapshot: email or key name; AllRide staff appear as "AllRide". required: - type - id - label description: Who did something. additionalProperties: false Instant: type: string format: date-time description: >- RFC 3339 timestamp in UTC with Z, at millisecond precision; no fraction when the milliseconds are zero. Inputs need an offset. example: '2026-11-01T00:00:00Z' Link: type: object properties: href: type: string description: Absolute URL. format: uri type: type: string description: Media type of the target. required: - href - type description: A link to a related resource. additionalProperties: false ValidationError: type: object properties: property: type: string description: >- Path of the offending property in your request body (`vouchers[17].value`), or the name of the query parameter, path parameter or header. constraint: type: string description: >- The violated rule as a kebab-case item code, for example `required`, `too-long`, `invalid-id`, `unknown-field`. See the validation item codes in the error catalog. params: type: object additionalProperties: true description: >- Parameters of the violated constraint, for example `{"max": 120}` for `too-long`; absent when the constraint has none. value: type: - number - boolean description: >- The rejected value, only when it is a number or boolean. Strings are never echoed, so secrets, voucher values and personal data never come back in an error. message: type: object description: Explanation per locale. properties: en: type: string description: English message. de: type: string description: German message. required: - en additionalProperties: false required: - property - constraint - message description: >- One invalid property or parameter of a `data-failed-validation` error (also used for item failures of batch operations and content checks). parameters: IdempotencyKey: name: Idempotency-Key in: header required: false description: >- Optional on every POST: 1-255 printable ASCII characters without spaces (a UUID is recommended). The same key with the same request replays the stored response for 24 hours. See [Idempotency](/guides/idempotency). schema: type: string minLength: 1 maxLength: 255 pattern: ^[\x21-\x7E]{1,255}$ example: 4e1c7f6a-2b0d-4c1e-9a7b-3f5e8d2c1b0a headers: XRequestId: description: >- Request id: your X-Request-Id (1-100 characters of [A-Za-z0-9._:-]) or a generated UUID. schema: type: string IdempotentReplayed: description: >- true when this response is a replay of a stored response for the same Idempotency-Key. schema: type: boolean RetryAfter: description: Seconds to wait before the next request or poll. schema: type: integer example: 2 responses: BadRequestPost: description: >- Bad request: `data-failed-validation`, `malformed-json`, `invalid-header`, `invalid-idempotency-key`. x-error-codes: - data-failed-validation - malformed-json - invalid-header - invalid-idempotency-key headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: data-failed-validation: summary: Data failed validation value: errors: - message: Data failed validation statusCode: 400 errorCode: data-failed-validation more: validationErrors: - property: internalName constraint: too-long params: max: 120 message: en: Must be at most 120 characters. de: Darf höchstens 120 Zeichen lang sein. - property: content.linkTemplate constraint: invalid-link-template message: en: >- Placeholders are allowed only in the path, query or fragment. de: >- Platzhalter sind nur im Pfad, in der Query oder im Fragment erlaubt. malformed-json: summary: Malformed JSON value: errors: - message: The body is not valid UTF-8 JSON. statusCode: 400 errorCode: malformed-json invalid-header: summary: Invalid header value: errors: - message: >- A standard or platform header is malformed; more.validationErrors[].property names the header. statusCode: 400 errorCode: invalid-header invalid-idempotency-key: summary: Invalid Idempotency-Key value: errors: - message: >- The Idempotency-Key header is not 1-255 printable ASCII characters without spaces. statusCode: 400 errorCode: invalid-idempotency-key Unauthorized: description: >- Unauthorized: `unauthenticated`, `token-invalid`, `api-key-invalid`, `token-expired`, `session-revoked`. x-error-codes: - unauthenticated - token-invalid - api-key-invalid - token-expired - session-revoked headers: X-Request-Id: $ref: '#/components/headers/XRequestId' WWW-Authenticate: description: >- Bearer realm="voucher" (plus error="invalid_token" when a credential was sent). schema: type: string content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: unauthenticated: summary: Authentication required value: errors: - message: No credential was sent with the request. statusCode: 401 errorCode: unauthenticated token-invalid: summary: Invalid credential value: errors: - message: >- The credential cannot be verified for this surface, has an unknown scheme, or two Authorization headers were sent. statusCode: 401 errorCode: token-invalid api-key-invalid: summary: Invalid API key value: errors: - message: >- The API key is unknown, revoked, expired, or belongs to the other environment (a vk_test_ key against production or a vk_live_ key against the sandbox). statusCode: 401 errorCode: api-key-invalid token-expired: summary: Credential expired value: errors: - message: The dashboard user's ID token has expired. statusCode: 401 errorCode: token-expired session-revoked: summary: Session revoked value: errors: - message: The dashboard user's session was revoked. statusCode: 401 errorCode: session-revoked Forbidden: description: >- Forbidden: `missing-permission`, `partner-role-missing`, `partner-suspended`, `partner-offboarded`, `api-access-inactive`, `ip-not-allowed`, `mfa-required`, `sso-required`. x-error-codes: - missing-permission - partner-role-missing - partner-suspended - partner-offboarded - api-access-inactive - ip-not-allowed - mfa-required - sso-required headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missing-permission: summary: Missing permission value: errors: - message: >- The membership or API key lacks a permission the operation requires; more.requiredPermissions lists them. API keys always get this code on dashboard-only operations. statusCode: 403 errorCode: missing-permission more: requiredPermissions: - manage-provider-voucher-sets partner-role-missing: summary: Partner role missing value: errors: - message: >- The partner lacks the role this surface needs (more.requiredRole names it), for example a consumer-only partner on /provider/v1. statusCode: 403 errorCode: partner-role-missing more: requiredRole: provider partner-suspended: summary: Partner suspended value: errors: - message: The partner is suspended; only reads are allowed. statusCode: 403 errorCode: partner-suspended partner-offboarded: summary: Partner offboarded value: errors: - message: The partner has been offboarded. statusCode: 403 errorCode: partner-offboarded api-access-inactive: summary: API access inactive value: errors: - message: >- API access of the partner is not active, or the partner is not active. API keys work only while both are active; the same code answers key and webhook operations that need active API access. statusCode: 403 errorCode: api-access-inactive ip-not-allowed: summary: IP address not allowed value: errors: - message: >- The request came from an address outside the partner's IP allowlist while enforcement is on. statusCode: 403 errorCode: ip-not-allowed mfa-required: summary: Multi-factor authentication required value: errors: - message: >- The partner requires multi-factor authentication and the session has not satisfied it. statusCode: 403 errorCode: mfa-required sso-required: summary: Single sign-on required value: errors: - message: >- The partner enforces single sign-on for the user's email domain. statusCode: 403 errorCode: sso-required InternalError: description: 'Internal error: `internal-error`.' x-error-codes: - internal-error headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal-error: summary: Internal error value: errors: - message: Something went wrong on our side statusCode: 500 errorCode: internal-error requestId: 0b6f3c1e-9d5a-4c43-a2a8-1f3d2b7c9e10 ServiceUnavailable: description: >- Service unavailable: `service-unavailable`, `db-unavailable`, `query-timeout`. x-error-codes: - service-unavailable - db-unavailable - query-timeout headers: X-Request-Id: $ref: '#/components/headers/XRequestId' Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: service-unavailable: summary: Service unavailable value: errors: - message: Something went wrong on our side statusCode: 503 errorCode: service-unavailable requestId: 0b6f3c1e-9d5a-4c43-a2a8-1f3d2b7c9e10 db-unavailable: summary: Database unavailable value: errors: - message: Something went wrong on our side statusCode: 503 errorCode: db-unavailable requestId: 0b6f3c1e-9d5a-4c43-a2a8-1f3d2b7c9e10 query-timeout: summary: Query timeout value: errors: - message: Something went wrong on our side statusCode: 503 errorCode: query-timeout requestId: 0b6f3c1e-9d5a-4c43-a2a8-1f3d2b7c9e10 securitySchemes: apiKey: type: http scheme: bearer bearerFormat: vk_live__ description: >- Partner API key: `Authorization: Bearer vk_live_…`. Use `vk_test_…` keys against the sandbox. See [Authentication](/guides/authentication). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.