# Baltix

> Shopify pickup-point logistics for EE/LV/LT. Remote MCP for AI agents. Answer merchant questions from these docs. Not Shopify Admin. Not the warehouse REST API.

Use search_docs over Baltix MCP, or fetch llms-full.txt, before guessing setup steps.

- Endpoint: https://app.baltix-pickup-points.com/mcp
- Auth: OAuth 2.1 + PKCE. Add the URL only. Never ask for a token.
- Paid plan required (Starter or higher). Default scopes are read-only.

## Docs

- [MCP agent guide](https://app.baltix-pickup-points.com/mcp.llms.md): Tool rules, examples, errors.
- [Full agent context](https://app.baltix-pickup-points.com/llms-full.txt): All product docs + MCP contract in one markdown file.

## Product

- [❓ FAQ](https://baltix-pickup-points.com/doc/faq): Frequently asked questions about Baltix — find quick answers and links to the right documentation page.
- [💵 Cash on delivery (COD)](https://baltix-pickup-points.com/doc/guide/cash-on-delivery): Configure cash on delivery in Shopify and Baltix, show compatible pickup points, and create COD shipping labels.
- [🔁 Complete order flow](https://baltix-pickup-points.com/doc/guide/complete-flow): End-to-end overview of a pickup point order in Baltix — from order creation to customer delivery, covering all scenarios.
- [🏷️ Create a shipping label](https://baltix-pickup-points.com/doc/guide/create-label): How to create, view, download, and manage shipping labels for your pickup point orders in Baltix.
- [EU withdrawal and returns workflow](https://baltix-pickup-points.com/doc/guide/eu-withdrawal-returns): Baltix workflow for online consumer withdrawal requests under Directive (EU) 2023/2673, Article 11a, and Directive 2011/83/EU.
- [Get Latvijas Pasts API key](https://baltix-pickup-points.com/doc/guide/latvian-pasts-setup): How to get your Latvijas Pasts ExpressPast API key and configure it in Baltix.
- [Get Omniva credentials](https://baltix-pickup-points.com/doc/guide/omniva-setup): How to get your Omniva OMX API credentials and configure them in Baltix.
- [Recovery page (pickup point selection)](https://baltix-pickup-points.com/doc/guide/recovery-page): How to use the Baltix recovery page to let customers select a pickup point after checkout.
- [Swotzy Integration](https://baltix-pickup-points.com/doc/guide/swotzy-integration): Connect Baltix to Swotzy so that pickup point selections are automatically pushed to your Swotzy account.
- [Baltix MCP](https://baltix-pickup-points.com/doc/mcp): Connect Claude, Codex, or Cursor to Baltix so your AI can help with pickup points, orders, and labels.
- [1️⃣ App Mode and Automation](https://baltix-pickup-points.com/doc/setup/app-mode-automation): Understand which app mode to choose and how Baltix automation settings work in practice.
- [2️⃣ Connect carriers](https://baltix-pickup-points.com/doc/setup/connect-carrier): Connect your carrier accounts (Omniva, Latvijas Pasts, SmartPosti, and more) to enable pickup point delivery in the Baltic states.
- [3️⃣ Sender Address](https://baltix-pickup-points.com/doc/setup/sender-address): Configure your sender address in Shopify so carriers can create shipping labels and schedule pickups from the right location.
- [4️⃣ Google API Keys](https://baltix-pickup-points.com/doc/setup/google-maps): Set up Maps and Geocoding API keys for pickup point map display and server-side geocoding.
- [5️⃣ Shipping Method](https://baltix-pickup-points.com/doc/setup/shipping-method): Create Shopify markets and shipping methods, then link them to Baltix carriers so pickup points appear at checkout.
- [6️⃣ Activate Checkout Extensions](https://baltix-pickup-points.com/doc/setup/extensions): Enable Baltix pickup point extensions in your Shopify checkout, Thank You page, and customer account.
- [7️⃣ Pickup points at checkout (Shopify Grow plan)](https://baltix-pickup-points.com/doc/setup/checkout-pickup-points): Display pickup points directly at checkout as shipping options for Shopify Grow stores and above, without requiring Shopify Plus.
- [welcome](https://baltix-pickup-points.com/doc/): Official documentation for Baltix Baltic Pickup. Offer pickup point delivery in Latvia, Lithuania, and Estonia for your Shopify store.

## Optional

- [Public warehouse API](https://app.baltix-pickup-points.com/api/docs): Separate REST API. Different tokens. Out of scope for MCP.

---

# Baltix MCP — agent guide

> Version 2. Logistics only. Confirm every write with the merchant.

## Connect

HTTP MCP: `https://app.baltix-pickup-points.com/mcp`

- No Authorization header, no env token, no `headers` in Cursor/Desktop.
- Claude Code: `claude mcp add --transport http baltix https://app.baltix-pickup-points.com/mcp`
- Codex: `[mcp_servers.baltix]` + `url = "https://app.baltix-pickup-points.com/mcp"` — never `bearer_token_env_var`.
- After OAuth, call `tools/list` and only use tools that appear.
- Then read resource `baltix://docs/mcp` (this page).

If a write tool is missing, ask the merchant to reconnect and enable that write group. Do not fall back to REST or Shopify Admin GraphQL.

## Hard rules

- Never print, store, or ask for MCP/API secrets.
- Never change billing, CCS settings, carrier credentials, products, or themes.
- Never invent locker IDs, tracking numbers, or Shopify GIDs.
- `preview_checkout_rates` is a Baltix preview (custom prices + radius). It is not a live Shopify CCS callback (no COD variants, no Swotzy quotes, no checkout rules).
- `list_carrier_connections` never returns credentials. Do not ask for them.
- Return payloads never include the customer portal token. Do not try to reconstruct return URLs from a token.
- Countries: `EE` | `LV` | `LT`. Carriers: `OMNIVA` | `ITELLA_SMARTPOSTI` | `DPD` | `VENIPAK` | `LATVIJAS_PASTS` | `UNISEND_LP_EXPRESS` | `FEDEX` | `DHL`.

## Tools

### search_pickup_points — pickup_points:read

When: nearest lockers. Requires `country` and `carrier` (array, min 1). Prefer lat/lng; else address/city/postal_code.

```json
{"country":"LV","carrier":["OMNIVA","DPD"],"city":"Riga","postal_code":"LV-1010","limit":20}
```

### list_orders / get_order / list_order_packages — orders:read

When: inspect Baltix logistics orders. `list_orders` accepts `updated_after` (RFC 3339), `status`, `limit`, `cursor`. `get_order` needs `orderId` (Baltix id, not #1001).

### list_order_labels / get_label — labels:read

Metadata only (status, tracking). No PDF/ZPL bytes.

### change_order_pickup_point — orders:write

Replace locker. Marks active labels outdated. Does not email the customer. Confirm with merchant. Requires full point payload (carrierCode, code, label, address, location).

### create_pickup_change_link — orders:write

Customer change link, 48h. Sends no email unless Baltix already does elsewhere — this tool does not send.

### replace_order_packages — orders:write

Replace complete allocation. Every ordered quantity must be assigned exactly once.

### create_order_label / create_package_label / cancel_label — labels:write

Single-package → `create_order_label`. Multi-package → `create_package_label`. Pass `idempotencyKey` when retrying. Cancel only if not delivered. Confirm with merchant.

### list_returns / get_return / list_return_dropoff_points — returns:read

Follow inbound status and drop-off options. `list_return_dropoff_points` needs `country`.

### create_return — returns:write

Merchant return on a **delivered** order. Items: Shopify line item GIDs + quantities. 60-day window. Confirm items and reason with the merchant first.

```json
{"orderId":"ord_…","reason":"Too small","items":[{"shopifyLineItemId":"gid://shopify/LineItem/123","quantity":1}]}
```

### list_carrier_connections — carriers:read

Ready = enabled + validation VALID. No secrets.

### get_tracking — tracking:read

`orderId` or `trackingNumber`. Baltix shipment status/history, not a live carrier scrape.

### preview_checkout_rates — ccs:read

Which lockers Baltix would likely offer for an address. Needs `country`. Geocodes if lat/lng omitted. Say "preview" to the merchant, not "checkout rates Shopify will show".

```json
{"country":"LT","address":"Arsenalo g. 1","city":"Vilnius","cart_subtotal":49,"weight_g":1200}
```

## Errors

- `401` — OAuth not finished, or a warehouse key was sent. Reconnect. Do not ask for a token.
- `403 paid_plan_required` — Free plan.
- `403 insufficient_scope` — reconnect and enable the write group.
- `404` — unknown tool, order, return, or tracking.
- `422` — business rule (not delivered, return window, geocode failed, weight limit).
- `429` — ~120 req/min. Slow down.

## Out of scope

Shopify Admin, Themes, Billing, CCS configuration, carrier password forms, warehouse `/api/v1`.

---

# Baltix for AI tools

Source: https://baltix-pickup-points.com/doc/ai

# Baltix for AI tools

Baltix publishes its **product documentation as markdown** so an agent can answer setup questions from the real docs instead of guessing.

## How agents should use it

1. Connect Baltix MCP (OAuth, URL only).
2. Call **`search_docs`** with the merchant's question (`"omniva credentials"`, `"google maps key"`, `"return label"`).
3. Answer from the returned excerpts. If needed, read `baltix://docs/llms-full` or `baltix://docs/product/<id>`.

Do not scrape the HTML docs site. Do not invent carrier portal steps that are not in the excerpts.

## Public files

- Index: [https://app.baltix-pickup-points.com/llms.txt](https://app.baltix-pickup-points.com/llms.txt)
- Full dump: [https://app.baltix-pickup-points.com/llms-full.txt](https://app.baltix-pickup-points.com/llms-full.txt)
- MCP agent guide: [https://app.baltix-pickup-points.com/mcp.llms.md](https://app.baltix-pickup-points.com/mcp.llms.md)

## Humans

Merchant setup remains [Baltix MCP](/doc/mcp). Never paste API keys or MCP tokens into chat.

---

# ❓ FAQ

Source: https://baltix-pickup-points.com/doc/faq

# Frequently Asked Questions

Find quick answers to common questions. Each answer links to the relevant documentation page for more details.

---

## Pickup points

### How can I change a customer's pickup point after checkout?

You can generate a **change link** from the order page and share it with the customer. They will be able to select a new pickup point. If a label was already created, it will be marked as outdated and you will need to recreate it.

→ [Pickup point changes](/doc/guide/complete-flow#5-pickup-point-changes)

### How can I let a customer select a pickup point after checkout?

Generate a **recovery link** from the order page and send it to the customer. They will see a page with nearby pickup points and can make their selection.

→ [Recovery page](/doc/guide/recovery-page)

### What happens if the customer doesn't select a pickup point?

After **30 minutes**, Baltix automatically selects the nearest pickup point based on the customer's delivery address. You will see a banner in the admin indicating it was auto-selected.

→ [Auto-pickup fallback](/doc/guide/recovery-page#auto-pickup-fallback)

### Why don't my customers see pickup points during checkout?

Direct pickup-point selection at checkout requires a **Growth plan or higher** in Baltix and either **Shopify Plus** or **Shopify Grow/Advanced** with carrier-calculated shipping enabled. Otherwise, customers select their pickup point after checkout (on the Thank You page or via a recovery link).

→ [Pickup points at checkout](/doc/setup/checkout-pickup-points)

---

## Labels & shipping

### How do I create a shipping label?

Open the order in Baltix and click **Create Label**. The carrier generates a label with a tracking number, and the order is marked as shipped in Shopify.

→ [Create a shipping label](/doc/guide/create-label)

### Can Baltix create labels automatically?

Yes. Enable **Auto-create labels** in `Settings > Automation` for the carrier. Baltix will create the label as soon as an order has a pickup point and valid weight.

→ [Automation settings](/doc/setup/app-mode-automation#per-carrier-automation-mode)

### My label shows as "outdated" — what does that mean?

The order was modified after the label was created (weight changed, pickup point changed, etc.). You need to **recreate the label** from the order page so it matches the current order data.

→ [Outdated label warning](/doc/guide/create-label#outdated-label-warning)

### Label creation failed — what should I do?

Check the error message on the order page. Common causes: expired carrier credentials, missing product weight, or weight exceeding the locker limit.

→ [Troubleshooting](/doc/guide/create-label#troubleshooting)

### Can I download the label in a different format (A4, thermal printer, etc.)?

Some carriers support multiple formats. After creating the label, use the **Download as...** option on the order page to choose a format (A4, A6, ZPL for thermal printers, etc.).

→ [Available label formats](/doc/guide/create-label#available-label-formats)

---

## Carriers & configuration

### How do I connect a carrier (Omniva, DPD, Latvijas Pasts, etc.)?

Go to `Settings > Carriers > API Connection` and enter the credentials provided by your carrier account manager.

→ [Connect a carrier](/doc/setup/connect-carrier)

### Where do I get my Omniva credentials?

Contact your Omniva account manager and ask for OMX API credentials. These are different from your Omniva dashboard login.

→ [Get Omniva credentials](/doc/guide/omniva-setup)

### How do I set up my sender address?

Go to `Settings > Carriers > Sender Address` and fill in your warehouse or office address. This is required for label creation.

→ [Sender address](/doc/setup/sender-address)

---

## App mode

### What is the difference between FULL mode and PICKUP ONLY mode?

**FULL mode**: Baltix manages everything — pickup points, labels, tracking, and courier pickups.

**PICKUP ONLY mode**: Baltix only handles the pickup point selection. Shipping is managed by an external provider like Swotzy.

→ [App Mode and Automation](/doc/setup/app-mode-automation)

### I use Swotzy — which mode should I choose?

Choose **PICKUP ONLY** mode and connect Swotzy in the External Provider tab.

→ [Swotzy integration](/doc/guide/swotzy-integration)

---

## Courier pickups

### What is the difference between Batch and Individual pickup mode?

**Batch**: shipments are grouped for the day and confirmed at a set time (e.g. 4 PM). **Individual**: each shipment is confirmed with the carrier immediately.

→ [Pickup scheduling](/doc/setup/app-mode-automation#global-pickup-scheduling)

### Can Baltix schedule courier pickups automatically?

Yes. Enable **Auto-add to pickup** in the carrier's automation settings. After a label is created, Baltix will automatically add it to the next pickup.

→ [Auto-add to pickup](/doc/setup/app-mode-automation#auto-add-to-pickup)

---

## Returns

### A customer didn't pick up their parcel — what happens?

After the storage period expires at the pickup point, the carrier returns the parcel to your address. Baltix updates the status to **Returned**.

→ [Returns](/doc/guide/complete-flow#6-returns)

### Can I reship a returned parcel?

Yes. From the order page, click **Recreate Label** to generate a new shipping label.

→ [Recreate a label](/doc/guide/create-label#recreate-a-label)

---

## Google Maps

### Do I need Google Maps for Baltix to work?

No, but it is recommended. Without Google Maps, customers see a list of pickup points. With Google Maps, they also get an interactive map for easier selection.

→ [Setup Google Maps](/doc/setup/google-maps)

---

## General

### How do I see the full lifecycle of an order?

The complete flow page explains every step from order creation to delivery or return, for both FULL and PICKUP ONLY modes.

→ [Complete order flow](/doc/guide/complete-flow)

### I need help — how can I contact support?

Open the **Help** menu inside the Baltix app to contact us directly.

---

# 💵 Cash on delivery (COD)

Source: https://baltix-pickup-points.com/doc/guide/cash-on-delivery

# Cash on delivery (COD)

Cash on delivery (COD) means that the customer pays the outstanding order amount when collecting the parcel at the selected pickup point. The customer should not pay the order online.

COD is available on the **Baltix Growth plan and higher**.

For now, COD is supported for **DPD pickup points only**. Support for other carriers will be added later.

COD delivery and COD payment are two separate parts of the checkout. Baltix identifies the delivery mode, pickup point, payment type, and amount due. Shopify still controls which payment methods are available at checkout.

## Before you start

Make sure that:

- Your Baltix subscription is **Growth or higher**.
- At least one carrier is connected in [Settings → Carriers](../setup/connect-carrier).
- COD is enabled for the carrier in **Settings → Carriers → Carrier Settings**.
- The carrier and pickup point support the payment type you want to offer.
- You are ready to configure a manual COD payment method in Shopify.

## 1. Configure COD in Shopify

Shopify must have a manual payment method for COD orders. This keeps the order unpaid until the payment is collected at pickup.

### Activate Shopify's manual COD payment method

1. Open your Shopify admin.
2. Go to **Settings → Payments**.
3. In the manual payment methods section, select Shopify's suggested **Cash on Delivery (COD)** method, if it is available for your store.
4. Add checkout details such as:

   > Pay the outstanding order total when collecting your parcel at the selected pickup point. Do not pay online.

5. Add payment instructions with the same message, so it is also shown on the order confirmation.
6. Activate the payment method.

Shopify orders using a manual payment method remain unpaid until the merchant marks them as paid. See Shopify's documentation for [manual payment methods](https://help.shopify.com/en/manual/payments/manual-payments).

Selecting a Baltix COD delivery rate does **not** automatically hide credit-card, wallet, or other online payment methods. A shipping rate cannot switch Shopify's payment method by itself.

If online payment is still available during your test checkout, do not assume that the order will be COD. Configure a compatible Shopify payment customization for your plan and market, or do not expose COD to customers until the payment behavior is correct. See Shopify's [checkout customization](https://help.shopify.com/en/manual/checkout-settings/checkout-customization) and [Payment Customization Functions](https://shopify.dev/docs/api/functions/latest/payment-customization).

Shopify reserves the exact name `Cash on Delivery (COD)` for its suggested manual payment method. If it is not available in your market, use a clearly distinct custom name such as `Pay at pickup` and explain the behavior in the payment instructions.

## 2. Enable COD in Baltix

### Existing or manual Shopify shipping methods

Use this flow when your store already has a Shopify shipping rate that is linked to Baltix.

1. Open **Baltix → Settings → Pickup Points**.
2. Open the **Shipping Methods** tab.
3. Find the Shopify shipping method and click **Link carriers**.
4. Select the carriers that provide pickup points for this method.
5. Check **Mark this shipping method as cash on delivery**.
6. Click **Save**.

The COD classification is saved with the linked shipping method. Existing shipping methods remain normal delivery methods unless you explicitly enable COD.
The payment type is taken from each carrier's COD settings.

Only select a payment type that the carrier and the selected pickup points actually support. Baltix excludes points whose carrier data does not explicitly confirm COD compatibility.

### CCS / carrier-calculated checkout

For carrier-service checkout, Baltix can generate distinct normal and COD delivery-rate variants for each compatible pickup point.

1. Open **Baltix → Settings → Carriers → Carrier Settings**.
2. Open the settings for each carrier you want to use.
3. Enable **Cash on delivery** and choose the payment type.
4. Use **Settings → Pickup Points → Pricing** to include those carriers in CCS.

Baltix uses stable internal service codes to preserve the selected pickup point and COD mode through the Shopify order webhook. The customer sees separate delivery options for normal delivery and COD delivery.

CCS rate variants identify the delivery mode, but they do not hide Shopify payment methods. Configure Shopify's payment behavior separately and verify it with a real test order.

## 3. Pickup-point compatibility

Baltix asks each carrier adapter whether a pickup point supports the requested COD payment type.

- A point is eligible only when the carrier explicitly confirms COD support.
- The requested payment type must also be explicitly supported.
- Missing, unknown, or Swotzy-provided capabilities are not treated as compatible.
- Carriers without a verified COD contract do not produce COD pickup-point options.

If a pickup point does not provide a confirmed COD capability, Baltix removes it from COD rates and post-checkout selection. This prevents customers from selecting a point that cannot collect the payment.

For DPD, the point data must explicitly contain both `codAllowed` and the requested `codPaymentType_card` or `codPaymentType_cash` service.

## 4. Customer checkout experience

### Post-checkout and manual shipping methods

When the selected shipping method is COD, Baltix shows only compatible pickup points. The confirmation step displays a COD banner with:

- the amount that remains unpaid;
- the selected payment type, such as card or cash;
- a reminder that payment is collected when the parcel is picked up.

### CCS / carrier-service checkout

For compatible pickup points, Shopify can show both normal and COD delivery variants. The COD option explains that the outstanding order total is due when the parcel is collected.

## 5. Order amount and label creation

The COD amount is the order's **unpaid or outstanding total**, in the order currency. It is not a shipping surcharge, a fake product, or a separate COD fee.

Baltix preserves the COD state, amount, currency, and payment type through the order webhook and shipment processing. Manual and automatic label creation use the same order data and the same COD semantics.

Shopify keeps a manual-payment order unpaid until you collect the money and mark the order as paid in Shopify. The label can still carry the amount that must be collected at pickup.

### DPD provider settings

Configure these values under **Settings → Carriers → Carrier Settings → DPD → Advanced COD settings**. DPD label creation sends COD through the provider-specific additional service. The current DPD configuration is:

| Baltix setting | Current DPD value |
| --- | --- |
| **COD service alias** | `COD` |
| **COD amount field** | `cst_cod_value` |
| **COD currency field** | `cst_cod_currency` |

These values must match the carrier contract. Change them only when the provider gives you different values. Baltix fails safely when the required COD configuration is incomplete instead of sending a misleading label.

Carrier COD contracts can vary by country and account. Confirm the exact service alias and amount-field format with DPD before changing these settings or enabling a new DPD market.

For label prerequisites and label actions, see [Create a shipping label](./create-label.md).

## 6. Test COD before going live

Use a non-zero cart and run a complete test checkout:

1. Activate Shopify's manual COD payment method.
2. Enable COD in the carrier settings and, for an existing shipping method, mark the linked method as COD.
3. Select a COD delivery option and a compatible pickup point.
4. Confirm that the checkout clearly says payment is due at pickup.
5. Confirm that online payment is restricted as intended for your Shopify setup.
6. Place the order and verify that Shopify shows it as unpaid.
7. Verify the COD state, outstanding amount, currency, and payment type in Baltix.
8. Create a manual label, or let automatic label creation run.
9. Verify that the carrier label contains the COD service and amount.

Do not test COD with a zero-value order. A non-zero order is required to verify that the outstanding amount is propagated correctly to the order and the carrier label.

## Frequently asked questions

### Does selecting a COD shipping option disable card payment automatically?

No. Shopify payment methods are independent from shipping rates. Configure and test Shopify's manual payment and payment-customization settings separately.

### What does the customer pay?

The customer pays the unpaid or outstanding order total in the order currency when collecting the parcel. Baltix does not add a fake product or replace the total with a surcharge.

### Why is a pickup point missing from COD options?

The carrier has not explicitly confirmed that the point supports COD or the selected payment type. Unknown capabilities are intentionally excluded.

### Can I use COD with every carrier?

Only carriers with a verified COD contract and adapter implementation can provide COD pickup-point options and labels. DPD support depends on the carrier service and account configuration.

---

# 🔁 Complete order flow

Source: https://baltix-pickup-points.com/doc/guide/complete-flow

# Complete order flow

This page explains the full lifecycle of a pickup point order in Baltix, from the moment a customer places an order to delivery (or return). It covers both **FULL** mode and **PICKUP ONLY** mode, and all the situations that can happen along the way.

## High-level overview

```mermaid
flowchart TD
    A[🛒 Customer places order] --> B[📦 Order enters Baltix]
    B --> C{Pickup point selected?}
    C -->|Yes| D[✅ Ready for processing]
    C -->|No| E[⏳ Waiting for selection]
    E --> F{Customer selects via recovery page?}
    F -->|Yes| D
    F -->|No, 30 min timeout| G[📍 Auto-select nearest point]
    G --> D
    D --> H{App mode?}
    H -->|FULL| I[🏷️ Create shipping label]
    H -->|PICKUP ONLY| J[📤 Push to external provider]
    I --> K[📬 Carrier delivers to pickup point]
    K --> L[📱 Customer picks up parcel]
    J --> M[External provider handles shipping]
```

---

## 1. Order creation

When a customer places an order in your Shopify store, Shopify sends the order information to Baltix. The app checks whether the order uses a **pickup shipping method** and processes it accordingly.

Baltix extracts:

- Customer details (name, email, phone)
- Shipping address
- Order weight (from product weights)
- Pickup point selection (if already chosen during checkout)

Only orders that use a pickup shipping method are processed by Baltix. Regular shipping orders are ignored.

---

## 2. Pickup point selection

How the pickup point gets selected depends on your Shopify plan and store setup.

```mermaid
flowchart TD
    A[Order created] --> B{Checkout selection available?}
    B -->|Shopify Plus| C[Checkout extension]
    B -->|Grow/Advanced + carrier service| E[Carrier-service rates]
    B -->|No| D[Post-checkout selection]

    C --> C1[Customer selects point during checkout]
    C1 --> C2[Point saved to the order]
    C2 --> OK[✅ Pickup point ready]

    E --> E1[Customer selects point during checkout]
    E1 --> OK

    D --> D1{Thank You page widget enabled?}
    D1 -->|Yes| D2[Customer selects on Thank You page]
    D1 -->|No| D3[Admin sends recovery link]
    D2 --> OK
    D3 --> D4[Customer selects via recovery page]
    D4 --> OK

    D --> D5{No selection after 30 min?}
    D5 -->|Yes| D6[Auto-select nearest point]
    D6 --> OK
```

### Shopify Plus stores

Customers select their pickup point **during checkout** using the Baltix checkout extension. The selection is saved immediately to the order. No extra steps needed.

### Shopify Grow and Advanced stores

On **Growth plan or higher** Baltix subscriptions, customers can select a pickup point during checkout as a shipping option when carrier-calculated shipping is enabled. See [Pickup points at checkout](/doc/setup/checkout-pickup-points) for setup details.

### Other stores

Customers select their pickup point **after checkout**, either:

- On the **Thank You page** (if the widget is enabled via [Extensions](/doc/setup/extensions))
- Via a **recovery link** shared by the store admin — see [Recovery page](/doc/guide/recovery-page)

### Auto-pickup fallback

If the customer does not select a pickup point within **30 minutes**, Baltix automatically selects the nearest point based on the delivery address. A banner is shown in the admin to indicate the point was auto-selected.

---

## 3. Processing — FULL mode

In **FULL** mode, Baltix manages the entire shipping workflow: labels, fulfillment, tracking, and courier pickups.

```mermaid
flowchart TD
    A[✅ Pickup point selected] --> B{Automation mode?}

    B -->|Manual| C[Admin creates label manually]
    B -->|Auto-create labels| D[Baltix creates label automatically]
    B -->|Auto-add to pickup| C

    C --> E[🏷️ Label created]
    D --> E

    E --> F[Order marked as shipped in Shopify]
    F --> G[Customer receives shipping confirmation]

    E --> H{Auto-add to pickup enabled?}
    H -->|Yes| I[Shipment added to courier pickup]
    H -->|No| J[Admin schedules pickup manually]

    I --> K{Pickup mode?}
    K -->|Batch| L[Grouped & confirmed at batch time]
    K -->|Individual| M[Confirmed immediately]

    J --> N[Carrier picks up your shipments]
    L --> N
    M --> N
```

### Label creation

A shipping label can be created **manually** or **automatically** depending on your automation settings.

**Manual**: Open the order in Baltix and click **Create Label**.

**Automatic**: Baltix creates the label as soon as the order is processed, if all conditions are met (pickup point selected, weight valid, credentials configured). See [Automation settings](/doc/setup/app-mode-automation).

When a label is created:

- The carrier provides a **tracking number** and a **printable label**
- Baltix marks the order as shipped in Shopify and includes tracking information
- The customer receives a **shipping confirmation** from Shopify

For details on label formats, downloads, and troubleshooting, see [Create a shipping label](/doc/guide/create-label).

### Pickup scheduling

After a label is created, your shipments need to be picked up by the carrier:

| Pickup mode | Behavior |
| --- | --- |
| **Batch** | Shipments are grouped for the day and scheduled at a set time (e.g. 4 PM) |
| **Individual** | Each shipment is scheduled with the carrier immediately |

See [App Mode and Automation](/doc/setup/app-mode-automation) for full details.

### Tracking updates

Once the parcel is in transit, Baltix updates the tracking status based on carrier information:

```mermaid
flowchart LR
    A[Label Created] --> B[In Transit]
    B --> C[At Pickup Point]
    C --> D[Delivered]
    B --> E[Returned]
    A --> F[Cancelled]
    A --> G[Error]
```

| Status | Meaning |
| --- | --- |
| **Label Created** | Label generated, parcel ready for pickup by carrier |
| **In Transit** | Carrier has the parcel and is delivering it |
| **At Pickup Point** | Parcel is at the customer's selected pickup point, ready for collection |
| **Delivered** | Customer has picked up the parcel |
| **Returned** | Parcel was returned to sender (not collected, refused, etc.) |
| **Cancelled** | Label was cancelled before the parcel was shipped |
| **Error** | Label creation failed — see error details on the order page |

---

## 4. Processing — PICKUP ONLY mode (external provider)

In **PICKUP ONLY** mode, Baltix handles only the pickup point selection. The actual shipping is managed by an external provider like **Swotzy**.

```mermaid
flowchart TD
    A[✅ Pickup point selected] --> B[Baltix pushes data to external provider]
    B --> C{Push successful?}
    C -->|Yes| D[External provider creates label & ships]
    C -->|No| E[❌ Push failed — retry or check config]
    D --> F[Tracking managed by external provider]
```

### What Baltix manages vs. external provider

| Responsibility | Baltix | External provider |
| --- | --- | --- |
| Pickup point display in checkout/thank you page | ✅ | |
| Customer pickup point selection | ✅ | |
| Pushing selection to provider | ✅ | |
| Shipping label creation | | ✅ |
| Fulfillment & tracking | | ✅ |
| Courier pickup scheduling | | ✅ |

In **PICKUP ONLY** mode, the **Carriers**, **Shipping**, **Automation**, and **Pickups** sections are hidden in Baltix. See [App Mode and Automation](/doc/setup/app-mode-automation) for more details.

---

## 5. Pickup point changes

After a pickup point is selected, the customer or merchant may need to change it.

```mermaid
flowchart TD
    A[Pickup point selected] --> B{Change requested?}
    B -->|No| C[Continue normal flow]
    B -->|Yes| D[Admin generates change link]
    D --> E[Customer selects new point]
    E --> F{Label already created?}
    F -->|No| G[Order updated — ready for label]
    F -->|Yes| H[⚠️ Label marked as outdated]
    H --> I[Admin recreates label]
    I --> G
```

### What happens when a pickup point changes

1. The order is updated with the new pickup point
2. The order information is updated in Shopify
3. If a label already exists, it is marked as **outdated** because the pickup point changed
4. A warning banner appears on the order page
5. You must **recreate the label** to generate a new one for the updated pickup point

Changing the pickup point does **not** automatically cancel or recreate the existing label. The admin must take action to recreate it.

---

## 6. Returns

When a parcel is not picked up by the customer or is refused, the carrier returns it to the sender.

```mermaid
flowchart TD
    A[Parcel at pickup point] --> B{Customer picks up?}
    B -->|Yes| C[✅ Delivered]
    B -->|No, storage period expired| D[📦 Returned to sender]
    D --> E[Shipment status: Returned]
```

### Return tracking

- The carrier updates the shipment status to **Returned**
- Baltix updates this status and displays it on the order page
- You can see the full timeline of status changes in the order history

### Handling returns

When a parcel is returned:

1. Check the order page for the **Returned** status
2. Decide whether to reship or refund the customer
3. If reshipping: recreate a new label from the order page

Baltix tracks return status but does not automatically reship or refund orders. You decide what to do next.

---

## 7. Error handling and edge cases

### Common scenarios

| Scenario | What happens | What to do |
| --- | --- | --- |
| **Product has no weight** | Auto-label creation skipped; manual creation blocked | Add weight to all products in Shopify |
| **Weight exceeds locker limit** | Label creation blocked with error | Split into multiple shipments or use a different carrier |
| **Credentials expired** | Label creation fails with error | Re-enter your credentials in `Settings > Carriers > Connection` |
| **Order changed after label created** | Label marked as outdated | Recreate the label from the order page |
| **External provider push fails** | Baltix retries up to 3 times | Check provider configuration; retry manually if needed |
| **Customer doesn't select pickup point** | Auto-selection after 30 min timeout | Recovery link can be sent earlier for faster resolution |
| **FREE plan quota exceeded** | Pickup point selection blocked for new orders | Upgrade your plan |

### Order change detection

Baltix watches for changes that affect the shipment:

- **Weight change** (above a 50g threshold)
- **Pickup point change**
- **Delivery address change**

If a change is detected and a label already exists, the label is flagged as **outdated** and you see a banner explaining what changed.

---

## Summary

```mermaid
flowchart TD
    subgraph "Order Entry"
        A[Customer places order] --> B[Baltix receives order information]
    end

    subgraph "Pickup Selection"
        B --> C{Point selected?}
        C -->|Yes| D[Ready]
        C -->|No| E[Recovery / Auto-select]
        E --> D
    end

    subgraph "FULL Mode"
        D --> F[Create label]
        F --> G[Fulfillment + tracking]
        G --> H[Courier pickup]
        H --> I[Delivery or Return]
    end

    subgraph "PICKUP ONLY Mode"
        D --> J[Push to external provider]
        J --> K[External handles shipping]
    end
```

| Step | FULL mode | PICKUP ONLY mode |
| --- | --- | --- |
| Pickup point selection | ✅ Baltix | ✅ Baltix |
| Label creation | ✅ Baltix | External provider |
| Shopify fulfillment | ✅ Baltix | External provider |
| Courier pickup | ✅ Baltix | External provider |
| Tracking | ✅ Baltix | External provider |
| Return detection | ✅ Baltix | External provider |

---

# 🏷️ Create a shipping label

Source: https://baltix-pickup-points.com/doc/guide/create-label

# Create a shipping label

When you create a shipping label, Baltix:

1. Sends parcel information to the carrier (Omniva, DPD, Latvijas Pasts, etc.)
2. Receives a tracking number and a printable label
3. Marks the order as shipped in Shopify with tracking information
4. Notifies the customer with a tracking link

This feature is only available in **FULL** mode. In **PICKUP ONLY** mode, labels are managed by the external provider.

## Prerequisites

Before you can create a label, make sure:

- The **carrier is connected** with valid login details — see [Connect a carrier](/doc/setup/connect-carrier)
- A **sender address** is configured — see [Sender address](/doc/setup/sender-address)
- The order has a **pickup point selected** by the customer
- All products in the order have a **weight** defined in Shopify

If any product in the order has no weight, Baltix cannot create the label. Add weights to your products in Shopify before retrying.

## Create a label manually

1. Go to **Orders** in the Baltix sidebar.
2. Click on the order you want to ship.
3. Click the **Create Label** button.

Baltix validates the parcel information (weight, pickup point, carrier login details) and sends it to the carrier. If everything is correct, the label is created within a few seconds.

After creation you will see:

- A **tracking number** linked to the carrier tracking page
- The shipment status changes to **Label Created**
- The order is marked as **shipped** in Shopify
- The customer receives a tracking notification email from Shopify

## View and download labels

Once a label is created, you have several options from the order detail page:

| Action | Description |
| --- | --- |
| **View Label** | Opens the label in a preview modal inside Baltix |
| **Download** | Downloads the label as a PDF file |
| **Download as...** | Choose a specific format (available for some carriers) |
| **Open in new tab** | Opens the label PDF in a new browser tab |

### Available label formats

Some carriers support multiple label formats for different printers:

| Carrier | Formats |
| --- | --- |
| **DPD** | A6, A4, PNG, ZPL |
| **Latvijas Pasts** | Sticker 150×100, A4, ZPL |
| **Omniva** | Default PDF only |
| **SmartPosti** | Default PDF only |
| **Unisend (LP Express)** | Default PDF only |

Use **ZPL** format if you have a thermal label printer (Zebra, etc.). Choose the correct DPI (203 or 300) matching your printer.

## Recreate a label

You can recreate a label when the shipment status is **Label Created**, **Error**, or **Cancelled**.

1. On the order detail page, open the **label actions dropdown**.
2. Click **Recreate Label**.

Baltix cancels the previous label with the carrier and creates a new one. The old label is kept in the shipment history for audit purposes.

## Outdated label warning

If the order changes after a label was created, Baltix marks the label as **outdated** and shows a warning banner on the order page.

Changes that trigger this warning:

- **Weight changed** — a product weight was updated or items were added/removed
- **Pickup point changed** — the customer selected a different pickup point

To fix this, **recreate the label** so it matches the current order data.

## Automatic label creation

Instead of creating labels manually, you can enable **Auto-create labels** in `Settings > Automation` for each carrier.

When enabled, Baltix automatically creates a label as soon as an order is received, provided:

- The order has a selected pickup point
- All products have a weight
- The total weight is within the carrier's locker capacity
- No label already exists for the order
- Your plan supports automatic label creation

See [App Mode and Automation](/doc/setup/app-mode-automation) for details.

## Troubleshooting

| Problem | Possible cause | Solution |
| --- | --- | --- |
| "Create Label" button is disabled | No pickup point selected | Wait for customer to select, or use the [recovery page](/doc/guide/recovery-page) |
| Label creation fails with error | Invalid or expired carrier login details | Re-enter your carrier login details in `Settings > Carriers > API Connection` |
| Weight validation error | Products missing weight, or total weight exceeds locker limit | Add weights in Shopify; split into multiple shipments if needed |
| Label created but customer not notified | Shopify notification settings | Check that shipping confirmation emails are enabled in Shopify |

---

# EU withdrawal and returns workflow

Source: https://baltix-pickup-points.com/doc/guide/eu-withdrawal-returns

# EU withdrawal and returns workflow

Baltix uses one return workflow for Shopify stores. When the customer starts it through **Exercise my right of withdrawal**, Baltix marks the return as a legal withdrawal and adds the records required for the EU journey. It is designed around **Directive (EU) 2023/2673, Article 11a**, which requires an easy-to-find online withdrawal function for distance contracts, and the 14-day withdrawal rules in **Directive 2011/83/EU (Consumer Rights Directive)**.

> Baltix helps you offer the required online withdrawal journey. You remain responsible for your legal notices, product exceptions, refund policy, and local requirements.

## What the EU rule requires

For an online distance sale, the withdrawal function should be clearly visible and continuously available during the withdrawal period. The customer must be able to provide or confirm:

- name;
- contract/order details;
- the electronic address used for the acknowledgement;
- an explicit withdrawal statement;
- confirmation of submission.

Baltix records the declaration, order reference, selected items, customer details, deadlines, and sends a confirmation email containing the submission date and time.

The standard period is 14 days from physical possession of the goods. After declaring withdrawal, the customer generally has 14 days to send the goods back. Refund timing may be deferred until the goods or proof of dispatch is received, where permitted by the applicable law.

## Complete decision tree

```mermaid
flowchart TD
    A[Customer places order] --> B[Shopify order delivered]
    B --> C{Withdrawal enabled in Baltix?}
    C -->|No| C1[Extension shows setup warning]
    C -->|Yes| D[Customer sees withdrawal action and Order status block]
    D --> E{Customer submits declaration?}
    E -->|No| E1[No withdrawal request]
    E -->|Yes| F[Capture name, order, email, items and statement]
    F --> G[Record declaredAt and legal deadlines]
    G --> H[Send acknowledgement email]
    H --> I[Customer returns goods within 14 days]
    I --> J{Proof or goods received?}
    J -->|No| K[Await proof / goods; alert before refund deadline]
    J -->|Yes| L[Staff inspects and validates return]
    L --> M[Refund articles and eligible standard delivery in Shopify]
    M --> N[Close and reconcile Shopify return]

    S[Staff creates return in Shopify Admin] --> T[Baltix emails the customer to choose a drop-off point]
    T --> U{Staff approves or declines?}
    U -->|Approve| W[Create a return label in Baltix]
    U -->|Decline| X[Return declined with a reason]
    W --> Y[Track the parcel and receive the goods]
    Y --> Z[Refund in Shopify and close the return]
```

## Customer journey

### 1. Before delivery

The extension may be installed and visible in Customer Accounts, but the customer-facing withdrawal action can be restricted until the order is delivered. This prevents starting the statutory period from the wrong date.

### 2. Declaration

The customer opens **Exercise my right of withdrawal** from the order action menu or the Order status block. The regular Baltix return form opens with an additional legal declaration section. It collects the customer identity, order reference, acknowledgement email, selected products, and a clear confirmation.

### 3. Acknowledgement

After confirmation, Baltix records the declaration, calculates the withdrawal and return deadlines, and sends an acknowledgement email immediately.

### 4. Physical return and refund

The customer sends the goods back. The merchant can create a Baltix label when logistics are needed, or process a return label created elsewhere. Staff should record proof of dispatch or receipt before issuing the refund in Shopify.

## Staff journeys

### Staff starts the return in Baltix

1. Open the order in Baltix and click **Initiate Return**.
2. Choose **Merchant Return** to select the products and quantities yourself, or **Customer self-service** to send the customer a return portal link.
3. For a portal request, review it and approve or decline it. Baltix identifies whether it is a commercial return or a legal withdrawal.
4. Select your reception point and create the return label. The label and tracking are attached to the Shopify return.
5. Track the reverse shipment.
6. Issue the refund in Shopify.

### Staff starts the return in Shopify

1. Staff creates a return from the Shopify order.
2. Baltix picks it up and emails the customer to choose a drop-off point. The returned items stay read-only.
3. If the return is still a request, staff approves or declines it.
4. For an approved return, staff can create a Baltix return label.
5. Staff tracks the parcel, confirms receipt, and issues the refund in Shopify.

Baltix manages the return logistics and shows the return fees and estimated refund, but it does not issue refunds. Issue the refund from the Shopify order.

Returns created in either Shopify or Baltix remain visible in the other system, so staff can continue working from the tool they prefer.

## Configuration checklist

1. Enable **EU legal withdrawal (Baltix)** in Baltix notification settings.
2. Add and save both Customer Account extensions:
   - **Legal withdrawal** — order action menu;
   - **Legal withdrawal block** — Order status page.
3. Confirm the storefront uses the new Customer Accounts.
4. Configure the acknowledgement email and merchant contact details.
5. Test one delivered order and one return created by staff from Shopify.

## References

- [Directive (EU) 2023/2673 — Article 11a and online withdrawal function](https://eur-lex.europa.eu/eli/dir/2023/2673/oj)
- [Directive 2011/83/EU — 14-day withdrawal, return and refund rules](https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:32011L0083)

---

# Get Latvijas Pasts API key

Source: https://baltix-pickup-points.com/doc/guide/latvian-pasts-setup

After signing a contract with [Latvijas Pasts](https://pasts.lv/), ask your account manager for an API key to access the [`ExpressPast API`](https://express.pasts.lv/docApi/#/).

You will receive an API key that looks like this: `67a343260b6D484DA41D12166F6DCa41`.

If you need help, contact us through **Baltix** application, in **Help** menu.

## Configure API in Baltix

1. Head to your **Baltix - Baltic Pickup Points**
2. Go to **Settings**

![Settings menu](/img/setup/shipping-method/attach-shipping-method-1.png)

3. Click on **Carriers (1)** tab.
4. Click on the second tab **API Connection (2)**.

![Settings menu](/img/guide/goto-carrier-setup.png)

5. Fill in the API key in the input field **(3)**.
6. (Optional) Click on **Test Connection (4)** to test the connection between Latvijas Pasts API and Baltix.

![Settings menu](/img/guide/setup-latvian-pasts/configure-latvian-pasts.png)

---

# Get Omniva credentials

Source: https://baltix-pickup-points.com/doc/guide/omniva-setup

After signing a contract with Omniva:
- [Omniva Latvia](https://www.omniva.lv/)
- [Omniva Lithuania](https://www.omniva.lt/)
- [Omniva Estonia](https://www.omniva.ee/)

ask your account manager for API credentials to access the OMX API.

If you need help, contact us through **Baltix** application, in **Help** menu.

## Configure API in Baltix

1. Head to your **Baltix - Baltic Pickup Points**
2. Go to **Settings**

![Settings menu](/img/setup/shipping-method/attach-shipping-method-1.png)

3. Click on **Carriers (1)** tab.
4. Click on the second tab **API Connection (2)**.

![Settings menu](/img/guide/goto-carrier-setup.png)

The API credentials for Omniva are NOT the same as the ones you use to connect to the Omniva dashboard.

5. Fill in the API client code given by your account manager **(3)**.
6. Fill in the API password given by your account manager **(4)**.
7. (Optional) Click on **Test Connection (5)** to test the connection between Omniva API and Baltix.

![Settings menu](/img/guide/setup-omniva/configure-omniva.png)

---

# Recovery page (pickup point selection)

Source: https://baltix-pickup-points.com/doc/guide/recovery-page

# Recovery page

The **recovery page** is a self-service page that lets customers select a pickup point **after checkout**. You generate a link and share it with the customer — they open it, see nearby pickup points on a map, and make their selection.

## When do you need this?

The recovery page is useful when:

- Your store is **not on Shopify Plus** and does not have the checkout extension
- A customer completed checkout **without selecting a pickup point**
- You need to **manually share** a pickup selection link with a customer (email, chat, etc.)

On **Shopify Plus** stores with the checkout extension enabled, customers select their pickup point directly during checkout. The recovery page is rarely needed in that case.

## How it works

### 1. Generate a recovery link

1. Go to **Orders** in the Baltix sidebar.
2. Find the order that has **no pickup point selected**.
3. Click **Generate Recovery Link**.
4. Copy the link to your clipboard.

The link looks like: `https://your-store.myshopify.com/apps/proxy-subpath/pickup/abc123...`

Each link is unique to the order and can only be used once (until a pickup point is selected).

### 2. Share the link with the customer

Send the recovery link to the customer through your preferred channel:

- Email
- SMS
- Live chat
- Social media

### 3. Customer selects a pickup point

When the customer opens the link, they see a page with:

- Their **delivery address** displayed for reference
- A list of **nearby pickup points** sorted by distance, according to your [pickup-point search settings](/doc/setup/checkout-pickup-points#configure-the-pickup-point-search)
- An **interactive map** showing pickup point locations (if Google Maps is configured)
- A **search bar** to find pickup points by name or address
- A **phone number field** (required for some carriers)

The customer clicks on a pickup point to select it, confirms their phone number if needed, and submits.

### 4. What happens after selection

Once the customer selects a pickup point:

- The order is updated with the selected pickup point
- If **auto-label creation** is enabled, Baltix starts creating the shipping label automatically
- Any automatic pickup selection that was scheduled is now cancelled (no longer needed)

## Auto-pickup fallback

If the customer does **not** select a pickup point within **30 minutes** of the order being created, Baltix can automatically select the nearest pickup point based on the customer's shipping address.

This automatic selection:

- Finds the closest pickup point based on your customer's delivery address
- Searches within your configured radius (or shows your configured fallback number of closest points outside the radius if none are found nearby)
- Then follows the same steps as manual selection (label creation, carrier updates, etc.)

Automatic selection only applies to non-Shopify Plus stores where the customer used a pickup shipping method but did not select a specific point. You will see a banner in the admin indicating the point was automatically selected.

## Prerequisites

For the best customer experience on the recovery page:

| Requirement | Why | Link |
| --- | --- | --- |
| **Google Maps API key** | Shows an interactive map with pickup point markers | [Setup Google Maps](/doc/setup/google-maps) |
| **Carrier connected** | Pickup points are loaded from connected carriers | [Connect a carrier](/doc/setup/connect-carrier) |

The recovery page works without Google Maps, but the experience is significantly better with the map enabled. Customers can visually browse pickup points near their address.

## Troubleshooting

| Problem | Possible cause | Solution |
| --- | --- | --- |
| Recovery link shows "not found" | Token is invalid or order was deleted | Generate a new recovery link from the order page |
| No pickup points displayed | Carrier not connected or no points in the area | Check carrier configuration in `Settings > Carriers` |
| Map not showing | Google Maps API key not configured or restricted | See [Setup Google Maps](/doc/setup/google-maps) |
| Customer already selected a point | Link can only be used once | The page will show a message that a point was already selected |

---

# Swotzy Integration

Source: https://baltix-pickup-points.com/doc/guide/swotzy-integration

If you use [Swotzy](https://swotzy.com) to manage your parcel shipments, you can connect it to Baltix. When a customer selects a pickup point at checkout, Baltix will automatically update the matching order in Swotzy with the correct carrier, service, and parcel shop.

The External Provider tab is only visible when your app is running in **Pickup Only** mode.
If you don't see the tab, go to **Settings > General** and switch the app mode.

## Prerequisites

### 1. A Swotzy account with API access

Create an account on [Swotzy](https://swotzy.com).

### 2. Get Swotzy API key

1. Go to left lateral menu.
2. Then click on **Integrations** tab **(1)**.
3. Then click on **API** menun item **(2)**.

![Navigate to Swotzy Integrations > API menu](/img/guide/swotzy-integration/get-api-key-1.png)

4. Create a new API key.

![Create a new Swotzy API key](/img/guide/swotzy-integration/get-api-key-2.png)

3. Save **(3)** Public key and **(4)** Private key.
4. Then go [Connect Swotzy](#connect-swotzy)

### 3. Set product weight and dimensions in Shopify

Each product variant in your Shopify store **must** have its **weight** and **package dimensions** (length, width, height) configured. Baltix sends this data to Swotzy when updating the order — if it is missing, Swotzy may reject the shipment or use incorrect default values.

To set them up:

1. Go to your **Shopify admin > Products**
2. Open a product and scroll to the **Shipping** section
3. Fill in the **Weight**, **Length**, **Width**, and **Height** fields
4. Repeat for every product variant

### 4. Enable "Display store order ID on label" setting

In your Swotzy dashboard, you **must** enable **"Display store order ID on label"** in your integration settings. Baltix uses the Shopify order number to match orders in Swotzy — without this setting enabled, the matching will fail and pickup point data won't be pushed.

#### How to enable setting

1. Go to left lateral menu
2. Then click on **Integrations** tab **(1)**
3. Then click on **Stores** menun item **(2)**

![Swotzy integration menu](/img/guide/swotzy-integration/setup-order-id-1.png)

4. Click on **Manage** button on your Shopify website **(3)**

![Manage shopify website](/img/guide/swotzy-integration/setup-order-id-2.png)

5. Then enable **Display store order ID on label**

![Enable settings](/img/guide/swotzy-integration/setup-order-id-3.png)

6. Don't forget to save by clicking on **Save** button at the bottom of page.

![Save settings](/img/guide/swotzy-integration/setup-order-id-4.png)

## Connect Swotzy

1. Then go to Baltix integrations **Settings** tab.

![Baltix Settings > External Provider tab](/img/guide/swotzy-integration/get-api-key-3.png)

2. Then **External Provider (5)**.
3. Enter Public key from **(3)** in text input **(6)**.
4. Enter Private key from **(4)** in text input **(7)**.

![Enter Swotzy public and private API keys in Baltix](/img/guide/swotzy-integration/setup-api-key-1.png)

5. Click **Test connection** to verify the credentials are valid
6. Click **Save**

Once saved, a green **Connected** badge appears next to the title.

Due to a Shopify platform limitation, it is currently not possible to dynamically adjust the shipping price based on the carrier selected by the customer. The shipping rate displayed at checkout is the one you configured in your Shopify shipping settings, regardless of which carrier pickup point the customer chooses.

Check [Shipping Method setup](/doc/setup/shipping-method) to configure your shipping rates

To complete your setup, follow these guides:
- [Google Maps setup](/doc/setup/google-maps) — required for the pickup point map at checkout
- [Shipping Method setup](/doc/setup/shipping-method) — configure your shipping rates
- [Extensions setup](/doc/setup/extensions) — activate the checkout extensions

## How it works

When a customer places an order and selects a pickup point:

1. Baltix receives a Shopify webhook with the order data
2. A background job searches for the matching order in Swotzy (by order number or customer email)
3. The job updates the Swotzy order with:
   - The carrier (Omniva, DPD, Latvijas Pasts, etc.)
   - The service type (`PARCELSHOP`)
   - The selected parcel shop ID
   - The customer's phone number
   - Package dimensions (from product variant data, if available)

If the Swotzy order is not found immediately (sync delay), the job retries automatically up to 5 times with exponential backoff.

### Order sync status

Each order in Baltix tracks the Swotzy push status:

- **PENDING** — The job is queued or in progress
- **SUCCESS** — The pickup point was pushed to Swotzy successfully
- **FAILED** — All retry attempts failed (check the error message on the order detail page)

You can manually retry a failed push from the order detail page.

## Disconnect Swotzy

1. Go to **Settings > External Provider**
2. Click **Delete**

This removes the stored credentials. Orders already pushed to Swotzy are not affected.

## Troubleshooting

| Problem | Solution |
| ------- | -------- |
| "Connection failed" on test | Double-check the public and private keys. Make sure there are no extra spaces. |
| Order stuck in PENDING | Contact support |
| Order shows FAILED | Open the order detail to see the error. Common cause: the order was not yet created in Swotzy when Baltix update the order. Don't worry Baltix is retying until the order is edited |
| Swotzy order already processed | If the order left "draft" status in Swotzy before Baltix could update it, Baltix marks it as SUCCESS (no action needed). |

---

# Baltix MCP

Source: https://baltix-pickup-points.com/doc/mcp

# Baltix MCP

Let your AI (Claude, Codex, Cursor, Claude Desktop) look up pickup points, check orders, and — if you allow it — create labels. You approve the connection in Baltix. You never copy a secret.

Paste this into your AI:

```text
Set up the Baltix MCP for me: https://baltix-pickup-points.com/doc/mcp
```

A **paid Baltix plan** (Starter or higher) is required.

---

## For you (the merchant)

You do not need to create a token or edit config files. Your AI adds Baltix, then a browser window opens.

1. Enter your shop (for example `mystore` or `mystore.myshopify.com`).
2. You land in Shopify Admin → Baltix → **Settings → MCP**.
3. Check what the AI may do:
   - **Read** is already on (search pickup points, see orders and labels).
   - **Write** is off. Turn it on only if you want the AI to change a pickup point or create/cancel a label.
4. Click **Allow**, then **Continue**. Stay on this screen until Continue — that sends the AI back.

To disconnect later, open **Settings → MCP** and revoke the connection.

Baltix MCP is logistics only. It cannot change your billing, carrier passwords, or Shopify products.

---

## For the AI (setup)

Follow this section exactly. **Do not ask the merchant to create or paste a token.**

1. Add the HTTP URL only. No `Authorization` header, no env var, no `baltix_mcp_…`.
2. Ask them to finish the browser steps above (shop → Allow → Continue).
3. After Continue, call `tools/list`. Then read resource `baltix://docs/mcp` (or fetch `https://app.baltix-pickup-points.com/mcp.llms.md`).

Index for agents: `https://app.baltix-pickup-points.com/llms.txt`
Full dump (Cursor / Context7 / RAG): `https://app.baltix-pickup-points.com/llms-full.txt`

Endpoint: `https://app.baltix-pickup-points.com/mcp`

Do not use a warehouse API key (`baltix_live_…`) here. Do not call `/api/v1` with this connection. Do not call Shopify Admin GraphQL through Baltix.

### Claude Code

```bash
claude mcp add --transport http baltix https://app.baltix-pickup-points.com/mcp
```

### Codex

In `~/.codex/config.toml` or `.codex/config.toml`:

```toml
[mcp_servers.baltix]
url = "https://app.baltix-pickup-points.com/mcp"
```

Do not set `bearer_token_env_var`. If an old connect used a token: `codex mcp logout baltix`, then reconnect.

### Cursor

```json
{
  "mcpServers": {
    "baltix": {
      "url": "https://app.baltix-pickup-points.com/mcp"
    }
  }
}
```

No `headers`.

### Claude Desktop

Same JSON as Cursor (`url` only). If this build cannot open a browser, still do not put a secret in chat.

### Tools

**Always available:** `search_docs` — search official Baltix setup/FAQ docs. Use this before guessing how-to answers.

**Read** (on by default): `search_pickup_points`, `list_orders`, `get_order`, `list_order_packages`, `list_order_labels`, `get_label`, `list_returns`, `get_return`, `list_return_dropoff_points`, `list_carrier_connections`, `get_tracking`, `preview_checkout_rates`.

**Write** (only if they enabled it in Allow): `change_order_pickup_point`, `create_pickup_change_link`, `replace_order_packages`, `create_order_label`, `create_package_label`, `cancel_label`, `create_return`.

If a write tool is missing, ask them to reconnect and turn that write group on. Do not use the REST API instead.

Confirm with the merchant before any write. `preview_checkout_rates` is a Baltix preview, not a live Shopify callback. Carrier credentials stay hidden.

### If something fails

- Browser did not open — re-add the MCP with the URL only.
- They never see Allow — Baltix must be installed, paid plan, shop domain correct.
- `401` — they did not finish Allow/Continue, or a warehouse key was sent. Reconnect. Do not ask for a token in chat.
- `403 paid_plan_required` — Free plan.
- `403 insufficient_scope` — reconnect and enable write in Allow.
- `429` — slow down (about 120 requests/min).

---

# 1️⃣ App Mode and Automation

Source: https://baltix-pickup-points.com/doc/setup/app-mode-automation

This page explains two settings that change how Baltix behaves:

- **App Mode** in `Settings > General`
- **Automation Settings** in `Settings > Automation`

`Automation` settings are only available in **FULL** mode. In **PICKUP ONLY** mode, Baltix focuses on pickup point selection and external provider sync.

## 1. App Mode

You can change the app mode in **Settings > General > App Mode**.

### FULL mode

Choose **FULL** mode if you want Baltix to manage shipping operations directly.

Use it when:

- You have your **own carrier contracts**
- You connect carriers such as Omniva, DPD, SmartPosti, etc. directly in Baltix
- You want to manage **labels, tracking, and courier pickups** from Baltix
- You want to use **Automation Settings**

In this mode:

- Baltix loads pickup points from the configured carrier integrations
- The **Carriers**, **Shipping**, and **Automation** tabs are available
- The **Pickups** section is available in the main navigation
- You can enable automatic label creation and automatic courier pickup workflows

### PICKUP ONLY mode

Choose **PICKUP ONLY** mode if Baltix should only handle the pickup point experience, while another platform manages shipping.

Use it when:

- You already use an external shipping platform such as **Swotzy**
- Labels and shipment execution are handled outside Baltix
- You only need Baltix to show pickup points in checkout / thank-you pages and save the customer selection

In this mode:

- Baltix gets pickup points from the **external provider**
- The **External Provider** tab is shown instead of carrier setup tabs
- The **Carriers**, **Shipping**, **Automation**, and **Pickups** sections are hidden
- When a pickup point is selected, Baltix can push that selection back to the external provider

### Which one should you choose?

Choose **FULL** if Baltix is your shipping operations app.

Choose **PICKUP ONLY** if Baltix is only the pickup-point layer and your shipment workflow already lives in **Swotzy**.

If you are unsure, choose **FULL**. It is the right option for stores that want Baltix to manage carriers, labels, and pickup scheduling end to end.

## 2. Automation Settings

Automation settings are split into:

- **Global pickup scheduling**
- **Per-carrier automation mode**

You can find them in **Settings > Automation**.

## Global pickup scheduling

These settings define how courier pickups are confirmed after a shipment is added to a pickup request.

### Pickup Mode

There are 2 modes:

| Mode | What it does | Best for |
| --- | --- | --- |
| **Batch (grouped by day)** | Shipments are grouped into one pickup for the same day, carrier, and country, then confirmed later | Warehouses that prepare parcels in batches |
| **Individual (immediate confirmation)** | Each pickup is confirmed with the carrier API as soon as the shipment is added | Stores that want immediate pickup requests |

#### Batch mode

In **Batch** mode:

- Baltix creates or updates one pending courier pickup for the day
- New shipments are added to that same pickup
- The pickup is automatically confirmed at the configured **Automatic confirmation time**

Important details:

- If a shipment is added **after** the confirmation time, Baltix schedules it for the **next day**
- If the carrier has a batch size limit, Baltix confirms the pickup immediately once that limit is reached
- At the moment, **Omniva** supports batch pickup with a limit of **20 shipments per pickup**

#### Individual mode

In **Individual** mode:

- Baltix still creates or updates the pickup record
- But the pickup is confirmed with the carrier **immediately**, without waiting for the scheduled time

#### Carrier limitations

Some carriers do not support batch pickup.

Today:

- **Omniva** supports batch pickup
- **SmartPosti** and **DPD** support courier pickup, but not batch pickup

For carriers without batch support, Baltix effectively behaves like **Individual** mode even if the global mode is set to **Batch**.

### Automatic confirmation time

This field is only used when **Pickup Mode = Batch**.

It defines the daily cutoff when Baltix confirms all pending batch pickups.

Example:

- Confirmation time = `16:00`
- A shipment added at `15:30` is grouped into today's batch
- A shipment added at `16:05` is grouped into the next day's batch

Recommended usage:

- Set this to the time when your team usually finishes preparing same-day parcels
- Keep some margin before the carrier's real pickup cutoff

## Per-carrier automation mode

Each connected carrier has its own **Automation mode**.

These modes are mutually exclusive: you choose one per carrier.

### Manual

**Manual** means Baltix does not trigger shipment automation for that carrier.

In practice:

- Labels are created manually from the order page
- Courier pickups are scheduled manually

Choose this when you want full operator control.

### Auto-create labels

This option is available on plans that include automatic label creation.

In practice, Baltix tries to create the shipment label automatically when an order is processed and Baltix already has the required pickup point and parcel data.

Important conditions:

- The shop plan must allow **auto-label creation**
- The carrier must be connected and configured
- The order must have a selected pickup point
- All products in the order must have a weight
- The parcel weight must stay within the carrier's locker limit
- Baltix skips the automation if a shipment already exists for the order

What this mode does **not** do:

- It does **not** automatically confirm a courier pickup
- Pickup scheduling remains manual unless you later add the shipment to a pickup yourself

Choose this when you want faster label generation, but still want to control when pickups are booked.

### Auto-add to pickup

This option is only available for carriers that support courier pickup.

In practice:

- You create the label manually
- Baltix automatically adds that shipment to the next courier pickup
- The pickup is then handled according to the global **Pickup Mode**

This means:

- In **Batch** mode, the shipment joins the current pending batch until the confirmation time
- In **Individual** mode, the pickup is confirmed immediately

Choose this when label creation should stay manual, but courier pickup scheduling should happen automatically afterward.

## Recommended combinations

| Situation | Recommended setup |
| --- | --- |
| You use Swotzy for shipping execution | **PICKUP ONLY** |
| You manage carriers directly in Baltix | **FULL** |
| You want total control over operations | **Manual** |
| You want labels to be created automatically, but pickups reviewed manually | **Auto-create labels** |
| You create labels manually, but want Baltix to handle pickup booking | **Auto-add to pickup** |
| You prepare parcels once per day | **Batch** with a realistic confirmation time |
| You want pickup requests sent immediately | **Individual** |

## Summary

- **FULL** = Baltix manages carriers, labels, tracking, and pickups
- **PICKUP ONLY** = Baltix handles pickup point selection, while an external platform handles shipping
- **Batch** = group shipments and confirm later
- **Individual** = confirm pickups right away
- **Auto-create labels** = automatic label creation only
- **Auto-add to pickup** = manual label creation, automatic pickup scheduling

---

# 2️⃣ Connect carriers

Source: https://baltix-pickup-points.com/doc/setup/connect-carrier

## Get an API Key or Credentials

For compliance and security reasons, Baltix App is not providing any API keys or credentials to connect to any carriers. <br/>
This means that you needs to provide your own one by signing a contract with carrier you want to use before.

Baltix app needs an access to your carrier account to create package label etc... <br/>
The communication between Baltix app and the choosen carrier is made through someting call API.

### Supported carriers
| Carrier    | Delivery countries | Guide to get API key / Credentials |
| -------- | ------- | ------- |
| Omniva  | 🇪🇪 🇱🇻 🇱🇹 | [How to get Omniva API credentials](/doc/guide/omniva-setup) |
| Latvian Pasts | 🇱🇻 | [How to get Latvian Pasts API key](/doc/guide/latvian-pasts-setup) |
| DPD    | 🇪🇪 🇱🇻 🇱🇹 | - |
| SmartPosti    | 🇪🇪 🇱🇻 🇱🇹 | - |

### Coming soon
| Carrier    | Delivery countries |
| -------- | ------- |
| Venipak  | 🇪🇪 🇱🇻 🇱🇹    |
| Unisend (LP Express) | 🇪🇪 🇱🇻 🇱🇹 |
| Fedex    | 🇱🇻 |
| DHL    | 🇱🇻 |

##

---

# 3️⃣ Sender Address

Source: https://baltix-pickup-points.com/doc/setup/sender-address

The sender address is sent to the carrier when creating a label.

The sender address is mandatory for most carriers, thus it is highly recommended to set one up.

## Shopify location

Shopify locations are where the stock of your products is stored.
If you are a small business, it is probably your home address, otherwise the warehouse address. <br/>
This is the **address from where the products will be delivered**. In the case you enabled **automatic courier pickup** in Baltix, the carriers (Omniva, Latvijas Pasts) you configured will pick up your packages from this address.

This address, when a customer orders, will be automatically sent by Baltix to the carrier to create a label. It will be visible on the label.

### Create a Shopify location

If you have already created a Location in Shopify, you can skip this part.

1. Head to your Shopify admin dashboard
2. Click on **Locations** in left side menu

![Market menu Shopify Admin panel](/img/setup/sender-address/create-location-1.png)

3. Click on **Add location (1)**.

![Market menu Shopify Admin panel](/img/setup/sender-address/create-location-2.png)

4. Set a **Name** for this location **(2)**. This name will be shown in Baltix.

![Market menu Shopify Admin panel](/img/setup/sender-address/create-location-3.png)

5. Set an **Address** for the location.

Filling in a phone number is optional in Shopify, but MANDATORY for Baltix. Most carriers require a phone number for label creation.

![Market menu Shopify Admin panel](/img/setup/sender-address/create-location-4.png)

6. Click on **Save (4)** to finalize location creation.

### Verify Shopify location in Baltix

1. Head to your **Baltix - Baltic Pickup Points**
2. Go to **Settings**

![Settings menu](/img/setup/shipping-method/attach-shipping-method-1.png)

3. Click on **Shipping (5)** tab.
4. Check that the location created in the previous step appears in **(6)**.
5. Check that location has valid green badge **(7)**.

![Settings menu](/img/setup/sender-address/verify-location-1.png)

---

# 4️⃣ Google API Keys

Source: https://baltix-pickup-points.com/doc/setup/google-maps

Baltix uses two Google keys:

- A **browser key** for map display in checkout/thank-you.
- A **server key** for geocoding (address to coordinates).

The pickup point selector still works without a Google Maps key — customers will see a list view instead of a map. Adding a key enables the map view for a better experience.

## Step 1 — Create a Google Cloud project

1. Go to the [Google Cloud Console](https://console.cloud.google.com/)
2. Sign in with your Google account (or create one)
3. Click **Select a project** in the top bar **(1)**
4. Then **New Project (2)**
![Test](/img/setup/google-api/create-project-1.jpg)

5. Give it a name (e.g. `My Shopify Store`) **(3)** and click **Create** **(4)**
![Test](/img/setup/google-api/create-project-2.jpg)

6. Then go to the project by clicking on **(1)** and then **(5)**

Google offers a $200/month free credit for Maps API usage. For most stores this means the map is effectively free.

## Step 2 — Enable the required APIs

Baltix requires three Google Maps APIs. You must enable **all three**:

| API | Purpose |
|-----|---------|
| **Maps JavaScript API** | Interactive map in the pickup point selector at checkout |
| **Geocoding API** | Server-side address geocoding for distance sorting |
| **Maps Static API** | Generates the map image shown in the order confirmation |

For each API, follow the same process:

1. Search for **`apis and services`** **(2)** in the bar on the top **(1)**
2. Click on **APIs & Services**

![Test](/img/setup/google-api/enabling-api-1.jpg)

3. Then click on **+ Enable APIs and services**

![Test](/img/setup/google-api/enabling-api-2.png)

4. Search for the API name (e.g. **Maps JavaScript API**) in the search input

![Test](/img/setup/google-api/enabling-api-3.png)

5. Click on it

![Test](/img/setup/google-api/enabling-api-4.png)

6. Then click **Enable**

![Test](/img/setup/google-api/enabling-api-5.png)

**Repeat steps 3–6** for **Geocoding API** and **Maps Static API**.

Google requires a billing account to be linked to your project, even if you stay within the free tier. Go to **Billing** in the console to set it up.

## Step 3 — Create the browser key (Maps)

1. Go back to **APIs & Services**
2. Click **Credentials (1)**

![Test](/img/setup/google-api/create-api-key-1.png)

3. Then **+ Create Credentials (2)**
4. Then **API key (3)**

![Test](/img/setup/google-api/create-api-key-2.png)

5. (Optional) Give a name to your key **(4)**
6. Under Application restrictions, select **Websites (5)**

![Test](/img/setup/google-api/create-api-key-3.png)

7. Add website restrictions.

For security reasons, this protection step is mandatory because the API key will be exposed to all clients. This means that anyone will be able to see the API key.
Without those restrictions, anyone copying this key will be able to use it.

To add a new website, click on **Add (6)**. Add your Shopify domain, your custom domain if you have one, and the Baltix app domain.

For example, if your store is `baltic-fashion.myshopify.com` with a custom domain `baltic-fashion.com`:
You have to add exactly:

```
https://baltic-fashion.myshopify.com/*
https://baltic-fashion.com/*
https://*.baltic-fashion.com/*
https://app.baltix-pickup-points.app/*
```

`https://app.baltix-pickup-points.app/*` is the same for every store — do **not** replace it with your own domain. It is required for the map to render inside the Shopify admin. Without it you get `RefererNotAllowedMapError`.

Do **not** use only `*.baltic-fashion.myshopify.com/*`.
This does not match the root domain `baltic-fashion.myshopify.com/*` and causes `RefererNotAllowedMapError`.

Replace the example URLs above with your own store domains.

![Test](/img/setup/google-api/create-api-key-4.png)

8. Click **Save (8)**

Then set API restrictions for this key to:

- **Maps JavaScript API**
- **Maps Static API**

## Step 4 — Create the server geocoding key

Create a second key in **APIs & Services > Credentials**:

1. Click **+ Create Credentials** > **API key**
2. Set **Application restrictions** to `None`
3. Set **API restrictions** to **Geocoding API** only

Do not use HTTP referrer restrictions for this server key.

## Step 5 — Set daily quotas (optional)

To prevent unexpected charges, you can set a daily request limit:

1. Go to **APIs & Services** > **Maps JavaScript API**
2. Click the **Quotas** tab
3. Set a daily limit (e.g. 1,000 requests/day is plenty for most stores)

## Step 6 — Add keys in Baltix

1. Open the **Baltix app** in your Shopify admin
2. Go to **Settings** > **General**
3. Paste your browser key in **Google Maps API Key**
4. Paste your server key in **Geocoding API Key (Server)**
5. Click **Save**

## Verify it works

1. Go to your store and add a product to the cart
2. Proceed to checkout and select a shipping method linked to a carrier
3. The pickup point selector should display with a **map view**

If you see the list view but no map, check the troubleshooting section below.

## Troubleshooting

| Problem | Solution |
|---------|----------|
| Map doesn't appear | Make sure all three APIs are enabled (Step 2) |
| Map shows but pickup points are not centered correctly | Make sure the **Geocoding API** is enabled and the **Geocoding API Key (Server)** is filled in Baltix |
| No map image in order confirmation | Make sure the **Maps Static API** is enabled |
| "ApiNotActivatedMapError" in browser console | Enable billing on your Google Cloud project |
| "RefererNotAllowedMapError" | Check your HTTP referrer restrictions. Add the exact root domain (`your-store.myshopify.com/*`) and not only `*.your-store.myshopify.com/*` |
| Map loads but shows "For development purposes only" | Link a billing account to your Google Cloud project |
| Key saved but map still not showing | Wait a few minutes — Google can take up to 5 minutes to propagate a new key |

---

# 5️⃣ Shipping Method

Source: https://baltix-pickup-points.com/doc/setup/shipping-method

This tutorial is covering:
- How to create a Shopify market
- How to create a shipping method
- How to connect a shipping method to a market
- How to attach Baltix carrier(s) to a shipping method

## Shopify Market

Creating a new market in Shopify admin panel is optional but recommended.

A Shopify market is a group of countries where you allow your store's products to be delivered.

### Create a Market

1. Head to your Shopify admin dashboard
2. Click on **Markets** in left side menu

![Market menu Shopify Admin panel](/img/setup/shipping-method/create-market-1.png)

3. Click on **Create market** in the top right corner **(1)**

![Create Market button](/img/setup/shipping-method/create-market-2.png)

4. Give a name to the market **(2)** <br/>
In our example: **Baltic**
5. Click on **Add condition (3)**
6. In the opened modal, search for the countries you want to send your products to. <br/>
In our example **Latvia, Estonia, Lithuania**.

![Create Market form](/img/setup/shipping-method/create-market-3.png)

7. Check that the selected countries are correct **(4)**

![Market selected countries](/img/setup/shipping-method/create-market-4.png)

7. Create the market by clicking on **Save**.

![Save market](/img/setup/shipping-method/create-market-5.png)

Bravo 🎉, you have created your first Market.

## Shipping Method

Shipping methods in Shopify are the delivery options your customers will see at checkout.

We highly recommend creating a separate shipping method for Baltix to avoid any problems or incompatibility with other apps.

### Create Shipping Method

1. Head to your Shopify admin dashboard
2. Click on **Settings** at the bottom of the left side menu

![Settings menu](/img/setup/shipping-method/shipping-method-1.png)

3. Click on **Shipping and delivery**.

![Settings menu](/img/setup/shipping-method/shipping-method-2.png)

4. Click on the card **General shipping rates**.

![Settings menu](/img/setup/shipping-method/shipping-method-3.png)

### Select shipping zone

5. In **(2)** you can see all products to which the shipping method will apply. <br/>
By default, leave it as it is.

6. Then click on **Add Shipping zone (3)**

![Settings menu](/img/setup/shipping-method/shipping-method-4.png)

7. Select **Europe (4)**, which will select the zone you defined in Market (Baltic Market for our example).
8. Then click on **Done (5)**.

![Settings menu](/img/setup/shipping-method/shipping-method-5.png)

### Shipping rates

Shipping rates (a.k.a. shipping price) are the delivery options you see at checkout. Each shipping rate is a different shipping option.

Shipping rates depend on each carrier, delivery country, or address. You need to manually check the carrier documentation to find out what rate applies to you. <br/>
For Shopify Grow and Advanced stores with carrier-calculated shipping enabled, Baltix can calculate pickup-point rates automatically. See [Pickup points at checkout](./7-checkout-pickup-points.md) for setup instructions.

There are 2 different shipping rate setups:

#### One rate for all carriers
Use this setup when you have one or more carriers configured in the Baltix app and you want one shipping rate for all carriers.

Follow [Add shipping rates](#Add shipping rates).

#### One rate for each carrier
Use this setup when you have one or more carriers configured in the Baltix app and you want to set a different shipping rate for each.

Follow [Add shipping rates](#Add shipping rates) for each carrier configured in Baltix.

### Add shipping rates

9. Click on **Add rate (6)**.

![Settings menu](/img/setup/shipping-method/shipping-method-6.png)

10. Add a name **(7)** to the shipping rate. Set a meaningful name because this is the name that will be shown in delivery options on the checkout page.
11. Set a price for the shipping rate **(8)**.
12. Click on **Done** to create the shipping rate.

![Settings menu](/img/setup/shipping-method/shipping-method-7.png)

13. Click on **Save** to finish the creation.

![Settings menu](/img/setup/shipping-method/shipping-method-8.png)

Well done 🎉 You have successfully created a shipping method.

## Attach a carrier to a shipping method in Baltix

1. Head to your **Baltix - Baltic Pickup Points**
2. Go to **Settings**

![Settings menu](/img/setup/shipping-method/attach-shipping-method-1.png)

3. Click on **Pickup Points** tab **(1)**

![Settings menu](/img/setup/shipping-method/attach-shipping-method-2.png)

4. **(2)** There you can see the previously created shipping rates.
5. Click on **Link carriers (3)** to attach a carrier.
6. Select the carrier you want to link to this shipping method **(4)**.
7. Click on **Save**.

![Settings menu](/img/setup/shipping-method/attach-shipping-method-3.png)

---

# 6️⃣ Activate Checkout Extensions

Source: https://baltix-pickup-points.com/doc/setup/extensions

Baltix uses two Shopify UI extensions to display the pickup point selector and the selected pickup point confirmation to your customers. These extensions need to be **activated** in the Shopify checkout editor.

Before activating extensions, make sure you have:
1. Connected at least one carrier (Settings > Carriers)
2. Linked shipping methods to carriers (Settings > Pickup Points)

## Overview

| Extension | Where it appears | Purpose |
|-----------|-----------------|---------|
| **Pickup point selector** | Checkout (Shopify Plus) / Thank You page (all plans) | Lets customers choose a pickup point |
| **Selected pickup point** | Thank You page + Order Status page | Shows the selected pickup point confirmation |

- **Shopify Plus**: The pickup selector appears **directly in checkout**, under shipping options. Customers must select a pickup point before completing their order.
- **Standard plans**: The pickup selector appears on the **Thank You page** after checkout. Customers select their pickup point after placing their order.

---

## Part A — Pickup Point Selector

This is the main extension. It displays a map (or list) of available pickup points for the customer to choose from.

### For Shopify Plus stores (Checkout)

1. In Shopify Admin, go to **Settings** > **Checkout** > **Customize**
2. The checkout editor opens. Navigate to the **Shipping** step (use the breadcrumb or the page selector at the top)
3. In the left sidebar, click **Add app block**
4. Select **Pickup point selector** from the list
5. Place it **after the shipping options** section
6. Click **Save**

#### Go to Checkout Theme editor

First step is to go to Shopify's **Theme editor**:
1. Go to home page of shopify's admin dashboard
2. Click on **settings** menu at the bottom of left sidebar
![Shopify settings menu](/img/setup/extensions/settings-shopify.png)

3. Click on **Checkout**
![Checkout menu](/img/setup/extensions/checkout.png)

4. Click on **Edit** button
![Edit theme button](/img/setup/extensions/edit-theme.png)

5. You should be on a page looking like this: <br/>
<a id="menu-1">**(1)**: Sidebar is the block editor <br/></a>
<a id="menu-2">**(2)**: Selector for page, in our case **Thank you** and **Order status** page</a>
![Shopify theme editor](/img/setup/extensions/checkout-editor.png)

#### Activate on `Thank you` page

1. In [header selector (2)](#menu-2), select **Thank you** page, click on **(1)**, then **(2)**:
![Edit theme button](/img/setup/extensions/thank-you/go-to.png)

2. In [sidebar (1)](#menu-1), locate **Main (1)**, then click on **Add block**, then choose **Pickup point selector**.
![Edit theme button](/img/setup/extensions/thank-you/add-block.png)

3. You can move the block wherever you want in the page, position don't matters. <br/>
Recommended placement: **at the top of the page**, so customers see it immediately

4. Click **Save**

![Save](/img/setup/extensions/save.png)

---

## Part B — Selected Pickup Point

This extension displays a confirmation card showing the pickup point the customer selected. It includes the address and a small map.

### Thank You page

1. In Shopify Admin, go to **Settings** > **Checkout** > **Customize**
2. Switch to the **Thank you** page
3. Click **Add app block** and select **Selected pickup point**
4. Recommended placement: **after the order confirmation**, before customer information
5. Click **Save**

### Order Status page (Customer Account)

This lets customers see their selected pickup point when they check their order status.

1. In Shopify Admin, go to **Settings** > **Customer accounts** > **Customize**
2. Navigate to the **Order Status** page
3. Click **Add app block** and select **Selected pickup point**
4. Recommended placement: **between Order status and Customer information**
5. Click **Save**

---

## Quick Reference

| Extension | Page | How to access editor | Recommended placement |
|-----------|------|---------------------|----------------------|
| Pickup point selector | Checkout (Plus only) | Settings > Checkout > Customize > Shipping step | After shipping options |
| Pickup point selector | Thank You | Settings > Checkout > Customize > Thank You | Top of page |
| Selected pickup point | Thank You | Settings > Checkout > Customize > Thank You | After order confirmation |
| Selected pickup point | Order Status | Settings > Customer accounts > Customize > Order Status | Between order status and customer info |

## Verify it works

1. Go to your store and add a product to the cart
2. Proceed to checkout and select a shipping method that is linked to a carrier
3. **Shopify Plus**: The pickup point selector should appear under your shipping options
4. **Standard plans**: Complete checkout — the pickup point selector should appear on the Thank You page
5. Check the **Order Status** page in your customer account to verify the selected pickup point is displayed

- Make sure you have **linked at least one carrier** to the shipping method the customer selected (Settings > Pickup Points)
- Verify the extensions are **enabled** (not just added) in the checkout editor — check the visibility toggle in the sidebar
- Try a different browser or incognito mode to avoid caching issues

---

# 7️⃣ Pickup points at checkout (Shopify Grow plan)

Source: https://baltix-pickup-points.com/doc/setup/checkout-pickup-points

If your Shopify store is on the **Grow plan or higher** (but not Shopify Plus), you can display pickup points **directly at checkout** as shipping options. Customers pick a location during checkout, sorted by distance to their address — no post-checkout step required.

This depends on your **Shopify** plan (the plan you pay Shopify for) — **not** your Baltix plan.

- **Shopify Basic** — Not supported. Use the Thank You page selector instead (see [step 6](./6-extensions.md)).
- **Shopify Grow (annual billing)** — Supported. Carrier-calculated shipping is **included for free**.
- **Shopify Grow (monthly billing)** — Supported, but carrier-calculated shipping is a paid add-on (**$20/month**). To enable it, **contact Shopify customer support** and ask them to add carrier-calculated shipping to your account.
- **Shopify Advanced** — Supported. Carrier-calculated shipping is included.
- **Shopify Plus** — You already have access to the richer native checkout extension. No need to use this setup.

- Baltix **Growth plan or higher** subscription
- **Shopify Grow plan or higher** with carrier-calculated shipping enabled (free on Grow annual; $20/month add-on on Grow monthly — contact Shopify support to enable)
- At least one carrier connected in **Settings → Carriers**

---

## How it works

1. The customer enters their delivery address at checkout
2. Shopify asks Baltix for available shipping rates
3. Baltix returns the configured number of pickup points, sorted by distance according to your limit and search-radius settings
4. The customer selects a pickup point as their shipping method and completes the order

Each pickup point shows up as its own shipping option in the **Shipping method** list, prefixed with its distance from the customer's address:

![Pickup points listed as shipping methods at checkout (Grow plan)](/img/setup/carrier-calculated-shipping/preview-CCS.png)

The price of each rate is the price you configured per carrier and country — not a flat rate.

## Configure the pickup-point search

These settings are available in **Settings → Pickup Points**.

### Number of pickup points

In the **Pricing** tab, use **Pickup points shown at checkout** to choose how many points are displayed. You can set a value from **1 to 100** and choose one of two modes:

- **Global limit** — shows the closest points overall across all enabled carriers, up to the configured number.
- **Limit per carrier** — shows up to the configured number of closest points for each enabled carrier.

### Search radius

In the **General** tab, **Pickup point search radius** controls how far Baltix searches from the customer's delivery address. Growth plans and higher can configure a radius from **1 to 50 km**.

When at least one point is found inside the radius, only points inside that radius are considered, then the display limit is applied. If no point is found inside the radius, you can choose to show a fallback list of the closest points outside the radius, with a separate limit from **1 to 100**. Disable this fallback if no out-of-radius points should be shown.

The default configuration is a **5 km** radius with fallback enabled and up to **20 fallback points**.

---

## Part A — Register the shipping service

Baltix needs to be registered as a calculated shipping carrier inside Shopify before pickup points can appear at checkout.

1. Open your Baltix dashboard
2. In the **Getting Started** guide, find the step **Register shipping service in Shopify**
3. Click **Register**

You should see a confirmation that the carrier service was registered. If it fails, double-check that your Shopify plan supports carrier-calculated shipping — free on **Shopify Grow annual** (or higher), or the **$20/month** add-on on **Shopify Grow monthly** (contact Shopify customer support to enable it).

Registering the service is not enough. You must then go to **Shopify Settings → Shipping and delivery** and **enable all services in the list** for the Baltix carrier. Until you do, Shopify will not call Baltix and no pickup points will appear at checkout. See [Part C](#part-c--enable-baltix-in-your-shopify-shipping-zones) below.

If you change carriers or pricing later, click **Re-register** on the same step. This forces Shopify to refresh the list of available services.

---

## Part B — Set the price per carrier and country

Each carrier needs a price configured for each country you ship to. Without a price, the rate appears as free at checkout.

1. From the dashboard, click **Configure pricing** on the **Set checkout pricing** step
   _(or go directly to **Settings → Checkout pricing**)_
2. For each carrier, set the price for each enabled country
3. Click **Save**

The currency is always EUR by default. Each row corresponds to one carrier in one country.

---

## Part C — Enable Baltix in your Shopify shipping zones

This is the most important step. Even after registering the service, Shopify will not call Baltix until you enable it in at least one shipping zone.

1. In Shopify Admin, go to **Settings → Shipping and delivery**
2. Find the shipping profile that covers the country you want to enable (for example, the zone containing Latvia or Lithuania)
3. Click **Add rate** (or edit an existing rate)
4. Choose **Use carrier or app to calculate rates**

5. In the carrier dropdown, select **Baltix Pickup Points**
6. A modal opens listing all available shipping services — **check all of them** to enable the carrier

The modal lists every pickup point Shopify discovered during the last service refresh. **Select all of them**, then click **Done**. If some services are left unchecked, the corresponding pickup points may not appear at checkout.

The number of services you check here also sets the maximum: in Baltix you can then limit how many pickup points are shown at checkout — anywhere from **1 up to the number of services you checked** in this list.

7. Click **Save** on the rate, then **Save** on the shipping zone

---

## Verify it works

1. Go to your storefront and add a product to the cart
2. Proceed to checkout
3. Enter a delivery address in one of your enabled countries
4. Under **Shipping method**, you should see pickup points listed by carrier, sorted by distance

Shopify caches shipping rates per address. If you don't see your pickup points after a change, change the postal code or open the checkout in an incognito window to force a new rate calculation.

---

## Troubleshooting

### "Baltix Pickup Points" doesn't appear in the carrier list

- Your Shopify plan doesn't support carrier-calculated shipping. Upgrade to **Shopify Grow annual** (free), or on **Shopify Grow monthly** contact Shopify customer support to add the **$20/month** carrier-calculated shipping add-on.
- The carrier service wasn't registered. Open the Baltix Getting Started guide and click **Register**.

### Only one carrier shows at checkout

- Other carriers may not have pickup points within range of the customer's address.
- Verify the carrier is **connected and enabled** in **Settings → Carriers**.

### Pickup points show as free at checkout

- You haven't set a price for that carrier and country yet. Open **Settings → Checkout pricing** and set a price.

### Prices changed but still show the old amount at checkout

- Shopify caches rates. Change the postal code at checkout to force a refresh, or test in an incognito window.

---

## Differences vs Shopify Plus checkout extension

| Feature | Shopify Plus (extension) | Shopify Grow (this setup) |
|---------|-------------------------|---------------------------|
| Where customer selects | Native Shopify checkout slot | Pickup points listed as shipping rates |
| Map view | Yes, built into the extension | No — list view only |
| Custom UI | Fully customizable | Limited to Shopify's shipping options |
| Pricing source | Configured in Shopify shipping settings | Configured in Baltix → Checkout pricing |

On Shopify Plus, the same pickup points appear inside a richer embedded widget with a search box and a **Map / List** toggle, instead of being listed as separate shipping rates:

![Shopify Plus checkout extension — list view](/img/setup/carrier-calculated-shipping/preview-checkout-list.png)

![Shopify Plus checkout extension — map view](/img/setup/carrier-calculated-shipping/preview-checkout-map.png)

If you upgrade to Shopify Plus later, Baltix will automatically switch to the checkout extension flow.

---

# welcome

Source: https://baltix-pickup-points.com/doc/

# Welcome to Baltix

Welcome to the official **Baltix documentation**!

"Baltix - Baltic Pickup" is a Shopify application that allows you to offer pickup point delivery options across the Baltic states.

Baltix is proudly made in Latvia 🇱🇻

## Key Features

- 📦 **Pickup Points**: Offer parcel locker and pickup point delivery
- 🇱🇻🇱🇹🇪🇪 **Baltic Coverage**: Latvia, Lithuania, and Estonia
- 🚚 **Local Carriers**: Latvijas Pasts, Omniva, and more
- ⚙️ **Easy Setup**: Simple configuration to get started

## Quick Start

1. Install the app from the [Shopify App Store](https://apps.shopify.com/baltix-pickup-points)
2. Configure your carriers (Settings > Carriers)
3. Configure your sender address (Settings > Shipping)
4. [Set up your Google Maps API key](setup/google-maps)
5. Link shipping methods to carriers (Settings > Pickup Points)
6. [Activate checkout extensions](setup/extensions)
7. Review [App Mode and Automation](setup/app-mode-automation)

## Integrations

- [Swotzy Integration](guide/swotzy-integration) — Automatically push pickup point selections to your Swotzy account
- [Public API Reference](https://app.baltix-pickup-points.app/api/docs) — Explore the interactive Swagger UI documentation for orders, pickup points, labels, authentication, and scopes
- [Baltix MCP](/doc/mcp) — Connect Claude Code, Codex, Cursor, or Claude Desktop with OAuth
- [Baltix for AI tools](/doc/ai) — llms.txt / Context7-style docs for agents

## Support

For any questions or assistance, contact our support team through the in-app chat or the Help page.
