### Example Response Body with Documents

Source: https://sendcloud.dev/docs/shipments/international-shipping

An example of a response body when creating an international parcel, showing the `documents` object with links to generated commercial invoices and labels.

```json
{
  // ... other parcel properties
  "documents": [
    {
      "type": "commercial-invoice",
      "size": "a4",
      "link": "https://panel.sendcloud.sc/api/v2/parcels/1/documents/commercial-invoice"
    },
    {
      "type": "label",
      "size": "a6",
      "link": "https://panel.sendcloud.sc/api/v2/parcels/1/documents/label"
    }
  ]
}
```

--------------------------------

### Example Parcel Items Array

Source: https://sendcloud.dev/docs/shipments/international-shipping

An example of the `parcel_items` array structure, including required and optional properties for each item.

```json
{
  "parcel_items": [
    {
      "description": "T-Shirt",
      "hs_code": "6109",
      "origin_country": "SE",
      "product_id": "898678671",
      "properties": {
        "color": "Blue",
        "size": "Medium"
      },
      "quantity": 2,
      "sku": "TST-OD2019-B620",
      "value": "19.95",
      "weight": "0.9"
    }
  ]
}
```

--------------------------------

### Basic Authentication Example

Source: https://sendcloud.dev/docs/getting-started/authentication

This example shows how to authenticate your API requests using your Public and Private API keys with Basic Authentication. Your Public Key acts as the username and your Private Key as the password, both base64-encoded.

```APIDOC
## Basic Authentication

### Description
Authenticates requests using your Sendcloud Public and Private API keys.

### Method
GET (example for parcels endpoint)

### Endpoint
`https://panel.sendcloud.sc/api/v2/parcels`

### Headers
- `Accept`: `application/json`
- `Authorization`: `Basic <base64-encoded-token>`

### Request Example
```sh
curl --location 'https://panel.sendcloud.sc/api/v2/parcels' \
--header 'Accept: application/json' \
--header 'Authorization: Basic <base64-encoded-token>'
```

### Note
The `<base64-encoded-token>` is generated by combining your Public Key and Private Key with a colon in between (e.g., `public_key:private_key`) and then base64 encoding the result.
```

--------------------------------

### GET Request to Retrieve Delivery Options

Source: https://sendcloud.dev/docs/dynamic-checkout/retrieve-delivery-options

Send a GET request to the endpoint, including required checkout context as query parameters. Ensure the configuration_id is published and linked to your integration.

```http
GET https://panel.sendcloud.sc/api/v3/checkout/configurations/{configuration_id}/delivery-options?weight_value=2500&total_order_value=45.90&from_country_code=NL&to_country_code=NL
```

--------------------------------

### OAuth2 Authentication - API Request

Source: https://sendcloud.dev/docs/getting-started/authentication

This example shows how to make an API request using the obtained OAuth2 access token. The token is included in the `Authorization` header as a Bearer token.

```APIDOC
## OAuth2 Authentication (beta)

### Description
Make API requests using the obtained OAuth2 access token.

### Method
GET (example for user endpoint)

### Endpoint
`https://panel.sendcloud.sc/api/v2/user`

### Headers
- `Authorization`: `Bearer <access_token>`

### Request Example
```sh
# Make a request to the Sendcloud API using OAuth2 authentication
curl --location "https://panel.sendcloud.sc/api/v2/user" \
  --header "Authorization: Bearer ${access_token}"
```

### Note
Replace `${access_token}` with the actual access token obtained from the token generation step.
```

--------------------------------

### Address Validation Response Example

Source: https://sendcloud.dev/docs/addresses/address-validation

The response indicates if the input address is valid and provides a list of results, including recommended addresses and analysis.

```json
{
  "input_address_is_valid": true,
  "results": [
    {
      "address": {
        "address_line_1": "Stadhuisplein",
        "house_number": "10",
        "postal_code": "5611 EM",
        "city": "Eindhoven",
        "country_code": "NL"
      },
      "recommended": true,
      "analysis": {
        "validation_result": {
          "is_valid": true,
          "reasons": []
        },
        "changed_attributes": []
      }
    }
  ]
}
```

--------------------------------

### Minimal JSON Request Body for Creating a Shipment

Source: https://sendcloud.dev/docs/shipments/create-a-shipment

This example demonstrates the essential fields required to create a shipment. It is valid for both synchronous and asynchronous API endpoints. Ensure all required fields for 'to_address', 'from_address', 'ship_with', and 'parcels' are correctly populated.

```json
{
  "to_address": {
    "name": "John Doe",
    "company_name": "Sendcloud",
    "address_line_1": "Insulindelaan 115",
    "house_number": "115",
    "postal_code": "5642CV",
    "city": "Eindhoven",
    "country_code": "NL",
    "phone_number": "+31612345678",
    "email": "john.doe@sendcloud.com",
    "po_box": "PO Box 678"
  },
  "from_address": {
    "name": "Marie Doe",
    "company_name": "Sendcloud",
    "address_line_1": "Stadhuisplein 10",
    "address_line_2": "2e verdieping",
    "house_number": "10",
    "postal_code": "5611 EM",
    "city": "Eindhoven",
    "country_code": "NL",
    "phone_number": "+31612345678",
    "email": "marie.doe@sendcloud.com",
    "po_box": "PO Box 478"
  },
  "ship_with": {
    "type": "shipping_option_code",
    "properties": {
      "shipping_option_code": "postnl:standard",
      "contract_id": 517
    }
  },
  "parcels": [
    {
      "weight": {
        "value": "1.320",
        "unit": "kg"
      }
    }
  ]
}
```

--------------------------------

### Retrieve Delivery Options

Source: https://sendcloud.dev/docs/dynamic-checkout/retrieve-delivery-options

Send a GET request to retrieve available delivery options for a given checkout context. This endpoint evaluates a published Dynamic Checkout configuration against shipment details.

```APIDOC
## GET /api/v3/checkout/configurations/{configuration_id}/delivery-options

### Description
Retrieves a list of delivery options available for a specific cart or order context based on a published Dynamic Checkout configuration.

### Method
GET

### Endpoint
/api/v3/checkout/configurations/{configuration_id}/delivery-options

### Parameters
#### Query Parameters
- **configuration_id** (string) - Required - UUID of the published Dynamic Checkout configuration.
- **weight_value** (integer) - Required - Total cart/order weight in grams.
- **total_order_value** (number) - Required - Total cart/order value in the configuration currency.
- **from_country_code** (string) - Required - ISO 3166-1 alpha-2 sender country code.
- **to_country_code** (string) - Required - ISO 3166-1 alpha-2 recipient country code.
- **to_postal_code** (string) - Optional - Recipient postal code.
- **parcel_length** (number) - Optional - Parcel length in centimeters.
- **parcel_width** (number) - Optional - Parcel width in centimeters.
- **parcel_height** (number) - Optional - Parcel height in centimeters.
- **checkout_metadata** (object) - Optional - Custom value used in rule evaluation.
- **checkout_identifier_type** (string) - Optional - Type of the checkout identifier (default: shipping_option_code).

### Response
#### Success Response (200)
- **configuration_id** (string) - The evaluated configuration ID.
- **delivery_options** (array) - A list of available delivery options.
  - **id** (string) - Unique identifier for the delivery option.
  - **checkout_identifier** (string) - Identifier used for shipment creation.
  - Delivery method and carrier information.
  - Pricing details.
  - Estimated delivery timing.

### Request Example
```http
GET https://panel.sendcloud.sc/api/v3/checkout/configurations/YOUR_CONFIGURATION_ID/delivery-options?weight_value=2500&total_order_value=45.90&from_country_code=NL&to_country_code=NL
```

### Response Example
```json
{
  "configuration_id": "YOUR_CONFIGURATION_ID",
  "delivery_options": [
    {
      "id": "delivery_option_1_id",
      "checkout_identifier": "shipping_option_code_1",
      "method": {
        "carrier": "CarrierName",
        "name": "Delivery Method Name"
      },
      "price": {
        "currency": "EUR",
        "amount": 5.99
      },
      "estimated_delivery": "2023-10-27"
    }
  ]
}
```
```

--------------------------------

### Example sender addresses response

Source: https://sendcloud.dev/docs/addresses/sender-addresses

This JSON object illustrates the structure of the response when retrieving sender addresses. It includes details for multiple addresses, each with a unique ID, company information, and location data.

```json
{
  "sender_addresses": [
    {
      "id": 2,
      "company_name": "French Company",
      "contact_name": "Marie Doe",
      "email": "info@sendcloud.fr",
      "telephone": "",
      "street": "Rue Villiers de l\'Isle Adam",
      "house_number": "33",
      "postal_box": "",
      "postal_code": "35000",
      "city": "Rennes",
      "country": "FR",
      "vat_number": "NL123456789B01",
      "coc_number": "NL12345678",
      "eori_number": "NL123456789",
      "brand_id": 1
    },
    {
      "id": 1,
      "company_name": "Sendcloud",
      "contact_name": "John Doe",
      "email": "johndoe@sendcloud.com",
      "telephone": "+31626262626",
      "street": "Bogert",
      "house_number": "115",
      "postal_box": "",
      "postal_code": "5642 CV",
      "city": "Eindhoven",
      "country": "NL",
      "vat_number": "NL123456789B01",
      "coc_number": "NL12345678",
      "eori_number": "NL123456789",
      "brand_id": 2
    }
  ]
}
```

--------------------------------

### OAuth2 Authentication - Token Generation

Source: https://sendcloud.dev/docs/getting-started/authentication

This example demonstrates how to generate an OAuth2 access token using your Sendcloud Public and Private API keys. This token is then used for authenticating subsequent API requests.

```APIDOC
## OAuth2 Authentication (beta)

### Description
Obtain an access token using OAuth2 for token-based authentication.

### Method
POST

### Endpoint
`https://account.sendcloud.com/oauth2/token`

### Headers
- `Content-Type`: `application/x-www-form-urlencoded`

### Request Body
- `grant_type` (string) - Required - `client_credentials`
- `scope` (string) - Required - `api`

### Request Example
```sh
curl -X POST --location "https://account.sendcloud.com/oauth2/token" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&scope=api" \
  --basic --user your_sendcloud_public_key:your_sendcloud_private_key
```

### Response
#### Success Response (200)
- `access_token` (string) - The generated access token.
- `expires_in` (integer) - The token's expiration time in seconds.
- `scope` (string) - The scope of the token.
- `token_type` (string) - The type of the token (e.g., `bearer`).

#### Response Example
```json
{
  "access_token": "ory_at_dK...",
  "expires_in": 3599,
  "scope": "api",
  "token_type": "bearer"
}
```
```

--------------------------------

### Validate an address at checkout

Source: https://sendcloud.dev/docs/addresses/address-validation

Call the validation endpoint with partial address data to get a corrected address. This is useful for guiding end consumers during checkout.

```http
POST /api/v3/addresses/validate
```

```json
{
  "address": {
    "house_number": "10",
    "postal_code": "5611 EM",
    "country_code": "NL"
  },
  "carrier_code": "postnl",
  "validation_methods": ["here"]
}
```

--------------------------------

### Set Up Event Subscriptions

Source: https://sendcloud.dev/docs/getting-started/api-user-flows

Set up real-time parcel event notifications via the Event Subscriptions API. This involves creating a connection, creating a subscription, and testing event delivery.

```mermaid
%%{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
```

--------------------------------

### Get Shipping Options API v3

Source: https://sendcloud.dev/docs/getting-started/api-user-flows

Call the Shipping Option API v3 to get a desired Shipping Option Code. This is the first step in creating a multicollo shipment.

```mermaid
%%{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
```

--------------------------------

### GET Request to Retrieve Tracking Information

Source: https://sendcloud.dev/docs/parcel-tracking/retrieve-tracking-info

Send a GET request to this endpoint, including the tracking number in the URL path. This is used to fetch the current status and full tracking timeline for a parcel.

```http
GET https://panel.sendcloud.sc/api/v3/parcels/tracking/{tracking_number}
```

--------------------------------

### Create or Update Orders in Batch (POST)

Source: https://sendcloud.dev/docs/orders/creating-and-managing-orders

Use this endpoint to create new orders or update existing ones based on order_id and integration.id. It supports batch processing up to 100 orders per request. If a matching order exists, it is updated; otherwise, a new order is created. Requests are all-or-nothing.

```http
POST https://panel.sendcloud.sc/api/v3/orders
```

--------------------------------

### Create Return Label (Asynchronous)

Source: https://sendcloud.dev/docs/returns

Use this endpoint to asynchronously create a return label. This is the recommended endpoint for better performance, provided your data quality is high.

```APIDOC
## POST /v3/returns/create-a-return

### Description
Creates a return label asynchronously.

### Method
POST

### Endpoint
/v3/returns/create-a-return

### Request Body
- **parcel_items** (array) - Required - Details of the items in the parcel.
- **shipping_method** (object) - Required - Information about the desired shipping method.
- **sender_address** (object) - Required - The address of the sender.
- **recipient_address** (object) - Required - The address of the recipient.
- **customs_info** (object) - Optional - Information for customs declarations.

### Response
#### Success Response (202 Accepted)
- **return_id** (string) - The unique identifier for the created return.
- **status** (string) - The current status of the return creation process.
```

--------------------------------

### Validate Address Request Example

Source: https://sendcloud.dev/docs/addresses/address-validation

Send an address to the validate endpoint for verification. Specify the carrier and validation methods.

```http
POST /api/v3/addresses/validate
```

--------------------------------

### Create Return Label (Synchronous)

Source: https://sendcloud.dev/docs/returns

Use this endpoint to synchronously create a return label. This is suitable if you need immediate confirmation of label creation.

```APIDOC
## POST /v3/returns/create-a-return-synchronously

### Description
Creates a return label synchronously.

### Method
POST

### Endpoint
/v3/returns/create-a-return-synchronously

### Request Body
- **parcel_items** (array) - Required - Details of the items in the parcel.
- **shipping_method** (object) - Required - Information about the desired shipping method.
- **sender_address** (object) - Required - The address of the sender.
- **recipient_address** (object) - Required - The address of the recipient.
- **customs_info** (object) - Optional - Information for customs declarations.

### Response
#### Success Response (200 OK)
- **return_id** (string) - The unique identifier for the created return.
- **label_url** (string) - The URL to download the return label.
- **status** (string) - The status of the return.
```

--------------------------------

### Parcel Document API v3

Source: https://sendcloud.dev/docs/getting-started/api-user-flows

Retrieve labels for each parcel by calling GET /api/v3/parcels/{id}/documents/{type} once for each parcel_id.

```APIDOC
## GET /api/v3/parcels/{id}/documents/{type}

### Description
Retrieve a parcel label file.

### Method
GET

### Endpoint
/api/v3/parcels/{id}/documents/{type}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the parcel.
- **type** (string) - Required - The type of document to retrieve (e.g., 'label').
```

--------------------------------

### Retrieve tracking information for a parcel

Source: https://sendcloud.dev/docs/parcel-tracking/retrieve-tracking-info

Send a GET request to retrieve tracking information for a parcel using its tracking number.

```APIDOC
## GET /api/v3/parcels/tracking/{tracking_number}

### Description
Retrieves the current status and full tracking timeline for a given parcel using its tracking number.

### Method
GET

### Endpoint
/api/v3/parcels/tracking/{tracking_number}

### Parameters
#### Path Parameters
- **tracking_number** (string) - Required - The tracking number of the parcel.

### Response
#### Success Response (200)
- **created_at** (string) - When the parcel tracking object was created in Sendcloud.
- **announced_at** (string) - When the parcel was handed to the carrier.
- **updated_at** (string) - Last time tracking information was updated.
- **details** (object) - Additional context such as `expected_delivery_date`, `integration_id`, service point indicators, return flags.
- **tracking_numbers** (array) - Carrier tracking identifiers associated with the parcel.
- **events** (array) - A chronological list of tracking events representing delivery milestones.
- **parent_status** (string) - Carrier status messages standardized into a consistent Sendcloud status.

#### Response Example
{
  "example": "{
    \"created_at\": \"2023-10-27T10:00:00Z\",
    \"announced_at\": \"2023-10-27T11:00:00Z\",
    \"updated_at\": \"2023-10-28T15:30:00Z\",
    \"details\": {},
    \"tracking_numbers\": [\"1Z999AA10123456784\"],
    \"events\": [
      {
        \"timestamp\": \"2023-10-27T11:00:00Z\",
        \"description\": \"Shipment picked up\",
        \"location\": {},
        \"carrier_status_code\": \"PICKUP\"
      },
      {
        \"timestamp\": \"2023-10-28T15:30:00Z\",
        \"description\": \"Out for delivery\",
        \"location\": {},
        \"carrier_status_code\": \"OUT_DELIVERY\"
      }
    ],
    \"parent_status\": \"OUT_DELIVERY\"
  }"
}
```

--------------------------------

### Asynchronous Request for Labels

Source: https://sendcloud.dev/docs/orders/ship-an-order

Use this endpoint for batch shipping up to 20 orders. All orders must belong to the same integration_id. This endpoint fails gracefully if one order fails.

```json
{
  "integration_id": 12345,
  "sender_address_id": 17,
  "orders": [
    {
      "order_id": "ORDER-ID-1"
    },
    {
      "order_number": "ORDER-NUMBER-2"
    }
  ]
}
```

--------------------------------

### Fetch an imported order

Source: https://sendcloud.dev/docs/getting-started/api-user-flows

Retrieve an order that has already been imported into Sendcloud. Use this endpoint to get order details before creating a shipment.

```http
GET /api/v3/orders
```

--------------------------------

### Limit MCP Server Toolsets

Source: https://sendcloud.dev/docs/getting-started/mcp-server

Use the `?toolsets=` query parameter to restrict the connection to a comma-separated list of toolset names. This filters both tool discovery and tool calls.

```bash
# Only the orders and shipments tools
claude mcp add --transport http sendcloud "https://mcp.sendcloud.com/mcp?toolsets=orders,shipments"
```

--------------------------------

### Get Shipping Options (API v3)

Source: https://sendcloud.dev/docs/getting-started/api-user-flows

Retrieve available shipping options from the carrier. Use the `shipping_option_code` from the response in your shipment payload.

```http
POST /api/v3/shipping-options
```

--------------------------------

### Create Shipment with Rules/Defaults (Asynchronous)

Source: https://sendcloud.dev/docs/shipments/shipping-rules-and-shipping-defaults

This endpoint creates a shipment instantly and applies shipping rules and defaults. Shipment announcement status must be polled separately. Recommended for large-scale operations.

```APIDOC
## POST /shipments/create-a-shipment-with-rules-and-or-default-and-announce-it-asynchronously

### Description
Creates a shipment instantly, applying shipping rules and defaults. The announcement status needs to be polled from another endpoint. Recommended for large-scale operations.

### Method
POST

### Endpoint
/shipments/create-a-shipment-with-rules-and-or-default-and-announce-it-asynchronously

### Parameters
#### Request Body
- **to_address** (object) - Required - The recipient's address details.
- **apply_shipping_rules** (boolean) - Optional - Set to `false` to disable shipping rules.
- **apply_shipping_defaults** (object) - Optional - Set to `false` to disable shipping defaults.

### Request Example
```json
{
  "to_address": {
    "name": "John Doe",
    "company_name": "Sendcloud",
    "address_line_1": "Insulindelaan 115",
    "house_number": "115",
    "postal_code": "5642CV",
    "city": "Eindhoven",
    "country_code": "NL",
    "phone_number": "+31612345678",
    "email": "john.doe@sendcloud.com",
    "po_box": "PO Box 678"
  }
}
```

### Response
#### Success Response (200)
- **shipment** (object) - The created shipment object.

#### Response Example
```json
{
  "example": "response body"
}
```
```

--------------------------------

### Validate an address

Source: https://sendcloud.dev/docs/addresses/address-validation

Call this endpoint with partial address input to validate and receive a corrected address. This is ideal for guiding consumers during checkout.

```APIDOC
## POST /api/v3/addresses/validate

### Description
Validates an address and returns a corrected version if found. This is useful for guiding users to enter valid addresses during checkout.

### Method
POST

### Endpoint
/api/v3/addresses/validate

### Parameters
#### Request Body
- **address** (object) - Required - The address details to validate.
  - **house_number** (string) - Required - The house number of the address.
  - **postal_code** (string) - Required - The postal code of the address.
  - **country_code** (string) - Required - The two-letter country code (e.g., NL).
- **carrier_code** (string) - Required - The carrier code for validation (e.g., postnl).
- **validation_methods** (array) - Required - A list of validation methods to use (e.g., ["here"]).

### Request Example
```json
{
  "address": {
    "house_number": "10",
    "postal_code": "5611 EM",
    "country_code": "NL"
  },
  "carrier_code": "postnl",
  "validation_methods": ["here"]
}
```

### Response
#### Success Response (200)
- **recommended** (boolean) - Indicates if a recommended address was found.
- **address** (object) - The validated and potentially corrected address details.
  - **street** (string) - The street name.
  - **house_number** (string) - The house number.
  - **postal_code** (string) - The postal code.
  - **city** (string) - The city.
  - **country_code** (string) - The country code.

#### Response Example
```json
{
  "recommended": true,
  "address": {
    "street": "Stadhuisplein",
    "house_number": "10",
    "postal_code": "5611 EM",
    "city": "Eindhoven",
    "country_code": "NL"
  }
}
```
```

--------------------------------

### Create a shipment with rules and/or defaults and announce it synchronously

Source: https://sendcloud.dev/docs/shipments/print-your-labels

Create a shipment with specified rules or defaults and announce it synchronously. For single-parcel shipments, the label file is immediately available in the response.

```APIDOC
## Create a shipment with rules and/or defaults and announce it synchronously

### Description
Creates a shipment with predefined rules or defaults and announces it synchronously. For single-parcel shipments, the label file is provided in the response.

### Method
POST

### Endpoint
/api/v3/shipments/create-a-shipment-with-rules-and-or-default-and-announce-it-synchronously

### Request Body
[Details of the shipment creation request body, including rules, defaults, and parcel information]

### Response
#### Success Response (200 or 201)
- **parcels** (array) - Contains parcel information, including:
  - **label_file** (string) - The base64 encoded label file for single-parcel shipments.
```