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

# Generate a PDF of a saved Client Report

> Creates a PDF of a saved Client Report, exactly as the report currently appears. This returns a `jobId` straight away - poll GET /clientReports/generatePDF?jobId={jobId} until `status` is "done" to get the download link. PDFs are created in turn, so allow up to 5 minutes for one to be ready. If it isn't ready yet, wait a little longer before checking again. The download link is valid for 4 hours.

A new PDF of the same report can be created once an hour: if you already created one in the last 60 minutes, that PDF is returned immediately (`status` "done") instead of creating a new one. If a PDF of the same report you requested is still being generated, that job is returned instead of starting another.

Owners and Administrators can create a PDF of any report in their organisation; other roles only of reports they created.



## OpenAPI

````yaml /api-reference/openapi.json post /clientReports/generatePDF
openapi: 3.0.1
info:
  title: MerchantSpring Public API
  version: 1.0.0
servers:
  - url: https://mm-api.merchantspring.io
    description: Production
  - url: https://mm-api-staging.merchantspring.io
    description: Staging
security: []
tags:
  - name: advertising
    x-group: Advertising
  - name: channel
    x-group: Channel
  - name: content-change
    x-group: Content Change
  - name: custom-group
    x-group: Custom Group
  - name: order
    x-group: Order
  - name: product
    x-group: Product
  - name: report
    x-group: Report
  - name: vendor
    x-group: Vendor
  - name: tag
    x-group: Tag
  - name: search-query-performance
    x-group: Search Query Performance
  - name: client-report
    x-group: Client Report
  - name: profitability
    x-group: Profitability
  - name: targets
    x-group: Targets
  - name: seller-health
    x-group: Seller Health
paths:
  /clientReports/generatePDF:
    post:
      tags:
        - client-report
      summary: Generate a PDF of a saved Client Report
      description: >-
        Creates a PDF of a saved Client Report, exactly as the report currently
        appears. This returns a `jobId` straight away - poll GET
        /clientReports/generatePDF?jobId={jobId} until `status` is "done" to get
        the download link. PDFs are created in turn, so allow up to 5 minutes
        for one to be ready. If it isn't ready yet, wait a little longer before
        checking again. The download link is valid for 4 hours.


        A new PDF of the same report can be created once an hour: if you already
        created one in the last 60 minutes, that PDF is returned immediately
        (`status` "done") instead of creating a new one. If a PDF of the same
        report you requested is still being generated, that job is returned
        instead of starting another.


        Owners and Administrators can create a PDF of any report in their
        organisation; other roles only of reports they created.
      operationId: createClientReport
      requestBody:
        description: Client Report identifier
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateClientReportRequest'
        required: true
      responses:
        '200':
          description: Successful operation
          headers:
            Access-Control-Allow-Origin:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientReportCreateResponse'
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missingReportId:
                  summary: reportId is missing from the request body, e.g. {}
                  value:
                    status: error
                    error: reportId is required
                emptyReportId:
                  summary: 'reportId is an empty string, e.g. { "reportId": "" }'
                  value:
                    status: error
                    error: reportId is required
                reportIdNotAString:
                  summary: 'reportId is not a string, e.g. { "reportId": 123 }'
                  value:
                    status: error
                    error: reportId is required
                invalidReportId:
                  summary: >-
                    reportId is not a valid report id, e.g. { "reportId": "abc"
                    }
                  value:
                    status: error
                    error: reportId must be a valid report id
        '403':
          description: >-
            A missing/invalid x-api-key, an account without the Client Reports
            entitlement, or a report the caller can't access. The x-api-key case
            has a different response shape - see examples.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ErrorResponse'
                  - $ref: '#/components/schemas/ApiGatewayForbiddenResponse'
              examples:
                accessDenied:
                  summary: The report isn't one the caller may access
                  value:
                    status: error
                    error: Access denied to this reportId
                noReportsEntitlement:
                  summary: The account doesn't have access to reports
                  value:
                    status: error
                    error: >-
                      Unauthorized: account does not have permission to access
                      this endpoint
                invalidApiKey:
                  summary: Missing or invalid x-api-key
                  value:
                    message: Forbidden
        '404':
          description: Report not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                reportNotFound:
                  summary: No report with this reportId
                  value:
                    status: error
                    error: Report not found
      security:
        - api_key: []
components:
  schemas:
    CreateClientReportRequest:
      type: object
      properties:
        reportId:
          type: string
          description: >-
            The reportId of the Client Report, as returned by the GET
            /clientReports listing endpoint
      required:
        - reportId
    ClientReportCreateResponse:
      type: object
      properties:
        reportId:
          type: string
          description: The Client Report's own ID, echoed back from the request
        jobId:
          type: string
          description: >-
            The PDF generation job's ID - use this with GET
            /clientReports/generatePDF?jobId={jobId} to poll for completion
        status:
          type: string
          enum:
            - started
            - inProgress
            - done
          description: >-
            "started" for a newly-created job. "started" / "inProgress" with an
            existing jobId if a PDF of this report you requested is still being
            generated - poll that job. "done" if you already created a PDF of
            this report within the last 60 minutes and it was returned instead
            (see downloadUrl/generatedAt)
        downloadUrl:
          type: string
          description: Only present when status is "done" (an existing PDF was reused)
        downloadUrlExpiresAt:
          type: string
          description: Only present when status is "done" - when downloadUrl stops working
        generatedAt:
          type: string
          description: >-
            Only present when status is "done" (an existing PDF was reused) -
            when that PDF was originally generated
    ErrorResponse:
      type: object
      properties:
        status:
          type: string
          enum:
            - error
        error:
          type: string
          description: >-
            Human-readable message. Validation failures list every failing rule,
            comma-separated.
      example:
        status: error
        error: Invalid request parameters
    ApiGatewayForbiddenResponse:
      type: object
      description: Returned for a missing or invalid x-api-key.
      properties:
        message:
          type: string
          enum:
            - Forbidden
      example:
        message: Forbidden
  securitySchemes:
    api_key:
      type: apiKey
      name: x-api-key
      in: header

````

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