Topic: Frequently asked questions related to custom-shop integrations using Sendcloud APIs.
- Sendcloud API's Quick Start Guide
- Sendcloud API Reference
- Sendcloud Developer's Portal
- Service points for API integrations
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
external_referencefield 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_shipment_idto 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.
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
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 cancel the label before 23:59 on the day of creation. See our documentation on 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 ID still relates to the method you want to use. Shipping method IDs 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
- 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
false. You can find the unique parcel ID (which you'll need in your request) to via the Retrieve all parcels endpoint.
What is the API rate limit?
- GET 420/min
- POST/PATCH/PUT 60/min
- GET 420/min
- POST/PATCH/PUT 100/min -- max burst 15/sec
This is subject to change at the discretion of Sendcloud.
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
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
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
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
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 Settings > Carriers 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
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?
country_state(Required only for Australia, Canada, Italy, and USA.)
What are the API 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. If you get rate limited, we return an empty response with HTTP status code 429.
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.
Our own API's rate limit is 420 rpm for "safe" verbs (GET, HEAD, OPTIONS), and 50rpm for "unsafe" verbs (POST), per access key. 15 POST p/s. We are able to grow both our API rate limits as well as effective throughput at carriers. Leveraging our great relationships with carriers, we are able to scale the throughput by negotiating additional broker contracts, effectively multiplying it.