Skip to main content
Return to top

Sendcloud APIs - FAQ

Louise Thomasson
  • Updated

Topic: In this article we answer the most frequently asked questions related to custom shop integrations using Sendcloud APIs.

What are the rate limits?

Requests to our API are limited on a per Sendcloud account basis. If you have multiple API keys per Sendcloud account, the budget is shared between these keys.

Rate limits

Our API has rate limits that limit the number of requests that can be made per minute. Keep in mind that there are different rate limits for Shipping-related endpoints.

  • Safe requests (GET): 1000 requests per minute
  • Unsafe requests (POST/PATCH/PUT/DELETE): 100 requests per minute.
  • Shipping-related safe requests (GET): 420 requests per minute.
  • Shipping-related unsafe requests (POST/PATCH/PUT/DELETE): 100 requests per minute.

Maximum burst

Endpoints that are considered unsafe have a set burst allowance, which is the maximum number of concurrent requests the API can handle. It allows for a temporary increase in the request rate to accommodate short periods of high traffic without exceeding the overall rate limits.

  • Unsafe requests (POST/PATCH/PUT/DELETE): 15 requests per second.
  • Shipping-related unsafe requests (POST/PATCH/PUT/DELETE): 15 requests per second.
To help prevent any interruptions and maintain optimal API usage, it is essential to stay within the API rate limits. If the limit is surpassed, you will receive an HTTP 429 (Too Many Requests) response.

Read more about rate limiting in our developers documentation.

This is subject to change at the discretion of Sendcloud.

How can I make efficient use of Sendcloud's API?

There are various ways to make efficient use of our API. For instance you can create Parcels in bulk, get newly updated Parcels using the “updated_after” parameter or make use of webhooks to get updates directly pushed to your system.

Do bulk announcements in parallel to our API, in smaller batches. For announcing 100 parcels you could do 5 x batches of 20 calls in parallel to our API.

I want to create labels immediately when I create a parcel via the API. How can I do that? 

To create parcels and shipping labels in a single API call, set the field request_label to 'true' in the request to the Create a parcel endpoint. This process is explained in more detail in our documentation. 

How can I maintain idempotency for orders/shipments that I import or create in Sendcloud?

In the context of APIs, idempotency refers to when making multiple requests has the same effect as a single request. This is to prevent user-error, and in the case of Sendcloud APIs, duplication of orders in our system. There are two endpoints which attempt to be idempotent:

  • Update a parcel
    Use the external_reference field to maintain idempotency. 
  • Create/Update a list of shipments
    This is an upsert endpoint, which means that, if a shipment is found to already exist within the Sendcloud database, the shipment will be updated. If there is no match, it will be created instead. You must use a combination of external_order_id and external_shipment_id to maintain idempotency. Only shipments which have had their updated_at (ISO 8601 DateTime) timestamp changed will be updated. We recommend using a combination of these fields for a robust integration. 

Why is sender_address a required field when creating labels via the API?

Carriers require a sender address to be present on every shipping label to identify where a parcel originated from. If no sender address is specified when you create a parcel via the API, then your default address (as saved in your Sendcloud account) will be used to print the label. We explain how to obtain a sender address ID and the relationship between sender addresses, labels and brands in more detail in our documentation. 

Can I use shipping rules when creating parcels via the API?

Shipping rules will apply to parcels you create via the panel, so long as the field apply_shipping_rules is true. We recommend that you use the shipping method “Unstamped letter” to create your parcels if you want shipping rules to apply correctly to your parcels. This will allow you to bypass the required shipping_method fields, and any rules you have configured that affect shipping method selection will be correctly applied to your parcel. 

Can I test the API without being charged for labels I create? 

You can use the Sendcloud shipping method “Unstamped letter” to create your parcels. This allows you to test the API without running the risk of being charged for any labels you create.

Please note that it's not possible to use this method to test return label creation. To test return shipping labels, use a shipping method which supports cancellation requests from Sendcloud and cancelthe label before 23:59 on the day of creation. See our documentationon test labels for more information. 

I'm receiving the error message “User is not allowed to announce”. What's going wrong?

Make sure you've followed all the steps involved in basic account set-up and activated a direct debit payment method. See: Getting started with Sendcloud. 

Can I see all of my shipping methods via the API when I connect a direct carrier contract?

Yes—if you've connected your own carrier contract, then you'll be able to retrieve your own methods alongside Sendcloud methods by making a GET request to the Retrieve a list of shipping methods endpoint. Note that your contract pricing will not be retrieved unless you've uploaded your own carrier pricing. 

Can I see my own pricing from my direct carrier contracts when I use the API to check rates and compare methods?

Yes, if you've uploaded your own prices to your Sendcloud account by following the steps in this article.  

I'm receiving the error message, “Invalid shipment ID” when I try to create a parcel via the API. What's going wrong?

It's likely that the shipping_method_id you're using refers to a method which does not support shipment to or from the given address, for instance, if you're using a national method for an international shipment. It could also be that you're trying to use a return method for an outgoing shipment, or vice versa. You can use the Shipping products endpoint to find a method that's appropriate for your parcel based on the parameters you define in the request.

Finally, take care that the shipping method name still relates to the method you want to use. Shipping method names in our database are volatile and shouldn't be cached for longer than an hour. 

I successfully created a parcel request, but the parcel does not show in my Sendcloud account. What's going wrong?

It's likely that the request didn't include a value for the boolean field request_label.

  • When this field is true, the label will be printed alongside the request to create a parcel, and the parcel will appear in the Created labels tab in Sendcloud.
  • When the value is false, the parcel object is created but will appear in the Incoming order overview, waiting to be processed.
  • If you didn't add a value, then you can use the Update a parcel endpoint to change the field request_label to true or false.  You can find the unique parcel ID (which you'll need in your request) to via the Retrieve all parcels endpoint. 

Does the API support importation of notes or remarks fields in orders?

Yes. For example, this could be used to add notes to orders, such as “Please gift wrap this item before shipping”. These will also appear on packing slips or picking lists if you use Pack & Go. 

I created a report from the API, but my CSV file is blank. What's going wrong?

Please be aware of the direction filter when you create the request to the reporting endpoint. If you specify the direction as incoming, then you will only see return parcels. If you don't have any return parcels incoming, then the report will be empty.

Secondly, you'll need to specify the integration ID in your request. It's not possible to create a report for all of your integrations, so be sure to specify the correct ID to see your outgoing or incoming parcels per integration. 

How can I find my integration_id?

You can find your integration_idin the Retrieve a list of integrations endpoint, or from your Sendcloud panel (Settings > Integrations > find your integration in the list > Edit). The integration ID will be shown at the end of the URL, e.g. 'https://app.sendcloud.com/v2/settings/integrations/api/95977'

How can I find my sender_address_id? 

Via the Retrieve a list of sender addresses endpoint, or from your Sendcloud panel (Settings > Addresses > Edit an address). The ID will be shown at the end of the URL, e.g. 'https://app.sendcloud.com/v2/settings/addresses/sender/132258'

How can I find my brand_id?

Via the Retrieve configured brands endpoint, or in your Sendcloud panel (Settings > Brands > Edit a brand). The ID will be shown at the end of the URL, e.g. 'https://app.sendcloud.com/v2/settings/brands/86054'

I'm receiving the error message, “Service point delivery is not enabled for this integration.” What's going wrong?

You need to enable service point delivery in the Sendcloud panel, by going to Settings > Integrations > API > Edit > Tick the box to enable service point delivery. This is described in more detail here. 

I don't see methods from all carriers when I make a GET request to Retrieve a list of shipping methods.

First, check that you have enabled all the carriers you want to use by going to Shipping > Carriers & pricing in your Sendcloud account. Use the drop-down menu to select more carriers per each of the countries in which you have an active sender address.

Secondly, you'll need to specify one of your sender addresses in your API call to the Shipping Methods endpoints to see methods for countries other than your default sender address country. For example, if your default sender address is in the Netherlands, but you want to see methods for Royal Mail (UK), you'll need to specify the sender address ID for your UK sender address to retrieve UK applicable methods. This is explained in more detail in our documentation. 

House numbers are duplicated on my shipping labels when I create parcels via the API. What's going wrong?

The most used address format is as follows:

  • address : Stadhuisplein
  • house_number: 10

Another common method is:

  • address: Stadhuisplein 10

Can I create multi-piece (multicollo) shipments via the API?

Yes, you can—this is described in more detail in our documentation. 

Can I assign the same brand to multiple sender addresses?

Yes, you can assign the same brand to some or all of your sender addresses.

Can I assign multiple brands to the same sender address?

Only one brand can be assigned per sender address. The workaround for this is to create a duplicate sender address and assign a different brand to each one. Only one can be specified as your default address, so we recommend giving the duplicate a memorable name, so you can easily identify it in the panel. 

Can I create international shipments via the API?

Yes, absolutely. Your customs documents will be generated automatically, so long as the mandatory fields (see below) are correctly specified per each product included in the shipment. This is explained in more detail in our documentation: International shipping

Which fields are mandatory for international shipping?

  • customs_invoice_number
  • customs_shipment_type
  • country_state(Required only for Australia, Canada, Italy, and USA.)
  • parcel_items
    • origin_country (ISO 2) 
    • hs_code

Related articles and resources

→ Sendcloud API's Quick Start Guide

→ Sendcloud API Reference

→ Sendcloud Developers Portal

→ Service points for API integrations