> ## Documentation Index
> Fetch the complete documentation index at: https://sendcloud.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# API user flows

Here we outline common user flows when using the Sendcloud APIs.

For an explanation of the terms used, visit the [Glossary](/docs/getting-started/glossary/).

## API v3 user flows

### Standard shipment creation flow (Shipments API v3)

```mermaid placement="top-right" theme={null}
%%{init: {'flowchart': {'defaultRenderer': 'elk', 'nodeSpacing': 25, 'rankSpacing': 30, 'padding': 4}}}%%
flowchart TD
    A([Start]) --> B("Call the Shipping Option API v3 to get a desired Shipping Option Code<br/><br/><code>POST&nbsp;/api/v3/shipping-options</code>")
    B --> C("Create parcel payload with desired <code>shipping_option_code</code>")
    C --> D{"Do you want your labels to be created synchronously?"}
    D -- No --> E("Create and announce a shipment asynchronously<br/><br/><code>POST&nbsp;/api/v3/shipments</code>")
    D -- Yes --> F("Create and announce a shipment synchronously<br/><br/><code>POST&nbsp;/api/v3/shipments/announce</code>")
    E --> G("Call Parcel Document API v3 with the <code>id</code> of Parcel<br/><br/><code>GET&nbsp;/api/v3/parcels/{id}/documents/label</code>")
    F --> H{"Did you announce a multicollo shipment?"}
    H -- Yes --> G
    H -- No --> I("Retrieve label from response")
    G --> I
    I --> J([Stick label on parcel and hand it to carrier])
    click B "/api/v3/shipping-options/return-a-list-of-available-shipping-options" _blank
    click E "/api/v3/ship-an-order/request-a-label-for-one-or-more-orders-asynchronously" _blank
    click F "/api/v3/ship-an-order/request-a-label-for-a-single-order-synchronously" _blank
    click G "/api/v3/parcel-documents/retrieve-a-parcel-document" _blank
```

1. **Choose a shipping option**: Retrieve available shipping options using [`POST /api/v3/shipping-options`](/api/v3/shipping-options/return-a-list-of-available-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`](/api/v3/ship-an-order/request-a-label-for-a-single-order-synchronously) which returns a `parcel_id` for later label retrieval via the [Parcel Document API](/api/v3/parcel-documents/retrieve-a-parcel-document).
   * **Synchronous path**: Use [`POST /api/v3/shipments/announce`](/api/v3/ship-an-order/request-a-label-for-one-or-more-orders-asynchronously) 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](/docs/shipments) to learn more.

### Shipping orders from E-commerce platforms

```mermaid placement="top-right" theme={null}
%%{init: {'flowchart': {'defaultRenderer': 'elk', 'nodeSpacing': 25, 'rankSpacing': 30, 'padding': 4}}}%%
flowchart TD
    A([Start]) --> B("Call Order API v3 to get an Order that has already been imported into Sendcloud<br/><br/><code>GET&nbsp;/api/v3/orders</code>")
    B --> C("Create the payload")
    C --> D{"Do you want to ship multiple orders in one API call?"}
    D -- yes --> E("Call Ship-an-Order API v3<br/><br/><code>POST&nbsp;/api/v3/orders/create-labels-async</code>")
    D -- no --> F("Call Ship-an-Order API v3<br/><br/><code>POST&nbsp;/api/v3/orders/create-label-sync</code>")
    E --> G("Retrieve id of created Parcels from the response")
    G --> H("Call Parcel Documents API v3 with the retrieved <code>parcel_id</code><br/><br/><code>GET&nbsp;/api/v3/parcels/{id}/documents/label</code>")
    H --> I("Retrieve a binary file from the response")
    F --> J("Retrieve a Base64 encoded file from the response")
    I --> K([Stick the label on parcel and hand it to carrier])
    J --> K
    click B "/api/v3/orders/retrieve-a-list-of-orders" _blank
    click E "/api/v3/ship-an-order/request-a-label-for-one-or-more-orders-asynchronously" _blank
    click F "/api/v3/ship-an-order/request-a-label-for-a-single-order-synchronously" _blank
    click H "/api/v3/parcel-documents/retrieve-a-parcel-document" _blank
```

1. **Fetch an imported order**: Retrieve an order that was synced from your e-commerce platform using [`GET /api/v3/orders`](/api/v3/orders/retrieve-a-list-of-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`](/api/v3/ship-an-order/request-a-label-for-one-or-more-orders-asynchronously) which returns `parcel_id` values for each created parcel.
   * **Single order (sync)**: Use [`POST /api/v3/orders/create-label-sync`](/api/v3/ship-an-order/request-a-label-for-a-single-order-synchronously) 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`](/api/v3/parcel-documents/retrieve-a-parcel-document") 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](/docs/orders) to learn more.

### Announcing a multicollo parcel

```mermaid placement="top-right" theme={null}
%%{init: {'flowchart': {'defaultRenderer': 'elk', 'nodeSpacing': 25, 'rankSpacing': 30, 'padding': 4}}}%%
flowchart TD
    A([Start]) --> B("Call the Shipping Option API v3 to get a desired Shipping Option Code<br/><br/><code>POST&nbsp;/api/v3/shipping-options</code>")
    B --> C("Create shipment payload with the desired <code>shipping_option_code</code>")
    C --> D("Call Shipments API v3 with multiple parcel objects<br/><br/><code>POST&nbsp;/api/v3/shipments/announce</code>")
    D --> E("Call Parcel Document API v3 with the parcel ID as many times as needed to get all labels<br/><code>GET&nbsp;/api/v3/parcels/{id}/documents/{type}</code>")
    E --> F("Retrieve label from the response")
    F --> G([Stick the label on the parcel and hand it to carrier])
    click B "/api/v3/shipping-options/return-a-list-of-available-shipping-options" _blank
    click D "/api/v3/shipments/create-and-announce-a-shipment-synchronously" _blank
    click E "/api/v3/parcel-documents/retrieve-a-parcel-document" _blank
```

1. **Choose a shipping option**: Retrieve available shipping options using [`POST /api/v3/shipping-options`](/api/v3/shipping-options/return-a-list-of-available-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`](/api/v3/shipments/create-and-announce-a-shipment-synchronously) 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}`](/api/v3/parcel-documents/retrieve-a-parcel-document) 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](/docs/shipments/multicollo) 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:

```mermaid placement="top-right" theme={null}
%%{init: {'flowchart': {'defaultRenderer': 'elk', 'nodeSpacing': 25, 'rankSpacing': 30, 'padding': 4}}}%%
flowchart TD
    A([Start]) --> B("Call the Shipping Option API v3 to get the desired shipping option<br/><br/><code>POST&nbsp;/api/v3/shipping-options</code>")
    B --> C("Call the Brands API v2 to get a desired brand ID<br/><code>GET&nbsp;/api/v2/brands</code>")
    C --> D("Create parcel payload with the <code>shipping_option_code</code> and <code>brand_id</code>")
    D --> E("Create shipment<br/><br/><code>POST&nbsp;/api/v3/shipments/announce</code>")
    E --> F("Retrieve label from the response")
    F --> G("Affix label and hand to carrier")
    G --> H("Status of the parcel updates along its journey")
    H --> I([Sendcloud sends branded notification via your selected channels e.g., email, WhatsApp, tracking page, or SMS])
    click B "/api/v3/shipping-options/return-a-list-of-available-shipping-options" _blank
    click C "/api/v2/brands/retrieve-a-list-of-brands" _blank
    click E "/api/v3/shipments/create-and-announce-a-shipment-synchronously" _blank
```

1. **Choose a shipping option**: Retrieve available shipping options using [`POST /api/v3/shipping-options`](/api/v3/shipping-options/return-a-list-of-available-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`](/api/v2/brands/retrieve-a-list-of-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`](/api/v3/shipments/create-and-announce-a-shipment-synchronously) 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](/api/v3/event-subscriptions/index) (BETA):

```mermaid placement="top-right" theme={null}
%%{init: {'flowchart': {'defaultRenderer': 'elk', 'nodeSpacing': 25, 'rankSpacing': 30, 'padding': 4}}}%%
flowchart TD
    A([Start]) --> B("Create a connection<br/><br/><code>POST&nbsp;/api/v3/event-subscriptions/connections</code>")
    B --> C("Create a subscription<br/><br/><code>POST&nbsp;/api/v3/event-subscriptions/subscriptions</code>")
    C --> D("Test event delivery<br/><br/><code>POST&nbsp;/api/v3/event-subscriptions/broadcast/test/{subscription_id}</code>")
    D --> E([Start receiving live events])
    click B "/api/v3/event-subscriptions/list-connections" _blank
    click C "/api/v3/event-subscriptions/create-a-subscription" _blank
    click D "/api/v3/event-subscriptions/test-event-delivery" _blank
```

1. **Create a connection**: Define where events should be delivered (e.g. a webhook URL or Klaviyo integration) using the [Create a connection](/api/v3/event-subscriptions/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](/api/v3/event-subscriptions/create-a-subscription) endpoint.
3. **Test your setup**: Verify that events are delivered correctly by using the [Test event delivery](/api/v3/event-subscriptions/test-event-delivery) (`/broadcast/test/{subscription_id}`) endpoint.