openapi: 3.1.0 info: title: Parcel Documents description: | For international shipments, customs documentation is generated alongside the shipping label. These documents can be downloaded separately from the shipping label in various formats and resolutions via this endpoint. version: 2.0.0 contact: name: Sendcloud API Support url: https://www.sendcloud.dev email: contact@sendcloud.com license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html servers: - url: https://panel.sendcloud.sc/api/v2 description: Sendcloud Production tags: - name: Parcel Documents paths: /parcels/{id}/documents/{type}: get: summary: Retrieve parcel documents x-mint: href: /api/v2/parcel-documents/retrieve-parcel-documents content: |- OAuth2 scopes required: `read:user`. See [Scopes for OAuth apps](/api/v3/scopes). **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). For international shipments, a commercial invoice, CN23 or CN22 (+CP71) form must be attached (either physically or [digitally](https://support.sendcloud.com/hc/en-us/articles/4417349714452-Send-your-customs-documents-digitally-via-Paperless-Trade-) for some carriers) to the shipment for customs officials to access. The type of document required depends on the shipping method and value of the shipment. When you use the [Create a parcel or parcels](/api/v2/parcels/create-a-parcel-or-parcels) endpoint, Sendcloud generates the correct type of document for your shipment if you have filled in all the information related to the parcel contents, value, and invoice. Use this endpoint to retrieve these documents in your preferred format. The supported document types are as follows: - `air-waybill` - `cn23` - `cn23-default` - `commercial-invoice` - `cp71` - `label` - `qr` description: Retrieve a document for a given parcel by providing the parcel `id` and document `type`. tags: - Parcel Documents responses: '200': description: Requested parcel document file content: application/pdf: schema: type: string format: binary application/zpl: schema: type: string format: binary image/png: schema: type: string format: binary '404': description: Document type requested is not available for the parcel content: application/json: schema: type: object properties: error: type: object properties: code: type: integer description: HTTP error code example: 404 request: type: string description: Endpoint URL that was requested example: api/v2/parcels/1/documents/commercial-invoice message: type: string description: A human readable error message example: No Parcel matches the given query. examples: NotFound: summary: Parcel Document Not Found value: error: code: 404 request: api/v2/parcels/1/documents/commercial-invoice message: No Parcel matches the given query. document_type_not_found: summary: Document Type Not Found value: error: code: 404 request: api/v2/parcels/1/documents/not-existing-document-type message: Not found. operationId: sc-public-v2-scp-get-retrieve_parcel_documents security: - HTTPBasicAuth: [] - OAuth2ClientCreds: - read:user parameters: - $ref: '#/components/parameters/dpi' - $ref: '#/components/parameters/rendering_format' - $ref: '#/components/parameters/raw' parameters: - $ref: '#/components/parameters/id' - $ref: '#/components/parameters/type' 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 parameters: id: name: id in: path schema: type: integer example: 1 minimum: 1 description: Identifier of the parcel which you want to retrieve a document from required: true type: name: type in: path schema: type: string example: commercial-invoice enum: - air-waybill - cn23 - cn23-default - commercial-invoice - cp71 - label - qr description: Document type you want to retrieve for this parcel required: true dpi: name: dpi in: query required: false schema: type: integer default: 72 enum: - 72 - 150 - 203 - 300 - 600 example: 300 minimum: 1 description: | DPI refers to the printing resolution of your shipping labels. It's important that labels are printed at a high enough resolution to ensure the clarity of address details and the barcode for scanning purposes. Use following amounts for appropriate result:
File format Default DPI Valid DPI
pdf 72 72
png 300 150, 300
ZPL labels are not affected by the DPI setting, as the resolution is determined by the carrier itself. Most carriers use a resolution of 203 DPI. Zebra printers need to be configured to print at the specific DPI of the label if they have higher resolution capabilities. rendering_format: name: Accept in: header required: false schema: type: string default: application/pdf enum: - application/pdf - application/zpl - image/png example: image/png description: The returned format of the document raw: name: raw in: query required: false schema: type: boolean description: There have been identified cases where custom documents, internally rendered, will only include some of the necessary information, mainly due to some restrictions. Using the raw query param, one can request to receive the document in the originally received format by the carrier. This temporary solution to the problem allows the normal operations of the affected customers. As such, you can expect this property to be sunsetted shortly once the necessary changes have been implemented.