openapi: 3.1.0
info:
  title: Labels
  version: 2.0.0
  description: >-
    Once a parcel has been announced, you can use the **Labels API** to request
    a PDF shipping label in order to print it and attach it to the box.
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  contact:
    name: Sendcloud API Support
    url: https://www.sendcloud.dev
    email: contact@sendcloud.com
servers:
  - url: https://panel.sendcloud.sc/api/v2
    description: Production
tags:
  - name: Labels
  - name: Label Download
  - name: Customs Documents Download
paths:
  /labels/{parcel_id}:
    parameters:
      - $ref: '#/components/parameters/path-parcel-id'
    get:
      operationId: sc-public-v2-scp-get-label_by_parcel_id
      security:
        - HTTPBasicAuth: []
        - OAuth2ClientCreds: []
      x-mint:
        href: /api/v2/labels/retrieve-a-label-for-a-specific-parcel
        content: |-
          <Warning>
            **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3).
          </Warning>
      summary: Retrieve a label for a specific parcel
      description: >-
        You will receive URLs to download the labels in PDF format, for both
        normal and label printers. You can get the `id` of a parcel from the
        [Create a parcel or parcels](/api/v2/parcels/create-a-parcel-or-parcels)
        endpoint.
      tags:
        - Labels
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LabelSingleResponse'
              examples:
                RetrieveLabel:
                  summary: Retrieve Label
                  value:
                    label:
                      normal_printer:
                        - >-
                          https://panel.sendcloud.sc/api/v2/label/normal_printer/1234?start_from=0
                        - >-
                          https://panel.sendcloud.sc/api/v2/label/normal_printer/1234?start_from=1
                        - >-
                          https://panel.sendcloud.sc/api/v2/label/normal_printer/1234?start_from=2
                        - >-
                          https://panel.sendcloud.sc/api/v2/label/normal_printer/1234?start_from=3
                      label_printer: >-
                        https://panel.sendcloud.sc/api/v2/label/label_printer/1234
                    customs_declaration: {}
        '404':
          $ref: '#/components/responses/error_404_not_found'
  /labels:
    post:
      operationId: sc-public-v2-scp-post-label_by_parcel_ids
      security:
        - HTTPBasicAuth: []
        - OAuth2ClientCreds: []
      x-mint:
        href: /api/v2/labels/bulk-pdf-label-printing
        content: |-
          <Warning>
            **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3).
          </Warning>
      summary: Bulk PDF label printing
      description: >-
        Request multiple shipping labels for an array of parcels at the same
        time. You will receive URLs to download the labels in PDF format, for
        both normal and label printers.
      tags:
        - Labels
      requestBody:
        content:
          application/json:
            schema:
              properties:
                label:
                  type: object
                  properties:
                    parcels:
                      type: array
                      items:
                        type: integer
                        minimum: 1
                      example:
                        - 1
                        - 2
                        - 3
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LabelMultipleResponse'
              examples:
                BulkPDFLabels:
                  summary: Bulk PDF label printing
                  value:
                    label:
                      normal_printer:
                        - >-
                          https://panel.sendcloud.sc/api/v2/label/normal_printer?ids=1,2,3?start_from=0
                        - >-
                          https://panel.sendcloud.sc/api/v2/label/normal_printer?ids=1,2,3?start_from=1
                        - >-
                          https://panel.sendcloud.sc/api/v2/label/normal_printer?ids=1,2,3?start_from=2
                        - >-
                          https://panel.sendcloud.sc/api/v2/label/normal_printer?ids=1,2,3?start_from=3
                      label_printer: >-
                        https://panel.sendcloud.sc/api/v2/label/label_printer?ids=1,2,3
        '404':
          $ref: '#/components/responses/error_404_not_found'
  /labels/normal_printer/{parcel_id}:
    parameters:
      - $ref: '#/components/parameters/path-parcel-id'
      - $ref: '#/components/parameters/query-start-from'
    get:
      operationId: sc-public-v2-scp-get-label_document_normal_printer
      security:
        - HTTPBasicAuth: []
        - OAuth2ClientCreds: []
      x-mint:
        href: /api/v2/labels/retrieve-a-pdf-label
        content: |-
          <Warning>
            **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3).
          </Warning>
      summary: Retrieve a PDF label
      description: >-
        Retrieve a shipping label for a specific parcel in PDF format for a
        normal printer.
      tags:
        - Label Download
      responses:
        '200':
          $ref: '#/components/responses/label_pdf_document_response'
        '400':
          $ref: '#/components/responses/error_400_bad_request'
        '404':
          $ref: '#/components/responses/error_404_not_found'
  /labels/normal_printer:
    parameters:
      - $ref: '#/components/parameters/path-parcel-ids'
      - $ref: '#/components/parameters/query-start-from'
    get:
      operationId: sc-public-v2-scp-get-label_document_multiple_normal_printer
      security:
        - HTTPBasicAuth: []
        - OAuth2ClientCreds: []
      x-mint:
        href: /api/v2/labels/retrieve-multiple-pdf-labels
        content: |-
          <Warning>
            **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3).
          </Warning>
      summary: Retrieve multiple PDF labels
      description: >-
        Retrieve PDF label documents suitable for normal printers for multiple
        different parcels at the same time.
      tags:
        - Label Download
      responses:
        '200':
          $ref: '#/components/responses/label_pdf_document_response'
        '400':
          $ref: '#/components/responses/error_400_bad_request'
        '404':
          $ref: '#/components/responses/error_404_not_found'
  /customs_declaration/normal_printer/{parcel_id}:
    parameters:
      - $ref: '#/components/parameters/path-parcel-id'
    get:
      operationId: sc-public-v2-scp-get-customs_document_normal_printer
      security:
        - HTTPBasicAuth: []
        - OAuth2ClientCreds: []
      x-mint:
        href: /api/v2/labels/retrieve-a-customs-declaration-pdf
        content: |-
          <Warning>
            **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3).
          </Warning>
      summary: Retrieve a customs declaration PDF
      description: >-
        Retrieve the customs documents associated with a label in PDF format for
        a normal printer.
      tags:
        - Customs Documents Download
      responses:
        '200':
          $ref: '#/components/responses/customs_pdf_document_response'
        '400':
          $ref: '#/components/responses/error_400_bad_request'
        '404':
          $ref: '#/components/responses/error_404_not_found'
  /customs_declaration/normal_printer:
    parameters:
      - $ref: '#/components/parameters/path-parcel-ids'
      - $ref: '#/components/parameters/query-start-from'
    get:
      operationId: sc-public-v2-scp-get-customs_document_multiple_normal_printer
      security:
        - HTTPBasicAuth: []
        - OAuth2ClientCreds: []
      summary: Retrieve multiple customs declaration PDFs
      x-mint:
        href: /api/v2/labels/retrieve-multiple-customs-declaration-pdfs
        content: |-
          <Warning>
            **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3).
          </Warning>

          <Warning>
            This endpoint is deprecated as of Mon, 08 Jan 2024 00:00:00 GMT. We recommend using the [Retrieve parcel documents](/api/v2/parcel-documents/retrieve-parcel-documents) endpoint instead.
          </Warning>
      description: >-
        Retrieve PDF customs documents suitable for normal printers for multiple
        different parcels at the same time.
      tags:
        - Customs Documents Download
      responses:
        '200':
          $ref: '#/components/responses/customs_pdf_document_response'
        '400':
          $ref: '#/components/responses/error_400_bad_request'
        '404':
          $ref: '#/components/responses/error_404_not_found'
      deprecated: true
  /labels/label_printer/{parcel_id}:
    parameters:
      - $ref: '#/components/parameters/path-parcel-id'
    get:
      operationId: sc-public-v2-scp-get-label_document_label_printer
      security:
        - HTTPBasicAuth: []
        - OAuth2ClientCreds: []
      x-mint:
        href: /api/v2/labels/retrieve-a-specific-pdf-label-for-a-label-printer
        content: |-
          <Warning>
            **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3).
          </Warning>
      summary: Retrieve a specific PDF label for a label printer
      description: >-
        Retrieve a shipping label for a specific parcel in PDF format for a
        label printer.
      tags:
        - Label Download
      responses:
        '200':
          $ref: '#/components/responses/label_pdf_document_response'
        '400':
          $ref: '#/components/responses/error_400_bad_request'
        '404':
          $ref: '#/components/responses/error_404_not_found'
  /labels/label_printer:
    parameters:
      - $ref: '#/components/parameters/path-parcel-ids'
    get:
      operationId: sc-public-v2-scp-get-label_document_multiple_label_printer
      security:
        - HTTPBasicAuth: []
        - OAuth2ClientCreds: []
      x-mint:
        href: /api/v2/labels/retrieve-pdf-labels-for-a-label-printer
        content: |-
          <Warning>
            **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3).
          </Warning>
      summary: Retrieve PDF labels for a label printer
      description: >-
        Retrieve PDF label documents suitable for label printers for multiple
        different parcels at the same time.
      tags:
        - Label Download
      responses:
        '200':
          $ref: '#/components/responses/label_pdf_document_response'
        '400':
          $ref: '#/components/responses/error_400_bad_request'
        '404':
          $ref: '#/components/responses/error_404_not_found'
components:
  securitySchemes:
    HTTPBasicAuth:
      type: http
      description: >-
        Basic Authentication using API key and secrets is currently the main
        authentication mechanism.
      scheme: basic
    OAuth2ClientCreds:
      type: oauth2
      description: >-
        OAuth2 is a standardized protocol for authorization that allows users to
        share their private resources stored on one site with another site
        without having to provide their credentials. OAuth2 Client Credentials
        Grant workflow. This workflow is typically used for server-to-server
        interactions that require authorization to access specific resources.
      flows:
        clientCredentials:
          tokenUrl: https://account.sendcloud.com/oauth2/token/
          scopes:
            api: Default OAuth scope required to access Sendcloud API.
  schemas:
    LabelSingleResponse:
      title: Single Label response
      properties:
        label:
          type: object
          title: Label object
          description: Label
          properties:
            normal_printer:
              title: >-
                URLs of labels documents in PDF format for normal printers for
                each position of an A4 size page
              type: array
              minLength: 4
              maxLength: 4
              items:
                type: string
                example: >-
                  https://panel.sendcloud.sc/api/v2/label/normal_printer/1234?start_from=0
            label_printer:
              title: URL of label document in PDF format for label printers
              type: string
              example: https://panel.sendcloud.sc/api/v2/label/label_printer/1234
        customs_declaration:
          title: Customs documents associated with the label
          deprecated: true
          type: object
          properties:
            normal_printer:
              type: string
              title: Normal printer PDF url
              description: >-
                URL that links to the customs documentation associated with the
                label in PDF format
          example: {}
    LabelMultipleResponse:
      title: Multi-Label response
      description: Response for multiple labels in bulk
      properties:
        label:
          type: object
          title: Label object
          description: Label
          properties:
            normal_printer:
              title: >-
                URLs of labels documents in PDF format for normal printers for
                each position of an A4 size page
              type: array
              minLength: 4
              maxLength: 4
              items:
                type: string
                example: >-
                  https://panel.sendcloud.sc/api/v2/label/normal_printer/1234?start_from=0
            label_printer:
              title: URL of label document in PDF format for label printers
              type: string
              example: >-
                https://panel.sendcloud.sc/api/v2/label/label_printer/1234?hash=bbfd669ee9ebb19408b85b33d
  parameters:
    path-parcel-id:
      schema:
        type: integer
        minimum: 1
      name: parcel_id
      in: path
      description: Unique parcel identifier
      required: true
      example: 1
    path-parcel-ids:
      schema:
        type: array
        minLength: 1
        items:
          type: integer
      name: ids
      in: query
      description: Comma separated parcel ids
      required: true
      explode: false
      example:
        - 1
        - 2
        - 3
    query-start-from:
      schema:
        type: integer
        minimum: 0
        maximum: 3
      name: start_from
      in: query
      required: true
      description: |-
        The position of the label on an A4 page.

        0 - Top left
        1 - Top right
        2 - Bottom left
        3 - Bottom right
  responses:
    label_pdf_document_response:
      description: OK
      content:
        application/pdf:
          schema:
            type: string
            format: binary
            title: Label PDF document
            description: Label PDF document ready to print
    customs_pdf_document_response:
      description: OK
      content:
        application/pdf:
          schema:
            type: string
            format: binary
            title: Customs document in PDF format
            description: Customs PDF document ready to print
      headers:
        Deprecation:
          schema:
            type: string
            example: Mon, 8 Jan 2024 00:00:00 GMT
        Sunset:
          schema:
            type: string
            example: Monday, 8 Jul 2024 00:00:00 GMT
    error_401_unauthorized:
      description: Unauthorized
    error_403_forbidden:
      description: Forbidden
    error_404_not_found:
      description: Not found
      content:
        application/json:
          schema:
            description: ''
            type: object
            example: {}
          example: {}
    error_400_bad_request:
      description: Bad request
      content:
        application/json:
          schema:
            description: ''
            type: object
            properties:
              message:
                type: string
                title: Error response message