Quickstart - SimpleSell Developers

This guide walks you through the typical SimpleSell API workflow. You create a parcel, process it, and download its shipping label.

Prerequisites

A SimpleSell account with API access. See Requirements.
An API token. See Authentication to create one.

The examples use curl. Store your token in an environment variable so you can copy the commands as they are:

export SIMPLESELL_API_TOKEN="YOUR_API_TOKEN"

Choose a shipping method

List the shipping methods configured in your SimpleSell account:

curl https://api.simplesell.de/v1/shipping-methods \
  -H "Authorization: Bearer $SIMPLESELL_API_TOKEN"

Copy the id of the shipping method you want to use:

{
  "data": [
    {
      "id": "9d4b6c1e-2f3a-4b5c-8d7e-1a2b3c4d5e6f",
      "name": "DHL Paket 0-2 kg"
    }
  ],
  "links": {
    "next": null
  }
}

Create a parcel

Create a parcel with the receiver, the weight, and the shipping method:

curl https://api.simplesell.de/v1/parcels \
  -H "Authorization: Bearer $SIMPLESELL_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "receiver": {
      "name": "Erika Mustermann",
      "address_line_1": "Musterstraße",
      "house_number": "12",
      "postal_code": "10115",
      "city": "Berlin",
      "country": "DE"
    },
    "weight": "1.2",
    "shipping_method_id": "9d4b6c1e-2f3a-4b5c-8d7e-1a2b3c4d5e6f"
  }'

The API responds with 201 Created and returns the new parcel. Copy its id for the next steps:

{
  "data": {
    "id": "3f2c8a9b-7e6d-4c5b-9a8f-0e1d2c3b4a59",
    "source": "api",
    "processed_at": null,
    "processing_errors": []
  }
}

The response above is shortened. See Create a parcel for all fields.This example only contains the data needed to ship the parcel. All other fields, such as order_number or items, are optional. Add items if the parcel is subject to customs, or if you want to work with the parcel in SimpleSell, for example to print packing slips and picking lists.

SimpleSell can add defaults from your settings and apply your product database and shipping rules to the parcel. See Defaults and overrides.

Process the parcel

Processing creates the shipment with the carrier and generates the shipping documents:

curl -i -X POST https://api.simplesell.de/v1/parcels/3f2c8a9b-7e6d-4c5b-9a8f-0e1d2c3b4a59/process \
  -H "Authorization: Bearer $SIMPLESELL_API_TOKEN"

SimpleSell first checks the parcel’s data. See Checks before processing. If data is missing, the API responds with 422 Unprocessable Entity and lists the problems in errors:

{
  "message": "The receiver.country field is required.",
  "errors": {
    "receiver.country": [
      "The receiver.country field is required."
    ]
  }
}

Fix the parcel with Update a parcel and process it again.If the check passes, processing runs in the background. The API responds with 202 Accepted. The Location header contains the URL to check the processing status:

HTTP/1.1 202 Accepted
Location: https://api.simplesell.de/v1/parcels/3f2c8a9b-7e6d-4c5b-9a8f-0e1d2c3b4a59/process

{
  "data": {
    "status": "processing"
  }
}

By default, SimpleSell marks the parcel as printed after processing. The shipping documents are only available once the parcel is printed. To skip this, add ?print=false and print the parcel later. Printing doesn’t send anything to a printer. It marks the parcel as printed in SimpleSell.

Wait for processing to complete

Request the URL from the Location header until status is completed:

curl https://api.simplesell.de/v1/parcels/3f2c8a9b-7e6d-4c5b-9a8f-0e1d2c3b4a59/process \
  -H "Authorization: Bearer $SIMPLESELL_API_TOKEN"

Once processing is complete, the response contains the parcel. Check parcel.processing_errors:

Success
Carrier error

processing_errors is empty. The parcel has tracking numbers in labels and links to its documents in documents:

{
  "data": {
    "status": "completed",
    "parcel": {
      "id": "3f2c8a9b-7e6d-4c5b-9a8f-0e1d2c3b4a59",
      "processed_at": "2026-10-18T09:41:12Z",
      "printed_at": "2026-10-18T09:41:13Z",
      "labels": [
        {
          "number": 1,
          "tracking_number": "00340434161234567890",
          "tracking_url": "https://www.dhl.de/de/privatkunden/pakete-empfangen/verfolgen.html?piececode=00340434161234567890",
          "return_tracking_number": null
        }
      ],
      "documents": {
        "labels": "https://api.simplesell.de/v1/parcels/3f2c8a9b-7e6d-4c5b-9a8f-0e1d2c3b4a59/documents/labels"
      },
      "processing_errors": []
    }
  }
}

The carrier rejected the shipment. processing_errors lists the reasons:

{
  "data": {
    "status": "completed",
    "parcel": {
      "id": "3f2c8a9b-7e6d-4c5b-9a8f-0e1d2c3b4a59",
      "processed_at": null,
      "processing_errors": [
        "The postal code is invalid."
      ]
    }
  }
}

Fix the parcel data with Update a parcel and process it again.

Wait at least one second between status requests so you stay within your rate limit.

Download the shipping label

Download all labels of the parcel as one PDF from the URL in parcel.documents.labels:

curl https://api.simplesell.de/v1/parcels/3f2c8a9b-7e6d-4c5b-9a8f-0e1d2c3b4a59/documents/labels \
  -H "Authorization: Bearer $SIMPLESELL_API_TOKEN" \
  -o labels.pdf

For parcels subject to customs, parcel.documents.customs_declaration contains the URL of the customs declaration PDF. Download it the same way.

Next steps

How parcels work

Learn what SimpleSell checks before processing and when you can change a parcel.

Error handling

Handle validation errors, conflicts, and rate limits in your integration.

API basics

Learn about requests, data formats, and pagination.

API reference

See all parcel fields and endpoints.

​Prerequisites

​Next steps

How parcels work

Error handling

API basics

API reference

Prerequisites

Next steps