> ## 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.

# How parcels work

> The parcel lifecycle, the checks before processing, and how defaults and overrides change parcel data.

This page explains how parcels behave beyond the basic workflow in the [Quickstart](/api/v1/quickstart).

## Parcel lifecycle

A parcel has no single status. Instead, its timestamps record which actions happened to it and when:

| Timestamp | Set when |
| - | - |
| `created_at` | The parcel was created. |
| `processed_at` | Processing succeeded. |
| `printed_at` | The parcel was printed for the first time. |
| `cancelled_at` | The parcel was cancelled. |

A timestamp is `null` until its action happens, and it stays set afterward. For example, a cancelled parcel keeps its `processed_at` and `printed_at`.

If processing failed, `processed_at` stays `null` and `processing_errors` lists the carrier errors. While processing runs, request the processing status with `GET /parcels/{id}/process` to see whether it has finished.

Which actions are possible depends on where the parcel is in its lifecycle:

| Action | Possible when |
| - | - |
| Update, delete, or process | The parcel isn't processed and isn't being processed. |
| Print | The parcel is processed and not cancelled. |
| Cancel | The parcel is processed, not cancelled, and `cancellable_until` hasn't passed. |
| Download documents | The parcel is printed and not cancelled. |

Other requests return `409 Conflict`. See [Error handling](/api/v1/error-handling#conflicts).

If `cancellable_until` is `null`, SimpleSell doesn't know of a deadline and lets you cancel the parcel at any time. Your carrier may still have its own deadline for cancellations.

Cancelling sets `cancelled_at` and marks the parcel's labels as cancelled in SimpleSell, so they drop out of your shipping workflow. If your carrier supports it, SimpleSell also tries to cancel the labels with the carrier in the background. Whether and how your carrier bills cancelled labels depends on your carrier.

## Checks before processing

When you [process a parcel](/api/v1/parcels/process-a-parcel), SimpleSell first checks the parcel's data. If something is missing, the request returns `422 Unprocessable Entity` and lists the missing data in `errors`.

Every parcel needs:

* A receiver `name` or `company`
* A receiver `country`
* A shipping method that supports the parcel, for example its destination, weight, and dimensions
* A default sender address in your SimpleSell settings
* A `sku` or a `name` for every item

Parcels subject to customs also need:

* Exactly one label
* At least one item
* A `weight`, `price`, `description`, `origin_country`, and `hs_code` for every item
* If you set the parcel's `weight`, at least the total weight of its items

SimpleSell decides automatically whether a parcel is subject to customs, based on the receiver's country and postal code. After printing, `documents.customs_declaration` contains the URL of the customs declaration.

<Tip>
  Send all the data you have, not only the fields listed here. Your carrier may need more, for example a complete receiver address, and checks it during processing. If the carrier rejects the shipment, `processing_errors` lists its reasons.
</Tip>

## Defaults and overrides

SimpleSell merges additional data into a parcel:

* **Defaults** fill fields you leave empty.
* **Overrides** replace values you send.

### Defaults

When you create a parcel, SimpleSell fills empty fields from your settings:

* **Sender address:** the default sender address
* **Items:** the default `weight`, `origin_country`, and `hs_code` from your product settings
* **Export reason:** the default export reason

These values are saved with the parcel and appear in the response right away.

When you process a parcel, SimpleSell fills these fields if they're empty:

* **Weight:** the sum of quantity × item weight, plus the packaging weight. Item `weight` is the weight of one unit.
* **Reference:** built from the reference format in your settings: the order number, the items' SKUs, the items' storage locations, or no reference. The reference is printed on the label if it fits.
* **Dimensions:** the dimensions of the parcel's packaging

Until the parcel is processed, `weight`, `reference`, and `dimensions` are `null` in responses unless you set them.

### Overrides

When you create a parcel, these sources replace the values you send:

* **Default product description:** If you set one in your settings, it replaces the `description` of every item. This lets you use one customs description for all your goods.
* **Product database:** With `apply_products=true`, SimpleSell matches items by their exact `sku`. For matching products, the product data replaces the item's name, weight, storage location, description, origin country, and HS code. The price stays as you sent it.
* **Shipping rules:** With `apply_shipping_rules=true`, matching rules of your SimpleSell account replace the shipping method, packaging, weight, reference, or number of labels. SimpleSell applies shipping rules after the product database, so rules that check item names or weights also work if you only send SKUs.

### Packaging or dimensions

Set either `packaging_id` or `dimensions`, not both. Sending both returns `422 Unprocessable Entity`. When you [update a parcel](/api/v1/parcels/update-a-parcel), setting one of them removes the other.

## Multiple labels

Set `number_of_labels` to ship several identical packages to the same receiver, up to 30. Processing creates one label for each package. All labels share the parcel's data, such as the weight, dimensions, and shipping method. Only their tracking numbers differ.

<Warning>
  `weight` is the weight of each package, not the total. Set it yourself when you use several labels. Otherwise, SimpleSell calculates the weight from all items and uses that total for every label.
</Warning>

To ship packages with different weights, dimensions, or contents, create a separate parcel for each package. This also gives every parcel the right items, for example for packing slips in SimpleSell.

`labels` lists the labels with their tracking numbers, and the labels download contains all labels in one PDF.

## Printing

Printing marks a parcel as printed in SimpleSell. It doesn't send anything to a printer. Shipping documents are only available once a parcel is printed.

By default, [processing](/api/v1/parcels/process-a-parcel) prints the parcel automatically. You can [print a parcel](/api/v1/parcels/print-a-parcel) again at any time. The response then contains `"reprint": true`, and `printed_at` keeps the time of the first print.

## Processed parcels don't change

When a parcel is processed, SimpleSell saves the data used for the shipment. Later changes in SimpleSell, such as renaming a shipping method, don't affect processed parcels.

## Reference codes

SimpleSell assigns every parcel a short `reference_code` to recognize it in SimpleSell.

<Warning>
  Reference codes are reused over time. Use `id` to identify parcels in your system.
</Warning>


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