print-one Design Previews API

openapi: 3.2.0
info:
  title: Print.one Design Previews API
  description: 'This documentation belongs to Print.one''s API. # Introduction

    This API is documented in **OpenAPI format**. In addition to standard

    OpenAPI syntax we use a few vendor extensions


    For technical information about our API, please consult our help center or request support. # Cross-Origin Resource Sharing

    This API features Cross-Origin Resource Sharing (CORS) implemented in compliance with W3C spec. And that allows cross-domain communication from the browser. All responses have a wildcard same-origin which makes them completely public and accessible to everyone, including any code on any site. # Authentication


    # Early Access

    Some features are marked as ''Early Access''. This means only a small portion of users have access to these features. We do this to conduct thorough testing before a major release. Would you like to gain access to one of our Early Access features? Please raise a >">support ticket here, specifying which feature you would like access to. # Premium Access

    Some features are marked as ''Premium''. This means this feature is only included on paid plans. Would you like to gain access to one of our Premium features? Have a look at the Subscriptions page. # API Errors

    Below is a list with all known errors returned by our API, identified by a unique `code`. These codes will also show in the error response of specific API responses. Unique code

    Error name

    Error type

    Example message


    10001

    InvalidInputData

    Combined

    Invalid input data


    10002

    OrderPropertyRequired

    Default

    The property recipient is required


    10003

    OrderCreationError

    Combined

    Could not create order


    10004

    RecipientAddressInvalid

    Default

    Recipient''s address is invalid


    10005

    AddressValidation

    Validation

    Address validation failed


    10006

    ResourceNotFound

    Default

    Campaign ''cmp_123456789'' does not exist


    10007

    BatchWrongMode

    Default

    Batch is ''live'', but received a ''live'' request


    10008

    BatchNotAcceptingOrders

    Default

    Batch ''batch_123456789'' is not in a state to accept orders


    10009

    BatchIsFull

    Default

    Batch ''batch_123456789'' is full and does not accept any more orders (max 10000 orders per batch)


    10010

    ArchivedCampaignNotAcceptingOrders

    Default

    Campaign ''My Campaign'' is archived and no longer accepts orders


    10011

    ProductFeatureNotAllowed

    Default

    The product ''GREETINGCARD_SQ15'' does not support batch


    10012

    ObjectMissingRequiredFields

    Default

    The recipient is missing required fields


    10013

    CannotRetrieveObject

    Default

    An error occurred while retrieving the design ''tmpl_123456798''


    10014

    DesignContentUnparsable

    Combined

    Could not parse the design content


    10015

    FormatPageRequirement

    Default

    The format ''POSTCARD_A5'' requires 2 pages, but 1 was provided


    10016

    DuplicateDesignPage

    Default

    Found page ''1'' multiple times in the design


    10017

    CountryNotSupported

    Default

    The country ''BE'' is not supported


    10018

    ProductDestinationNotAllowed

    Default

    The product ''GREETINGCARD_SQ15'' does not support GERMANY


    10019

    UnknownCreationError

    Default

    An unknown error occurred while creating the campaign


    10020

    UnknownPublishError

    Default

    An unknown error occurred while publishing the order


    10021

    SendDateInPast

    Default

    The send date must be in the future


    10022

    SendDateBeyondYear

    Default

    The send date must be within one year


    10023

    InstallNotAllowed

    Default

    You are not allowed to install this integration


    10024

    BatchRecipientCountryRestriction

    Default

    Only addresses shipped to ''NL'' are allowed for this batch


    10025

    PostalStampCountryUnavailable

    Default

    Postal stamp ''stmp_123456789'' is not available for the country ''BE''


    10026

    EarlyAccessRestricted

    Default

    Sorry, some-early-access-feature is in early access.'
  version: v3
  contact:
    name: Print.one
    url: https://support.print.one
    email: info@print.one
servers:
- url: https://api.print.one
tags:
- name: Design Previews
paths:
  /v3/campaigns/{campaignId}/designs/preview:
    post:
      description: Preview the default Destination Design based on recipient address
      operationId: CampaignDesignPreviews/createDesignPreview
      parameters:
      - name: campaignId
        required: true
        in: path
        description: Campaign ID
        schema:
          type: string
      - name: asImages
        required: false
        in: query
        description: Render the Design as images instead of PDF (optional, slower)
        schema:
          default: false
          type: boolean
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCampaignDesignPreviewRequestV3Dto'
      responses:
        '200':
          description: Design preview generated successfully as PDF
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/V3ResponseDto'
                - properties:
                    data:
                      type: object
                      $ref: '#/components/schemas/DesignPreviewPdfResponseV3Dto'
        '400':
          description: Recipient's address is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V3ErrorResponsefe7a005b465edac4e1cfcf89f52d19ac3c70694a29f9c202c73418a091704f01'
        '403':
          description: Your account does not have access to the early access feature 'campaign'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V3ErrorResponsebdcbee75be4f56aacf4bc663f5c734adb8c46ce1d7350353f9a97a390481a4f0'
        '404':
          description: Design template '{id}' does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V3ErrorResponsee7323fd91ea07a3d699979a4c26bfd6458130441b1ba6feaf78df6239ac6bce1'
      security:
      - API Key: []
      - Oauth2:
        - template.read
        - live.api.key
        - test.api.key
      summary: Campaign design previews/create design preview
      tags:
      - Design Previews
      x-summary-source: derived
  /v3/campaigns/{campaignId}/designs/{destination}/{designId}/{version}/preview:
    post:
      description: Preview a Design
      operationId: CampaignDesignPreviews/createDesignDestinationPreview
      parameters:
      - name: campaignId
        required: true
        in: path
        description: Campaign ID
        schema:
          type: string
      - name: destination
        required: true
        in: path
        description: Design destination
        schema:
          enum:
          - NETHERLANDS
          - GERMANY
          - INTERNATIONAL
          type: string
      - name: designId
        required: true
        in: path
        description: Design ID
        schema:
          type: string
      - name: asImages
        required: false
        in: query
        description: Render the Design as images instead of PDF (optional)
        schema:
          type: boolean
      - name: version
        required: false
        in: path
        description: Design version (optional)
        schema:
          type: number
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDesignPreviewRequestV3Dto'
      responses:
        '400':
          description: Invalid input data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V3ErrorResponse64121f1a15c13f54ced1aad7426cc04ed4a66c8892ca8e23cf43181ffc72b662'
        '403':
          description: Your account does not have access to the early access feature 'campaign'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V3ErrorResponsebdcbee75be4f56aacf4bc663f5c734adb8c46ce1d7350353f9a97a390481a4f0'
        '404':
          description: Design template '{id}' does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V3ErrorResponsee7323fd91ea07a3d699979a4c26bfd6458130441b1ba6feaf78df6239ac6bce1'
      security:
      - API Key: []
      - Oauth2:
        - template.read
        - live.api.key
        - test.api.key
      summary: Campaign design previews/create design destination preview
      tags:
      - Design Previews
      x-summary-source: derived
  /v3/campaigns/{campaignId}/designs/{destination}/{designId}/{version}/preview/{previewId}:
    get:
      description: Retrieve a Design preview
      operationId: CampaignDesignPreviews/getDesignPreview
      parameters:
      - name: previewId
        required: true
        in: path
        description: Preview ID
        schema:
          type: string
      - name: asImages
        required: false
        in: query
        description: Whether the preview was rendered as images (PNG) or PDF
        schema:
          default: false
          example: true
          type: boolean
      - name: version
        required: false
        in: path
        description: Design version (optional)
        schema:
          type: number
      - name: designId
        required: true
        in: path
        description: Design ID
        schema:
          type: string
      - name: destination
        required: true
        in: path
        description: Design destination
        schema:
          enum:
          - NETHERLANDS
          - GERMANY
          - INTERNATIONAL
          type: string
      - name: campaignId
        required: true
        in: path
        description: Campaign ID
        schema: {}
      responses:
        '200':
          content:
            application/pdf:
              schema:
                type: string
                format: binary
          description: Preview of rendered Design
          headers:
            Content-Type:
              example: application/pdf
            Content-Disposition:
              schema:
                oneOf:
                - title: Download PDF
                  description: Will download the PDF if query 'asImages=false'
                  example: attachment; filename=order-preview.pdf
                - title: Download PNG
                  description: Will download the PNG if query 'asImages=true'
                  example: attachment; filename=order-preview.png
        '403':
          description: Your account does not have access to the early access feature 'campaign'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V3ErrorResponsebdcbee75be4f56aacf4bc663f5c734adb8c46ce1d7350353f9a97a390481a4f0'
        '404':
          description: Design preview 'previewId' does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V3ErrorResponse822bae4614789387071f7305996c7b911d43a318e679dbbdc04fb162eed5c400'
      security:
      - API Key: []
      - Oauth2:
        - template.read
        - live.api.key
        - test.api.key
      summary: Campaign design previews/get design preview
      tags:
      - Design Previews
      x-summary-source: derived
  /v3/campaigns/{campaignId}/designs/{destination}/{designId}/{version}/preview/{previewId}/details:
    get:
      description: Retrieve the details of a Design preview
      operationId: CampaignDesignPreviews/getDesignPreviewDetails
      parameters:
      - name: previewId
        required: true
        in: path
        description: Preview ID
        schema:
          type: string
      - name: campaignId
        required: true
        in: path
        description: Campaign ID
        schema:
          type: string
      - name: destination
        required: true
        in: path
        description: Design destination
        schema:
          enum:
          - NETHERLANDS
          - GERMANY
          - INTERNATIONAL
          type: string
      - name: designId
        required: true
        in: path
        description: Design ID
        schema:
          type: string
      - name: asImages
        required: false
        in: query
        description: Whether the preview was rendered as images (PNG) or PDF
        schema:
          default: false
          example: true
          type: boolean
      - name: version
        required: false
        in: path
        description: Design version (optional)
        schema:
          type: number
      responses:
        '200':
          description: Details of Design preview
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/V3ResponseDto'
                - properties:
                    data:
                      type: object
                      $ref: '#/components/schemas/GetDesignPreviewDetailsPdfDto'
        '403':
          description: Your account does not have access to the early access feature 'campaign'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V3ErrorResponsebdcbee75be4f56aacf4bc663f5c734adb8c46ce1d7350353f9a97a390481a4f0'
        '404':
          description: Design preview 'previewId' does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V3ErrorResponse822bae4614789387071f7305996c7b911d43a318e679dbbdc04fb162eed5c400'
      security:
      - API Key: []
      - Oauth2:
        - template.read
        - live.api.key
        - test.api.key
      summary: Campaign design previews/get design preview details
      tags:
      - Design Previews
      x-summary-source: derived
components:
  schemas:
    V3ErrorResponsee7323fd91ea07a3d699979a4c26bfd6458130441b1ba6feaf78df6239ac6bce1:
      type: object
      properties:
        status:
          type: number
          description: HTTP status code associated with the error message
          example: 404
        message:
          type: string
          description: Message describing the error
          example: Design template '{id}' does not exist
        code:
          type: number
          description: Unique code to backtrace the type of error
          example: 10006
        uri:
          type: string
          description: The requested URL
          example: https://api.print.one/v3/some-url?filter.query=$eq:value
      required:
      - status
      - message
      - code
      - uri
    V3ValidationErrorDto:
      type: object
      properties: {}
    V3ErrorResponse822bae4614789387071f7305996c7b911d43a318e679dbbdc04fb162eed5c400:
      type: object
      properties:
        status:
          type: number
          description: HTTP status code associated with the error message
          example: 404
        message:
          type: string
          description: Message describing the error
          example: Design preview 'previewId' does not exist
        code:
          type: number
          description: Unique code to backtrace the type of error
          example: 10006
        uri:
          type: string
          description: The requested URL
          example: https://api.print.one/v3/some-url?filter.query=$eq:value
      required:
      - status
      - message
      - code
      - uri
    CreateDesignPreviewRequestV3Dto:
      type: object
      properties:
        recipient:
          description: Address information of the recipient
          allOf:
          - $ref: '#/components/schemas/AddressDto'
        mergeVariables:
          type: object
          additionalProperties:
            oneOf:
            - type: string
            - type: number
            - type: boolean
          example:
            firstName: John
            lastName: Doe
          description: Optional personalization data (can be an empty object)
    V3ErrorResponse64121f1a15c13f54ced1aad7426cc04ed4a66c8892ca8e23cf43181ffc72b662:
      type: object
      properties:
        status:
          type: number
          description: HTTP status code associated with the error message
          example: 400
        message:
          type: string
          description: Message describing the error
          example: Invalid input data
        code:
          type: number
          description: Unique code to backtrace the type of error
          example: 10001
        uri:
          type: string
          description: The requested URL
          example: https://api.print.one/v3/some-url?filter.query=$eq:value
        errors:
          description: List of errors
          example:
          - message: Version is out of bounds
            code: 10034
            field: filter.version
            error: isOutOfBounds
          type: array
          items:
            oneOf:
            - $ref: '#/components/schemas/V3ErrorDto'
            - $ref: '#/components/schemas/V3ValidationErrorDto'
      required:
      - status
      - message
      - code
      - uri
      - errors
    CreateCampaignDesignPreviewRequestV3Dto:
      type: object
      properties:
        recipient:
          description: Address information of the recipient
          allOf:
          - $ref: '#/components/schemas/AddressDto'
        mergeVariables:
          type: object
          additionalProperties:
            oneOf:
            - type: string
            - type: number
            - type: boolean
          example:
            firstName: John
            lastName: Doe
          description: Optional personalization data (can be an empty object)
      required:
      - recipient
    V3ErrorResponsefe7a005b465edac4e1cfcf89f52d19ac3c70694a29f9c202c73418a091704f01:
      type: object
      properties:
        status:
          type: number
          description: HTTP status code associated with the error message
          example: 400
        message:
          type: string
          description: Message describing the error
          example: Recipient's address is invalid
        code:
          type: number
          description: Unique code to backtrace the type of error
          example: 10004
        uri:
          type: string
          description: The requested URL
          example: https://api.print.one/v3/some-url?filter.query=$eq:value
      required:
      - status
      - message
      - code
      - uri
    GetDesignPreviewDetailsPdfDto:
      type: object
      properties:
        id:
          type: string
          description: The ID of the preview
          example: prev_zUsy4RK6bXSGrn3eqPDku
        designId:
          type: string
          description: The ID of the Design the preview was generated for
          example: tmpl_zUsy4RK6bXSGrn3eqPDku
        url:
          type: string
          description: The url of where to download the preview
          example: https://api.print.one/v3/campaigns/:campaignId/designs/:destination/:designId/preview/prev_abc123456?asImages=false
        errors:
          description: List of errors that occurred during rendering the preview
          example:
          - The resource at "https://example.com/idontexist.png" returned status code 404.
          type: array
          items:
            type: string
      required:
      - id
      - designId
      - url
    AddressDto:
      type: object
      properties:
        name:
          type: string
        address:
          type: string
        addressLine2:
          type: string
        postalCode:
          type: string
        city:
          type: string
        country:
          type: string
      required:
      - name
      - address
      - postalCode
      - city
      - country
    V3ResponseDto:
      type: object
      properties:
        data:
          type: object
      required:
      - data
    V3ErrorDto:
      type: object
      properties: {}
    DesignPreviewPdfResponseV3Dto:
      type: object
      properties:
        url:
          type: string
          description: The URL to the preview PDF
          example: https://api.print.one/v3/campaigns/:campaignId/designs/:destination/:designId/preview/prev_abc123456?asImages=false
        detailsUrl:
          type: string
          description: The URL to the details page of the Design preview
          example: https://api.print.one/v3/campaigns/:campaignId/designs/:destination/:designId/preview/prev_abc123456/details?asImages=false
        warnings:
          description: Warning messages
          example:
          - Some warning message
          type: array
          items:
            type: string
      required:
      - url
      - detailsUrl
    V3ErrorResponsebdcbee75be4f56aacf4bc663f5c734adb8c46ce1d7350353f9a97a390481a4f0:
      type: object
      properties:
        status:
          type: number
          description: HTTP status code associated with the error message
          example: 403
        message:
          type: string
          description: Message describing the error
          example: Your account does not have access to the early access feature 'campaign'
        code:
          type: number
          description: Unique code to backtrace the type of error
          example: 10037
        uri:
          type: string
          description: The requested URL
          example: https://api.print.one/v3/some-url?filter.query=$eq:value
      required:
      - status
      - message
      - code
      - uri
  securitySchemes:
    API_Key:
      type: apiKey
      in: header
      name: x-api-key
    Oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://api.print.one/v2/oauth/authorize
          refreshUrl: https://api.print.one/v2/oauth/token
          scopes:
            coupons.read: coupons.read
            coupons.write: coupons.write
            shorten.urls.read: shorten.urls.read
            shorten.urls.write: shorten.urls.write
            campaign.read: campaign.read
            campaign.write: campaign.write
            campaign.delete: campaign.delete
            company.read: company.read
            customfile.read: customfile.read
            customfile.write: customfile.write
            live.orders.read: live.orders.read
            live.orders.write: live.orders.write
            test.orders.read: test.orders.read
            test.orders.write: test.orders.write
            draft.orders.read: draft.orders.read
            draft.orders.write: draft.orders.write
            template.read: template.read
            template.write: template.write
            webhooks.read: webhooks.read
            webhooks.write: webhooks.write
            integrations.read: integrations.read
            tracking.event.read: tracking.event.read
            tracking.event.write: tracking.event.write
            live.batches.read: live.batches.read
            live.batches.write: live.batches.write
            test.batches.read: test.batches.read
            test.batches.write: test.batches.write
            tenant.admin: tenant.admin
            live.api.key: live.api.key
            test.api.key: test.api.key
          tokenUrl: https://api.print.one/v2/oauth/token
      name: Oauth2 Bearer Token