DOCSEARCHbyAlgolia
Submit Docs

Shipcloud API Documentation

website·Indexed 35 days ago

https://developers.shipcloud.io/

Technical documentation for integrating shipping services into software, online shops, or ERP solutions. The API provides a directory of supported shipping carriers (including DHL, UPS, DPD, and GLS), covering shipment creation, pickup options, label formats, and multi-package shipments. Includes details on SSL authentication, rate limiting, versioning, and a Ruby wrapper library.

Tokens
15.6K
Snippets
38
Records
120
Agent score
64%

What's inside Shipcloud

  1. Manage Sandbox vs Production environments

    shipcloud provides two distinct environments:

    • Sandbox: Used for development and testing. Uses a specific sandbox API key. Shipment prices are always returned as 0,0. Sandbox shipments are automatically deleted after 2 weeks.
    • Production: Used for creating actual shipping labels. Uses a live API key.

    Both keys can be managed or regenerated in the shipcloud backoffice under the API Key menu.

  2. Understand shipcloud shipping journeys

    The shipcloud API supports two primary shipping workflows:

    1. Ship: Used to generate shipping labels for orders directly from a backend system, suitable for manual order processing or automated fulfillment.
    2. Checkout to Ship: Enhances the customer experience by allowing users to select a preferred carrier service during the checkout process. Once the order is confirmed, the shipping label is automatically generated from the backend system.

  3. Use the Order API for Return Portal Plus

    The Order API allows you to send order data to shipcloud. This data is primarily used by the 'Return Portal Plus', which enables customers to select items from an existing order and generate a return shipping label, including the reason for the return.

  4. Create multi-package shipments

    To send a shipment with multiple packages, provide an array of package objects instead of a single package object. Note that this is currently only supported by UPS. For carriers that do not support multi-package shipments, you must still send an array containing exactly one package object. Using a single package object (non-array) is deprecated.
    POST /shipments
{
  "carrier": "ups",
  "service": "standard",
  "create_shipping_label": true,
  "from": { ... },
  "to": { ... },
  "packages": [
    {
      "length": 30,
      "width": 30,
      "height": 30,
      "weight": 3.0,
      "type": "parcel",
      "description": "PackageDescription1"
    },
    {
      "length": 20,
      "width": 20,
      "height": 20,
      "weight": 2.0,
      "type": "parcel",
      "description": "PackageDescription2"
    }
  ],
  "reference_number": "Ref-No-17433"
}

  5. Specify DHL Packstation or Postfiliale addresses

    When using the DHL webservice, you can provide a Packstation or Postfiliale address by including the keyword packstation or postfiliale and the corresponding identification number within the street attribute of the address object.

  7. Configure Saturday Delivery

    For carriers that do not provide Saturday delivery by default, you must explicitly specify that delivery on a Saturday should occur. This is supported by DHL Express, DPD, GLS, and UPS.

  8. Get started with shipcloud integration

    To begin integrating shipcloud into your service, shop, or application, follow these three steps:

    1. Register for a free developer plan.
    2. Retrieve your API keys from the shipcloud backoffice.
    3. Implement your first API call using the API reference documentation.

  9. Authenticate requests to the shipcloud API

    All API requests must be made over HTTPS. Authentication is handled via HTTP Basic Auth. Use your API key (which must be Base64 encoded) as the username; no password is required. API keys can be managed in the account page.

  10. Address requirements for shipments

    When providing to or from parameters, you must specify a contact. You must provide either a company name OR a combination of first_name and last_name. At least one of these must be present in the request.

  11. Pass parameters in API requests

    The method for passing parameters depends on the HTTP verb:

    • GET: Use HTTP query string parameters.
    • POST, PATCH, PUT, DELETE: Use a JSON body with Content-Type: application/json.
    # GET request example
curl -i -u YOUR_API_KEY: "https://api.shipcloud.io/v1/shipments?service=returns"

# POST request example
curl -i -u YOUR_API_KEY: -H "Content-Type: application/json" -d '{"service":["returns"]}' "https://api.shipcloud.io/v1/shipments"

  12. Enable Cash on Delivery (COD) for shipments

    The cash on delivery additional service allows customers to pay for goods directly to the carrier upon receipt. This service is supported by Cargo International, DHL, GLS, Hermes, and UPS.