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

# Download an invoice document

> Returns a 15-minute signed URL for the invoice PDF or XML, with its SHA-256 and size. Use `format=xml` for machine processing. While the document is still rendering, the answer is 409 `invoice-document-not-ready` with `Retry-After: 30`. See [E-invoices](/consumer/billing#e-invoices-zugferd-xrechnung).

**Required permissions:** `view-consumer-billing` · **API keys:** allowed



## OpenAPI

````yaml /openapi/consumer.v1.json get /consumer/v1/billing/invoices/{invoiceId}/document
openapi: 3.1.1
info:
  title: AllRide Voucher Consumer API
  version: 1.0.0
  description: >-
    The Consumer API (`/consumer/v1`) and the shared Workspace API
    (`/partner/v1`) of the AllRide Voucher Platform for Partner Consumers:
    browse your catalog, redeem vouchers, manage redemption entities and
    Redemption Links, configure email OTP, read analytics and billing, and
    administer your workspace. Start with the
    [quickstart](https://docs-consumer.voucher.allride.io/quickstart). This
    document lists the sandbox server; production uses
    `https://api.voucher.allride.io`.
  contact:
    name: AllRide
    url: https://allride.io
servers:
  - url: https://api.voucher-staging.allride.io
    description: Sandbox
security:
  - apiKey: []
tags:
  - name: Catalog
    description: >-
      Browse the providers, voucher sets and categories AllRide makes available
      to you.
  - name: Catalog settings
    description: >-
      Turn providers and voucher sets on or off for your channels and keep your
      own settings and references.
  - name: Redemptions
    description: >-
      Redeem vouchers (single or batch), read issued codes and links, and void
      redemptions.
  - name: Redemption entities
    description: Your end customers or accounts, identified by your own opaque `refId`.
  - name: Redemption links
    description: >-
      Shareable links that let an end customer redeem on an AllRide-hosted
      landing page.
  - name: Email (SMTP and templates)
    description: >-
      Email OTP Gate settings, your SMTP configuration and the OTP email
      templates.
  - name: Analytics
    description: Redemption, entity and link statistics in your partner time zone.
  - name: Billing
    description: >-
      Billing account, contacts, payment methods, invoices (including
      Stornorechnungen), payments, usage and balance.
  - name: Pricing
    description: Your resolved Price Terms per voucher set and your Price Acceptances.
  - name: Partner
    description: >-
      Your partner record, settings, principal introspection, API access and the
      developer reference.
  - name: Members
    description: Users of your partner and their invitations.
  - name: Groups
    description: Groups, their permissions and the permission catalog.
  - name: API keys
    description: API keys of your partner (dashboard only).
  - name: Webhook endpoints
    description: Webhook endpoints, their secrets and the event types you can subscribe to.
  - name: Webhook deliveries
    description: The webhook delivery log and replays.
  - name: IP allowlist
    description: Source address ranges allowed to call the API.
  - name: Custom domains
    description: Your own host names for Redemption Link landing pages.
  - name: Workspace branding
    description: Workspace Branding (dashboards and landing pages) and brand assets.
  - name: Single sign-on
    description: SAML and OIDC connections for your users.
  - name: Audit log
    description: Every change made in your partner, by whom and when.
paths:
  /consumer/v1/billing/invoices/{invoiceId}/document:
    get:
      tags:
        - Billing
      summary: Download an invoice document
      description: >-
        Returns a 15-minute signed URL for the invoice PDF or XML, with its
        SHA-256 and size. Use `format=xml` for machine processing. While the
        document is still rendering, the answer is 409
        `invoice-document-not-ready` with `Retry-After: 30`. See
        [E-invoices](/consumer/billing#e-invoices-zugferd-xrechnung).


        **Required permissions:** `view-consumer-billing` · **API keys:**
        allowed
      operationId: consumer.billing-invoices.document
      parameters:
        - name: invoiceId
          in: path
          required: true
          description: Id of the invoice.
          schema:
            $ref: '#/components/schemas/ULong'
        - name: format
          in: query
          required: false
          description: >-
            `pdf` (default; for ZUGFeRD a PDF/A-3 with embedded XML) or `xml`
            (the EN 16931 CII XML separately; for XRechnung the legal original).
          schema:
            type: string
            enum:
              - pdf
              - xml
            default: pdf
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            Idempotency-Key-Ignored:
              $ref: '#/components/headers/IdempotencyKeyIgnored'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingDocumentDownloadResponse'
              examples:
                default:
                  summary: OK
                  value:
                    data:
                      resource: document-download
                      format: xml
                      url: >-
                        https://storage.googleapis.com/allride-voucher-billing/VP-R-2026-000042.xml?X-Goog-Signature=example
                      expiresAt: '2026-11-02T08:20:00Z'
                      sha256: >-
                        9f2c1b7e4d3a5c6b8e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d
                      sizeBytes: 48211
                      fileName: VP-R-2026-000042.xml
        '400':
          description: Bad Request
          x-error-codes:
            - data-failed-validation
          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: >-
                          One or more properties or parameters are invalid; each
                          is listed in `more.validationErrors` with its property
                          path and violated constraint. Unknown properties and
                          query parameters are refused as well.
                        statusCode: 400
                        errorCode: data-failed-validation
                        more:
                          validationErrors:
                            - property: name
                              constraint: required
                              message:
                                en: This property is required.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Not found.
          x-error-codes:
            - route-not-found
            - invoice-not-found
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                route-not-found:
                  summary: Route not found
                  value:
                    errors:
                      - message: No operation exists for this path.
                        statusCode: 404
                        errorCode: route-not-found
                invoice-not-found:
                  summary: Invoice not found
                  value:
                    errors:
                      - message: >-
                          No finalised invoice with this id exists on your
                          billing account (drafts are not visible).
                        statusCode: 404
                        errorCode: invoice-not-found
        '409':
          description: Conflict
          x-error-codes:
            - invoice-document-not-ready
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invoice-document-not-ready:
                  summary: Invoice document not ready
                  value:
                    errors:
                      - message: >-
                          The PDF or XML document of this invoice is still being
                          rendered.
                        statusCode: 409
                        errorCode: invoice-document-not-ready
        '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 (ids and large counters). May exceed 2^53; parse
        with a BigInt-safe JSON parser in JavaScript.
    BillingDocumentDownloadResponse:
      type: object
      description: Single-object envelope around a `BillingDocumentDownload`.
      properties:
        data:
          $ref: '#/components/schemas/BillingDocumentDownload'
      required:
        - data
      additionalProperties: false
    ErrorResponse:
      type: object
      description: >-
        Error body of every 4xx and 5xx response (`Content-Type:
        application/json`).
      properties:
        errors:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/ErrorEntry'
          description: The errors; in v1 always exactly one.
      required:
        - errors
      additionalProperties: false
    BillingDocumentDownload:
      type: object
      description: >-
        A short-lived download of an invoice document (also of a
        Stornorechnung).
      properties:
        resource:
          type: string
          enum:
            - document-download
          description: Always `document-download`.
        format:
          type: string
          enum:
            - pdf
            - xml
          description: 'Document format. Treat as an open set: new values may be added.'
        url:
          type: string
          format: uri
          description: >-
            Signed download URL, valid for 15 minutes. Download immediately; do
            not store it.
        expiresAt:
          $ref: '#/components/schemas/Instant'
          description: When the URL expires.
        sha256:
          type: string
          pattern: ^[0-9a-f]{64}$
          description: Lower-case hex SHA-256 of the file; verify it after download.
        sizeBytes:
          type: integer
          minimum: 0
          description: File size in bytes.
        fileName:
          type: string
          description: Suggested file name.
      required:
        - resource
        - format
        - url
        - expiresAt
        - sha256
        - sizeBytes
        - fileName
      additionalProperties: false
    ErrorEntry:
      type: object
      description: One error. Branch on `errorCode`; ignore members you do not know.
      properties:
        message:
          type: string
          description: >-
            Human-readable message. 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.
        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
      additionalProperties: true
    Instant:
      type: string
      format: date-time
      description: >-
        RFC 3339 timestamp in UTC with `Z`, millisecond precision, truncated: no
        fraction when the milliseconds are zero (`2026-11-01T00:00:00Z`),
        otherwise exactly three digits (`2026-10-21T17:42:10.120Z`). Inputs must
        carry an offset and are normalised to UTC.
      example: '2026-11-01T00:00:00Z'
    ValidationError:
      type: object
      description: >-
        One invalid property or parameter of a `data-failed-validation` error
        (also used for item failures of batch operations and content checks).
      properties:
        property:
          type: string
          description: >-
            Path of the offending property in your request body
            (`items[2].quantity`), 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 constraint, for example `min` and `max` for
            `invalid-page` or `allowed` for `invalid-sort`.
        value:
          description: The rejected value, when it is safe to return.
        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
      additionalProperties: true
  headers:
    XRequestId:
      description: Request id (yours if you sent a valid `X-Request-Id`, else generated).
      schema:
        type: string
    IdempotencyKeyIgnored:
      description: '`true` when you sent `Idempotency-Key` on a method that ignores it.'
      schema:
        type: string
        enum:
          - 'true'
    RetryAfter:
      description: Seconds to wait before retrying or polling.
      schema:
        type: integer
  responses:
    Unauthorized:
      description: 'Unauthorized: the credential is missing or invalid.'
      x-error-codes:
        - unauthenticated
        - token-invalid
        - token-expired
        - api-key-invalid
      headers:
        X-Request-Id:
          $ref: '#/components/headers/XRequestId'
      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 (wrong
                      scheme, signature or credential kind).
                    statusCode: 401
                    errorCode: token-invalid
            token-expired:
              summary: Credential expired
              value:
                errors:
                  - message: The dashboard ID token has expired.
                    statusCode: 401
                    errorCode: token-expired
            api-key-invalid:
              summary: Invalid API key
              value:
                errors:
                  - message: >-
                      The API key is unknown, revoked, expired, past its roll
                      grace period or belongs to the other environment
                      (`vk_test_` against production or `vk_live_` against the
                      sandbox).
                    statusCode: 401
                    errorCode: api-key-invalid
    Forbidden:
      description: 'Forbidden: an access gate refused the request.'
      x-error-codes:
        - partner-role-missing
        - partner-suspended
        - partner-offboarded
        - api-access-inactive
        - ip-not-allowed
        - mfa-required
        - sso-required
        - missing-permission
        - reauthentication-required
      headers:
        X-Request-Id:
          $ref: '#/components/headers/XRequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            partner-role-missing:
              summary: Partner role missing
              value:
                errors:
                  - message: >-
                      Your partner lacks the role (provider or consumer) this
                      surface needs.
                    statusCode: 403
                    errorCode: partner-role-missing
                    more:
                      requiredRole: consumer
            partner-suspended:
              summary: Partner suspended
              value:
                errors:
                  - message: >-
                      Your partner is suspended: writes are refused (billing
                      writes from the dashboard excepted).
                    statusCode: 403
                    errorCode: partner-suspended
            partner-offboarded:
              summary: Partner offboarded
              value:
                errors:
                  - message: Your partner has been offboarded; every route is refused.
                    statusCode: 403
                    errorCode: partner-offboarded
            api-access-inactive:
              summary: API access inactive
              value:
                errors:
                  - message: >-
                      API access of your partner is not active (not yet granted,
                      revoked, or the partner is suspended), so API keys are
                      refused.
                    statusCode: 403
                    errorCode: api-access-inactive
            ip-not-allowed:
              summary: IP address not allowed
              value:
                errors:
                  - message: >-
                      The request's source address is not in your IP allowlist
                      while enforcement is on.
                    statusCode: 403
                    errorCode: ip-not-allowed
            mfa-required:
              summary: Multi-factor authentication required
              value:
                errors:
                  - message: >-
                      Your partner requires multi-factor authentication for
                      dashboard users.
                    statusCode: 403
                    errorCode: mfa-required
            sso-required:
              summary: Single sign-on required
              value:
                errors:
                  - message: >-
                      Your partner enforces single sign-on for this user's email
                      domain.
                    statusCode: 403
                    errorCode: sso-required
            missing-permission:
              summary: Missing permission
              value:
                errors:
                  - message: >-
                      The membership or API key lacks a permission the operation
                      requires, including non-delegable permissions called with
                      an API key.
                    statusCode: 403
                    errorCode: missing-permission
                    more:
                      requiredPermissions:
                        - create-consumer-redemptions
            reauthentication-required:
              summary: Recent sign-in required
              value:
                errors:
                  - message: >-
                      The operation needs a sign-in within the last 15 minutes
                      (dashboard users only).
                    statusCode: 403
                    errorCode: reauthentication-required
    InternalError:
      description: Unexpected failure; quote the `requestId`.
      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: 0c9f2ea5-fe09-463c-8f96-b6cae67800ad
    ServiceUnavailable:
      description: Temporarily unavailable; retry after `Retry-After`.
      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: 0c9f2ea5-fe09-463c-8f96-b6cae67800ad
            db-unavailable:
              summary: Database unavailable
              value:
                errors:
                  - message: Something went wrong on our side
                    statusCode: 503
                    errorCode: db-unavailable
                    requestId: 0c9f2ea5-fe09-463c-8f96-b6cae67800ad
            query-timeout:
              summary: Query timeout
              value:
                errors:
                  - message: Something went wrong on our side
                    statusCode: 503
                    errorCode: query-timeout
                    requestId: 0c9f2ea5-fe09-463c-8f96-b6cae67800ad
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: vk_live_<keyId>_<secret>
      description: >-
        Your API key in `Authorization: Bearer <key>`. Use `vk_test_…` keys
        against the sandbox and `vk_live_…` keys against production.

````

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