> ## Documentation Index > Fetch the complete documentation index at: https://sendcloud.dev/llms.txt > Use this file to discover all available pages before exploring further. # Upload a customs document > Upload a PDF customs document that you can attach to shipments. > [!NOTE] > > OAuth2 scopes required: `write:parcel`. See [Scopes for OAuth apps](/api/v3/scopes). Upload your own customs document, such as a certificate of origin, so it's sent to the carrier together with the customs documents Sendcloud generates. The response contains the document `id`. To attach the document, add the `id` to `customs_information.additional_documents` when you create a shipment with any of the create shipment endpoints. You can attach up to 3 documents to a shipment. > [!NOTE] > > This endpoint is in beta and only available to organizations with access to the additional customs documents beta. Other organizations get a `403` response. Details or behavior may change before the feature is generally available. The request must be `multipart/form-data` with a `file` part and a `document_type` field. The file must be a PDF of at most 5 MB. > [!WARNING] > > A document expires 30 days after upload. You can attach it to any number of shipments until then. After it expires, a create shipment request that includes the document fails with a `400` "not found or expired" error, and you need to upload the document again. An organization can have at most 1000 uploaded documents that aren't attached to a shipment yet. When you reach the limit, uploads fail with a `409` response until you attach documents or they expire. ## OpenAPI ````yaml /.openapi/v3/shipments/openapi.yaml post /shipments/documents openapi: 3.1.0 info: title: Shipments version: 3.0.0 description: >- The Shipments API allows you to create and announce, retrieve, and cancel outgoing shipments and their associated parcels within the Sendcloud platform. contact: name: Sendcloud API Support 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: Shipments description: Shipments API paths: /shipments/documents: post: tags: - Shipments summary: Upload a customs document description: Upload a PDF customs document that you can attach to shipments. operationId: sc-public-v3-scp-post-upload_shipment_document requestBody: required: true content: multipart/form-data: schema: type: object properties: file: type: string format: binary description: The customs document. Must be a PDF of at most 5 MB. document_type: $ref: '#/components/schemas/document_type' required: - file - document_type responses: '201': description: Created content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/customs-document' required: - data examples: CustomsDocumentUploaded: summary: Customs document uploaded value: data: id: 9f1c8e2a-4b7d-4e2f-9a3c-1d5e6f7a8b9c document_type: commercial_invoice '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/errors' examples: InvalidFileType: summary: File is not a PDF value: errors: - status: '400' code: validation_error detail: File must be a PDF. FileTooLarge: summary: File is too large value: errors: - status: '400' code: validation_error detail: File size must not exceed 5 MB. '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/errors' examples: BetaNotEnabled: summary: Beta not enabled value: errors: - status: '403' code: forbidden detail: >- Customs documents are not enabled for this organization. '409': description: Conflict content: application/json: schema: $ref: '#/components/schemas/errors' examples: TooManyUnattachedDocuments: summary: Too many unattached documents value: errors: - status: '409' code: conflict detail: >- Organization already has 1000 customs documents not attached to a shipment. security: - HTTPBasicAuth: [] - OAuth2ClientCreds: - write:parcel components: schemas: document_type: type: string description: |- The type of the customs document. - `certificate_of_origin`: A certificate of origin. - `commercial_invoice`: A commercial invoice. - `customs_declaration`: A customs declaration. - `other`: Any other document that customs needs. enum: - certificate_of_origin - commercial_invoice - customs_declaration - other example: commercial_invoice customs-document: title: Customs document description: >- A customs document uploaded with the [Upload a customs document](/api/v3/shipments/upload-a-customs-document) endpoint. type: object properties: id: type: string format: uuid description: >- ID of the customs document. Use it in `customs_information.additional_documents` to attach the document to a shipment. example: 9f1c8e2a-4b7d-4e2f-9a3c-1d5e6f7a8b9c document_type: type: string description: |- The type of the customs document. - `certificate_of_origin`: A certificate of origin. - `commercial_invoice`: A commercial invoice. - `customs_declaration`: A customs declaration. - `other`: Any other document that customs needs. enum: - certificate_of_origin - commercial_invoice - customs_declaration - other example: commercial_invoice required: - id - document_type errors: title: Errors description: >- A standardized format for errors in [JSON:API](https://jsonapi.org/format/#error-objects) responses. type: array items: 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.