API user flows

Documentation Index

Fetch the complete documentation index at: https://sendcloud.dev/llms.txt

Use this file to discover all available pages before exploring further.

Here we outline common user flows when using the Sendcloud APIs. For an explanation of the terms used, visit the Glossary.

​

API v3 user flows

​

Standard shipment creation flow (Shipments API v3)

1. Choose a shipping option: Retrieve available shipping options using POST /api/v3/shipping-options to get carrier services with their shipping_option_code values.
2. Create the parcel payload: Assemble your shipment payload with the desired shipping_option_code, along with sender address, recipient details, parcel dimensions, and weight.
3. Choose synchronous or asynchronous announcement: Decide whether labels should be created immediately (synchronous) or in the background (asynchronous).
   • Asynchronous path: Use POST /api/v3/shipments which returns a parcel_id for later label retrieval via the Parcel Document API.
   • Synchronous path: Use POST /api/v3/shipments/announce which returns the label immediately in the response.
4. Handle multicollo shipments: If you announced a multicollo shipment (multiple parcels announced together to stay linked throughout delivery), you must retrieve individual labels using the GET /api/v3/parcels/{id}/documents/label endpoint for each parcel in the shipment.
5. Apply the label: Extract the label from the API response. Print the label, affix it to the parcel, and hand it to the carrier via pickup or drop-off.

Need more information on this flow? Visit Shipments API Overview to learn more.

​

Shipping orders from E-commerce platforms

1. Fetch an imported order: Retrieve an order that was synced from your e-commerce platform using GET /api/v3/orders.
2. Create the payload: Assemble your payload with the order information and shipping preferences.
3. Choose batch or single shipment: Decide whether to ship multiple orders in one API call (batch processing) or ship one order at a time.
4. Ship the order(s):
   • Multiple orders (async): Use POST /api/v3/orders/create-labels-async which returns parcel_id values for each created parcel.
   • Single order (sync): Use POST /api/v3/orders/create-label-sync which returns a Base64 encoded label immediately.
5. Retrieve labels for batch shipments: For async/batch processing, call GET /api/v3/parcels/{id}/documents/label with each parcel_id to retrieve binary label files.
6. Apply the label: Extract the label (Base64 or binary), print it, affix it to the parcel, and hand it to the carrier.

Need more information on this flow? Visit Orders API Overview to learn more.

​

Announcing a multicollo parcel

1. Choose a shipping option: Retrieve available shipping options using POST /api/v3/shipping-options to get carrier services with their shipping_option_code values.
2. Create the multicollo shipment payload: Assemble your payload with the desired shipping_option_code and include multiple parcel objects in a single shipment. This creates a multicollo shipment where all parcels stay linked for the customer’s tracking purposes throughout delivery.
3. Announce the multicollo shipment: Use POST /api/v3/shipments/announce with your array of parcel objects. This returns an array of parcel_id values, one for each parcel in the multicollo shipment.
4. Retrieve labels for each parcel: Call GET /api/v3/parcels/{id}/documents/{type} once for each parcel_id to retrieve individual label files. Each parcel in the multicollo shipment requires its own label.
5. Apply labels to parcels: Extract each label from the responses, print them, affix each label to its corresponding parcel. In some cases certain parcels in the shipment may have to be shipped at a later date (e.g., limited stock) so coordinate with the carrier accordingly.

Need more information on this flow? Visit the Multicollo guide in the Shipments API section to learn more.

​

Shipping a parcel as a white-label product in the marketplace

Use this flow to ship a parcel under your own branding. To get started:

1. Choose a shipping option: Retrieve available shipping options using POST /api/v3/shipping-options to get carrier services with their shipping_option_code values.
2. Choose your brand: Retrieve your configured brands using GET /api/v2/brands and select the brand_id to apply to this shipment. Brands customize customer-facing features like tracking pages and notifications.
3. Create the parcel payload: Combine your chosen shipping_option_code and brand_id in the parcel payload along with sender address, recipient details, and parcel dimensions.
4. Announce the shipment: Use POST /api/v3/shipments/announce to create and announce the shipment with the carrier, which returns the label.
5. Apply the label: Print the label from the response, affix it to the parcel, and hand it to the carrier via pickup or drop-off.
6. Tracking with branded notifications: Once the carrier scans the parcel and updates its status, Sendcloud automatically sends tracking notifications via your chosen channels (email, WhatsApp, tracking page, or SMS) under your selected brand. No further API calls needed.

​

Setting up event subscriptions

To start receiving real-time parcel event notifications via the Event Subscriptions API (BETA):

1. Create a connection: Define where events should be delivered (e.g. a webhook URL or Klaviyo integration) using the Create a connection endpoint.
2. Create a subscription: Specify which events to listen for and link them to your connection using the Create a subscription endpoint.
3. Test your setup: Verify that events are delivered correctly by using the Test event delivery (/broadcast/test/{subscription_id}) endpoint.