# soundsgood.dev — Full Documentation
> Complete documentation for Shopify apps by Sounds Good Agency
> Generated from source files. For the latest version, visit https://soundsgood.dev
---
## Source: src/content/docs/en/czech-names/billing.mdx
---
title: Billing & Plans
description: CZ Names app pricing, Shopify Plus pricing, and subscription management
---
CZ Names offers two pricing plans. Both include a 14-day free trial and are billed through Shopify's standard app billing system — no separate payment method required.
## Plans
| | Regular | Shopify Plus |
|---|---------|--------------|
| **Monthly price** | $9.90 / month | $19.99 / month |
| **Free trial** | 14 days | 14 days |
| **All features included** | Yes | Yes |
| **Klaviyo integration** | Yes | Yes |
| **UI Extensions** | Yes | Yes |
| **For** | All Shopify plans | Shopify Plus stores |
Both plans include the same full feature set. The difference in pricing reflects the higher transaction volume and customer base typical of Shopify Plus stores.
## Automatic plan detection
When you install the app, it reads your Shopify plan and pre-selects the appropriate billing option:
- **Shopify Plus store** → Shopify Plus plan pre-selected
- **All other plans** → Regular plan pre-selected
You can review and change the selection before confirming your free trial.
## Free trial
Your 14-day free trial begins the moment you accept the billing confirmation. During the trial:
- All features are fully active
- No charge is made to your account
- You can cancel at any time without being billed
At the end of the trial, Shopify charges the monthly fee automatically. You will receive a receipt from Shopify (not from SGA) as the charge goes through the standard Shopify app billing system.
:::tip
If you install the app but do not complete the billing confirmation step, the app will remain inactive. Make sure to click **Start free trial** after installation to activate all features.
:::
## Managing your subscription
### Viewing your current plan
Go to **Settings → Billing** in the Shopify admin, then select **Apps**. CZ Names appears in the list of active app subscriptions with its monthly charge.
Alternatively, open the CZ Names app in your Shopify admin — the current plan and next billing date are shown on the app dashboard.
### Cancelling
1. Go to your Shopify admin
2. Navigate to **Settings → Apps and sales channels**
3. Find **CZ Names** and click **Delete**
4. Confirm the deletion
When you delete the app, your subscription is cancelled immediately and no further charges are made. Any metafields already written to customer profiles will remain in Shopify but the app will no longer process new customers or update existing ones.
:::note
Cancelling during the free trial period incurs no charge. Cancelling mid-billing-cycle does not generate a partial refund — the current month's charge has already been processed by Shopify.
:::
### Reinstalling after cancellation
You can reinstall the app at any time from the Shopify App Store. A new 14-day trial is not offered on reinstall — the standard monthly fee applies from day one. Existing metafields on customer profiles will be picked up by the app automatically on the next customer update event.
## Billing questions
For billing issues, contact Shopify Support — charges appear on your Shopify invoice and are managed through Shopify's app billing system. For questions about the app itself or your plan, contact us at [integrace@soundsgood.agency](mailto:integrace@soundsgood.agency).
---
## Source: src/content/docs/en/czech-names/getting-started.mdx
---
title: Getting Started
description: Install and configure the CZ Names app for Czech customer name declension
---
This guide walks you through installing CZ Names, choosing a billing plan, and verifying that the app is processing your customers correctly.
## Prerequisites
- A Shopify store with Czech-speaking customers
- Admin access to your Shopify store
## Step 1 — Install the app
1. Open the [Skloňování jmen](https://apps.shopify.com/sklonovani-jmen) listing on the Shopify App Store
2. Click **Add app**
3. Review the requested permissions and click **Install app**
The app requests the following permissions:
| Permission | Why it's needed |
|------------|-----------------|
| `read_customers` | Read customer first and last name to send for declension |
| `write_customers` | Write declined name forms back as customer metafields |
## Step 2 — Choose a billing plan
After installation, you are presented with the billing plan selection screen.
| Plan | Price | For |
|------|-------|-----|
| Regular | $9.90 / month | All Shopify plans |
| Shopify Plus | $19.99 / month | Shopify Plus stores |
The app detects your Shopify plan automatically. If you are on Shopify Plus, you will see the Plus plan pre-selected.
Both plans include a **14-day free trial** — you will not be charged until the trial ends. You can cancel at any time during the trial without being billed.
Confirm your subscription to activate the app and start the trial.
## Step 3 — Verify the app is running
After accepting billing, the app is immediately active. You can verify this by checking the app settings page, which shows your billing status and processing statistics.
:::note
Existing customers are not automatically back-processed. The app processes customers **on create or update events**. To process an existing customer, make a small edit to their profile (for example, re-save their name) to trigger the webhook.
:::
## Step 4 — Test with a sample customer
The quickest way to verify everything is working:
1. Go to **Customers** in your Shopify admin
2. Create a test customer with a common Czech name, for example:
- First name: `Jana`
- Last name: `Nováková`
3. Save the customer
4. Wait a few seconds, then reload the customer profile
5. Scroll to the **Metafields** section and look for the `czech-names-app` namespace
You should see three metafields:
```
czech-names-app.addressing → "Jano"
czech-names-app.last-name-addressing → "Novákové"
czech-names-app.gender → "female"
```
:::tip
If you don't see the metafields immediately, wait 10–15 seconds and refresh. The declension API call is asynchronous and typically completes within a few seconds.
:::
## Step 5 — Configure templates (optional)
The app includes a template system that lets you combine the declined first and last name with gender-conditional text (for example, "Pane" vs "Paní"). See [Name Templates](../name-templates) for the full template syntax.
## Step 6 — Add UI Extensions (optional)
The app ships with five UI Extension slots for the customer account portal and checkout flow. These display the addressing form wherever you embed them. To activate them, go to **Online Store → Customize** (or **Checkout Editor**) and add the CZ Names blocks to your desired sections.
Available extension slots:
| Extension | Location |
|-----------|----------|
| `czech-names-profile` | Customer account profile page |
| `czech-names-order-index` | Customer account order list |
| `czech-names-order-status` | Customer account order detail |
| `czech-names-thankyou` | Post-purchase thank-you page |
| `czech-names-checkout-reductions-before` | Checkout page (before reductions) |
## Next steps
- [Use declined names in Liquid templates](../liquid-usage) — email notifications, order confirmations, themes
- [Set up Klaviyo integration](../klaviyo) — sync Czech data to Klaviyo profiles
- [Customize name templates](../name-templates) — gender-aware greeting formats
---
## Source: src/content/docs/en/czech-names/index.mdx
---
title: CZ Names
description: Czech name declension app for Shopify — personalize emails with proper Czech addressing
---
CZ Names automatically converts your Czech customers' names into the **vocative (addressing) form** — the grammatical form Czech speakers use when addressing someone directly. Instead of "Vážený Jan Novák", your emails read "Vážený Jane Nováku".
## Why this matters
Czech is a highly inflected language. When you address a customer in an email, SMS, or notification, the grammatical form of their name changes. Using the dictionary form ("nominative") sounds unnatural and impersonal. CZ Names handles this automatically, so your customer communications feel native and professional.
| Dictionary form | Addressing form |
|-----------------|-----------------|
| Jan | Jane |
| Jana | Jano |
| Novák | Nováku |
| Nováková | Novákova |
## Key features
- **Automatic declension** — processes every new and updated customer using the [sklonovani-jmen.cz](https://sklonovani-jmen.cz) API
- **Gender detection** — determines linguistic gender (male, female, unknown) for use in gender-conditional templates
- **Shopify metafields** — writes results directly to customer metafields, available everywhere Shopify supports metafields
- **Liquid support** — use declined names in email notifications, order confirmations, and theme templates
- **UI Extensions** — place the addressing form on the customer account portal, order pages, checkout, and thank-you page
- **Klaviyo integration** — sync Czech addressing data to Klaviyo profiles for personalized email campaigns
- **Smart caching** — results cached in Firestore to avoid redundant API calls
- **14-day free trial** — no charge until the trial ends
## How it works
1. A customer is created or updated in your Shopify store
2. The app receives a webhook and sends the name to the declension API
3. The declined forms and gender are cached and written back as customer metafields
4. The metafields are available in Liquid templates, UI Extensions, and Klaviyo
## Metafields written
| Metafield key | Contents | Example |
|---------------|----------|---------|
| `czech-names-app.addressing` | Declined first name | `Jane` |
| `czech-names-app.last-name-addressing` | Declined last name | `Nováku` |
| `czech-names-app.gender` | Linguistic gender | `male`, `female`, or `unknown` |
All metafields are `single_line_text_field` type.
## What gets processed
The app processes names that contain only standard Czech and Latin alphabet characters (plus digits and underscores) and are at least 2 characters long. Names with hyphens, spaces, apostrophes, or non-Latin scripts are marked as non-translatable and the original name is kept as the fallback value.
## Get started
Install the app from the Shopify App Store: [**Skloňování jmen**](https://apps.shopify.com/sklonovani-jmen), then follow the [Getting Started](./getting-started) guide.
---
## Source: src/content/docs/en/czech-names/klaviyo.mdx
---
title: Klaviyo Integration
description: Sync Czech addressing data to Klaviyo for personalized email campaigns
---
The CZ Names Klaviyo integration automatically syncs the declined name forms and gender to matching Klaviyo profiles. Once synced, you can use the Czech addressing data in any Klaviyo email, SMS, or flow template.
## Setup
You need two Klaviyo API keys: a **Public key** (also called Site ID) and a **Private key**.
### Finding your Klaviyo API keys
1. Log in to your Klaviyo account
2. Go to **Account → Settings → API Keys**
3. Copy your **Public API Key** (visible on the main API Keys page)
4. Create a new **Private API Key** with at least `profiles:read` and `profiles:write` scopes, then copy it
### Entering keys in the app
1. Open the CZ Names app in your Shopify admin
2. Go to **Settings → Klaviyo Integration**
3. Paste your Public API Key and Private API Key
4. Click **Save**
The integration activates immediately for all subsequent customer creates and updates.
## How the sync works
When a customer's name is processed:
1. The app declines the name and writes the Shopify metafields
2. The app then looks up the customer's email address in Klaviyo to find their profile
3. If found, the app updates the Klaviyo profile with three custom properties:
- `Czech addressing` — declined first name
- `Czech last name` — declined last name
- `Gender` — `male`, `female`, or `unknown`
:::caution
There is a **3–5 minute delay** between a new customer being created in Shopify and their profile becoming available in Klaviyo. During this window, the sync will be skipped. The Klaviyo sync does **not** retry automatically — it runs once per customer event.
:::
If you have customers who signed up before the integration was enabled, trigger a re-sync by making a small edit to their Shopify customer profile (for example, re-saving their name). This fires a customer update webhook, which triggers both the declension and the Klaviyo sync.
## Using Czech addressing in Klaviyo templates
Once the properties are synced to a Klaviyo profile, you can use them in any Klaviyo email or SMS template with the `person|lookup` filter.
### Display declined first name
```liquid
{% if person|lookup:'Czech addressing' %}
{{ person|lookup:'Czech addressing'|default:'' }}
{% endif %}
```
### Full greeting with fallback
```liquid
{% if person|lookup:'Czech addressing' %}
Vážený zákazníku {{ person|lookup:'Czech addressing' }} {{ person|lookup:'Czech last name' }},
{% else %}
Vážený zákazníku {{ person.first_name }},
{% endif %}
```
### Gender-conditional greeting
```liquid
{% if person|lookup:'Gender' == 'male' %}
Vážený pane {{ person|lookup:'Czech addressing' }},
{% elif person|lookup:'Gender' == 'female' %}
Vážená paní {{ person|lookup:'Czech addressing' }},
{% else %}
Dobrý den, {{ person|lookup:'Czech addressing'|default:person.first_name }},
{% endif %}
```
:::tip
Always include a `| default: person.first_name` fallback for the case where the Czech data has not yet synced to Klaviyo. This prevents empty greetings in your emails.
:::
## Using in Klaviyo flows
The Czech profile properties can be used as **flow filter conditions** as well. For example:
- Trigger a flow only for customers where `Gender` equals `female`
- Personalize product recommendations with a gendered greeting
To access the properties in a flow condition, select **Profile property** → **Czech addressing** (or `Czech last name` / `Gender` for the other properties).
## Troubleshooting Klaviyo sync
### Properties not appearing on Klaviyo profiles
**Cause 1 — Incorrect API keys**: Verify the Private API Key has `profiles:read` and `profiles:write` permissions. Re-enter the keys in the app settings and save.
**Cause 2 — New customer, timing issue**: For customers created very recently, Klaviyo may not have created their profile yet. Wait 5 minutes and then make a small edit to the Shopify customer to trigger a re-sync.
**Cause 3 — Email mismatch**: The sync matches customers by email address. If the email on the Shopify customer record differs from the email on the Klaviyo profile, the profile will not be found and the sync will be skipped.
### Sync skipped for a customer
A sync is skipped when the customer email doesn't exist as a Klaviyo profile yet. This is expected for brand-new customers — re-triggering the webhook after 5 minutes will resolve it. If the issue persists, contact support at [integrace@soundsgood.agency](mailto:integrace@soundsgood.agency).
### Template shows blank instead of the name
Ensure you have the fallback in place:
```liquid
{{ person|lookup:'Czech addressing'|default:person.first_name }}
```
If the property is completely absent on the profile (not just empty), the `|default:` filter will catch it.
---
## Source: src/content/docs/en/czech-names/liquid-usage.mdx
---
title: Liquid Usage
description: Access Czech name data in Shopify Liquid templates for emails, pages, and notifications
---
The declined name values are stored as customer metafields and are available anywhere Shopify exposes the `customer` object in Liquid — including email notification templates, order confirmations, theme pages, and customer account templates.
## Metafield reference
| Metafield | Liquid key | Example value |
|-----------|------------|---------------|
| `czech-names-app.addressing` | `customer.metafields["czech-names-app"]["addressing"]` | `Jane` |
| `czech-names-app.last-name-addressing` | `customer.metafields["czech-names-app"]["last-name-addressing"]` | `Novákové` |
| `czech-names-app.gender` | `customer.metafields["czech-names-app"]["gender"]` | `male`, `female`, `unknown` |
:::note
Because the namespace `czech-names-app` and key `last-name-addressing` contain hyphens, Liquid requires **bracket notation** for access. Dot notation does not work with hyphenated identifiers.
:::
## Basic access with fallback
Always provide a fallback in case the metafield has not been populated yet (for example, for customers who existed before the app was installed):
```liquid
{% if customer.metafields["czech-names-app"]["addressing"] != blank %}
{{ customer.metafields["czech-names-app"]["addressing"] }}
{% else %}
{{ customer.first_name }}
{% endif %}
```
Or using the compact form with the `| default` filter:
```liquid
{{ customer.metafields["czech-names-app"]["addressing"] | default: customer.first_name }}
```
## Full name addressing with fallback
```liquid
{% assign czech_first = customer.metafields["czech-names-app"]["addressing"] %}
{% assign czech_last = customer.metafields["czech-names-app"]["last-name-addressing"] %}
{% if czech_first != blank %}
{{ czech_first }} {{ czech_last }}
{% else %}
{{ customer.first_name }} {{ customer.last_name }}
{% endif %}
```
## Gender-conditional greeting
Use the gender metafield to render different text for male and female customers:
```liquid
{% assign gender = customer.metafields["czech-names-app"]["gender"] %}
{% assign czech_first = customer.metafields["czech-names-app"]["addressing"] | default: customer.first_name %}
{% assign czech_last = customer.metafields["czech-names-app"]["last-name-addressing"] | default: customer.last_name %}
{% if gender == "male" %}
Vážený pane {{ czech_first }} {{ czech_last }},
{% elsif gender == "female" %}
Vážená paní {{ czech_first }} {{ czech_last }},
{% else %}
Vážený zákazníku {{ czech_first }} {{ czech_last }},
{% endif %}
```
## Use in email notification templates
Shopify email notification templates (order confirmation, shipping confirmation, etc.) support Liquid. To add a personalized Czech greeting:
1. Go to **Settings → Notifications** in your Shopify admin
2. Select the notification you want to customize (for example, **Order confirmation**)
3. Click **Edit code**
4. Add the greeting block near the top of the email body:
```liquid
{% assign czech_first = customer.metafields["czech-names-app"]["addressing"] %}
{% assign gender = customer.metafields["czech-names-app"]["gender"] %}
{% if czech_first != blank %}
{% if gender == "male" %}Vážený pane{% elsif gender == "female" %}Vážená paní{% else %}Dobrý den{% endif %} {{ czech_first }},
{% else %}
Dobrý den {{ customer.first_name }},
{% endif %}
```
:::tip
Test notification templates using Shopify's built-in **Send test email** button before activating them for live customers.
:::
## Use in theme templates
In theme `.liquid` files (account pages, custom pages), you can access customer metafields when a customer is logged in:
```liquid
{% if customer %}
{% assign czech_first = customer.metafields["czech-names-app"]["addressing"] | default: customer.first_name %}
Vítejte, {{ czech_first }}!
{% endif %}
```
## Use in order confirmation page
The order confirmation (`checkout.liquid` or `order-status.liquid`) exposes `checkout.customer` or `order.customer`:
```liquid
{% assign czech_first = order.customer.metafields["czech-names-app"]["addressing"] | default: order.customer.first_name %}
Děkujeme, {{ czech_first }}!
```
:::caution
Metafields are not guaranteed to be populated at the exact moment of order placement. If a customer just registered, the app may not have had time to write the metafields yet. Always include a `| default: customer.first_name` fallback.
:::
## Checking all three metafield values
If you need to inspect the raw values for debugging, you can output all three at once:
```liquid
{% comment %}Debug block — remove before publishing{% endcomment %}
addressing: {{ customer.metafields["czech-names-app"]["addressing"] }}
last-name-addressing: {{ customer.metafields["czech-names-app"]["last-name-addressing"] }}
gender: {{ customer.metafields["czech-names-app"]["gender"] }}
```
---
## Source: src/content/docs/en/czech-names/name-templates.mdx
---
title: Name Templates
description: Configure name display templates with gender-conditional formatting
---
The CZ Names template system lets you compose addressing strings that combine the declined first and last name with gender-conditional text. Templates are used by the UI Extensions to render the final greeting wherever you place them.
## Placeholders
| Placeholder | Replaced with |
|-------------|---------------|
| `{{czechFirstName}}` | Declined first name (from `addressing` metafield) |
| `{{czechLastName}}` | Declined last name (from `last-name-addressing` metafield) |
If a name could not be declined (non-translatable), the original name is used as a fallback.
## Gender conditionals
You can render different text depending on the customer's linguistic gender using the conditional block syntax:
```
{male:text}{female:text}{unknown:text}
```
All three segments are optional. The block is replaced with the segment that matches the customer's gender (`male`, `female`, or `unknown`). If a segment is omitted, nothing is displayed for that gender — this is often the desired behavior (for example, omitting `{unknown:}` means unknown-gender names produce no prefix).
:::note
Gender in CZ Names is **linguistic gender** inferred from the Czech name — it is used for grammatical addressing only. It is not a statement about personal identity.
:::
## Default template
When no custom template is configured, the app uses:
```
{{czechFirstName}} {{czechLastName}}
```
This produces the declined full name, for example: `Jane Novákové`.
## Template examples
### Full name only (default)
```
{{czechFirstName}} {{czechLastName}}
```
Output examples:
- `Jane Novákové`
- `Tomáši Čermáku`
---
### Formal Czech greeting (Pane / Paní)
```
{male:Pane }{female:Paní }{unknown:}{{czechFirstName}} {{czechLastName}}
```
Output examples:
- Male: `Pane Tomáši Čermáku`
- Female: `Paní Jane Novákové`
- Unknown: `Janse Smiths`
---
### Formal English title (Mr. / Mrs.)
```
{male:Mr. }{female:Mrs. }{unknown:}{{czechFirstName}} {{czechLastName}}
```
Output examples:
- Male: `Mr. Tomáši Čermáku`
- Female: `Mrs. Jane Novákové`
---
### Informal first name only
```
{male:Ahoj }{female:Ahoj }{unknown:Dobrý den, }{{czechFirstName}}
```
Output examples:
- Male: `Ahoj Tomáši`
- Female: `Ahoj Jano`
- Unknown: `Dobrý den, Janse`
---
### Email subject line with title
```
{male:Vážený pane }{female:Vážená paní }{unknown:Vážený zákazníku}{{czechFirstName}}
```
Output examples:
- Male: `Vážený pane Tomáši`
- Female: `Vážená paní Jano`
- Unknown: `Vážený zákazníku`
---
## Using templates in Liquid
If you prefer to build the greeting directly in a Liquid template rather than using the UI Extensions, access the metafields individually and construct the string yourself. See [Liquid Usage](../liquid-usage) for examples.
## Tips
- Omitting a gender segment means nothing is displayed for that gender — this is intentional for templates where you want silence rather than a fallback (for example, `{unknown:}` produces an empty string for unknown-gender names)
- For the `unknown` case, consider using a neutral form like `Vážený zákazníku` or simply leaving it empty so only the name renders
- Test your template with customers of each gender (male, female, and an untranslatable name like `Alex`) to confirm all three branches render correctly
---
## Source: src/content/docs/en/czech-names/troubleshooting.mdx
---
title: Troubleshooting
description: Technical reference for the CZ Names Czech declension app
---
import FaqSchema from '../../../../components/FaqSchema.astro';
This page is a technical reference covering how the app processes names, what makes a name non-translatable, and the prerequisites for correct operation. We have no support ticket history to identify "common issues" — if you run into something not covered here, contact us directly.
## Name validation rules
The app accepts a name for declension only if it passes a regex check (`/^[\wá-ž]{2,}$/i`). Names that fail this check are marked non-translatable and the original value is kept as the fallback — this is intentional behavior, not a bug.
Names that **pass** (accepted for declension):
- Standard Czech and Latin letters (a–z, á–ž, A–Ž)
- Digits and underscores
Names that **fail** (non-translatable, original value kept):
| Character | Example |
|-----------|---------|
| Hyphen | `Anne-Marie` |
| Space | `van den Berg` |
| Apostrophe | `O'Brien` |
| Non-Latin script | `李偉`, `محمد` |
| Fewer than 2 characters | `A` |
When a name is non-translatable, the `addressing` and `last-name-addressing` metafields receive the original name unchanged, and `gender` is set to `unknown`.
## Metafield keys
The app writes to three metafields in the `czech-names-app` namespace, type `single_line_text_field`:
| Key | Content |
|-----|---------|
| `czech-names-app.addressing` | Declined first name (e.g. "Jano") |
| `czech-names-app.last-name-addressing` | Declined last name (e.g. "Nováková") |
| `czech-names-app.gender` | `male`, `female`, or `unknown` |
To verify values in Shopify admin: open a customer profile, scroll to the **Metafields** section, and look for the `czech-names-app` namespace.
:::caution
When referencing metafields in Liquid, always use bracket notation — the hyphen in the namespace name breaks dot notation:
```liquid
{{ customer.metafields['czech-names-app'].addressing }} {# correct #}
{{ customer.metafields.czech-names-app.addressing }} {# broken — hyphen is parsed as subtraction #}
```
:::
## Billing prerequisite
The app silently skips all webhook processing if billing is not active. If metafields are not appearing at all, check the subscription status first. In Shopify admin: **Settings → Apps and sales channels → CZ Names**. The app dashboard also shows "Billing is not enabled" when the subscription is inactive.
If billing lapsed or was never accepted at install, reactivate the subscription and then re-trigger processing by editing and saving a customer profile.
## Klaviyo sync timing and limitations
The Klaviyo sync runs once per customer event (create or update). It does **not retry automatically**.
Klaviyo requires 3–5 minutes after customer creation before their profile is accessible via the Klaviyo API. If a customer is synced before their Klaviyo profile exists, the sync is permanently skipped for that event. The only way to re-trigger it is a subsequent customer update in Shopify.
The properties written to Klaviyo are:
- `Czech addressing`
- `Czech last name`
- `Gender`
See the [Klaviyo Integration](../klaviyo) page for API key setup and required permissions.
## Gender detection
Gender is detected by the external [sklonovani-jmen.cz](https://sklonovani-jmen.cz) API using Czech linguistic conventions. The app has no internal gender logic — the API result is stored as-is.
- `male` or `female` — the API assigned a grammatical gender with confidence
- `unknown` — the name did not match Czech linguistic patterns (common for foreign names)
This value is **linguistic gender** used for grammatical addressing only (Pane / Paní / neutral). There is no setting to override it.
## UI Extensions render nothing while loading
Extensions show blank while customer data is loading, and also show blank if the `czech-names-app` metafields do not yet exist on the customer. Customers created before the app was installed have no metafields — edit and save their profile to trigger processing.
## Need help?
Contact us at [integrace@soundsgood.agency](mailto:integrace@soundsgood.agency). Include:
- Your store URL
- The customer first name and last name causing the issue
- What you expected and what actually happened
- A screenshot of the Metafields section on the customer profile (if relevant)
---
## Source: src/content/docs/en/general/collaborator-access.mdx
---
title: Collaborator Access
description: How to grant Sounds Good Agency access to your Shopify store for support
sidebar:
order: 1
---
When you contact support for issues that require us to investigate your store configuration, our team will ask you to grant **Shopify Collaborator Access**. This is a secure, revocable access method built into Shopify — it does not require sharing your account password.
## What Access We Need
To diagnose and resolve most issues, we need the following permissions:
| Area | Why We Need It |
|------|---------------|
| **Apps** | View app configuration, extension status, and settings |
| **Themes** | Check that extension blocks are correctly placed in your theme |
| **Orders** | Verify order tags and attributes on affected orders |
We do not need access to your products, customers, financial data, or any other store areas.
:::note
Collaborator access can be revoked at any time from your Shopify admin. We recommend revoking access once your issue is resolved.
:::
## Video Walkthrough
## Step-by-Step Instructions
### Step 1: Go to Users and Permissions
1. Log in to your **Shopify Admin**.
2. Click **Settings** in the bottom-left corner.
3. Click **Users and permissions** in the left sidebar.
### Step 2: Open Collaborators Section
Scroll down to the **Collaborators** section on the Users and permissions page. You will see a list of any existing collaborators and a button to manage collaborator access.
### Step 3: Send the Collaborator Request
You have two options:
**Option A — Share your collaborator request code (recommended):**
1. Click **Edit collaborator request code** or find the **Collaborator request code** section.
2. Enable the collaborator request code if it's not already enabled.
3. Copy the code shown.
4. Send us the code at **integrace@soundsgood.agency** along with your store URL.
We will use this code to send you a collaborator request from our end.
**Option B — Invite us directly:**
1. Click **Add collaborator**.
2. Search for **Sounds Good Agency** — this is our partner name in Shopify.
3. Select the permissions: **Apps**, **Themes**, **Orders**.
4. Click **Send invite**.
:::tip
In Shopify, we appear as **Sounds Good Agency** (sometimes shown as **Sounds good agency s.r.o.**). If you can't find us by name, use our email address: **integrace@soundsgood.agency**.
:::
### Step 4: We Accept and Get to Work
Once we receive the collaborator request or invitation, we will accept it and begin investigating your issue. We will update you by email with findings and next steps.
### Step 5: Revoke Access When Done
After your issue is resolved:
1. Go back to **Settings → Users and permissions → Collaborators**.
2. Find **Sounds Good Agency** in the list.
3. Click **Remove collaborator**.
This immediately revokes our access to your store.
## Security and Privacy
Shopify collaborator access is:
- **Scoped** — we can only access the areas you specifically grant.
- **Logged** — all actions taken by collaborators are recorded in your Shopify activity log.
- **Revocable** — you can remove access instantly at any time.
- **No password sharing** — we never ask for your Shopify login credentials.
If you have a security policy that prohibits external collaborator access, please reach out at **integrace@soundsgood.agency** and we will work with you to find an alternative way to diagnose the issue (such as screen-sharing or providing detailed screenshots and logs).
## Contact Us
**Email**: integrace@soundsgood.agency
Please include your store URL and a brief description of the issue when you reach out. This helps us prepare before gaining access and resolve your issue faster.
---
## Source: src/content/docs/en/index.mdx
---
title: Sounds Good Docs
description: Documentation for Shopify apps by Sounds Good Agency
template: splash
hero:
tagline: Help center and documentation for our Shopify apps. Find setup guides, troubleshooting tips, and best practices.
actions:
- text: Pickup Points CZ/SK/HU
link: /en/zasilkovna/
icon: right-arrow
variant: primary
- text: CZ Names
link: /en/czech-names/
icon: right-arrow
variant: secondary
---
import { Card, CardGrid } from '@astrojs/starlight/components';
## Our Apps
Pickup point selection for Shopify checkout. Supports Zásilkovna, GLS, DPD, PPL, and Balíkovna carriers with CSV export.
[View documentation →](/en/zasilkovna/)
Czech name declension for personalized customer communication. Automatic vocative form conversion with Klaviyo integration.
[View documentation →](/en/czech-names/)
## Need Help?
Can't find what you're looking for? Email us at **integrace@soundsgood.agency** — we typically respond within one business day.
---
*[Sounds Good Agency](https://www.soundsgood.agency) — Shopify Experts*
---
## Source: src/content/docs/en/zasilkovna/billing.mdx
---
title: Billing & Plans
description: Zásilkovna app pricing plans, free trial, and subscription management
---
The Pickup Points CZ/SK/HU app is available in two plans. Both include a 14-day free trial so you can test the app fully before being charged.
## Plans Comparison
| Feature | Basic | Premium |
|---------|-------|---------|
| **Price** | $5 / month | $9.99 / month |
| **Free trial** | 14 days | 14 days |
| **Carriers** | 1 carrier at a time | Multiple carriers simultaneously |
| **All 5 carriers available** | Yes | Yes |
| **CSV export** | Yes | Yes |
| **Email reminders** | Yes | Yes |
| **Custom translations** | Yes | Yes |
| **Unlimited orders** | Yes | Yes |
| **Pickup point widgets** | Yes | Yes |
| **Email support** | Yes | Yes |
| **Priority support** | — | Yes |
## Choosing the Right Plan
**Choose Basic if:**
- You only offer pickup point delivery via one carrier (e.g., Zásilkovna/Packeta only).
- You don't need the pickup point widget for GLS, DPD, PPL, or Balíkovna simultaneously.
- You want the lowest possible cost.
**Choose Premium if:**
- You offer pickup point delivery via multiple carriers at the same time (e.g., both Zásilkovna and GLS).
- You want priority support with faster response times.
- You need to configure multiple carrier keywords simultaneously.
:::note
Both plans let you use any of the 5 supported carriers. The difference is how many can be active at the same time in **Interface Settings**. On Basic, you configure one carrier's widget at a time — you can still use multiple carriers for shipping, but only one will show the pickup point widget.
:::
## Free Trial
Both plans include a **14-day free trial**. During the trial:
- The app is fully functional with no limitations.
- You will not be charged until the trial ends.
- You can cancel at any time during the trial without being charged.
The trial starts on the day you install the app and select a plan. After 14 days, your Shopify account will be billed automatically at the plan rate.
## How Billing Works
The app uses **Shopify's standard recurring billing**. This means:
- Charges appear on your Shopify invoice, not as a separate payment.
- The billing cycle aligns with your existing Shopify billing date.
- If you install the app mid-cycle, the first charge is prorated.
You can see the current subscription status and upcoming charges in **Shopify Admin → Apps → Zásilkovna**.
## Upgrading or Downgrading
### Upgrading from Basic to Premium
1. Open the app in your Shopify admin.
2. Go to the **Billing** section.
3. Click **Select plan** next to the Premium plan.
4. Confirm the plan change in Shopify's billing confirmation screen.
### Downgrading from Premium to Basic
1. Open the app in your Shopify admin.
2. Go to the **Billing** section.
3. Click **Select plan** next to the Basic plan.
4. Confirm the plan change.
:::caution
When downgrading to Basic, the GLS, DPD, PPL, and Balíkovna carrier configurations will be disabled. Customers who select those carriers' shipping methods will see the default Zásilkovna widget instead. Make sure to update your shipping methods or inform customers before downgrading.
:::
## Cancelling the Subscription
To cancel, uninstall the app from your Shopify admin:
1. Go to **Shopify Admin → Settings → Apps and sales channels**.
2. Find **Pickup Points CZ/SK/HU** in the list.
3. Click **Delete** or **Uninstall**.
4. Confirm the uninstallation.
Shopify will cancel the recurring charge automatically. You will not be charged for the next billing cycle. Any remaining days in the current paid period are not refunded (this is standard Shopify app billing).
:::note
Uninstalling the app removes the widget from your checkout. Customers who choose a Zásilkovna/Packeta shipping method will no longer see the pickup point selector. Make sure to inform your shipping carrier or update your shipping methods if you're fully discontinuing pickup point delivery.
:::
## Billing Questions
If you have questions about a charge on your Shopify invoice, or if you believe you were billed incorrectly, contact us at **integrace@soundsgood.agency** with your Shopify store URL and the billing date in question.
For disputes related to Shopify's billing system itself, contact [Shopify Support](https://help.shopify.com/en/support).
---
## Source: src/content/docs/en/zasilkovna/carriers.mdx
---
title: Supported Carriers
description: All carriers supported by the Zásilkovna app and their configuration keywords
---
The Pickup Points CZ/SK/HU app supports five carriers for pickup point delivery. All carriers are available on both plans — the difference is how many you can have active at once.
## Carrier Overview
| Carrier | Default Keyword |
|---------|-----------------|
| Zásilkovna / Packeta | `zasilkovna` or `packeta` |
| GLS | `gls` |
| DPD | `dpd` |
| PPL | `ppl` |
| Balíkovna | `balikovna` |
For current country coverage, check each carrier's website directly.
:::note
**Basic plan**: 1 carrier configured at a time. **Premium plan**: multiple carriers configured simultaneously. All 5 carriers are available on both plans. See [Billing & Plans](../billing/) for details.
:::
## Zásilkovna / Packeta
Zásilkovna (known internationally as Packeta) is the primary carrier this app was built for. It has the largest pickup point network in Central and Eastern Europe, with thousands of Z-Points and Z-BOX automated lockers.
**Recommended keywords**: `zasilkovna`, `packeta`
You can configure both keywords using a comma-separated value:
```
zasilkovna,packeta
```
This is useful if you have separate shipping methods for Czech and Slovak customers (one named with "Zásilkovna", one with "Packeta").
**Widget**: When triggered, the widget connects to Zásilkovna's pickup point API and shows an interactive map and list of nearby locations.
## GLS
GLS ParcelShops are available across most of Europe. Use the GLS carrier setting if you offer GLS pickup point delivery in your store.
**Recommended keyword**: `gls`
Example shipping method names that match:
- "GLS ParcelShop"
- "GLS - výdejní místo"
- "Delivery to GLS point"
## DPD
DPD Pickup points (formerly DPD Parcelshops) are widely available in the Czech Republic and Slovakia.
**Recommended keyword**: `dpd`
Example shipping method names that match:
- "DPD Pickup"
- "DPD ParcelShop"
- "DPD - výdejní místo"
## PPL
PPL (Professional Parcel Logistic) operates a pickup point network primarily in the Czech Republic and Slovakia.
**Recommended keyword**: `ppl`
Example shipping method names that match:
- "PPL ParcelShop"
- "PPL - výdejní místo"
- "PPL Pickup"
## Balíkovna
Balíkovna is the Czech Post's pickup point service, available throughout the Czech Republic at post offices and partner locations.
**Recommended keyword**: `balikovna`
Example shipping method names that match:
- "Balíkovna - výdejní místo"
- "Balíkovna pickup"
- "Czech Post Balíkovna"
## Home Delivery vs Pickup Points
This app handles **pickup point selection only**. Home delivery shipping methods (e.g., PPL home courier, DPD home courier) are standard Shopify shipping rates and do not interact with this app — customers choosing home delivery will not see the widget.
Only assign a keyword to shipping methods where customers need to choose a specific pickup location. If a shipping method name contains a keyword but it's a home delivery method, the widget will incorrectly appear for those customers. To prevent this, use distinct shipping method names that don't contain your pickup point keywords.
:::tip
If a customer doesn't need to choose a specific location, don't give that shipping method a keyword.
:::
---
## Country and Region Filtering
The pickup point widget displays locations based on the carrier's own network configuration.
**Zásilkovna/Packeta**: Country filtering is supported via Zásilkovna's API. You can configure which countries are shown in your [Packeta client portal](https://client.packeta.com). The app passes these settings through to the Zásilkovna widget automatically.
**GLS, DPD, PPL, Balíkovna**: Country filtering is not configurable through this app for these carriers. The widget displays all pickup points available in the carrier's network for the shipping address country. For country-specific restrictions, contact the carrier directly.
If you need help configuring country restrictions for Zásilkovna, contact us at [integrace@soundsgood.agency](mailto:integrace@soundsgood.agency).
---
## Default Fallback Behavior
If a customer selects a shipping method that **does not match any configured keyword**, the app falls back to showing the **Zásilkovna/Packeta** widget by default.
This means:
- If you have GLS configured but a customer selects a method that doesn't match `gls`, they will see the Zásilkovna widget.
- If no keywords are configured at all, all customers will see the Zásilkovna widget regardless of their shipping choice.
:::tip
To avoid showing the wrong carrier's widget to customers, make sure every pickup point shipping method in your store has a matching keyword configured. See [Keyword Configuration](../keyword-config/) for guidance.
:::
## How to Check Which Carrier Was Detected
After a customer completes checkout, you can see which carrier was used by checking the order in Shopify admin:
1. Go to **Shopify Admin → Orders**.
2. Open the relevant order.
3. Check the **Tags** section — it will show one of the status tags (e.g., `zasilkovna_selected`).
4. Check the **Additional details / Notes** section — it will contain `CarrierPickupPointId` and `PickupPointName`, showing the actual pickup point the customer selected.
See [Order Tags](../order-tags/) for a full explanation of all tags and attributes.
## Configuring Multiple Carriers (Premium)
On the Premium plan, each carrier has its own keyword field in **Interface Settings**. Configure each one independently:
1. Open the app and go to **Interface Settings**.
2. For each carrier you use, enter the keyword that matches your shipping method name.
3. Save settings.
A customer's selected shipping method will be matched against each keyword in turn. The first match determines which carrier's pickup point widget is shown.
:::caution
If two carrier keywords accidentally match the same shipping method name (for example, if a method name contains both "gls" and "dpd"), the app will use the first matching carrier. Avoid overlapping keywords by making each carrier's shipping method names distinct.
:::
---
## Source: src/content/docs/en/zasilkovna/csv-export.mdx
---
title: CSV Export
description: Step-by-step guide to exporting orders to Zásilkovna CSV format
---
The app includes a built-in CSV export that formats your Shopify orders into the format required by Zásilkovna's legacy system at **packeta.podnikat.online**. This lets you batch-upload orders for label printing without manual data entry.
## Before You Export
Make sure:
- Orders you want to export are tagged `zasilkovna_selected` (pickup point has been selected by the customer).
- You are logged into [packeta.podnikat.online](https://packeta.podnikat.online) to receive the exported file.
:::tip
Create a saved order filter for `tag:zasilkovna_selected` to quickly find all export-ready orders. See [Order Tags](../order-tags/) for instructions.
:::
## Video Walkthrough
## Step-by-Step Export
### Step 1: Select Orders
1. Go to **Shopify Admin → Orders**.
2. Apply your saved filter for `tag:zasilkovna_selected`, or manually search for the orders you want to export.
3. Select the orders using the checkboxes on the left side of the order list.
- To select all visible orders: check the checkbox in the header row.
- To select a range: check the first order, then Shift+click the last.
:::caution
Export in batches of a manageable size. If you have hundreds of orders, exporting them all at once can result in a large file that is slow to process. We recommend batches of 50–100 orders at a time.
:::
### Step 2: Open the Export Action
1. With orders selected, click the **three dots menu (⋯)** that appears in the action bar above the order list.
2. Look for **Export to Zásilkovna** in the dropdown menu.
:::note
If you don't see "Export to Zásilkovna" in the menu, make sure the app extension is installed. Go to the app settings and verify the **export-to-zasilkovna-order-selection** extension is active.
:::
### Step 3: Configure the Export
A configuration panel will open. Review and adjust the export settings as needed for this batch of orders.
### Step 4: Export and Download
1. Click **Export**.
2. The app generates a CSV file in Zásilkovna's required format.
3. The download starts automatically. Save the file to your computer.
### Step 5: Upload to packeta.podnikat.online
1. Log in to [packeta.podnikat.online](https://packeta.podnikat.online).
2. Navigate to the import/upload section.
3. Upload the downloaded CSV file.
4. Review the order list and confirm.
5. Print shipping labels.
## Exporting a Single Order
For a single order, you can export directly from the order detail page:
1. Go to **Shopify Admin → Orders** and open the order.
2. In the order detail page, look for the **Export to Zásilkovna** action link in the top-right area.
3. This uses the `export-to-zasilkovna-order-details` extension and exports just that one order.
## What's Included in the CSV
The exported CSV contains order details in Zásilkovna's required format, including the pickup point ID and name collected from the customer during checkout.
## Troubleshooting Export Issues
### "Export to Zásilkovna" not showing in the menu
The app extension may not be active. Try:
1. Go to the app in your Shopify admin.
2. Check that extensions are enabled.
3. If the issue persists, uninstall and reinstall the app.
### Export fails or shows an error
Try exporting a smaller batch (10–20 orders). If a specific order is causing the error, open that order and check that:
- It has the `zasilkovna_selected` tag.
- The `CarrierPickupPointId` attribute is present and non-empty.
### CSV uploads to packeta.podnikat.online but some orders are rejected
This usually means the pickup point ID is no longer valid (the location may have closed). Contact the customer to reselect a pickup point, or manually assign a new one.
### Downloaded CSV file is empty
Make sure you actually had orders selected before clicking the export option. If no orders were selected, the export may produce an empty file.
---
## Source: src/content/docs/en/zasilkovna/getting-started.mdx
---
title: Getting Started
description: Install and configure the Zásilkovna pickup point app for your Shopify store
---
This guide walks you through installing the Pickup Points CZ/SK/HU app and getting the pickup point widget working in your store. The full setup takes about 10 minutes.
:::note
The app was formerly known as **Zásilkovna | Packeta**.
:::
## Step 1: Install from the Shopify App Store
1. Open the [Pickup Points CZ/SK/HU](https://apps.shopify.com/pickup-points-cz-sk-hu) app listing on the Shopify App Store.
2. Click **Add app**.
3. You will be redirected to your Shopify admin to review the required permissions.
## Step 2: Accept Permissions
The app requires the following access to work correctly:
| Permission | Why It's Needed |
|-----------|----------------|
| Read/write content | Metaobject management (translations) |
| Read/write metaobjects | Store translation and configuration data |
| Read customers | Associate pickup points with customer orders |
| Read/write orders | Tag orders with pickup point status |
| Read fulfillments | Track order shipment status |
| Read shipping | Detect which shipping method was selected |
| Read locales | Apply the correct language to the widget |
Click **Install app** to accept and continue.
## Step 3: Choose Your Billing Plan
After installation, you will be prompted to select a plan. Both plans include a **14-day free trial** — you won't be charged until the trial ends.
| | Basic | Premium |
|-|-------|---------|
| Price | $5/month | $9.99/month |
| Carriers | 1 at a time | Multiple simultaneously |
| CSV export | Yes | Yes |
| Email reminders | Yes | Yes |
| Custom translations | Yes | Yes |
| Priority support | — | Yes |
:::tip
If you only need one carrier at a time, the **Basic plan** covers everything you need. Upgrade to Premium if you want to configure multiple carriers simultaneously.
:::
Select your plan and confirm through Shopify's billing flow. Your trial begins immediately.
## Step 4: Configure Your Shipping Keyword
This is the most important setup step. The app detects which carrier the customer selected by checking whether the shipping method name contains your configured keyword.
1. In the app, go to **Interface Settings**.
2. Find the **Keyword** field.
3. Enter the keyword that matches your Zásilkovna/Packeta shipping method name. For example, if your shipping method is called "Zásilkovna - Pickup Point", enter `zasilkovna`.
:::caution
The keyword must appear somewhere in your shipping method name. It is matched case-insensitively, so `zasilkovna`, `Zasilkovna`, and `ZASILKOVNA` all work — but the word must be present in the name.
:::
:::note
If you use Zásilkovna/Packeta as your carrier, you will also need to enter your **Packeta API key** and **API password** in the app's **Interface Settings**. You can find these credentials in your Packeta client portal at [client.packeta.com](https://client.packeta.com).
:::
See the [Keyword Configuration guide](../keyword-config/) for a full explanation and common mistakes.
## Step 5: Add the Widget to Your Store
The app uses Shopify checkout extensions to display the widget. Where you can add the widget depends on your Shopify plan.
### All plans: Thank You page and Order Status page
All merchants can add the widget to the Thank You page (shown immediately after order placement) and the Order Status page (visible in customer accounts). These are the primary locations where customers select their pickup point.
**Thank You page:**
1. In Shopify admin, go to **Settings → Checkout**.
2. Click **Customize** to open the checkout editor.
3. Navigate to the **Thank You** page.
4. Click **Add block** and look for the **Zásilkovna / Packeta Pickup Point** block.
5. Add the block and save.
**Order Status page:**
1. In Shopify admin, go to **Settings → Customer accounts**.
2. Click **Customize**.
3. Navigate to the **Order Status** page.
4. Add the **Zásilkovna / Packeta Pickup Point** block and save.
### Shopify Plus only: Checkout page
Shopify Plus stores can also show the widget directly in the checkout flow (before the order is placed). This requires a Shopify Plus subscription and is configured in the checkout editor under **Settings → Checkout → Customize → Checkout page**.
:::note
Showing the widget at checkout is available on Shopify Plus only. On all other plans, the widget appears on the Thank You page and Order Status page after the order is placed.
:::
## Step 6: Test the Widget
Place a test order using a shipping method that includes your configured keyword:
1. Add a product to your cart and proceed to checkout.
2. Select the shipping method that contains your keyword.
3. Complete checkout and land on the Thank You page.
4. Confirm the pickup point widget appears and allows you to select a location.
After selecting a pickup point, go to the order in your Shopify admin and verify:
- The order is tagged with `zasilkovna_selected`.
- The order's additional details contain `CarrierPickupPointId` and `PickupPointName`.
If the widget does not appear, check the [Troubleshooting guide](../troubleshooting/) for common fixes.
## You're All Set
Your store is now configured to collect pickup point selections from customers. Here are some useful next steps:
- [Configure keywords for multiple carriers](../keyword-config/) (Premium plan)
- [Customize widget text and translations](../translations/)
- [Set up CSV export for batch label printing](../csv-export/)
- [Enable email reminders for unselected pickup points](../billing/)
---
## Still Need Help?
If you run into any issues during setup, our support team is here to help.
Email: **integrace@soundsgood.agency**
Please include your Shopify store URL and a description of what you're seeing. We typically respond within one business day.
---
## Source: src/content/docs/en/zasilkovna/index.mdx
---
title: Pickup Points CZ/SK/HU
description: Pickup point selection app for Shopify — overview, features, and supported carriers
---
import { Card, CardGrid } from '@astrojs/starlight/components';
The **Pickup Points CZ/SK/HU** app adds a pickup point selector widget to your Shopify store. When a customer places an order using a shipping method that matches your configured keyword, they are shown a widget to select their preferred pickup point.
:::note
The app was formerly known as **Zásilkovna | Packeta**.
:::
The app supports five major Central and Eastern European carriers and works on both the Thank You page and the customer account order status page. Shopify Plus stores can also enable the widget directly in the checkout flow.
## Key Features
Interactive widget displayed after carrier selection, letting customers choose their preferred pickup point.
Supports Zásilkovna/Packeta, GLS, DPD, PPL, and Balíkovna. All carriers available on both plans.
Automatically tags orders with pickup status so you can filter, search, and manage them in Shopify admin.
Export orders directly to Zásilkovna's legacy CSV format for batch label printing.
Override all widget text for any language, with full Shopify locale fallback support.
Send automated reminders to customers who haven't selected a pickup point yet.
## Supported Carriers
| Carrier | Default Keyword |
|---------|-----------------|
| Zásilkovna / Packeta | `zasilkovna` or `packeta` |
| GLS | `gls` |
| DPD | `dpd` |
| PPL | `ppl` |
| Balíkovna | `balikovna` |
:::note
If no keyword matches the customer's chosen shipping method, the widget defaults to **Zásilkovna** as a fallback carrier.
:::
## Where the Widget Appears
The pickup point widget is displayed in two places in your Shopify store:
- **Thank You page** — shown immediately after order placement, so customers can select their pickup point right away.
- **Customer Account — Order Status page** — allows customers to select or change their pickup point later from their account.
## App Navigation
Once installed, the app contains these sections in your Shopify admin:
| Section | What You Can Do |
|---------|----------------|
| **Home** | Redirects to the Help / How to use section |
| **How to use** | In-app setup guide |
| **Interface Settings** | Configure shipping keywords, widget behavior |
| **Export Settings** | Set up CSV export parameters |
| **Email Reminders** | Configure automated reminders for unselected pickup points |
| **Billing** | Manage your subscription plan |
| **Translations** | Customize all widget text for any language |
## Install the App
Install the app directly from the Shopify App Store: [**Pickup Points CZ/SK/HU**](https://apps.shopify.com/pickup-points-cz-sk-hu).
After installation, follow the [Getting Started guide](./getting-started/) to complete the initial setup.
## Plans at a Glance
| | Basic | Premium |
|-|-------|---------|
| Price | $5/month | $9.99/month |
| Free trial | 14 days | 14 days |
| Carriers | 1 at a time | Multiple simultaneously |
| CSV export | Yes | Yes |
| Email reminders | Yes | Yes |
| Custom translations | Yes | Yes |
| Priority support | — | Yes |
See [Billing & Plans](./billing/) for full details.
---
## Source: src/content/docs/en/zasilkovna/keyword-config.mdx
---
title: Keyword Configuration
description: How to configure shipping method keywords for the pickup point widget
---
Keyword configuration is the most common source of support questions. If the pickup point widget is not appearing for your customers, the keyword setting is almost always the cause. This guide explains exactly how keyword matching works and how to configure it correctly.
## How Keyword Matching Works
When a customer reaches checkout and selects a shipping method, the app checks whether the **name of that shipping method** contains your configured keyword.
The matching logic is:
```
shippingTitle.toLowerCase().includes(keyword)
```
In plain English:
- The shipping method name is converted to lowercase.
- The app checks whether your keyword appears **anywhere** in that name.
- The match is **case-insensitive** — `zasilkovna`, `Zasilkovna`, and `ZASILKOVNA` all work.
If a match is found, the widget for that carrier is shown. If no keyword matches, the widget defaults to Zásilkovna.
## Rules for Keywords
- **Substring matching** — the keyword must appear somewhere in the shipping method name. Multi-word keywords work as long as the shipping title contains that exact substring (e.g., `pickup point` will match "Zásilkovna pickup point").
- **Comma-separated for multiple** — the app may support comma-separated keywords for matching multiple terms (e.g., `zasilkovna,packeta`). Check the Interface Settings page for the exact input format supported by your version.
- **One keyword field per carrier** — each carrier has its own keyword field. On the Premium plan, you can configure a separate keyword for each carrier.
- **Keywords must match the shipping method name** — the keyword you enter must appear in the exact shipping method name you have configured in Shopify.
## Step-by-Step Configuration
### 1. Find your shipping method name
Go to **Shopify Admin → Settings → Shipping and delivery**. Look at the names of your shipping rates. Make a note of the exact name of the shipping method you use for Zásilkovna or Packeta pickup points.
For example:
- "Zásilkovna - pickup"
- "Packeta - výdejní místo"
- "Zásilkovna Z-BOX"
### 2. Choose a keyword
Pick a word that appears in that shipping method name. It should be unique enough that it won't accidentally match other shipping methods.
| Shipping Method Name | Good Keyword | Why |
|---------------------|--------------|-----|
| "Zásilkovna pickup" | `zasilkovna` | Unique to Zásilkovna methods |
| "Packeta - výdejní místo" | `packeta` | Unique to Packeta methods |
| "GLS ParcelShop" | `gls` | Unique to GLS methods |
| "DPD Pickup" | `dpd` | Unique to DPD methods |
### 3. Enter the keyword in the app
1. Open the app in your Shopify admin.
2. Go to **Interface Settings**.
3. Find the **Keyword** field for the relevant carrier.
4. Enter your keyword (lowercase recommended, though it doesn't matter technically).
5. Save the settings.
### 4. Test the match
Place a test order and select the shipping method. The pickup point widget should appear on the Thank You page.
## Multiple Keywords for One Carrier
If you have multiple shipping methods for the same carrier (for example, "Zásilkovna - standard" and "Zásilkovna - Z-BOX"), you can match both with a single keyword by using the common word: `zasilkovna`.
If the shipping methods use different words, you can enter multiple keywords separated by commas:
```
zasilkovna,packeta
```
:::tip
The comma-separated list works for a single carrier field. Both keywords will trigger the same carrier's pickup point widget.
:::
## Common Mistakes
### Mistake 1: Keyword doesn't match the shipping method name
The most common error. The keyword you entered does not appear in the exact name of your Shopify shipping method.
**Fix**: Go to Shopify → Settings → Shipping and delivery, copy the exact name of your shipping method, and make sure your keyword is a substring of that name.
### Mistake 2: Extra spaces in the keyword field
Accidentally entering `zasilkovna ` (with a trailing space) instead of `zasilkovna` will cause the match to fail.
**Fix**: Remove any leading or trailing spaces from the keyword field.
### Mistake 3: Keyword phrase doesn't match the shipping title
If you enter a keyword phrase (e.g., "Zásilkovna pickup"), it will only match if the shipping method name contains that exact substring in sequence. For example, "Zásilkovna pickup point" would match, but "Zásilkovna - pickup" would not.
**Fix**: Use the shortest distinctive term that uniquely identifies the carrier, like `zasilkovna` or `packeta`.
### Mistake 4: Wrong carrier keyword field
On the Premium plan, each carrier has its own keyword field in the Interface Settings. Make sure you're entering the keyword in the correct carrier's field.
### Mistake 5: Shipping method name changed after configuration
If you rename a shipping method in Shopify after setting up the keyword, the keyword may no longer match.
**Fix**: After renaming shipping methods, always verify that your keywords still match the new names.
:::caution
If no keyword matches the customer's selected shipping method, the widget will default to Zásilkovna. This means customers might see a Zásilkovna pickup point selector even when they chose a DPD or GLS method — if the DPD/PPL keyword isn't configured correctly.
:::
## Keyword Examples by Carrier
| Carrier | Example Shipping Method Names | Recommended Keyword |
|---------|------------------------------|---------------------|
| Zásilkovna | "Zásilkovna - výdejní místo", "Zásilkovna Z-BOX" | `zasilkovna` |
| Packeta | "Packeta pickup", "Packeta - výdejní místo" | `packeta` |
| GLS | "GLS ParcelShop", "GLS - výdejní bod" | `gls` |
| DPD | "DPD Pickup", "DPD ParcelShop" | `dpd` |
| PPL | "PPL ParcelShop", "PPL - výdejní místo" | `ppl` |
| Balíkovna | "Balíkovna - výdejní místo" | `balikovna` |
## Verifying Your Configuration
After saving your keyword:
1. Go to your store's checkout in a test session.
2. Select the shipping method that should trigger the widget.
3. Complete checkout and check the Thank You page — the widget should appear.
4. Check the order in Shopify admin — it should be tagged `zasilkovna_unselected` if the widget appeared but no point was selected.
If the widget still doesn't appear, see the [Troubleshooting guide](../troubleshooting/).
---
## Source: src/content/docs/en/zasilkovna/order-tags.mdx
---
title: Order Tags
description: How the Zásilkovna app tags orders and how to use them for workflow automation
---
The app automatically applies tags to orders based on their pickup point status. These tags let you filter, search, and bulk-manage orders directly in Shopify admin — or build automations using Shopify Flow.
## Tags Reference
| Tag | When Applied | What It Means |
|-----|-------------|---------------|
| `zasilkovna_unselected` | Widget shown but no pickup point chosen | Customer needs to select a pickup point |
| `zasilkovna_selected` | Customer selected a pickup point | Ready to process; pickup point data is in the order |
| `zasilkovna_cancelled` | Order or shipping was cancelled | No fulfillment action needed |
| `zasilkovna_fulfilled` | Order has been fulfilled / shipped | Parcel is on its way |
## Order Custom Attributes
In addition to tags, the app stores pickup point details as custom order attributes (also called "additional details" or "notes attributes" in Shopify). Three attributes are written to each order:
### 1. Carrier-specific pickup point ID
The attribute name depends on which carrier the customer selected:
| Carrier | Attribute Name | Value |
|---------|---------------|-------|
| Zásilkovna / Packeta | `PickupPointId` | Pickup point identifier |
| Balíkovna | `Balikovna id` | Pickup point identifier |
| GLS | `GLS id` | Pickup point identifier |
| PPL | `PPL id` | Pickup point identifier |
| DPD | `DPD id` | Pickup point identifier |
### 2. Universal carrier pickup point ID
| Attribute | Value |
|-----------|-------|
| `CarrierPickupPointId` | The pickup point identifier — always written regardless of which carrier was used |
### 3. Pickup point name
| Attribute | Value |
|-----------|-------|
| `PickupPointName` | The human-readable name of the pickup point (e.g., "Tesco Letňany, Praha 9") |
These attributes appear in the **Additional details** section of an order in Shopify admin. They are also included when you export orders via the API or to CSV.
## Tag Lifecycle
A typical order flows through these tags in this order:
```
(order placed, widget shown)
↓
zasilkovna_unselected
↓
(customer selects pickup point)
↓
zasilkovna_selected
↓
(order shipped)
↓
zasilkovna_fulfilled
```
If the order is cancelled at any point:
```
zasilkovna_unselected or zasilkovna_selected
↓
(order/shipping cancelled)
↓
zasilkovna_cancelled
```
## Creating Saved Searches Using Tags
You can create saved order filters in Shopify admin to quickly find orders in each status:
1. Go to **Shopify Admin → Orders**.
2. In the search bar, type the tag you want to filter by. For example: `tag:zasilkovna_unselected`.
3. Click **Save filter** and give it a name (e.g., "Zásilkovna - Needs Pickup Point").
Repeat for each tag you want to monitor regularly. These saved filters will appear in your order views sidebar for quick access.
### Recommended Saved Filters
| Filter Name | Search Query | Use Case |
|------------|-------------|---------|
| Zásilkovna - Needs Selection | `tag:zasilkovna_unselected` | Daily review — contact these customers or wait for email reminder |
| Zásilkovna - Ready to Export | `tag:zasilkovna_selected` | Export these to Zásilkovna CSV for label printing |
| Zásilkovna - Fulfilled | `tag:zasilkovna_fulfilled` | Confirm shipments went out correctly |
| Zásilkovna - Cancelled | `tag:zasilkovna_cancelled` | Audit cancelled pickup deliveries |
## Bulk Actions Workflow
The tags make it easy to process orders in batches:
### Export selected orders to CSV
1. Open the saved filter **"Zásilkovna - Ready to Export"** to see all orders tagged `zasilkovna_selected`.
2. Select the orders you want to export (checkbox next to each order, or "Select all").
3. Click the **three dots menu (⋯)** at the top of the order list.
4. Click **Export to Zásilkovna**.
5. Configure the export settings and download the CSV.
See [CSV Export](../csv-export/) for the full step-by-step walkthrough.
### Contact customers with unselected pickup points
1. Open the **"Zásilkovna - Needs Selection"** filter.
2. Review orders where the customer hasn't selected a pickup point.
3. Use the email reminder feature or contact customers directly.
:::tip
The app's built-in email reminder feature can automatically contact customers who have the `zasilkovna_unselected` tag. Configure this in **Email Reminders** within the app.
:::
## Using Tags with Shopify Flow
If you have Shopify Flow available (Shopify and Advanced Shopify plans), you can build automations triggered by these tags.
Example automations:
- **Send a Slack notification** when an order is tagged `zasilkovna_unselected` and hasn't been updated in 24 hours.
- **Create a to-do task** for your fulfillment team when an order receives `zasilkovna_selected`.
- **Send a shipping confirmation** email when an order is tagged `zasilkovna_fulfilled`.
To trigger a Flow on a tag:
1. In Shopify Flow, create a new workflow.
2. Set the trigger to **Order tagged**.
3. Set the condition to check for your specific tag (e.g., `zasilkovna_selected`).
4. Add your desired action.
---
## Source: src/content/docs/en/zasilkovna/translations.mdx
---
title: Translations
description: Customize the pickup point widget text and language using the translation system
---
The app ships with default English text for all widget labels and messages. You can override any or all of these with your own translations for Czech, Slovak, German, or any other language your store uses.
## How the Translation System Works
Translations are stored as a **Shopify metaobject** of type `zasilkovna_translations`. When the widget renders, it applies this fallback chain to determine which text to display:
1. **Locale-specific metaobject translations** — if a locale-specific version of the translation metaobject exists (added via Shopify's Translate & Adapt app), those values are used first.
2. **Base metaobject values** — if no locale-specific translation exists, the base values you configured in the app's Translations section are used.
3. **Built-in English defaults** — if no custom translation metaobject exists at all, the built-in English defaults are used.
The fallback chain applies at the metaobject level, not per field. If the translation metaobject exists, all 6 fields must be filled in.
## Translation Fields
There are 6 text fields you can customize:
| Field Key | Default English Text | Where It Appears |
|-----------|---------------------|-----------------|
| `title` | "Packeta / Zasilkovna pickup point" | Widget heading on the Thank You page |
| `confirmationTitle` | "Packeta / Zasilkovna pickup point" | Heading shown after a pickup point is selected |
| `textChoosePickupPoint` | "Please select the pickup point where your order will be delivered." | Instructional text shown before a point is selected |
| `textChoosenPickupPoint` | "Selected pickup point" | Label shown next to the name of the selected point |
| `btnChoosePickupPoint` | "Select Pickup point" | Button text before a point is selected |
| `btnChoosenPickupPoint` | "Change pickup point" | Button text after a point is selected (allows changing) |
## The `{{carrierName}}` Placeholder
Any of the text fields above can include the `{{carrierName}}` placeholder. At render time, this is replaced with the actual carrier name (e.g., "Zásilkovna", "GLS", "DPD").
This is useful when you want generic text that works for all carriers:
```
Select your {{carrierName}} pickup point
```
Renders as:
```
Select your GLS pickup point
```
or:
```
Select your Zásilkovna pickup point
```
## How to Configure Translations
1. Open the app in your Shopify admin.
2. Go to the **Translations** section.
3. You will see a form with all 6 translation fields, pre-filled with the current values (or English defaults if not yet configured).
4. Fill in all 6 fields with your desired text. All fields are required — the UI enforces this with validation.
5. Click **Save**.
Changes take effect immediately for new customer sessions.
## Czech Translation Example
Here is a sample Czech translation for all 6 fields:
| Field | Czech Translation |
|-------|-----------------|
| `title` | `Výdejní místo {{carrierName}}` |
| `confirmationTitle` | `Výdejní místo {{carrierName}}` |
| `textChoosePickupPoint` | "Vyberte prosím výdejní místo, kam má být vaše objednávka doručena." |
| `textChoosenPickupPoint` | "Vybrané výdejní místo" |
| `btnChoosePickupPoint` | "Vybrat výdejní místo" |
| `btnChoosenPickupPoint` | "Změnit výdejní místo" |
## Slovak Translation Example
| Field | Slovak Translation |
|-------|------------------|
| `title` | `Výdajné miesto {{carrierName}}` |
| `confirmationTitle` | `Výdajné miesto {{carrierName}}` |
| `textChoosePickupPoint` | "Vyberte prosím výdajné miesto, kam má byť vaša objednávka doručená." |
| `textChoosenPickupPoint` | "Vybrané výdajné miesto" |
| `btnChoosePickupPoint` | "Vybrať výdajné miesto" |
| `btnChoosenPickupPoint` | "Zmeniť výdajné miesto" |
## Multilingual Stores
If your store serves customers in multiple languages, you can provide per-locale widget text using Shopify's **Translate & Adapt** app.
**How it works**:
- The `zasilkovna_translations` metaobject is configured as `Translatable: true` with `PublicRead` storefront access.
- Shopify's Translate & Adapt app can add locale-specific versions of the 6 translation fields.
- At render time, the widget uses the customer's active locale to select the correct translation automatically.
**To add per-locale translations**:
1. Install the **Translate & Adapt** app from the Shopify App Store (free).
2. In Translate & Adapt, find the `zasilkovna_translations` metaobject entry.
3. Add translations for each locale you support — all 6 fields per locale.
4. The app will serve the correct locale's text to each customer automatically.
:::caution
Do not create multiple `zasilkovna_translations` metaobject records. The app expects exactly one record and uses Shopify's native translation system for per-locale values. Creating additional records will cause unpredictable behaviour. If you accidentally created duplicates, delete the extras and keep only one.
:::
:::tip
For stores that only serve Czech or Slovak customers, entering a single set of translations in the **Translations** section of the app is the simplest approach and covers most cases.
:::
## Technical Details
- **Metaobject type**: `zasilkovna_translations`
- **Storefront access**: PublicRead (required for the widget to read translations)
- **Translatable**: Yes (supports Shopify's native translation system)
- **Translations are fetched at render time**, so changes take effect without any cache clearing.
---
## Source: src/content/docs/en/zasilkovna/troubleshooting.mdx
---
title: Troubleshooting
description: Solutions to common issues with the Zásilkovna pickup point app
---
import FaqSchema from '../../../../components/FaqSchema.astro';
This page covers the most common issues reported by merchants.
## Widget Doesn't Appear at Checkout
This is the most frequently reported issue.
### Check 1: Keyword doesn't match the shipping method name
The widget only activates when the customer selects a shipping method whose name contains the keyword you configured in the app. A mismatch here is the most common root cause.
1. Go to **Shopify Admin → Settings → Shipping and delivery** and copy the exact name of your Zásilkovna shipping method.
2. Open the app and go to **Interface Settings**. Check the configured keyword.
3. Confirm the keyword appears inside the shipping method name (case-insensitive).
Example: if your shipping method is "Zásilkovna – výdejní místo" and your keyword is `zasilkovna`, it will match. If your keyword is `pickup`, it will not.
See [Keyword Configuration](../keyword-config/) for the full explanation.
### Check 2: Checkout extension block is missing
The widget requires the app block to be added in the checkout editor.
1. Go to **Shopify Admin → Settings → Checkout** and click **Customize**.
2. Navigate to the **Thank You** page in the editor.
3. Verify the **Zásilkovna / Packeta Pickup Point** block is present and enabled.
4. If it's missing, click **Add block** and add it from the app blocks section.
For the Order Status page, go to **Settings → Customer accounts → Customize** instead.
---
## Widget Shows Empty — No Pickup Points to Select
The widget opens but the map or list of pickup points is blank.
**Likely causes:**
- The carrier's pickup point API is temporarily unavailable
- The carrier keyword is configured incorrectly (wrong carrier is being called)
- A network issue is preventing the widget from loading pickup point data
**Fix:**
1. Verify the keyword in Interface Settings matches the correct carrier.
2. Check if the carrier's pickup point service is operational (try searching on their website directly).
3. If the issue affects only some customers, it may be a network or browser issue on their end.
---
## Widget Appears on Wrong Orders (Showing for Home Delivery)
If the widget shows up for customers who chose a home delivery method, your keyword is too generic and is matching unintended shipping methods.
**Fix:** Use a more specific keyword. If "zasilkovna" appears in both your pickup and home delivery method names, rename the home delivery method to remove the overlap.
See the [Carriers](../carriers/) page — specifically the "Home Delivery vs Pickup Points" section — for guidance on which shipping methods need keywords configured.
---
## Pickup Point Selector Not Showing on Mobile
The carrier select button or the widget itself doesn't render correctly on smaller screens.
**Fix:** This was a known UI rendering issue fixed in a recent app update. Update the app to the latest version. If it still occurs after updating, contact support.
---
## "Link Expired" Error on First Pickup Point Selection
A "link expired" error appears when the customer tries to select a pickup point for the first time.
**Fix:** This was a known bug fixed in a recent app update. If you are still seeing this error after updating the app, contact support.
---
## Widget Hidden on Order Status Page
The pickup point widget is not visible on the order status / customer account page after checkout.
**Fix:** The extension block needs to be added separately for the customer accounts area.
1. Go to **Shopify Admin → Settings → Customer accounts**.
2. Click **Customize**.
3. Add the Zásilkovna extension block to the order status section.
4. Save.
---
## All App Pages Show 404 / "Invalid Token" / App Won't Load
If all pages inside the app return 404 errors or you see an "Invalid token" error, check the following:
1. **Verify your API key**: Go to app settings and confirm the API key matches the one in your Zásilkovna/Packeta account at [client.packeta.com](https://client.packeta.com).
2. **Reinstall the app**: If the API key is correct but the app still fails, reinstall it from the Shopify App Store. Your order history and tags are stored in Shopify and won't be lost.
3. **Contact support** if reinstalling doesn't resolve it.
---
## Export Stuck in "In Progress" State
The export to Zásilkovna starts but never completes, staying in a "progress" state.
**Fix:**
1. Refresh the page and check if the export completed in the background.
2. Cancel the export and retry with a smaller batch (10–20 orders).
3. Verify the orders you're exporting have the `zasilkovna_selected` tag — only orders with a confirmed pickup point selection can be exported.
---
## Widget Shows Wrong Language / English Instead of Czech
The widget displays English text even though the store is in Czech.
**Fix:**
1. Go to the **Translations** section in the app.
2. Check that all 6 text fields have Czech content entered.
3. All 6 fields are required — if any are empty, the app may fall back to English defaults.
4. Test in a private/incognito browser window after saving to avoid cached content.
---
## Order Tags Not Being Applied
Orders don't receive the `zasilkovna_selected` or `zasilkovna_unselected` tags automatically.
**Fix:**
1. Open the app and check for any pending permission requests — approve them.
2. If no prompts appear, go to **Shopify Admin → Settings → Apps**, find the Zásilkovna app, and verify it has Orders (write) permissions.
3. If permissions are missing: uninstall the app, reinstall from the App Store, and accept all requested permissions during installation.
---
## Pickup Point Widget Shows for the Wrong Carrier
The widget appears but shows Zásilkovna pickup points when the customer selected GLS, DPD, or another carrier.
**Cause:** The keyword for the other carrier is either not configured or is too generic and overlapping with another shipping method name.
**Fix:**
1. Go to **Interface Settings** and verify each carrier has its own keyword configured.
2. Make sure carrier keywords don't overlap — if a shipping method name contains two different keywords, the app uses the first match.
3. Use distinct shipping method names per carrier. See [Supported Carriers](../carriers/).
---
## Uninstalling the App
To uninstall the Zásilkovna app:
1. Go to **Settings → Apps and sales channels** in your Shopify admin.
2. Find **Pickup Points CZ/SK/HU** in the list.
3. Click **Remove app** and confirm.
After uninstalling:
- Your order tags (`zasilkovna_selected`, etc.) and custom attributes remain in Shopify — they are not deleted.
- Translation metaobjects remain in your store's content.
- Your billing subscription is automatically cancelled.
- If you reinstall later, you will need to reconfigure your settings.
---
## Still Need Help?
Email: **integrace@soundsgood.agency**
Please include your Shopify store URL, a description of the issue, and any screenshots. Mention the steps you've already tried.