Sendcloud APIs - FAQ

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

What are the rate limits?

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.

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.

Read more about rate limiting in our developers documentation.

This is subject to change at the discretion of Sendcloud.

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

To create shipments and shipping labels in a single API call, use the synchronous endpoint of the Shipments or Ship an Order API. The label will be automatically returned in the response in the data.parcels.label_file field. This is only available for Single Collo shipments (shipment composed of one parcel only).

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 four endpoints which attempt to be idempotent:

• All POST shipments endpoints
  Use the external_reference_id field to maintain idempotency. 

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

Shipping rules will apply to shipments you create via the API, so long as you create shipments using the Create a shipment with rules and/or defaults synchronously or asynchronously endpoints. We recommend that you use the shipping option “Unstamped letter” ("shipping_option_code": "sendcloud:letter") to create your shipments if you want shipping rules to apply correctly. This will allow you to bypass the required ship_with object, and any rules you have configured that affect shipping option 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 option “Unstamped letter” ("shipping_option_code": "sendcloud:letter") to create your shipments. 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 shipping option to test return label creation. To test return shipping labels, use a shipping option 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 options 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 shipping options alongside Sendcloud shipping option by making a request to the Shipping options API 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, “No shipping option could be found for[…]” when I try to create a shipment via the API. What's going wrong?

It's likely that the shipping_option_codeyou're using refers to a shipping option 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 shipping option for an outgoing shipment, or vice versa. You can use the Shipping options endpoint to find a shipping option that's appropriate for your shipment based on the parameters you define in the request.

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. 

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 Developer's Portal

→ Service points for API integrations