# InPost – Tale Commerce Documentation

Language: English

## Installation and setup

Explore the technical requirements of the app and learn more about the available features.

### Store requirements

#### Carrier Calculated Shipping (CCS)

**Carrier Calculated Shipping (CCS)** is a Shopify feature required for our app to work. It displays a list of the nearest InPost pickup points in checkout based on the customer's address. Without CCS enabled, the app cannot show shipping methods in checkout.

## How to enable CCS

CCS is not available on all Shopify plans by default. It may need to be enabled by Shopify Support, or it may be included with certain plans. Below are the main options:

### Option 1: Annual billing (Grow plan) — Most popular

**Requirements:** Grow plan, billed annually  
**Cost:** Free (CCS is included at no extra cost)

1. Log in as the store owner
2. Go to **Settings → Plan → Change plan → Pay annually** to switch to annual billing
3. Contact [Shopify Help Center](https://help.shopify.com/search/Contact-Support), click **Chat with a human**, and ensure you are connected to a support agent
4. Use this message template:

   > Good day, I understand that Carrier-Calculated Shipping is available at no extra cost on the Grow annual plan. Could you please enable this feature for my store? Thanks in advance!

**Bonus:** You save 25% on your Shopify subscription with annual billing.

### Option 2: À la carte (Grow plan, monthly)

**Requirements:** Grow plan, billed monthly  
**Cost:** +$20 USD per month

1. Log in as the store owner
2. Go to [Shopify Help Center](https://help.shopify.com/search/Contact-Support)
3. Click **Chat with a human** and ensure you are connected to a support agent
4. Use this message template:

   > Good day, I understand that enabling Carrier-Calculated Shipping comes with an extra $20/month fee on the Grow monthly plan. Could you please add that feature to my store? Thanks in advance!

### Option 3: Advanced plan

**Requirements:** Advanced Shopify plan  
**Cost:** Free (CCS is included)

1. Log in as the store owner
2. Go to **Settings → Plan → Change plan** to upgrade to Advanced

## Note: Shopify plan changes

When your plan changes (e.g. billing currency, billing frequency), Shopify may automatically disable CCS. In that case, the app will stop displaying pickup points. Contact [Shopify Help Center](https://help.shopify.com/search/Contact-Support) to re-enable this feature.


#### Recommended store settings

To seamlessly ship orders to pickup points, we recommend changing the following settings in the store:

### Required email, first name, last name and phone number

1. Go to [Settings → Checkout](shopify://admin/settings/checkout)
2. Scroll down to **Customer contact method**
3. Select to **Email**
4. Scroll down to **Customer Information**
5. In the **Full name** section, select **Require first and last name**
6. In the **Shipping address phone number** section, select **Required**
7. Click **Save**

### **If you offer Apple Pay or Google Pay via Shopify Payments / Stripe**

We recommend disabling the express checkout options for Apple Pay and Google Pay. Make sure that the express checkout buttons are not visible on: the product page, cart page, and checkout page. In the case of Apple Pay - it will remain available as a standard payment method in Shopify Checkout.

### If your store has more than one location

If your store has more than one location, the shipping settings should be adjusted so that the shipping fees are calculated only based on the primary location

1. Go to [Settings → Shipping and delivery](shopify://admin/settings/shipping)
2. In the **Shipping** section, click on the area directly below **General shipping rates**
3. Expand the **Shipping origins** section by clicking on **Show details**
4. Click on the **Edit Icon**, and the **Manage rates for Shop location** window will appear
5. Select the **Remove rates** option, and click **Done** - repeat this for all locations except the primary one
6. Click **Save**

### If you are using the Google & YouTube app

The Google & YouTube app syncs the shipping rates set in your store settings by default. Unfortunately, it ignores rates from shipping apps such as ours. The only solution is to turn off the sync of delivery methods and add them manually in Google Merchant Center.

**Warning:** If you do not disable sync, the Google & YouTube app will delete the manually added shipping methods during the next sync. We reported this issue to Shopify, but it is unlikely that it will be fixed soon.

1. Go to [Sales channels → Google & YouTube](shopify://admin/apps/google)
2. Go to the **Settings** tab
3. In section **Your product feed settings**, next to **Shipping settings** click **Manage**
4. Select **Manually set up shipping settings in Google Merchant Center**
5. Click **Save**
6. Go to [Google Merchant Center](https://merchants.google.com/mc)
7. Go to the **Shipping and returns** tab
8. Add your shipping methods, including delivery to pickup points


### Using the app

#### How to exclude certain products from shipping to pickup points?

### Option 1: Variant weight limit (recommended)

If you're not using the weight attribute in Shopify, you can assign a weight to selected variants (e.g. 1 kg) and then set the weight limit option in the InPost app to the same weight (i.e. 1 kg). Shipping to pickup points will not be available if the total cart weight exceeds the limit.

### Option 2: Product tag exclusion

You can assign a tag to products, for example, `large-product`, and then in the InPost app, check the **Enable product exclusions** option and enter this tag. Shipping to pickup points will not be available if any of the products in the cart contain this tag.

**Note**: the option to exclude by tag may slightly slow down the display of pickup points, we recommend using the option to exclude by weight.


#### How to add information when selecting a shipping method?

You can add any additional information when choosing a shipping method at checkout:

![Shipping notice in checkout](./shipping-notice-checkout.png)

Steps:

1. Go to the [Online Store](shopify://admin/themes) sales channel.
2. Next to the name of the live theme, click the button with three dots, and then **Edit default theme content**
3. In the search input, enter `shipping_method_notice`.
4. Enter your text in the **Shipping method notice** input, for example:
   > If you'd like to select a different pickup point, change the shipping address to one closest to the desired pickup point.
5. Click **Save**.

![Shipping notice in the theme](./shipping-notice-theme.png)


#### How to add courier shipping method?

Our app handles pickup point delivery only. Courier delivery is best configured directly in Shopify settings - Shopify provides built-in tools for managing shipping rates, so there's no need to duplicate this functionality in the app.

Below is a step-by-step guide on how to add the InPost courier delivery option with free delivery:

1. Go to [Settings → Shipping and Delivery](shopify://admin/settings/shipping)
2. Click on the **General** shipping rate profile
3. For a delivery area including Poland, click **Add rate**
4. Enter the name of the shipping method, e.g. **InPost Courier** and its cost for the client, e.g. 5 EUR
5. Click **Add conditional pricing**
6. Select **Based on order price**
7. If you want to offer free shipping from, for example, 50.00 EUR in the **Maximum price** field, enter the amount you want with a single penny removed from it (e.g. 49.99 EUR)
8. Click **Done**
9. Click **Add rate** again
10. Enter the same shipping method name as before
11. Leave the **Price** field blank
12. Click **Add conditional pricing**
13. Select **Based on order price**
14. In the **Minimum price** field, enter the amount (e.g. 50.00 EUR)
15. Click **Done**
16. Save the changes by clicking **Save**

The final result:

![Courier shipping rates](./shipping-rates.png)

In the same way, you can add other delivery methods such as DPD, DHL or GLS.


## Common questions and issues

Here is a summary of the most frequently asked questions and issues you may encounter. If you do not find what you are looking for on this list, please contact us.

### Common issues

#### Changes made in settings are not reflected in checkout

**Problem:** While configuring the InPost app and simultaneously checking the checkout page, the changes made in the app settings may not be immediately visible.

**Cause:** This occurs because Shopify caches the proposed delivery methods for a given cart for 5 to 15 minutes, causing a delay in updating.

**Solution:** Return to the shipping address form and make a small change, such as adding a character to the last name. This will prompt the system to retrieve the updated shipping methods.


#### Pickup points are not shown when using Apple Pay or Google Pay

In the case of express checkout Apple Pay and Google Pay, the delivery to parcel lockers option will not be displayed. This happens because Shopify does not pass the complete delivery address to the InPost application, which is required to search for the nearest pickup points.

If this poses a problem, we recommend disabling the express checkout options for Apple Pay and Google Pay. Make sure that the express checkout buttons are not visible on: the product page, cart page, and checkout page. In the case of Apple Pay - it will remain available as a standard payment method in Shopify Checkout.


### Common questions

#### Can the customer choose a different pickup point than the suggested ones?

Buyers may only choose between pickup points selected based on their selected shipping address. We realize that this is not a perfect solution; however, we would like to offer 95% of customers a more pleasant shopping experience.

**When Shopify starts allowing apps to expand the checkout, we will surely add the option to select a different pickup point.**

For the time being, the buyer has three options:

1. Changing the shipping address to one that is close to the parcel locker and then selecting that parcel locker
2. Adding a note to the order
3. Contacting the merchant, after submitting the order

It's possible to add a notice on the shipping method selection page, for example: "If you would like to select a different parcel locker, change the delivery address to one closest to the preferred locker". See article: [How to add information when selecting a shipping method?](?article_id=122317718)

You may also consider using our other app, [Atlas Pickup Points](https://apps.shopify.com/atlas-pickup-points), which works differently and does not have this issue.


#### Are the data on the pickup points up to date?

Yes, pickup point data is updated every hour, ensuring that your customers do not place orders to temporarily unavailable locations.


#### What happens if the store doesn't support the currency of the destination country?

Shopify automatically converts the shipping cost to the store's currency. For example - if a store operates in PLN and doesn't support EUR, and shipping to France costs 5 EUR, the amount will be automatically converted to PLN at checkout.


#### What names are pickup point delivery methods listed under?

Names depend on the country and language. Depending on the market, shipping methods may appear under the InPost, Mondial Relay, or local partner brands (e.g. Austrian Post, Express One). The app automatically adapts shipping method names to the local language and naming conventions.


#### Do you need a contract with InPost or an API key for the app to work?

Our app does not require a contract with InPost or an API key.


#### Is it possible to ship to a pickup point with Cash On Delivery?

Yes, however Shopify does not allow adding a surcharge for COD to the shipping cost. If you charge a COD fee, you need to include it in the shipping price.


#### How to ship with InPost?

The role of the InPost – Tale Commerce app is to allow buyers to select a pickup point.

The ID of the pickup point selected by the customer is displayed next to every Shopify order:

![Selected pickup point](./selected-pickup-point.png)

You can choose the method by which the parcels will be delivered.

Possible options are:

1. [BaseLinker](https://baselinker.com/en-US/integrations/inpostkurier/) - if you're using BaseLinker to manage orders, the InPost Lockers app automatically passes the pickup point ID to BaseLinker. Thanks to BaseLinker, you can send parcels through brokers or direct InPost integration.
2. [Apilo](https://apilo.com/) - if you're using Apilo to manage orders, the InPost Lockers app automatically passes the pickup point ID to Apilo. Thanks to Apilo, you can send parcels through brokers or direct InPost integration.
3. [Furgonetka](https://furgonetka.pl/?lang=en_GB) broker service - if you're using the Furgonetka broker service, their [Shopify integration](https://furgonetka.pl/pomoc/272,integracja__shopify) allows you to send shipments quickly. Address details along with the ID of the pickup point are passed automatically.
4. For smaller stores, it is possible to send shipments manually by entering the address and ID of the pickup point. You can use any broker of your choice or the [InPost Parcel Manager](https://manager.paczkomaty.pl/).


#### Integrating with the InPost - Tale Commerce app

The **InPost - Tale Commerce** app allows customers to select an InPost pickup point directly during Shopify checkout. Once an order is placed, the selected pickup point data is stored in the order object - you can retrieve it via Shopify webhooks or the Admin GraphQL API.

This article explains how to extract the pickup point identifier from a Shopify order, detect the shipment type, and normalize shipping method names.

## Order data structure

The selected pickup point information is stored in the `shipping_lines` array (webhooks) or `shippingLines` (GraphQL) on the order object. Each element in this array contains, among others:

- **name** (String) - the shipping method name visible to the customer
- **carrier_identifier** / **carrierIdentifier** (String) - the app identifier
- **code** (String) - the shipping method code containing the pickup point identifier

For the InPost - Tale Commerce app, the `carrier_identifier` is always:

```
817bcd956c0dec08763dd1d56479cc14
```

## Retrieving data from a webhook

Shopify webhooks documentation: [https://shopify.dev/docs/api/webhooks/latest](https://shopify.dev/docs/api/webhooks/latest)

A typical order payload contains the `shipping_lines` array:

```json
{
  "shipping_lines": [
    {
      "carrier_identifier": "817bcd956c0dec08763dd1d56479cc14",
      "code": "INPOST-WAW77N",
      "name": "InPost Paczkomat 24/7 • 1.1 km • WAW77N"
    }
  ]
}
```

## Retrieving data from the Admin GraphQL API

Order object documentation: [https://shopify.dev/docs/api/admin-graphql/latest/objects/Order](https://shopify.dev/docs/api/admin-graphql/latest/objects/Order)

Example GraphQL query:

```graphql
query GetOrder($id: ID!) {
  order(id: $id) {
    id
    name
    shippingLines(first: 5) {
      nodes {
        carrierIdentifier
        code
        title
      }
    }
  }
}
```

## Identifying the pickup point

To extract the pickup point identifier from an order:

1. Check whether `carrier_identifier` (webhook) or `carrierIdentifier` (GraphQL) equals `817bcd956c0dec08763dd1d56479cc14`.
2. If it does - retrieve the `code` value.
3. Remove the `INPOST-` prefix from the `code` value to get the pickup point ID.

JavaScript example:

```javascript
function getPickupPointId(shippingLine) {
  const INPOST_APP_CARRIER_ID = "817bcd956c0dec08763dd1d56479cc14"

  if (shippingLine.carrier_identifier !== INPOST_APP_CARRIER_ID) {
    return null
  }

  const code = shippingLine.code

  if (!code.startsWith("INPOST-")) {
    return null
  }

  return code.replace("INPOST-", "")
}
```

### Example point codes - Poland

| `code` value        | Point ID after removing prefix | Type         |
| ------------------- | ------------------------------ | ------------ |
| `INPOST-CSZ17M`     | `CSZ17M`                       | Locker       |
| `INPOST-KRMA01BAPP` | `KRMA01BAPP`                   | Locker       |
| `INPOST-POP-BIA114` | `POP-BIA114`                   | Pickup point |

### Example point codes - other countries

For international shipments, the point identifier starts with the country code:

| `code` value         | Point ID after removing prefix |
| -------------------- | ------------------------------ |
| `INPOST-AT981002P`   | `AT981002P`                    |
| `INPOST-BE041176`    | `BE041176`                     |
| `INPOST-ES059572`    | `ES059572`                     |
| `INPOST-FR033579`    | `FR033579`                     |
| `INPOST-ITAAQ02468P` | `ITAAQ02468P`                  |
| `INPOST-ITBAT44063M` | `ITBAT44063M`                  |
| `INPOST-LU010779`    | `LU010779`                     |
| `INPOST-NL022165`    | `NL022165`                     |
| `INPOST-PT002296`    | `PT002296`                     |
| `INPOST-UK00008334`  | `UK00008334`                   |

## Detecting shipment type - Weekend Delivery

The "Paczka w Weekend" (Weekend Delivery) option does not change the pickup point code in the `code` field. To detect this delivery type, check the `name` attribute - if it contains the keyword **"weekend"**, the order is a weekend delivery.

```javascript
function isWeekendDelivery(shippingLine) {
  return shippingLine.name.toLowerCase().includes("weekend")
}
```

Example `name` values:

- `InPost Paczkomat 24/7 • 1.1 km • WAW77N` - standard delivery
- `InPost Paczkomat 24/7 • 1.1 km • WAW77N • Paczka w Weekend` - Weekend Delivery

> **Note:** Apart from detecting Weekend Delivery, you should not rely on the `name` attribute to identify shipping methods. The name can be changed at any time. Always use the `code` field to identify the pickup point.

## Normalizing shipping method names

Shipping method names generated by the app include the pickup point code and distance, for example:

```
InPost Paczkomat 24/7 • 1.1 km • WAW77N
InPost Paczkopunkt • 0.5 km • POP-WAW722
Locker Mondial Relay • 1.1 km • FR020947
Points Relais® • 0.6 km • FR019857
Abholstation • 0.5 km • AT981002B
Postfiliale • 0.5 km • AT981002P
InPost Locker • 0.5 mi • UK00192101
InPost Shop • 0.4 mi • UK00253499
```

If your system provides shipping method statistics or filtering by shipping method name, normalizing names will make reporting easier. To normalize, remove the part containing the distance and point code:

```javascript
function normalizeShippingName(name) {
  return name.replace(/ • \d+\.?\d*\s*(km|mi) • [\w-]+/g, "")
}
```

Normalization results:

| Original name                                                | After normalization                        |
| ------------------------------------------------------------ | ------------------------------------------ |
| `InPost Paczkomat 24/7 • 1.1 km • WAW77N`                    | `InPost Paczkomat 24/7`                    |
| `InPost Paczkomat 24/7 • 1.1 km • WAW77N • Paczka w Weekend` | `InPost Paczkomat 24/7 • Paczka w Weekend` |
| `InPost Paczkopunkt • 0.5 km • POP-WAW722`                   | `InPost Paczkopunkt`                       |
| `Locker Mondial Relay • 1.1 km • FR020947`                   | `Locker Mondial Relay`                     |
| `Points Relais® • 0.6 km • FR019857`                        | `Points Relais®`                          |
| `InPost Locker • 0.5 mi • UK00192101`                        | `InPost Locker`                            |

## Complete example

Below is a complete function that processes a shipping line from an order and returns all the necessary information:

```javascript
const INPOST_APP_CARRIER_ID = "817bcd956c0dec08763dd1d56479cc14"

function parseShippingLine(shippingLine) {
  const carrierId = shippingLine.carrier_identifier ?? shippingLine.carrierIdentifier

  if (carrierId !== INPOST_APP_CARRIER_ID) {
    return null
  }

  const code = shippingLine.code

  if (!code || !code.startsWith("INPOST-")) {
    return null
  }

  const pickupPointId = code.replace("INPOST-", "")
  const name = shippingLine.name ?? shippingLine.title
  const isWeekend = name?.toLowerCase().includes("weekend") ?? false
  const normalizedName = name?.replace(/ • \d+\.?\d*\s*(km|mi) • [\w-]+/g, "")

  return {
    pickupPointId,
    isWeekend,
    originalName: name,
    normalizedName,
  }
}
```

Webhook usage example:

```javascript
app.post("/webhooks/orders/create", (req, res) => {
  const order = req.body

  for (const shippingLine of order.shipping_lines) {
    const result = parseShippingLine(shippingLine)

    if (result) {
      console.log(`Pickup point: ${result.pickupPointId}`)
      console.log(`Weekend Delivery: ${result.isWeekend}`)
      console.log(`Shipping method: ${result.normalizedName}`)
    }
  }

  res.sendStatus(200)
})
```

GraphQL response usage example:

```javascript
const orderData = await shopifyGraphQL(GET_ORDER_QUERY, { id: orderId })

for (const shippingLine of orderData.order.shippingLines.nodes) {
  const result = parseShippingLine(shippingLine)

  if (result) {
    console.log(`Pickup point: ${result.pickupPointId}`)
    console.log(`Weekend Delivery: ${result.isWeekend}`)
    console.log(`Shipping method: ${result.normalizedName}`)
  }
}
```