print-one Coupons API

openapi: 3.2.0
info:
  title: Print.one Coupons 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: Coupons
paths:
  /v3/coupons:
    post:
      operationId: Coupons/addCoupon
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateV3CouponRequestDto'
      responses:
        '201':
          description: Coupon was created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V3ResponseDto'
        '403':
          description: Request has invalid grant scope, missing one of (<code>own.coupons.create</code>)
      security:
      - Oauth2:
        - coupons.write
        - live.api.key
        - test.api.key
      tags:
      - Coupons
      summary: Coupons/add coupon
      x-summary-source: derived
    get:
      operationId: Coupons/getCouponsList
      parameters:
      - name: page
        required: false
        in: query
        description: "Page number to retrieve. If you provide an invalid value the default page number will be applied'\n        <p>\n             <b>Default Value: </b> 1\n          </p>\n        "
        schema:
          example: 1
          type: number
      - name: limit
        required: false
        in: query
        description: "Number of records per page.\n      <p>\n             <b>Default Value: </b> 20\n          </p>\n      <p>\n             <b>Max Value: </b> 200\n          </p>\n      <i><b>If provided value is greater than max value, max value will be applied.</b></i>\n      "
        schema:
          example: 20
          type: number
      - name: filter.name
        required: false
        in: query
        description: "Filter by name query param.\n          <p>\n             <b>Format: </b> filter.name=OPERATION:VALUE\n          </p>\n          <h4><b>Available Operations:</b></h4><ul><li>$eq</li><li>$in</li></ul>"
        schema:
          example: $eq:value
          type: string
      - name: filter.createdAt
        required: false
        in: query
        description: "Filter by createdAt query param.\n          <p>\n             <b>Format: </b> filter.createdAt=OPERATION:VALUE\n          </p>\n          <h4><b>Available Operations:</b></h4><ul><li>$gte</li><li>$gt</li><li>$btw</li><li>$lt</li><li>$lte</li></ul>"
        schema:
          example: $gte:value
          type: string
      - name: sortBy
        required: false
        in: query
        description: "Parameter to sort by.\n      <p>To sort by multiple fields, just provide query param multiple types. The order in url defines an order of sorting</p>\n      <p>\n             <b>Format: </b> fieldName:DIRECTION\n          </p>\n      <p>\n             <b>Default Value: </b> createdAt:DESC\n          </p>\n      <h4><b>Available Fields:</b></h4><ul><li>createdAt</li><li>name</li></ul>\n      "
        schema:
          example: id:DESC,createdAt:ASC
          type: array
          items:
            type: string
      responses:
        '200':
          description: Get a list of coupons
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/PaginatedDocumented'
                - properties:
                    data:
                      type: array
                      items:
                        $ref: '#/components/schemas/GetV3CouponResponseDto'
                    meta:
                      properties:
                        select:
                          type: array
                          items:
                            type: string
                        filter:
                          type: object
                          properties:
                            name:
                              oneOf:
                              - type: string
                              - type: array
                                items:
                                  type: string
                            companyId:
                              oneOf:
                              - type: string
                              - type: array
                                items:
                                  type: string
                            createdAt:
                              oneOf:
                              - type: string
                              - type: array
                                items:
                                  type: string
        '400':
          description: The provided pagination query was incorrect
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse6a1ea2613cf2c41bb65e6b9eb34bea04f7ba0c4ac3abeec93be5a78e665f2d6b'
        '403':
          description: Request has invalid grant scope, missing one of (<code>own.coupons.read</code>)
      security:
      - Oauth2:
        - coupons.read
        - live.api.key
        - test.api.key
      tags:
      - Coupons
      summary: Coupons/get coupons list
      x-summary-source: derived
  /v3/coupons/{id}:
    get:
      operationId: Coupons/getCoupon
      parameters:
      - name: id
        required: true
        in: path
        description: The ID of the coupon
        schema:
          type: string
      responses:
        '200':
          description: The coupon
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V3ResponseDto'
        '403':
          description: Request has invalid grant scope, missing one of (<code>own.coupons.read</code>)
        '404':
          description: Coupon not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse352c8d6544bab884304b2e571acb970dd2414f1f2488c0c5a84555d639eefb76'
      security:
      - Oauth2:
        - coupons.read
        - live.api.key
        - test.api.key
      tags:
      - Coupons
      summary: Coupons/get coupon
      x-summary-source: derived
    delete:
      operationId: Coupons/deleteCoupon
      parameters:
      - name: id
        required: true
        in: path
        description: The ID of the coupon
        schema:
          type: string
      responses:
        '200':
          description: Coupon was successfully deleted
        '403':
          description: Request has invalid grant scope, missing one of (<code>own.coupons.delete</code>)
        '404':
          description: Coupon 'coupon_id' does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V3ErrorResponseebea3b2f021870a22ad727abacf5f8e3b0bf981b48237f5aa5ed50edfa4fef1e'
      security:
      - Oauth2:
        - coupons.write
        - live.api.key
        - test.api.key
      tags:
      - Coupons
      summary: Coupons/delete coupon
      x-summary-source: derived
    post:
      operationId: Coupons/importCouponCodes
      parameters:
      - name: id
        required: true
        in: path
        description: The ID of the coupon
        schema:
          type: string
      responses:
        '201':
          description: The coupon codes were successfully uploaded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V3ResponseDto'
        '403':
          description: Request has invalid grant scope, missing one of (<code>own.coupons.create</code>)
        '404':
          description: Coupon 'coupon_id' does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V3ErrorResponseebea3b2f021870a22ad727abacf5f8e3b0bf981b48237f5aa5ed50edfa4fef1e'
      security:
      - Oauth2:
        - coupons.write
        - live.api.key
        - test.api.key
      tags:
      - Coupons
      summary: Coupons/import coupon codes
      x-summary-source: derived
  /v3/coupons/{id}/codes:
    get:
      operationId: Coupons/getCouponCodesList
      parameters:
      - name: id
        required: true
        in: path
        description: The ID of the coupon
        schema:
          type: string
      - name: page
        required: false
        in: query
        description: "Page number to retrieve. If you provide an invalid value the default page number will be applied'\n        <p>\n             <b>Default Value: </b> 1\n          </p>\n        "
        schema:
          example: 1
          type: number
      - name: limit
        required: false
        in: query
        description: "Number of records per page.\n      <p>\n             <b>Default Value: </b> 20\n          </p>\n      <p>\n             <b>Max Value: </b> 200\n          </p>\n      <i><b>If provided value is greater than max value, max value will be applied.</b></i>\n      "
        schema:
          example: 20
          type: number
      - name: filter.createdAt
        required: false
        in: query
        description: "Filter by createdAt query param.\n          <p>\n             <b>Format: </b> filter.createdAt=OPERATION:VALUE\n          </p>\n          <h4><b>Available Operations:</b></h4><ul><li>$gte</li><li>$gt</li><li>$btw</li><li>$lt</li><li>$lte</li></ul>"
        schema:
          example: $gte:value
          type: string
      - name: sortBy
        required: false
        in: query
        description: "Parameter to sort by.\n      <p>To sort by multiple fields, just provide query param multiple types. The order in url defines an order of sorting</p>\n      <p>\n             <b>Format: </b> fieldName:DIRECTION\n          </p>\n      <p>\n             <b>Default Value: </b> createdAt:DESC\n          </p>\n      <h4><b>Available Fields:</b></h4><ul><li>createdAt</li><li>used</li></ul>\n      "
        schema:
          example: id:DESC,createdAt:ASC
          type: array
          items:
            type: string
      - name: search
        required: false
        in: query
        description: "Search term to filter result values\n      <p>\n             <b>Default Value: </b> No default value\n          </p>\n      "
        schema:
          example: John
          type: string
      - name: searchBy
        required: false
        in: query
        description: "List of fields to search by term to filter result values\n        <p>\n             <b>Default Value: </b> By default all fields mentioned below will be used to search by term\n          </p>\n        <h4><b>Available Fields:</b></h4><ul><li>code</li></ul>\n        "
        schema:
          example: code
          type: string
      responses:
        '200':
          description: Get a list of campaign items
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/PaginatedDocumented'
                - properties:
                    data:
                      type: array
                      items:
                        $ref: '#/components/schemas/GetV3CouponCodeResponseDto'
                    meta:
                      properties:
                        select:
                          type: array
                          items:
                            type: string
                        filter:
                          type: object
                          properties:
                            createdAt:
                              oneOf:
                              - type: string
                              - type: array
                                items:
                                  type: string
                            couponId:
                              oneOf:
                              - type: string
                              - type: array
                                items:
                                  type: string
                            coupon.companyId:
                              oneOf:
                              - type: string
                              - type: array
                                items:
                                  type: string
        '400':
          description: The provided pagination query was incorrect
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse6a1ea2613cf2c41bb65e6b9eb34bea04f7ba0c4ac3abeec93be5a78e665f2d6b'
        '403':
          description: Request has invalid grant scope, missing one of (<code>own.coupons.read</code>)
        '404':
          description: Coupon 'coupon_id' does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V3ErrorResponseebea3b2f021870a22ad727abacf5f8e3b0bf981b48237f5aa5ed50edfa4fef1e'
      security:
      - Oauth2:
        - coupons.read
        - live.api.key
        - test.api.key
      tags:
      - Coupons
      summary: Coupons/get coupon codes list
      x-summary-source: derived
webhooks:
  coupon_code_used:
    post:
      tags:
      - Coupons
      parameters:
      - in: header
        name: X-Webhook-Event
        description: The event which triggered the webhook
        schema:
          type: string
          example: coupon_code_used
      - in: header
        name: X-Webhook-HMAC-SHA256
        description: Encrypted body with your webhook-secret - to verify the webhook request
        schema:
          type: string
      operationId: coupon_code_used
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/GetV3CouponCodeResponseDto'
                  description: The data sent with the webhook
                event:
                  type: string
                  description: The event which triggered the webhook
                  example: coupon_code_used
                created_at:
                  type: string
                  description: The date at which the webhook was triggered
                  example: '2024-01-01T12:00:00.000Z'
      responses:
        '200':
          description: Return a 20x status to indicate that the webhook was received successfully
        '400':
          description: Return a 40x status to indicate that the webhook could not be processed
        '500':
          description: Return a 50x status to indicate that the webhook could not be processed
      summary: Coupon code used
      x-summary-source: derived
components:
  schemas:
    V3ErrorResponseebea3b2f021870a22ad727abacf5f8e3b0bf981b48237f5aa5ed50edfa4fef1e:
      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: Coupon 'coupon_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
    PaginatedMetaDocumented:
      type: object
      properties:
        itemsPerPage:
          type: number
          title: Number of items per page
        totalItems:
          type: number
          title: Total number of items
        currentPage:
          type: number
          title: Current requested page
        totalPages:
          type: number
          title: Total number of pages
        sortBy:
          type: array
          title: Sorting by columns
          items:
            type: array
            items:
              oneOf:
              - type: string
              - type: string
                enum:
                - ASC
                - DESC
        searchBy:
          title: Search by fields
          type: array
          items:
            type: string
        search:
          type: string
          title: Search term
        filter:
          type: object
          title: Filters that applied to the query
          required: []
          properties: {}
        filterOptions:
          type: object
          title: Filters that applied to the query
          required: []
          properties: {}
      required:
      - itemsPerPage
      - totalItems
      - currentPage
      - totalPages
    CreateV3CouponRequestDto:
      type: object
      properties:
        name:
          type: string
          example: great deal
          description: Name of the Coupon
      required:
      - name
    GetV3CouponResponseDto:
      type: object
      properties:
        id:
          type: string
          example: '1234567890'
          description: Unique ID for the Coupon
        name:
          type: string
          example: great deal
          description: Name of the Coupon
        stats:
          type: object
          example:
            total: 100
            used: 50
            remaining: 50
          description: Stats of the Coupon
          properties:
            total:
              type: number
              example: 100
              description: Total number of coupons created
            used:
              type: number
              example: 50
              description: Number of coupons used
            remaining:
              type: number
              example: 50
              description: Number of coupons remaining
        createdAt:
          type: object
          description: Date when the Coupon was created
          example: '2024-01-01T00:00:00.000Z'
          nullable: true
      required:
      - id
      - name
      - stats
      - createdAt
    V3ResponseDto:
      type: object
      properties:
        data:
          type: object
      required:
      - data
    PaginatedLinksDocumented:
      type: object
      properties:
        first:
          type: string
          title: Link to first page
          nullable: true
        previous:
          type: string
          title: Link to previous page
          nullable: true
        current:
          type: string
          title: Link to current page
        next:
          type: string
          title: Link to next page
          nullable: true
        last:
          type: string
          title: Link to last page
          nullable: true
      required:
      - current
    ErrorResponse6a1ea2613cf2c41bb65e6b9eb34bea04f7ba0c4ac3abeec93be5a78e665f2d6b:
      type: object
      properties:
        statusCode:
          type: number
          description: HTTP status code
          example: 400
        message:
          description: Error messages
          examples:
          - - Invalid paginated query provided
          type: array
          items:
            type: string
      required:
      - statusCode
      - message
    ErrorResponse352c8d6544bab884304b2e571acb970dd2414f1f2488c0c5a84555d639eefb76:
      type: object
      properties:
        statusCode:
          type: number
          description: HTTP status code
          example: 404
        message:
          description: Error messages
          examples:
          - - Coupon not found
          type: array
          items:
            type: string
      required:
      - statusCode
      - message
    PaginatedDocumented:
      type: object
      properties:
        data:
          required: []
          title: Array of items
          properties: {}
          type: array
          items:
            type: object
        meta:
          title: Pagination Metadata
          allOf:
          - $ref: '#/components/schemas/PaginatedMetaDocumented'
        links:
          title: Links to pages
          allOf:
          - $ref: '#/components/schemas/PaginatedLinksDocumented'
      required:
      - meta
      - links
    GetV3CouponCodeResponseDto:
      type: object
      properties:
        id:
          type: string
          example: '1234567890'
          description: Unique ID for the Coupon Code
        couponId:
          type: string
          example: '1234567890'
          description: Unique ID for the Coupon
        code:
          type: string
          example: '1234567890'
          description: Code of the Coupon
        used:
          type: boolean
          example: false
          description: If the Coupon Code has been used
        usedAt:
          type: object
          description: Date when the Coupon Code was used
          example: '2024-01-01T00:00:00.000Z'
          nullable: true
        redeemedAt:
          type: object
          description: Date when the Coupon Code was redeemed
          example: '2024-01-01T00:00:00.000Z'
          nullable: true
        orderId:
          type: string
          example: ord_1234567890
          description: Order ID where the Coupon Code was used
          nullable: true
        createdAt:
          format: date-time
          type: string
          description: Date when the Coupon Code was created
          example: '2024-01-01T00:00:00.000Z'
        campaignId:
          type: string
          example: cmp_1234567890
          description: Campaign ID where the Coupon Code was used
          nullable: true
      required:
      - id
      - couponId
      - code
      - used
      - usedAt
      - redeemedAt
      - orderId
      - createdAt
      - campaignId
  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