Sendcloud APIs

https://sendcloud.dev/docs/
Admin
Sendcloud is an all-in-one shipping solution for e-commerce, automating processes and consolidating...
Tokens:95,349
Snippets:682
Trust Score:7.1
Update:1 month ago
Show doc for...
Tokens:
Raw
### 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"
    }
  ]
}
```

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

### 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
```

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

### Example request payload for shipping options

Source: https://sendcloud.dev/docs/shipments/shipping-options-and-quotes

Example JSON request payload for the Return a list of available shipping options endpoint. Includes from_address and to_address objects with country_code, postal_code, and city, plus carrier_code and calculate_quotes. Providing more address details improves pricing accuracy.

```json
{
  "from_address": {
    "country_code": "NL",
    "postal_code": "1012AB",
    "city": "Eindhoven"
  },
  "to_address": {
    "country_code": "NL",
    "postal_code": "2000AB",
    "city": "Amsterdam"
  },
  "carrier_code": "dhl",
  "calculate_quotes": true
}
```

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

### Example request: Search with integration carriers

Source: https://sendcloud.dev/docs/service-points/find-service-points-with-the-api

Performs a GET request to the service points endpoint using the carriers configured for your integration. The address, country_code, and use_integration_carriers=true parameters are required.

```HTTP
GET https://panel.sendcloud.sc/api/v3/service-points?country_code=NL&address=Stadhuisplein%2010%2C%20Eindhoven&use_integration_carriers=true
```

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

### Example response body - service points found

Source: https://sendcloud.dev/docs/service-points/find-service-points-with-the-api

Example response body for a successful service point search. The closest matching service points are returned first. Check `data.geocoding` to see how the address was resolved: `status` indicates whether the address was matched, partially matched, or not found; `precision` shows how precisely the location was resolved; `formatted_address` shows the address the search was based on.

```json
{
  "data": {
    "results": [
      {
        "id": 1000001,
        "name": "Stadhuisplein Parcel Shop",
        "carrier": {
          "code": "postnl",
          "name": "PostNL",
          "logo_url": <...>,
          "icon_url": <...>
        },
        "carrier_service_point_id": "NL-00001",
        "address": {
          "street": "Stadhuisplein",
          "house_number": "1",
          "postal_code": "5611EM",
          "city": "Eindhoven",
          "country_code": "NL"
        },
        "position": {
          "latitude": 51.438022,
          "longitude": 5.478543
        },
        "opening_times": <...>,
        "is_open_tomorrow": true,
        "next_open_at": "2026-03-11T09:00:00+01:00",
        "is_expired": false,
        "distance": 85
      },
      <...>
    ],
    "geocoding": {
      "status": "matched",
      "precision": "house_number",
      "formatted_address": "Stadhuisplein 10, 5611 EM Eindhoven, Nederland"
    }
  }
}
```

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

### Example response - no matching service points

Source: https://sendcloud.dev/docs/service-points/find-service-points-with-the-api

Example response when no service points match the search, but the address was resolved successfully. An empty `results` list does not necessarily mean the address could not be found. Check `data.geocoding.status` to distinguish between a resolved address and one that could not be resolved. If the status is `matched` or `partially_matched`, the location was resolved but no service points matched the search.

```json
{
  "data": {
    "results": [],
    "geocoding": {
      "status": "matched",
      "precision": "house_number",
      "formatted_address": "Stadhuisplein 10, 5611 EM Eindhoven, Nederland"
    }
  }
}
```

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

### Example response - address not found

Source: https://sendcloud.dev/docs/service-points/find-service-points-with-the-api

Example response when the address itself could not be resolved. `data.geocoding.status` is `not_found`. In a customer-facing flow, ask the customer to review the address and try again. In other flows, handle the unresolved address according to your integration's fallback logic.

```json
{
  "data": {
    "results": [],
    "geocoding": {
      "status": "not_found",
      "precision": null,
      "formatted_address": null
    }
  }
}
```

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

### Inspect the validation response

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

Example response from the validate endpoint. Shows the structure with input_address_is_valid, results array, recommended flag, and analysis details including validation_result, changed_attributes, and invalid_attributes.

```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": [],
        "invalid_attributes": []
      }
    }
  ]
}
```

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

### API v2 response structure

Source: https://sendcloud.dev/docs/getting-started/migration-guidelines-for-api-v3

Example of the API v2 service points list response, which returned a bare array of service point objects with flat fields like carrier, street, city, latitude, and longitude.

```json
[
  {
    "id": 10875349,
    "carrier": "postnl",
    "street": "Voorbeeldstraat",
    "city": "EINDHOVEN",
    "latitude": "51.441444",
    "longitude": "5.475185",
    <...>
  }
]
```

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

### API v3 response structure

Source: https://sendcloud.dev/docs/getting-started/migration-guidelines-for-api-v3

Example of the API v3 service points list endpoint response, which wraps results under data.results and includes geocoding information under data.geocoding. Related fields are grouped into carrier, address, position, and contact objects.

```json
{
  "data": {
    "results": [
      {
        "id": 10875349,
        "carrier": {
          "code": "postnl",
          "name": "PostNL",
          "logo_url": <...>,
          "icon_url": <...>
        },
        "address": {
          "street": "Voorbeeldstraat",
          "city": "Eindhoven",
          <...>
        },
        "position": {
          "latitude": 51.441444,
          "longitude": 5.475185
        },
        "contact": {
          <...>
        },
        <...>
      }
    ],
    "geocoding": {
      <...>
    }
  }
}
```

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

### Partially matched address response

Source: https://sendcloud.dev/docs/getting-started/migration-guidelines-for-api-v3

Example response when the address is only partially matched. The geocoding status is partially_matched, precision is postal_code, and the formatted_address shows the resolved location. The search still returns service points.

```json
{
  "data": {
    "results": [
      <...>
    ],
    "geocoding": {
      "status": "partially_matched",
      "precision": "postal_code",
      "formatted_address": "5611, Eindhoven, Noord-Brabant, Nederland"
    }
  }
}
```

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

### Example request: Use specific carriers

Source: https://sendcloud.dev/docs/service-points/find-service-points-with-the-api

Performs a GET request to the service points endpoint using specific carrier codes (carrier_code=postnl and carrier_code=dhl) instead of the integration carriers.

```HTTP
GET https://panel.sendcloud.sc/api/v3/service-points?country_code=NL&address=Stadhuisplein%2010%2C%20Eindhoven&carrier_code=postnl&carrier_code=dhl
```

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

### Open the service point picker with sendcloud.servicePoints.open()

Source: https://sendcloud.dev/docs/service-points/integrate-the-hosted-service-point-picker-into-your-checkout

Displays the hosted service point picker. The method takes three arguments: a configuration object, a success callback, and a failure callback.

```js
sendcloud.servicePoints.open(config, onSuccess, onFailure)
```

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

### 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
```

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

### POST /api/v3/shipping-options - Example request method and URL

Source: https://sendcloud.dev/docs/service-points/create-a-shipment-with-service-point-delivery

Use this HTTP request to find shipping options for a selected service point. The endpoint is 'Return a list of available shipping options'. The request method is POST and the URL is 'https://panel.sendcloud.sc/api/v3/shipping-options'.

```http
POST https://panel.sendcloud.sc/api/v3/shipping-options
```

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

### 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
```

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

### Create and announce a shipment with service point delivery

Source: https://sendcloud.dev/docs/service-points/create-a-shipment-with-service-point-delivery

Use the Create and announce a shipment synchronously endpoint to create and announce a shipment with service point delivery. Include the selected service point id in to_service_point.id and the shipping option code from Find a shipping option in ship_with.properties.shipping_option_code. Some service points require a post number, which is passed as to_address.po_box.

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

```json
{
  "to_address": {
    "name": "John Doe",
    "address_line_1": "Stadhuisplein",
    "house_number": "10",
    "postal_code": "5611EM",
    "city": "Eindhoven",
    "country_code": "NL",
    "email": "john.doe@example.com"
  },
  "from_address": {
    "sender_address_id": 42
  },
  "to_service_point": {
    "id": "1000001"
  },
  "ship_with": {
    "type": "shipping_option_code",
    "properties": {
      "shipping_option_code": "postnl:pakjegemak"
    }
  },
  "parcels": [
    {
      "weight": {
        "value": "1.500",
        "unit": "kg"
      }
    }
  ]
}
```
Tokens:
Raw