Skip to main content
This page explains how parcels behave beyond the basic workflow in the Quickstart.

​
Parcel lifecycle

A parcel has no single status. Instead, its timestamps record which actions happened to it and when: 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: Other requests return 409 Conflict. See Error handling. 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, 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.
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.

​
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, 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.
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.
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 prints the parcel automatically. You can 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.
Reference codes are reused over time. Use id to identify parcels in your system.