> ## Documentation Index
> Fetch the complete documentation index at: https://developers.simplesell.de/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Create your first parcel, process it, and download its shipping label.

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](/api/v1/introduction#requirements).
* An API token. See [Authentication](/api/v1/authentication) to create one.

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

```bash theme={null}
export SIMPLESELL_API_TOKEN="YOUR_API_TOKEN"
```

<Steps>
  <Step title="Choose a shipping method">
    List the shipping methods configured in your SimpleSell account:

    ```bash theme={null}
    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:

    ```json theme={null}
    {
      "data": [
        {
          "id": "9d4b6c1e-2f3a-4b5c-8d7e-1a2b3c4d5e6f",
          "name": "DHL Paket 0-2 kg"
        }
      ],
      "links": {
        "next": null
      }
    }
    ```
  </Step>

  <Step title="Create a parcel">
    Create a parcel with the receiver, the weight, and the shipping method:

    ```bash theme={null}
    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:

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

    The response above is shortened. See [Create a parcel](/api/v1/parcels/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.

    <Tip>
      SimpleSell can add defaults from your settings and apply your product database and shipping rules to the parcel. See [Defaults and overrides](/api/v1/how-parcels-work#defaults-and-overrides).
    </Tip>
  </Step>

  <Step title="Process the parcel">
    Processing creates the shipment with the carrier and generates the shipping documents:

    ```bash theme={null}
    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](/api/v1/how-parcels-work#checks-before-processing). If data is missing, the API responds with `422 Unprocessable Entity` and lists the problems in `errors`:

    ```json theme={null}
    {
      "message": "The receiver.country field is required.",
      "errors": {
        "receiver.country": [
          "The receiver.country field is required."
        ]
      }
    }
    ```

    Fix the parcel with [Update a parcel](/api/v1/parcels/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 theme={null}
    HTTP/1.1 202 Accepted
    Location: https://api.simplesell.de/v1/parcels/3f2c8a9b-7e6d-4c5b-9a8f-0e1d2c3b4a59/process

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

    <Note>
      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](/api/v1/parcels/print-a-parcel) later. Printing doesn't send anything to a printer. It marks the parcel as printed in SimpleSell.
    </Note>
  </Step>

  <Step title="Wait for processing to complete">
    Request the URL from the `Location` header until `status` is `completed`:

    ```bash theme={null}
    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`:

    <Tabs>
      <Tab title="Success">
        `processing_errors` is empty. The parcel has tracking numbers in `labels` and links to its documents in `documents`:

        ```json theme={null}
        {
          "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": []
            }
          }
        }
        ```
      </Tab>

      <Tab title="Carrier error">
        The carrier rejected the shipment. `processing_errors` lists the reasons:

        ```json theme={null}
        {
          "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](/api/v1/parcels/update-a-parcel) and process it again.
      </Tab>
    </Tabs>

    <Tip>
      Wait at least one second between status requests so you stay within your [rate limit](/api/v1/rate-limits).
    </Tip>
  </Step>

  <Step title="Download the shipping label">
    Download all labels of the parcel as one PDF from the URL in `parcel.documents.labels`:

    ```bash theme={null}
    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.
  </Step>
</Steps>

## Next steps

<CardGroup cols={2}>
  <Card title="How parcels work" icon="box" href="/api/v1/how-parcels-work">
    Learn about the lifecycle, processing checks, defaults, and overrides.
  </Card>

  <Card title="Error handling" icon="triangle-exclamation" href="/api/v1/error-handling">
    Handle validation errors, conflicts, and rate limits in your integration.
  </Card>

  <Card title="API basics" icon="book" href="/api/v1/requests-and-responses">
    Learn about requests, data formats, and pagination.
  </Card>

  <Card title="API reference" icon="code" href="/api/v1/parcels/list-parcels">
    See all parcel fields and endpoints.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.