openapi: 3.1.0
info:
title: Air Waybill (AWB)
description: |
Closes the current open order/box and generates an AWB (Air Waybill) document for all international parcels in that Deutsche Post box.
**How it works:**
1. As you create Deutsche Post International parcels, they are automatically added to the current box (identified by the current box_number).
2. When the box is full or you're ready to ship, call this endpoint to finalize the box.
3. The finalization process:
- Generates a single AWB label that is shared by all parcels in the finalized box
- Attaches the AWB label to all parcels in the box
- Increments the box_number, automatically starting a new box for subsequent parcels
4. You can create and finalize multiple boxes throughout the day as needed.
**Important notes:**
- Each box has its own unique AWB label
- All parcels within a single box share the same AWB label
- The AWB document can be retrieved from any parcel that was in the finalized box
- New parcels created after finalization will be added to the new box
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: Air Waybill (AWB)
paths:
/box/finalize:
post:
summary: Finalize a Deutsche Post order
tags:
- Air Waybill
operationId: sc-public-v2-scp-post-finalize_box
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds:
- write:parcel
description: Finalize a Deutsche Post order by closing the current open box and generating an AWB (Air Waybill) document for all parcels in that box.
x-mint:
href: /api/v2/air-waybill/finalizing-a-box
content: |-
OAuth2 scopes required: `write:parcel`. 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).
This endpoint closes the current open order/box and generates an AWB (Air Waybill) document for all parcels in that box.
**How it works:**
1. As you create Deutsche Post International parcels, they are automatically added to the current box (identified by the current box_number).
2. When the box is full or you're ready to ship, call this endpoint to finalize the box.
3. The finalization process generates a single AWB label that is shared by all parcels in the finalized box and increments the box_number, automatically starting a new box for subsequent parcels.
4. You can create and finalize multiple boxes throughout the day as needed.
**Parameters:**
- `copy_count`: Specify how many AWB copies you need (1-99). Use this if the parcels are split over multiple physical boxes or pallets.
**Response:**
When the request is successful, a `200` code will be returned with the `copy_count` requested. The AWB is generated and you can retrieve the AWB label from any parcel that was in the finalized box, as the AWB label is identical for all parcels included in the box.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AwbCopies'
examples:
AWBCopiesQuantity:
summary: AWB copies quantity
value:
copy_count: 10
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: integer
request:
type: string
message:
type: string
examples:
CopyLessThanMinimum:
summary: Copy count falls short than minimum
value:
error:
code: 400
request: api/v2/box/finalize
message: 'copy_count: "Ensure this value is greater than or equal to 1."'
CountExceedsMaximum:
summary: Copy count exceeds maximum
value:
error:
code: 400
request: api/v2/box/finalize
message: 'copy_count: "Ensure this value is less than or equal to 99."'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AwbCopies'
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:
AwbCopies:
type: object
properties:
copy_count:
type: integer
format: int64
default: 1
minimum: 1
maximum: 99
description: Specify how many AWB copies you need
title: AWB Copies Object