Masterarbeit

Search

SearchSearch

Sendcloud API

Jun 20, 202435 min read

Search Link: https://www.google.com/search?channel=fs&client=ubuntu-sn&q=postman+collection+17867205-42468079-d6a1-4cf8-9e9f-6d7b1f3cc111

Overview

GET /reporting/parcels/{report_id}

Summary: Retrieve Parcels Report

Get parcels report

Once you’ve created a parcel report, use this endpoint to generate a URL which will allow you to download it in CSV format. The report id is the one you obtained via the Create parcels report endpoint:

"id": "9d2e0de3-204e-4edf-992f-71dd624f8e2e",

Depending on the size of the report, it may not be immediately available for download. The status of the report is indicated in the response:

  "status_message": "The report is ready",

The report will expire after a certain amount of time, after which you will have to generate it again. The time of expiry is indicated in the response body:

"expires_at": "2022-05-24T16:10:21.084724",

Example:

GET https://panel.sendcloud.sc/api/v2/reporting/parcels/9d2e0de3-204e{...}71dd624f8e2e

PARAMETERS /reporting/parcels/{report_id}

POST /reporting/parcels

Summary: Create Parcels Report

This endpoint allows you to generate a CSV report containing information about outgoing or incoming parcels. The parcels included in the report will depend on the filters provided, and the columns will be determined by the fields parameter.

Use this endpoint to create the report and obtain the report id, which you will use to obtain the actual CSV download via the Get parcels report endpoint.

GET /user/invoices/{id}

Summary: Retrieve a specific invoice

Retrieve a single invoice issued to your Sendcloud account. You need to provide the invoice id to fetch details of a specific invoice. You can retrieve an invoice id via the Retrieve all invoices endpoint.

PARAMETERS /user/invoices/{id}

GET /user/invoices

Summary: Retrieve all invoices that have been issued to your account

With this endpoint, you can retrieve all of the invoices and the associated invoice id which have been issued to your account to date.

GET /brands/{id}

Summary: Retrieve a brand

Retrieves a user’s configured brand and its properties, identified by its unique ID

PARAMETERS /brands/{id}

GET /brands

Summary: Retrieve a list of brands

Retrieves a list of all brands and their associated properties.

GET /user

Summary: Retrieve the current user data

Use this endpoint to request the data connected with your user account. The response includes your invoice address details, your Sendcloud username, a list of all the invoices, and the associated invoice id issued on your account.

POST /parcels/{id}/cancel

Summary: Cancel a parcel

You can use this endpoint to:

  1. Cancel an announced parcel; or,
  2. Delete an unnanounced parcel

Cancelling a parcel

When you cancel a parcel which is already announced (has a shipping label attached to it), you will still be able to find it via the parcel_id and the Retrieve a parcel endpoint. In the Sendcloud panel, it will appear in your Cancelled labels overview.

Insurance Notice: If you proceed to ship a parcel that was initially cancelled, the parcel’s insurance coverage will become void, and any insurance claims will not be valid for that shipment.

After 42 days, it’s no longer possible to cancel a parcel, even if it hasn’t been shipped.

Deleting a parcel

When you delete a parcel which hasn’t been announced, the parcel will be removed from the Sendcloud system and you will no longer be able to locate it via the parcel id. You will need to create the parcel again if you want to announce it at a later date.

Conditions for label cancellation

It’s not always possible to cancel a parcel which is aleady announced. As a result, cancellation is not guaranteed and may be asynchronous depending on the state of the parcel. When you send a cancellation request via this endpoint, the response will indicate the status of the cancellation request.

Each carrier will have different cancellation deadlines. Some carriers do not accept cancellation requests regardless of whether or not the label is cancelled within the deadline. You can find more information about cancellation deadlines on our Help Center.

PARAMETERS /parcels/{id}/cancel

GET /parcels/{id}/return_portal_url

Summary: Retrieve a return portal URL

This endpoint lets you see which of your branded Return portals is associated with a specific parcel based on the provided parcel id. The URL which is retrieved will link directly to the parcel in the Sendcloud Return portal, so a return parcel can be created immediately based on the outgoing shipment. If no Return portal is configured, or if no brand is connected to the parcel, this endpoint will return a status code 404 error.

PARAMETERS /parcels/{id}/return_portal_url

GET /parcels/{id}

Summary: Retrieve a parcel

This endpoint allows you to retrieve a specific parcel created under your Sendcloud credentials, based on the parcel id.

PARAMETERS /parcels/{id}

GET /parcels

Summary: Retrieve parcels

This endpoint allows you to retrieve a list of all the parcels which you have created or imported into your Sendcloud account under your API credentials. You can filter the results based on the query parameters provided below, in order to retrieve a specific parcel or list of parcels which match the defined criteria.

PUT /parcels

Summary: Update a parcel

This endpoint allows you to update a parcel which has not yet been announced, either to make changes to the original parcel data, or to request a shipping label if one hasn’t yet been created. You’ll need to include the parcel_id of the parcel you wish to update, which you can retrieve via the Get all parcels endpoint. Note that, when updating a parcel with a quantity higher than 1 (e.g. a multi-collo shipment), setting request_label=true is not allowed, since multiple parcels will be returned.

Once a parcel is announced and a label is created, it’s not possible to make further changes via this endpoint.

Change address or parcel details

If you need to make adjustments to details in the original parcel, such as customer address details, shipping method, etc., you can do so by adding any of the post request parameters listed under Create a parcel. The post request parameters must be nested under a parcel object.

Create a shipping label for a parcel which is not yet announced**:

Use this endpoint to update the request_label: false parameter to truefor parcels which you chose not to announce at the time of parcel creation, and which now need a shipping label.

{
  "parcel": {
	"id": 184063539,
	"request_label": true
  }
}

The shipping label will be announced and can be downloaded via the Get a PDF label endpoint.

POST /parcels

Summary: Create a parcel

This endpoint creates a parcel under your API credentials.

  • You can choose to announce the parcel and create the shipping label at the same time as you create the parcel by providing the parameter request_label: true.

  • When request_label is false, you can create the parcel but it will not be announced.

  • You can then request the shipping label at a later date by changing the request_label parameter via the Update a parcel endpoint.

Pay attention to enter the correct sender_address if you wish to ship this parcel from a location other than your default sender address. You can find the sender_address for each of the addresses you’ve saved in your Sendcloud account via the Retrieve a sender address endpoint.

International parcel creation

If you want to create a parcel to ship to a destination country outside the EU, it’s mandatory to include additional information related to the parcel contents. This allows Sendcloud to automatically generate the required customs documentation based on the international shipping method selected. After the shipping label and associated documents are generated, you can retrieve and download them via the Parcel documents endpoint.

If you have more than one added active contracts for specific carrier, you must fill contract attribute with your desired contract’s ID in your request. You can get your contracts ID from Retrieve a list of contracts.

International parcels require more information than domestic parcels. Certain customs documents must be created when shipping to countries outside the EU. For Sendcloud to successfully generate these documents, all the necessary information must be available in your parcel request. For more in-depth information on international shipping and the requirements, please check our developers portal.

Multicollo

More information on how to create multiple parcels within one shipment can be found on the related page of our developers portal.

GET /shipping-price

Summary: Retrieve a shipping price

This endpoint retrieves shipping rate information for a specific shipping_method_id and from_country.

For users that have uploaded their own prices, the response will show the prices that have been uploaded. The response is an Array of prices for all available receiver countries. If to_country query parameter is present, the Array will only contain one item.

price and currency will be null when no pricing is available for a receiver country.

If you have more than one added active contracts for specific carrier, you must fill contract attribute with your desired contract’s ID in your request. You can get your contracts ID from Retrieve a list of contracts.

In order to view remote surcharges, you are required to provide the to_country and to_postal_code. Similarly, to access zonal prices, you need to provide to_country, from_postal_code and to_postal_code. This information ensures accurate and customized pricing based on the specific location, enabling you to understand any additional charges associated with remote areas and access pricing based on their designated zones.

GET /shipping-products

Summary: Retrieve a list of shipping products

This endpoint allows you to retrieve a list of shipping methods that are associated with your default sender address, filtered by specific criteria such as parcel dimensions, weight classes, from and to country and shipping functionality.

In situations where you need to find a method which supports a specific means of delivery, type of parcel or delivery deadline, for example, this endpoint allows you to filter all available shipping methods based on one or more query parameters.

The response body will include the id of any suitable methods, which you can then use to Create a parcel and announce the shipment directly.

You must have either enabled a carrier in your Sendcloud account, or connected your own direct carrier contract, in order to be able to retrieve shipping methods related to that carrier via this endpoint.

If you have more than one added active contracts for specific carrier, you must fill contract attribute with your desired contract’s ID in your request. You can get your contracts ID from Retrieve a list of contracts.

To see zonal carrier shipping methods, you need to provide from_postal_code and to_postal_code query parameters.

To filter by {shipping_functionality}, you can find a glossary of accepted values and a description of each functionality under the Retrieve a list of shipping functionalities endpoint.

Use cases

Find a shipping method id for a parcel weighing 5kg, shipping from the Netherlands to the United States with carrier PostNL.

GET https://panel.sendcloud.sc/api/v2/shipping-products?from_country=NL&to_country=US&carrier=postnl&weight=5&weight_unit=kilogram

Find a shipping method which includes the Age Check functionality for shipping alcohol products from France to Belgium.

GET https://panel.sendcloud.sc/api/v2/shipping-products?from_country=NL&to_country=BE&age_check=18

Find a shipping method that supports same day delivery for a product shipping from the Netherlands to the Netherlands.

GET https://panel.sendcloud.sc/api/v2/shipping-products?from_country=NL&to_country=NL&delivery_deadline=sameday

Find a return shipping method for a parcel returning from France to the Netherlands:

GET https://panel.sendcloud.sc/api/v2/shipping-products?from_country=FR&to_country=NL&returns=true

GET /shipping-functionalities

Summary: Retrieve a list of shipping functionalities

This endpoint lists all of the available shipping functionalities across the Sendcloud system. A shipping functionality is an additional characteristic or ‘add on’ service that defines one shipping method from another. Some functionalities are related to the form of the shipment that’s accepted for shipment, such as letterbox, parcel or pallet, while other functionalities specify any additional handling that’s required, such as Age check or Signature required. Functionalities can also denote specific delivery deadlines or weekend delivery availability.

The below Glossary of shipping functionalities provides a description of every possible shipping functionality associated with a Sendcloud-supported shipping method.

Shipping functionalityDescription
age_checkIndicates whether the recipient must be above a certain age (e.g., to accept alcohol products).
b2bIndicates whether the shipment is a b2b shipment.
b2cIndicates whether the shipment is a b2c shipment.
boxableIndicates whether the shipment fits in a box.
bulky_goodsIndicates whether the shipment is bulky, e.g. it does not fit in a box.
carrier_billing_typeIndicates whether the shipment is billed on a country to country basis, or based on a shipping zone to shipping zone. Example is shipping from mainland Spain to the Canary Islands (a zone) or Netherlands to the Netherlands (country to country).
cash_on_deliveryIndicates whether the receiver of the shipment should pay for the shipment when receiving it.
dangerous_goodsIndicates whether the shipment can contain dangerous goods.
delivery_attemptsIndicates the number of delivery attempts the carrier should attempt before returning (or discarding) the parcel.
delivery_beforeIndicates whether shipment will be delivered before a certain time of the day (Example: before 12:00).
delivery_deadlineIndicates the period of time in which the shipment will be delivered (Example: 24 hours, 28 hours).
direct_contract_onlyIndicates whether shipping is only possible using your own carrier contract, or if it is possible using Sendcloud contract rates.
eco_deliveryIndicates whether the shipping process will be environmently friendly.
ersIndicates whether shipment will use the ERS (Easy Return Solution) system.
first_mileIndicates how transportation of the first mile of the shipment will take place. Example is that the parcel is dropped of at a service point, or is picked up by the carrier.
flex_deliveryIndicates whether the receiver of the parcel can, before delivery takes place, choose where and when the shipment should be delivered.
form_factorIndicates the form factor of the parcel. Examples are letter, pallet, parcel.
fragile_goodsIndicates whether shipment can contain fragile goods (glass, electronics, etcetera).
fresh_goodsIndicates whether shipment can contain fresh goods (e.g. food with an expiration date).
harmonized_labelIndicates whether shipment label contains the customs information on as well.
id_checkIndicates whether the receiver should identify him/herself to the carrier driver, conforming the identity of the receiver.
incotermIndicates what incoterm is used for an (international) shipment. Mainly used to determine if the receiver or the sender pays the customs duties.
insuranceIndicates whether the shipment has carrier insurance or not.
labellessIndicates whether a return shipment can be done using only a QR code or numerical number, needed by the end-consumer to return the parcel. In other words, no shipping label is required.
last_mileIndicates what the last mile of the shipment looks like. For instance, the shipment can be delivered to a service point or a home address.
manuallyIndicates a subset of Deutsche Post shipping methods where a consumer should manually attach the label to the parcel.
multicolloIndicates whether the shipment can be a multi-collo shipment. Note: Not all carriers support multicollo shipment. See the supported carriers and more in our help center
neighbor_deliveryIndicates whether shipment is allowed to be delivered at the neighbours of the receiver.
non_conveyableIndicates whether the shipment fits on a conveyor belt.
personalized_deliveryIndicates a subset of Deutsche Post shipping methods shipping to a consumer.
premiumIndicates whether the carrier identifies the shipments shipping process as premium.
priorityIndicates the priority level of the shipment. Examples are Express or Standard.
registered_deliveryIndicates whether a Proof of Delivery (POD) is communicated to the sender.
returnsIndicates whether the shipment should be a return shipment or not.
segmentIndicates the international pricing zone for PostNL shipments.
service_areaIndicates the service area of the shipment. Examples are domestic or international.
signatureIndicates whether the shipment requires a signature upon delivery.
sizeIndicates the allowed size of the shipment.
sortedIndicates whether the shipment(s) are handed over the carrier in a sorted fashion, decreasing costs.
surchargeIndicates whether the carrier can surcharge the shipment later, based on (volumetric) weight.
trackedIndicates whether the shipment can be tracked online.
tyresIndicates whether the shipment can be used to ship tyres.
weekend_deliveryIndicates whether shipment can delivery in the weekend or on a specific weekend-day.

GET /parcels/statuses

Summary: Retrieve a list of parcel statuses

Retrieve a list of all possible parcel statuses.

GET /labels/{parcel_id}

Summary: Retrieve a Label

Retrieve a shipping label for a specific parcel in PDF format. You can lookup the id of a parcel via the /parcels endpoint.

PARAMETERS /labels/{parcel_id}

GET /labels/normal_printer/{parcel_id}

Summary: Retrieve a PDF label

Retrieve a shipping label for a specific parcel in PDF format for a normal printer.

PARAMETERS /labels/normal_printer/{parcel_id}

GET /labels/normal_printer

Summary: Retrieve multiple PDF labels

Retrieve PDF label documents suitable for normal printers for multiple different parcels at the same time.

GET /labels/label_printer/{parcel_id}

Summary: Retrieve a PDF label for a specific label printer

Retrieve a shipping label for a specific parcel in PDF format for a label printer.

PARAMETERS /labels/label_printer/{parcel_id}

GET /labels/label_printer

Summary: Retrieve a PDF label for a label printer

Retrieve PDF label documents suitable for label printers for multiple different parcels at the same time.

POST /labels

Summary: Bulk PDF label printing

Request multiple shipping labels for an array of parcels at the same time.

GET /customs_declaration/normal_printer/{parcel_id}

Summary: Retrieve a customs declaration PDF

Retrieve the customs documents associated with a label in PDF format for a normal printer.

PARAMETERS /customs_declaration/normal_printer/{parcel_id}

GET /customs_declaration/normal_printer

Summary: Retrieve multiple customs declaration PDF

This endpoint is deprecated as of Mon, 08 Jan 2024 00:00:00 GMT. We will sunset this enpoint Mon, 08 Jul 2024 00:00:00 GMT. It is recommended to use the Retrieve Parcel Documents endpoint instead.

Retrieve PDF customs documents suitable for normal printers for multiple different parcels at the same time.

GET /parcels/{id}/documents/{type}

Summary: Retrieve Parcel Documents

For international shipments, a commercial invoice, CN23 or CN22 (+CP71) form must be attached (either physically or digitally for some carriers) to the shipment for customs officials to access. The type of document required depends on the shipping method and value of the shipment.

When you Create a parcel, Sendcloud generates the correct type of document for your shipment if you have filled in all the information related to the parcel contents, value, and invoice. Use this endpoint to retrieve these documents in your preferred format.

The supported document types are as follows:

  • air-waybill
  • cn23
  • cn23-default
  • commercial-invoice
  • cp71
  • label
  • qr

PARAMETERS /parcels/{id}/documents/{type}

POST /box/finalize

Summary: Finalizing a box

This endpoint allows you to create an Air Waybill for a box containing multiple Deutsche Post International parcels. When you call this endpoint, you finalize the box, then an AWB tracking number is assigned to each parcel and the AWB label is generated. If the parcels included in the AWB are split over multiple boxes or pallets, you can use the copy_count parameter to specify how many AWB copies you need.

When the request is successful, a 200 code will be returned alongside the copy_count requested. After a few minutes, the AWB labels and tracking numbers are assigned to each parcel. You only need to retrieve any single parcel to obtain the AWB label, as the AWB label and tracking numbers are identical for all parcels included in the box.

GET /shipping_methods/{id}

Summary: Retrieve a shipping method

This endpoint will return information about a shipping method based on the provided shipping method id and your default sender address.

As described in Retrieve a list of shipping methods, to retrieve information about a shipping method which operates in a different country than your default sender address, provide a different sender_address id.

To see zonal carrier shipping methods, you need to provide to_country, from_postal_code and to_postal_code query parameters.

Example:

GET https://panel.sendcloud.sc/api/v2/shipping_methods/365?sender_address=102964

{
	"shipping_method": {
		"id": 365,
		"name": "Colissimo Service Point 0.75-1kg",
		"carrier": "colissimo",
		"min_weight": "0.751",
		"max_weight": "1.001",
		"service_point_input": "required",
		"price": 0,
		"countries": [

PARAMETERS /shipping_methods/{id}

GET /shipping_methods

Summary: Retrieve a list of shipping methods

This endpoint will return a detailed list of all the shipping methods which are available to you under your Sendcloud credentials. You can use this endpoint to find a specific shipping method id, which you can then specify in your request to Create a parcel.

If a shipping method id value is present, and if the request_label parameter has the value true, then a shipping label is created and the parcel is announced.

The shipping methods returned are based on the following factors:

  1. The carriers you have enabled in your Sendcloud account;
  2. (Optional) The direct carrier contracts you have connected; and,
  3. Your sender address

Tip: Via this endpoint you can only retrieve shipping methods based on three parameters: sender_address, service_point_id and is_return. If you need to filter the results because you require a method which contains a specific shipping functionality or other criteria, you can refer to the Retrieve a list of shipping products endpoint.

In order to view remote surcharges, you are required to provide the to_country and to_postal_code. Similarly, to access zonal prices, you need to provide to_country, from_postal_code and to_postal_code. This information ensures accurate and customized pricing based on the specific location, enabling you to understand any additional charges associated with remote areas and access pricing based on their designated zones.

Specifying a sender address

You can have multiple sender addresses stored in your Sendcloud account. This endpoint will return the shipping methods associated with your default sender address, unless you provide a specific sender_adress id.

Tip: You can find the id for each of your sender addresses via the Retrieve a single sender address endpoint.

Use case

For example, your default sender address may be based in the Netherlands, but you have a second sender address based in Austria. If you don’t specify a sender_address id, this endpoint will only return shipping methods applicable for shipments from the Netherlands.

To see shipping methods applicable for Austria, e.g. from DPD Austria, specify the id for your Austrian sender address in the HTTP request. The retrieved results will now include carriers such as Post AT, DPD Austria, etc, depending on your enabled carriers.

Example:

GET https://panel.sendcloud.sc/api/v2/shipping_methods?sender_address={ID}

Use cases

  • Find a service point delivery shipping method

If you want to retrieve a list of shipping methods which are applicable for service point delivery, provide a service_point_id in the request. You can find an appropriate service_point_id via the Service Points API.

  • Find a suitable shipping method for a return

Return shipping methods are treated differently than methods for outgoing parcels. If you want to filter the results to show only the methods which you can apply to return parcels, include the argument is_return: "true".

  • Invalid shipment ID Error message If you try to Create a parcel but receive the error message “Invalid shipment id”, this could be because the specified id relates to a shipping method which is not possible for the given destination address.

For example, if you need to ship a parcel internationally but the specific shipping method only supports national (domestic) shipping, then you would need to lookup a new shipping method id which supports method of delivery and change the request.

GET /pickups/{id}

Summary: Retrieve a pickup

This endpoint allows you to retrieve information about a specific pickup based on the pickup id.

PARAMETERS /pickups/{id}

GET /pickups

Summary: Retrieve a list of pickups

This endpoint retrieves information about all the pickups which have been created from your account. This is limited to the carriers which support pickups via the API. The response includes information about when the pickup was scheduled, the latest status, the parcel tracking number and the time frame in which the pickup is due to take place.

POST /pickups

Summary: Create a pickup

This endpoint allows you to schedule a pickup with a supporting carrier. You can schedule the pickup to take place from a location and time of your choosing, and include any additional instructions to the driver by including the special_instructions parameter. When a pickup is successfully scheduled a pickup id will be returned.

If you have more than one added active contracts for specific carrier, you must fill contract attribute with your desired contract’s ID in your request. You can get your contracts ID from Retrieve a list of contracts.

GET /insights/carriers/transit-times

Summary: Retrieve Carriers transit times

This endpoint retrieves the average transit time of a parcel per selected carrier code. You can filter the results by origin and destination country, as well as by start and end dates.

GET /insights/shipping-methods/transit-times

Summary: Retrieve Shipping method transit times

This endpoint retrieves the average transit time of a parcel per selected shipping method and carrier code. You can filter the results by origin and destination country, as well as start and end dates.

GET /brand/{brand_domain}/return-portal/outgoing

Summary: Retrieve an outgoing parcel

This endpoint returns all the necessary data from the outgoing parcel. It takes two mandatory query parameters: either the tracking number or the order number, and the postal code. On a successful lookup, along with the parcel data, you will receive two JWT tokens: one for the incoming parcel creation, and one for service points lookup.

PARAMETERS /brand/{brand_domain}/return-portal/outgoing

POST /brand/{brand_domain}/return-portal/incoming

Summary: Create a return

This endpoint creates a new return parcel based on an outgoing parcel. The outgoing parcel and related data needed to make a request to this endpoint can be retrieved with /brand/{brand_domain}/return-portal/outgoing. This also returns the JWT Token needed for authentication with this endpoint

PARAMETERS /brand/{brand_domain}/return-portal/incoming

POST /brand/{brand_domain}/return-portal/rule-modifications

Summary: Apply return rules

This endpoint evaluates return rules against the data provided in the request. Returns the new values to set on the fields and instructions for next steps.

PARAMETERS /brand/{brand_domain}/return-portal/rule-modifications

GET /brand/{brand_domain}/return-portal/label/polling

Summary: Retrieve the status of a return

Once a return parcel is successfully created, a polling URL is included in the response. Creating a label depends on the response time of the carrier, so you need to make a request to this endpoint to see the status of the label. The URL you received contains a token with the id, so you don’t need to provide any additional lookup details or authentication.

  • A 200 response will indicate that the label is ready and can be downloaded.
  • A 202 response will indicate that the label is not ready to be downloaded but the return data has been accepted. If you have paid returns enabled this status is used to indicate we are waiting for payment. For more information take a look at this help center article.
  • A 500 response means that the label announcement failed.

PARAMETERS /brand/{brand_domain}/return-portal/label/polling

GET /brand/{brand_domain}/return-portal/label/download

Summary: Retrieve a return label

Once a return parcel is successfully created and announced to the carrier, the label will be ready to download. This endpoint returns the results from announcing the parcel, including the url to download the label itself. The URL for calling this endpoint is part of the response to /brand/{brand_domain}/return-portal/label/polling and does not need to be formed manually.

PARAMETERS /brand/{brand_domain}/return-portal/label/download

POST /brand/{brand_domain}/return-portal/uploads

Summary: Create a file upload for the return portal

Currently only used for images, this endpoint allows users to upload media that may be used during the return creation purposes. The response from this endpoint contains filenames used to identify the files in later requests.

Note:

  • Files are only kept for 48 hours after upload, unless used somewhere else (for example, when creating a return).
  • The URLs returned in this response will only be available for 48 hours.
  • This endpoint allows a maximum of 10 files, so groups larger than that should be batched.
  • Files should be smaller than 10MB.

Note: This API is currently in in beta, and may change in the near future.

PARAMETERS /brand/{brand_domain}/return-portal/uploads

GET /brand/{brand_domain}/return-portal

Summary: Retrieve return portal settings

This endpoint will retrieve information about the settings you have configured for your Sendcloud-hosted Returns Portal. This includes branding details, delivery options and return methods. Due to the public nature of this API, you could potentially utilize these for your own self-hosted returns solution.

PARAMETERS /brand/{brand_domain}/return-portal

GET /returns

Summary: Retrieve a list of returns

Retrieve a paginated list of all the returns belonging to the authenticated user, sorted by the creation date.

GET /returns/{id}

Summary: Retrieve a return

Retrieve the details of a specific return by its unique identifier

PARAMETERS /returns/{id}

GET /contracts/{id}

Summary: Retrieve a contract

Include the contract_ID for a specific direct contract as a query parameter to retrieve information for this single contract.

PARAMETERS /contracts/{id}

GET /contracts

Summary: Retrieve a list of contracts

This endpoint will retrieve information about all of the available contracts you have in your Sendcloud account. It will also return the contract_id of your contracts, which you can use to retrieve information about a specific contract.

GET /user/addresses/sender/{id}

Summary: Retrieve a sender address

You can retrieve information about a specific sender address saved to your account via this endpoint. Sender address id can be obtained via the Get sender address endpoint.

PARAMETERS /user/addresses/sender/{id}

GET /user/addresses/sender

Summary: Retrieve a list of sender addresses

This endpoint returns a list of all the sender addresses which have been saved to your account. The response will include the id of each address, which you can include as a parameter when creating parcels or looking up shipping methods via the API.

GET /checkout/configurations/{configuration_id}/delivery-options

Summary: Retrieve a list of delivery options

To use this API, you first need to create your own Dynamic Checkout configuration in the Sendcloud panel.

To get started, take the following steps:

  1. Login to your Sendcloud account and click the Dynamic Checkout tab.
  2. Select your API integration from the Shops menu to customize your delivery options.
  3. When you’re done, click Publish to apply your configuration to your API integration.

This API allows you to let your customers pick delivery options. The options returned via this endpoint are based on the delivery methods they previously configured, in addition to cart/order information, for example — parcel weight, total order value, destination country, etc.

Then you can present the returned delivery options to your customer on your checkout page, where they can select their preferred one for their order.

How do delivery options correspond to configured delivery methods?

This API returns one delivery option per carrier configured in Dynamic Checkout. If a delivery method is configured with multiple carriers, then multiple delivery options will be returned - one per carrier. In cases when delivery options correspond to the same delivery method, delivery options’ ids will refer to the same delivery method id, leaving API users with a flexibility to perform grouping based on a delivery method id, if desired.

Only Service point delivery method currently allows selection of multiple carriers. Hence, multiple delivery options will be returned only for a delivery method of this type.

How can I create a parcel out of the selected delivery option?

You’ll need to make an API call to the Create a parcel endpoint, passing request_label=true and shipping_method_id=checkout_identifier.value, where the checkout_identifier field refers to the identifier of the selected delivery option.

PARAMETERS /checkout/configurations/{configuration_id}/delivery-options

POST /integrations/{id}/shipments/delete

Summary: Delete a shipment

Deleting orders from an integration

If an order is canceled or deleted in your shop system, delete it from the Sendcloud database via this endpoint. The order_status and payment_status fields we retrieve from integrations are not mapped in our system, meaning that orders will not be automatically updated or deleted if the values for these fields change after an order is placed.

You can delete an order by providing either a shipment_uuid, or a combination of the external_order_id and external_shipment_id properties.

PARAMETERS /integrations/{id}/shipments/delete

GET /integrations/{id}/shipments

Summary: Retrieve a list of shipments

Retrieving shipments from an integration

Via this endpoint, you can retrieve a list of orders that were imported from a specific webshop integration. Note that these orders are not affected by shipping rules at the time of retrieval, unless enabled explicitly. This endpoint is paginated, meaning that you can navigate through the results via the URLs provided within the next and previous fields.

POST /integrations/{id}/shipments

Summary: Create or update a list of shipments

Inserting shipments into an integration

This end-point is only available for official Sendcloud partners.

This endpoint allows you to insert shipments (or ‘orders’) into an API integration from your shop system, and have them appear in your Sendcloud account. Imported orders will appear in the Sendcloud panel under the Incoming order overview with the status Ready to process. This allows you to easily generate parcels and create shipping labels via the API or directly from the Sendcloud panel. The validation for this endpoint is more relaxed, therefore we recommend this method over the Create a parcel endpoint for third-party integrators.

This is an UPSERT endpoint which attempts to be idempotent given specific fields to ensure that orders are not duplicated. If there’s an existing match in our database for specific fields (external_order_id and external_shipment_id), then the shipment will be updated. The system will only update orders that have had their updated_at (ISO 8601 DateTime) timestamp changed.

The external_shipment_id field is used to split orders across multiple shipments, however, this field is not supported by all shop systems. If your shop system supports the distribution of product items within an order across multiple shipments, you can use the shipment data to create multiple entries. If your shop does not support this feature, you can set the external_shipment_id value to null.

Batches are limited to 100 orders at once. This endpoint should accept most values in any of the available fields, but in the case of erroneous data, an error message will be returned directly. Your requests should almost always succeed unless the field structure is not correct.

PARAMETERS /integrations/{id}/shipments

GET /integrations/{id}/logs

Summary: Retrieve integration exceptions logs

Retrieving integration exception logs

Allows you to retrieve integration exception logs that are created automatically if integrations have problems with API requests to the shop systems. For examples, if some resource cannot be found, or API credentials are not valid anymore. Log record could contain information about request and response, status code and code exception, and be used as a reference to identify issues between Sendcloud and shops APIs. This endpoint could be used to get exception logs of specific integration.

POST /integrations/{id}/logs

Summary: Create integration exceptions logs

Creating integration log records

You can create exeption logs with this endpoint and logs will appear in connection issue log screen of user’s integration.

PARAMETERS /integrations/{id}/logs

GET /integrations/{id}

Summary: Retrieve an integration

Retrieving your integration

Allows you to to retrieve information about a specific integration by specifying the integration id. The information returned includes the shop name and URL, the date and the time of the last order fetch. The response will also indicate whether service point delivery is enabled for this integration, and for which carriers.

PUT /integrations/{id}

Summary: Update an integration

Updating an integration’s settings

You can update the settings for the integration by making a PUT request to our integration endpoint and including your integration id as the path parameter. Using this endpoint, you can change the webshop name and URL, edit the list of carriers you want to enable for service point delivery and enable or disable service point delivery by setting service_point_enabled to true or false.

You can obtain an integration id via the Retrieve your list of integrations endpoint.

DELETE /integrations/{id}

Summary: Delete an integration

Deleting your integration

Delete a webshop integration from the Sendcloud system.

PATCH /integrations/{id}

Summary: Update an integration

Updating an integration’s settings

You can update the settings for the integration by making a PATCH request to our integration endpoint and including your integration id as the path parameter. Using this endpoint, you can change the webshop name and URL, edit the list of carriers you want to enable for service point delivery, and enable/disable service point delivery by setting service_point_enabled to true or false.

You can obtain an integration id via the Retrieve your list of integrations endpoint.

PARAMETERS /integrations/{id}

GET /integrations/logs

Summary: Retrieve all integration exceptions logs

Retrieving all integration exception logs

Allows you to retrieve integration exception logs that are created automatically if integrations have problems with API requests to the shop systems. For examples, if some resource cannot be found, or API credentials are not valid anymore. Log record could contain information about request and response, status code and code exception, and be used as a reference to identify issues between Sendcloud and shops APIs.

GET /integrations

Summary: Retrieve a list of integrations

Retrieving your list of integrations

Retrieve information about all shop integrations currently connected to your Sendcloud account. The information returned includes the shop name and URL, the date, and the time of the last order fetch. The response indicates whether service point delivery is enabled for this integration and for which carriers.

GET /service-points/{service_point_id}/check-availability

Summary: Retrieve availability of a service point

Retrieve a true or false value which reflects the current availability of a given service point id.

PARAMETERS /service-points/{service_point_id}/check-availability

GET /service-points/{service_point_id}

Summary: Retrieve a service point

Retrieve information about a specific service point location, including opening hours and applicable carriers, based on the service point id.

PARAMETERS /service-points/{service_point_id}

GET /service-points

Summary: Retrieve a list of service points

Retrieve a list of available service points and the associated service point id. Only service points which are applicable to the carriers you have enabled in the integration settings menu will be returned. You can filter the results based on GPS location or address in combination with a search radius.

Notes

  • If provided, latitude and longitude specify a reference point from which a distance will be computed for each service point, and returned with the response.
  • Some carriers impose limits for certain service point, which means that they cannot accept parcels above a certain weight range. For this reason, you can specify the weight parameter to ensure that only usable service points are returned.
  • If provided, postal_code will return a list of service points which are located exactly within the bounds of the specified postal code area.
  • The address parameter retrieves a list of service points closest to the referenced location. You can adjust the radius of the results through the ‘radius’ parameter.
  • The address parameter accepts postal codes in addition to street names.

GET /carriers

Summary: Retrieve a list of service point carriers

Retrieve a list of carriers which are enabled for service point delivery and can be accessed by the authenticating integration. Carriers can be enabled or disabled via the integration settings menu in the Sendcloud panel.

GET /tracking/{tracking_number}

Summary: Retrieve tracking information of a parcel

Fetches the detailed tracking information, including the status history of the parcel

PARAMETERS /tracking/{tracking_number}

POST /oauth2/token

Summary: The OAuth 2.0 Token Endpoint

Use open source libraries to perform OAuth 2.0 available for any programming language. You can find a list of libraries here https://oauth.net/code/

Graph View

Backlinks

  • No backlinks found