> ## Documentation Index
> Fetch the complete documentation index at: https://sendcloud.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Retrieve a parcel document
> Retrieve a specific document for a given parcel, and download it in your preferred format and resolution.
OAuth2 scopes required: `read:parcel`. See [Scopes for OAuth apps](/api/v3/scopes).
Sendcloud generates the correct type of document for your shipment when you [Create a parcel](/api/v2/parcels/create-a-parcel-or-parcels), provided that 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.
This endpoint supports the following document types:
* `label`
* `customs-declaration`
* `air-waybill`
* `proof-of-delivery`
For international shipments, customs declaration 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.
`proof-of-delivery` is retrieved directly from the carrier on request and is only available once the parcel has been delivered. It is only returned in PDF format (`application/pdf`), and availability depends on the carrier supporting proof of delivery.
## OpenAPI
````yaml /.openapi/v3/parcel-documents/openapi.yaml get /parcels/{id}/documents/{type}
openapi: 3.1.0
info:
title: Parcel documents API
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 API.
version: 3.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/v3
description: Sendcloud Production
security: []
tags:
- name: Parcel Documents
paths:
/parcels/{id}/documents/{type}:
get:
tags:
- Parcel Documents
summary: Retrieve a parcel document
description: >-
Retrieve a specific document for a given parcel, and download it in your
preferred format and resolution.
operationId: sc-public-v3-scp-get-retrieve_parcel_documents
parameters:
- $ref: '#/components/parameters/id'
- $ref: '#/components/parameters/typeSingle'
- $ref: '#/components/parameters/dpi'
- $ref: '#/components/parameters/rendering_format'
- $ref: '#/components/parameters/paper-size'
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
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errors'
examples:
InvalidType:
value:
errors:
- code: invalid
status: '400'
detail: Invalid document type.
'404':
description: Document type requested is not available for the parcel
content:
application/json:
schema:
$ref: '#/components/schemas/errors'
examples:
NotFound:
summary: Parcel Document Not Found
value:
errors:
- code: not_found
status: '404'
detail: No Parcel matches the given query.
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds:
- read:parcel
components:
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
typeSingle:
name: type
in: path
schema:
type: string
example: customs-declaration
enum:
- label
- customs-declaration
- air-waybill
- proof-of-delivery
description: >-
Document type you want to retrieve.
**Note:** `proof-of-delivery` is only available in PDF format
(`application/pdf`) and depends on the carrier supporting proof of
delivery.
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, or dots per inch, refers to the printing resolution of your
shipping labels. Labels must be printed at a high enough resolution to
ensure the clarity of address details and the barcode for scanning
purposes.
Use the following table to find the appropriate DPI for each file
format:
| 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.
**Note:** If a label is requested as native ZPL from the carrier it
can't be converted to another format and will always be returned in ZPL.
paper-size:
in: query
name: paper_size
description: >
The paper size of the document you would like to retrieve. Paper size
can be one of:
- A4
- A5
- A6
Omitting this query parameter leads to the internal paper size of the
document being used. Generally this is A6 for labels and A4 for larger
documents, like customs documents.
schema:
type: string
enum:
- A4
- A5
- A6
example: A4
schemas:
errors:
title: Errors
type: object
description: A standardized format for errors in JSON:API responses.
properties:
errors:
type:
- array
- object
items:
type: object
allOf:
- $ref: '#/components/schemas/ErrorObject'
required:
- status
- code
- detail
ErrorObject:
title: Error
type: object
description: Error in a JSON:API error format
properties:
id:
type: string
description: A unique identifier for the error.
links:
type: object
description: >-
A set of hyperlinks that provide additional information about the
error.
properties:
about:
type: string
description: A URL that provides additional information about the error.
status:
type: string
format: int32
description: The HTTP status code of the error.
minLength: 1
code:
type: string
description: A unique error code for the error, in snake case format.
minLength: 1
enum:
- unknown_field
- invalid
- forbidden
- invalid_choice
- min_value
- 'null'
- not_found
- required
- not_a_list
- non_field_errors
- authentication_failed
- validation_error
- parcel_announcement_error
title:
type: string
description: A short, human-readable summary of the error.
minLength: 1
detail:
type: string
description: A human-readable explanation of the error.
minLength: 1
source:
type: object
description: >-
An object that identifies the source of the error within the request
payload.
properties:
pointer:
type: string
description: >-
A `JSON` pointer to the location of the error within the request
payload.
parameter:
type: string
description: The name of the `query` parameter that caused the error.
header:
type: string
description: The name of the `header` parameter that caused the error.
meta:
type: object
description: Additional metadata about the error.
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
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.