Shipping Assistant for Tindie

This application helps streamline the process of shipping goods sold on the Tindie marketplace.

It simplifies the creation of shipping labels and order reviews. It is best suited for use with postal services that do not provide automatic shipping label generation.

Features

• Formats addresses according to local rules, not just U.S.-specific formats.
• Supports multiple label sizes.
• Prints on single labels or sheets of labels.
• Optimized for label printers.
• Can print a list of order items, stamps, and sender addresses.
• Prints stamps.
• Configurable label parameters.

Workflow

Purchase Stamps

Purchase electronic stamps from your postal service (depending on your country). These typically come in the form of a QR code or similar.

Generate a PDF file with one stamp per page. The size of the stamp/page does not matter but should be small enough to fit in the top-right corner of the address label.

Do not generate multiple labels on one page, as this is usually intended for adhesive label sheets.

Retrieve Orders from Tindie

Click the Get Orders button to download orders.

Select Orders

Select all orders that qualify to be shipped using one type of postage stamp.

This typically includes all countries in one region, such as Europe.

Use the country and shipping columns to determine which orders qualify.

Click the checkbox next to each order.

Generate Labels

Click the Print Labels button.

This will generate a PDF file with labels and open it automatically using the default PDF viewer (on Windows, this is typically a web browser).

Print

Verify that the labels look correct.

Use the print function of the PDF viewer to print the labels.

Important: Always print using the "Actual Size" option. Do not rescale or use the "Fit to Page" option.

Installation

You need Python installed.

git clone https://github.com/aquaticus/shipping-assistant.git
cd shipping-assistant
pip install -r requirements.txt
python shipping_assistant.py

It is recommended to use a Python virtual environment.

git clone https://github.com/aquaticus/shipping-assistant.git
cd shipping-assistant
python -m venv venv
source venv/bin/activate  # For Windows: venv\Scripts\Activate
pip install -r requirements.txt
python shipping_assistant.py

User Interface

• Get Orders - Downloads unshipped orders. You can download shipped orders by selecting the Get shipped orders checkbox.
• Print Labels - Generates labels for selected orders and opens them in the default PDF viewer.
• Shipments - Displays the contents of the directory containing archived PDF files.
• Cancel Last Print - Removes the last generated PDF file. If stamps were used, it removes marks from the stamp file so the stamp can be reused. Use this function if the generated labels are incorrect.
• Label - Lists available labels. You can add or modify labels in the configuration file.
• (0,0) - Indicates the coordinates of the first label printed for sheets with multiple labels.
• Print Stamps - If selected, prompts for a PDF file with stamps, selects an unused stamp, and adds it to the label.
• Print Items - Prints a list of items in the orders.
• Print Sender - Prints the sender's address.

Double-clicking an order opens the order details dialog.

Stamps

When a stamp is printed, the program automatically marks used stamps in the PDF file by adding XXXX, the country, and the order number. This ensures the stamp will not be reused.

If an incorrect label is generated, you can reuse the stamp by using the Cancel Last Print button.

Generated Files

All PDF files are stored in the Shipments directory located in the user's folder. You can review them by clicking the Shipments button. When the Cancel Last Print button is used, the file is removed.

When a stamp file is used, the program creates a backup of the previous version of the file in the same directory.

Notes

• It is not possible to configure label sheets with margins. Labels must always occupy the full page.
• The stamp file and folder must be writable.
• The program never modifies orders on Tindie. Any changes to orders are always local.
• Orders are never marked as shipped automatically. You must use the Tindie UI to mark orders as shipped.
• Order instructions are not printed. If an order has instructions, a small (I) icon is shown next to the shipping method. You can review the instructions manually.

Configuration

By default, the program reads its configuration from the .shipping_assistant_config.yaml file. This file can be located in the current folder or the user's home directory.

Tindie credentials (username and API token) are stored in a separate file, .shipping_assistant_secrets.yaml, which must be located in the same directory as the configuration file. This file is created automatically when the program prompts for credentials but can also be modified manually.

Configuration Settings

Name	Type	Default Value	Description
font_file	str	None	Path to the TTF font file for label text.
bold_font_file	str	None	Path to the TTF font file for bold label text (used for country names).
sender_address	str	Required	Multiline string for the sender's address.
default_label_type_index	int	4	Index of the default label type.
home_country_code	str	Required	Two-letter ISO code for the home country.
do_not_mark_stamps	bool	False	Whether to avoid marking stamps.
get_orders_shipped	bool	False	Whether to fetch shipped orders instead of unshipped ones.
stamp_scale_factor	PositiveFloat	1.0	Scale factor for resizing stamps.
print_items	bool	True	Whether to print the list of items on the label.
optimize_stamp_for_thermal_printer	bool	False	Whether to optimize stamps for thermal printers.
optimize_stamp_printer_dpi	int	203	DPI for optimizing stamps (range: 200–1200).
print_stamps	bool	True	Whether to print stamps on the label.
print_sender	bool	True	Whether to print the sender's address on the label.
shipments_dir	str	"~/Shipments"	Directory where shipment PDFs are saved.
local_orders_file	str	None	Path to a local orders file for diagnostics.
labels	list[Label]	Required	List of label configurations.
mark_eu_countries	bool	True	Whether to mark EU countries on the order list.
frame	bool	False	Whether to print a frame around the labels.
use_model_number_for_product_list	bool	False	Whether to use product model numbers instead of names in the product list.
secrets_file	str	".shipping_assistant_secrets.yaml"	Path to the secrets file containing username and API token.

Label Settings

Name	Type	Default Value	Description
name	str	Required	Name of the label.
width	PositiveFloat	Required	Width of the label in millimeters.
height	PositiveFloat	Required	Height of the label in millimeters.
sender_offset_x	int	0	Horizontal offset for the sender's address (must be ≥ 0).
sender_offset_y	int	0	Vertical offset for the sender's address (must be ≥ 0).
recipient_offset_x	int	0	Horizontal offset for the recipient's address (must be ≥ 0).
recipient_offset_y	int	0	Vertical offset for the recipient's address (must be ≥ 0).
sender_font_size	PositiveInt	10	Font size for the sender's address in points.
recipient_font_size	PositiveInt	Required	Font size for the recipient's address in points.
stamps	bool	True	Whether to include stamps on the label.
items	bool	True	Whether to include the list of items on the label.
sender	bool	True	Whether to include the sender's address on the label.
columns	PositiveInt	1	Number of label columns on the page.
rows	PositiveInt	1	Number of label rows on the page.
font_file	str	None	Path to the font file for the label text.
bold_font_file	str	None	Path to the bold font file for the label text (country name).
group	str	None	Group name for categorizing or organizing labels.

Command-Line Options

Argument	Short Form	Type	Description
--config	-c	str	Path to the application configuration file.
--log-level	-l	str	Set the logging level. Choices: DEBUG, INFO, WARNING, ERROR, CRITICAL.
--orders-file	-f	str	Load orders from a local JSON file instead of fetching from the Tindie API.

Sample Files

The sample-data directory contains the following files:

• fake-stamps.pdf - A sample stamps file.
• sample-orders.json - Sample orders. Load this file using the --orders-file command-line option.

License

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.