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:
            - read:parcel
      x-mint:
        href: /api/v2/labels/retrieve-a-label-for-a-specific-parcel
        content: |-
          <Info>
            OAuth2 scopes required: `read:parcel`. See [Scopes for OAuth apps](/api/v3/scopes).
          </Info>

          <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:
            - read:parcel
      x-mint:
        href: /api/v2/labels/bulk-pdf-label-printing
        content: |-
          <Info>
            OAuth2 scopes required: `read:parcel`. See [Scopes for OAuth apps](/api/v3/scopes).
          </Info>

          <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:
            - read:parcel
      x-mint:
        href: /api/v2/labels/retrieve-a-pdf-label
        content: |-
          <Info>
            OAuth2 scopes required: `read:parcel`. See [Scopes for OAuth apps](/api/v3/scopes).
          </Info>

          <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:
            - read:parcel
      x-mint:
        href: /api/v2/labels/retrieve-multiple-pdf-labels
        content: |-
          <Info>
            OAuth2 scopes required: `read:parcel`. See [Scopes for OAuth apps](/api/v3/scopes).
          </Info>

          <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:
            - read:parcel
      x-mint:
        href: /api/v2/labels/retrieve-a-customs-declaration-pdf
        content: |-
          <Info>
            OAuth2 scopes required: `read:parcel`. See [Scopes for OAuth apps](/api/v3/scopes).
          </Info>

          <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:
            - read:parcel
      summary: Retrieve multiple customs declaration PDFs
      x-mint:
        href: /api/v2/labels/retrieve-multiple-customs-declaration-pdfs
        content: |-
          <Info>
            OAuth2 scopes required: `read:parcel`. See [Scopes for OAuth apps](/api/v3/scopes).
          </Info>

          <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:
            - read:parcel
      x-mint:
        href: /api/v2/labels/retrieve-a-specific-pdf-label-for-a-label-printer
        content: |-
          <Info>
            OAuth2 scopes required: `read:parcel`. See [Scopes for OAuth apps](/api/v3/scopes).
          </Info>

          <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:
            - read:parcel
      x-mint:
        href: /api/v2/labels/retrieve-pdf-labels-for-a-label-printer
        content: |-
          <Info>
            OAuth2 scopes required: `read:parcel`. See [Scopes for OAuth apps](/api/v3/scopes).
          </Info>

          <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:
            read:analytics: View your shipping analytics
            read:audit-log: View your account's audit log
            read:brand: View your brands
            write:brand: Manage your brands
            write:carrier: Configure carriers and contracts
            read:checkout: View your dynamic checkout configurations and templates
            read:event-subscription: View your event subscriptions
            write:event-subscription: Create and manage your event subscriptions
            read:integration: View your integrations
            write:integration: Connect and manage integrations
            read:invoice: View your invoices
            read:notification: View your notifications
            write:notification: Manage your notifications
            read:operational-settings: View your warehouses, shipping lanes, and other operational settings
            write:operational-settings: Manage your warehouses, shipping lanes, and other operational settings
            read:order: View your orders
            write:order: Import and process your orders
            read:organization: View organization settings
            write:organization: Change organization settings
            read:parcel: View your shipments and their tracking status
            write:parcel: Create, announce, and cancel shipments
            read:pickup: View carrier pickups and the options available for scheduling them
            write:pickup: Schedule and manage carrier pickups
            read:price: View shipping prices
            write:product: Manage your product catalog
            read:return: View your returns
            write:return: Create and manage returns
            read:return-settings: View your return settings
            write:return-settings: Configure your return settings
            read:service-point: View carrier service points
            read:shipping-method: View shipping methods, products and prices
            read:shipping-rule: View your shipping rules
            write:shipping-rule: Create and manage shipping rules
            read:support-ticket: View your support tickets
            write:support-ticket: Manage your support tickets
            read:tracking-message: View your tracking notifications
            write:tracking-message: Manage your tracking notifications
            read:tracking-page: View your tracking page
            write:tracking-page: Customize your tracking page
            read:user: Read your basic account information
  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