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

# Edit QR Code

> Changes a QR code created with `POST /v1/qr`, or any link's QR code. Send `url_id` and only what changes: omitted fields, also inside `content` and `design`, keep their value. `PATCH` behaves the same.

Change a QR code: its design, its logo, its content, its PDF, or the settings of its link. It works with QR codes created by [Create QR Code](https://shortpen.com/docs/api-reference/endpoint/create-qr.md) and with the QR of any link. `PUT` and `PATCH` behave the same.

### How it works

Send `url_id` and only what changes. Everything you leave out keeps its value, also inside `content` and `design`: `{"design": {"frame_layout": "balloon"}}` changes the frame and keeps colors, pattern and eyes.

* **Design and logo**: the keys you send go on top of the current design. Without `logo` the current logo stays. A `qr_template_id` restarts from that template.
* **Static types**: the `content` fields you send replace those fields only.
* **PDF**: a new `pdf_data` replaces the file (and `pdf_name` names the new one). The old file is deleted.
* **Link settings**: `url`, `domain_id`, `custom_slug` and the other link fields work as in [Edit Link](https://shortpen.com/docs/api-reference/endpoint/edit-link.md).
* The type of a QR code cannot change, and a QR code never moves to another workspace.

### Request body

| Field | Type | Required | Description |
| - | - | - | - |
| `url_id` | integer | ✅ | `data.id` of the creation, or the `id` of a link from [List Links](https://shortpen.com/docs/api-reference/endpoint/list-links.md). |
| `design` | object | | Design keys to change. Values and Free plan limits as in [Create QR Code](https://shortpen.com/docs/api-reference/endpoint/create-qr.md#design). |
| `logo` | enum(`none`, `organization`, `upload`) | | New logo. |
| `logo_data` | base64 string | | New uploaded logo, PNG, JPEG or SVG, 2 MB at most. |
| `qr_template_id` | integer | | Restart from one of your QR templates. Paid plans only. |
| `content` | object | | Static types: fields to change, see [Content fields](https://shortpen.com/docs/api-reference/endpoint/create-qr.md#content-fields). |
| `pdf_data`, `pdf_name` | string | | `pdf`: a new file and its name. |
| `type` | string | | Optional check: when sent it must be the current type. |
| Link fields | | | `link` and `pdf`: `url` (`link` only), `domain_id`, `title`, `notes`, `custom_slug`, `folder_id`, `tag_ids`, `param`, `redirect_type`, `with_password`, `url_password`. |

On a Free plan an edit can keep a paid style the QR code already has (for example after a downgrade), but it cannot add a new one.

### Response

The same as [Create QR Code](https://shortpen.com/docs/api-reference/endpoint/create-qr.md#response), with `data.created` set to `false`.

### Errors

As in [Create QR Code](https://shortpen.com/docs/api-reference/endpoint/create-qr.md#errors), plus `400` when only `url_id` is sent, `404` when the QR code is not in your organization, and `422` when `type` is not the current one.


## OpenAPI

````yaml PUT /v1/qr
openapi: 3.1.0
info:
  title: ShortPen API
  version: 1.0.0
  description: >-
    Create branded links, fetch organization resources, and pull analytics
    programmatically with the ShortPen REST API.
servers:
  - url: https://{environment}.shortpen.com
    description: ShortPen API host
    variables:
      environment:
        default: api
        enum:
          - api
          - staging-api
security: []
tags:
  - name: Core
    description: Utility endpoints for checking service health.
  - name: Authentication
    description: Endpoints that return identity, limits, and feature availability.
  - name: Links
    description: Create, edit, and list links and their auxiliary assets like QR codes.
  - name: QR Codes
    description: >-
      Create and edit QR codes: the QR of a short link, of a PDF, or a static
      one (Text, Wi-Fi, vCard...), with every style of the QR designer.
  - name: Resources
    description: >-
      Lookup supporting entities such as domains, workspaces, folders, and
      pixels.
  - name: Analytics
    description: Retrieve click analytics and raw tracking events.
paths:
  /v1/qr:
    put:
      tags:
        - QR Codes
      summary: Edit a QR code
      description: >-
        Changes a QR code created with `POST /v1/qr`, or any link's QR code.
        Send `url_id` and only what changes: omitted fields, also inside
        `content` and `design`, keep their value. `PATCH` behaves the same.
      operationId: editQr
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateQrRequest'
            examples:
              design:
                summary: Change the frame
                value:
                  url_id: 9012
                  design:
                    frame_layout: balloon
                    frame_text: MENU
              content:
                summary: Change a Wi-Fi password
                value:
                  url_id: 9013
                  content:
                    password: n3w-pass
              pdf:
                summary: Replace the PDF
                value:
                  url_id: 9014
                  pdf_name: Menu winter.pdf
                  pdf_data: JVBERi0xLjQKJ...
      responses:
        '200':
          description: QR code updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QrResponse'
        '400':
          description: Nothing to change (edit only)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: >-
            A paid option or a QR template on a Free plan (`data.paid_options`
            lists the design keys), or phone verification required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: QR code or QR template not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: The custom slug is already taken
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: >-
            Validation error: `message` says what to fix, `data.errors` lists
            the fields
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Monthly QR code or link limit reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Unexpected error, retry
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - bearerAuth: []
components:
  schemas:
    UpdateQrRequest:
      type: object
      description: >-
        Only `url_id` is required, plus at least one field to change. Omitted
        fields keep their value, also inside `content` and `design`. The type
        cannot change.
      properties:
        url_id:
          type: integer
          description: ID of the QR code (`data.id` of the creation).
          example: 9012
        type:
          type: string
          enum:
            - link
            - pdf
            - text
            - wifi
            - vcard
            - mecard
            - location
            - bitcoin
            - email
            - phone
            - sms
            - whatsapp
          description: 'Optional: when sent it must be the current type.'
        content:
          $ref: '#/components/schemas/QrContent'
        url:
          type: string
          maxLength: 2048
          description: '`link` only: destination URL. Required on creation.'
          example: https://example.com/menu
        domain_id:
          type: integer
          description: >-
            `link` and `pdf`: domain that hosts the short link. Required on
            creation.
          example: 1
        pdf_data:
          type: string
          description: >-
            `pdf` only: the PDF file, base64-encoded (a
            `data:application/pdf;base64,` prefix is accepted). 20 MB at most.
            Required on creation; on edit it replaces the file.
        pdf_name:
          type: string
          maxLength: 200
          description: >-
            `pdf` only: file name used for the download, with `pdf_data`.
            Defaults to `document.pdf`.
          example: Menu.pdf
        design:
          $ref: '#/components/schemas/QrDesign'
        logo:
          type: string
          enum:
            - none
            - organization
            - upload
          description: >-
            Logo in the center of the code: none, the organization logo, or the
            image in `logo_data`. Omitted: the template's logo, else the QR's
            current one (edit), else none.
        logo_data:
          type: string
          description: >-
            PNG, JPEG or SVG image, base64-encoded (a data URI is accepted), 2
            MB at most. Sending it implies `logo: "upload"`.
        qr_template_id:
          type: integer
          description: >-
            QR template of the organization used as the starting design and
            logo; `design` and `logo` override it. Paid plans only.
          example: 7
        title:
          type: string
          maxLength: 256
          description: >-
            `link` and `pdf`: title in your lists. A PDF without one gets the
            file name. Static types get a title from their content.
        notes:
          type: string
          maxLength: 300
          description: Private note.
        custom_slug:
          type: string
          maxLength: 64
          description: '`link` and `pdf`: branded slug instead of an auto-generated code.'
        folder_id:
          type: integer
          description: '`link` and `pdf`: folder of the link.'
        tag_ids:
          type: array
          items:
            type: integer
          description: >-
            `link` and `pdf`: tags of the link (same rules as the link
            endpoints).
        param:
          type: object
          additionalProperties:
            type: string
          description: >-
            `link` only: query parameters added to the destination URL (for
            example UTM tags).
        redirect_type:
          type: integer
          enum:
            - 301
            - 302
          description: '`link` and `pdf`: redirect status.'
        with_password:
          type: boolean
          description: '`link` and `pdf`: protects the link with `url_password`.'
        url_password:
          type: string
          description: Password asked before the redirect (or the download).
      required:
        - url_id
    QrResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        status_code:
          type: integer
          example: 200
        message:
          type: string
          example: ''
        data:
          $ref: '#/components/schemas/QrData'
      required:
        - success
        - status_code
        - data
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        status_code:
          type: integer
          example: 401
        message:
          type: string
          example: There was an error while processing your request.
        data:
          description: Optional payload returned for additional context.
          nullable: true
      required:
        - success
        - status_code
        - message
    QrContent:
      description: >-
        Fields of a static QR code, by `type`. Required on creation; on edit
        send only the fields to change.
      oneOf:
        - type: object
          title: text
          properties:
            text:
              type: string
              maxLength: 500
              description: Any text.
          required:
            - text
          example:
            text: Welcome to the office!
        - type: object
          title: wifi
          properties:
            ssid:
              type: string
              maxLength: 32
              description: Network name.
            password:
              type: string
              maxLength: 63
              description: Required unless `encryption` is `nopass`.
            encryption:
              type: string
              enum:
                - WPA
                - WEP
                - nopass
              default: WPA
            hidden:
              type: boolean
              description: Hidden network.
          required:
            - ssid
          example:
            ssid: Office
            password: s3cret-pass
            encryption: WPA
        - type: object
          title: vcard
          properties:
            first_name:
              type: string
              maxLength: 64
              description: First name.
            last_name:
              type: string
              maxLength: 64
              description: Last name.
            organization:
              type: string
              maxLength: 100
              description: Company.
            title:
              type: string
              maxLength: 100
              description: Job title.
            email:
              type: string
              maxLength: 254
              description: A valid email address.
            phone:
              type: string
              maxLength: 32
              description: Phone number.
            url:
              type: string
              maxLength: 2048
              description: Website, starting with http:// or https://.
          required:
            - first_name
          example:
            first_name: Ada
            last_name: Lovelace
            email: ada@example.com
        - type: object
          title: mecard
          properties:
            first_name:
              type: string
              maxLength: 64
              description: First name.
            last_name:
              type: string
              maxLength: 64
              description: Last name.
            phone:
              type: string
              maxLength: 32
              description: Phone number.
            email:
              type: string
              maxLength: 254
              description: A valid email address.
            url:
              type: string
              maxLength: 2048
              description: Website, starting with http:// or https://.
            address:
              type: string
              maxLength: 200
              description: Postal address.
          required:
            - first_name
          example:
            first_name: Ada
            phone: +44 20 7946 0000
        - type: object
          title: location
          properties:
            latitude:
              type: string
              maxLength: 20
              description: Between -90 and 90. A decimal comma is read as a dot.
            longitude:
              type: string
              maxLength: 20
              description: Between -180 and 180.
          required:
            - latitude
            - longitude
          example:
            latitude: '45.4642'
            longitude: '9.1900'
        - type: object
          title: bitcoin
          properties:
            address:
              type: string
              maxLength: 100
              description: Wallet address.
            amount:
              type: string
              maxLength: 20
              description: Amount in BTC, greater than 0.
            label:
              type: string
              maxLength: 64
              description: Label shown by the wallet.
          required:
            - address
          example:
            address: bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh
            amount: '0.001'
        - type: object
          title: email
          properties:
            to:
              type: string
              maxLength: 254
              description: A valid email address.
            subject:
              type: string
              maxLength: 120
              description: Subject.
            body:
              type: string
              maxLength: 500
              description: Message.
          required:
            - to
          example:
            to: hello@example.com
            subject: Hello
        - type: object
          title: phone
          properties:
            number:
              type: string
              maxLength: 32
              description: Phone number.
          required:
            - number
          example:
            number: +39 02 1234567
        - type: object
          title: sms
          properties:
            number:
              type: string
              maxLength: 32
              description: Phone number.
            body:
              type: string
              maxLength: 160
              description: Message.
          required:
            - number
          example:
            number: +39 333 1234567
            body: Hi!
        - type: object
          title: whatsapp
          properties:
            number:
              type: string
              maxLength: 32
              description: Phone number with the country code.
            body:
              type: string
              maxLength: 500
              description: Message.
          required:
            - number
          example:
            number: +39 333 1234567
            body: Hi!
    QrDesign:
      type: object
      description: >-
        Styles of the QR code, as in the QR designer. Send only what you want to
        change: the rest comes from `qr_template_id`, else from the QR being
        edited, else from the defaults. On a Free plan only the first two values
        of `module_style`, `eye_frame_style` and `eye_ball_style`, and `none` or
        `box` for `frame_layout`, can be saved.
      additionalProperties: false
      properties:
        module_style:
          type: string
          enum:
            - square
            - dots
            - smooth
            - extra-rounded
            - vertical
            - gapped
            - classy
            - diamond
            - chamfer
          default: square
          description: 'Pattern of the modules. Free: `square`, `dots`.'
        eye_frame_style:
          type: string
          enum:
            - square
            - circle
            - rounded
            - drop
            - leaf
            - pointed
            - soft
          default: square
          description: 'Outer frame of the three corner eyes. Free: `square`, `circle`.'
        eye_ball_style:
          type: string
          enum:
            - square
            - circle
            - rounded
            - drop
            - leaf
            - star
            - diamond
            - sunburst
            - sparkle
            - octagon
          default: square
          description: 'Center of the three corner eyes. Free: `square`, `circle`.'
        frame_layout:
          type: string
          enum:
            - none
            - box
            - box-top
            - banner-bottom
            - banner-top
            - balloon
          default: none
          description: >-
            Frame with a call to action around the code: `box` is a bottom
            label, `box-top` a top label. Free: `none`, `box`.
        frame_text:
          type: string
          maxLength: 24
          default: ''
          description: Text of the frame. HTML is removed, longer text is cut.
        foreground_color:
          type: string
          pattern: ^#[0-9A-Fa-f]{6}$
          default: '#000000'
          description: Color of the modules.
        background_color:
          type: string
          default: '#FFFFFF'
          description: Background color, or `transparent`.
        eye_frame_color:
          type: string
          default: match
          description: Color of the eye frames, or `match` to follow `foreground_color`.
        eye_ball_color:
          type: string
          default: match
          description: Color of the eye centers, or `match` to follow `foreground_color`.
        frame_color:
          type: string
          pattern: ^#[0-9A-Fa-f]{6}$
          default: '#000000'
          description: Color of the frame.
        frame_text_color:
          type: string
          pattern: ^#[0-9A-Fa-f]{6}$
          default: '#FFFFFF'
          description: Color of the frame text.
      example:
        module_style: dots
        eye_frame_style: rounded
        foreground_color: '#1F4E79'
        frame_layout: box
        frame_text: SCAN ME
    QrData:
      type: object
      properties:
        id:
          type: integer
          description: ID of the QR code, the `url_id` of the edit endpoint.
          example: 9012
        type:
          type: string
          enum:
            - link
            - pdf
            - text
            - wifi
            - vcard
            - mecard
            - location
            - bitcoin
            - email
            - phone
            - sms
            - whatsapp
          example: link
        link:
          type:
            - string
            - 'null'
          description: The short link (`link`, `pdf`); `null` for static types.
          example: https://shr.pn/a1B2
        qr:
          type: string
          description: The QR code as a PNG data URI (1024 px wide).
          example: data:image/png;base64,iVBORw0KGgo...
        created:
          type: boolean
          description: '`true` on creation, `false` on edit.'
      required:
        - id
        - type
        - link
        - qr
        - created
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Personal Access Token

````

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