Koru Shipday

Connects VTEX with Shipday: bulk-load shipping rates by postal code, automatically create paid orders in your delivery fleet, and push tracking and delivery confirmation back into VTEX.

Koru Shipday is a VTEX Admin App that connects a VTEX store with Shipday, the last-mile delivery management software for in-house fleets. It covers the full shipping cycle: loading shipping rates by postal code into VTEX, creating every paid order in Shipday so it goes out for delivery, and returning the tracking reference and delivery confirmation to VTEX.

The app is organized into three modules, plus a cross-cutting configuration, diagnostics, and audit layer:

• Rates — replaces the postal-code rate table of one or more shipping policies from a single spreadsheet, in one operation with an automatic backup.
• Orders — detects orders with approved payment whose shipping policy is enabled, calculates packages, and creates them in Shipday without duplicates.
• Events — receives the Shipday webhook and reflects the tracking reference and confirmed delivery in VTEX.

Before you begin

Recommended owners

One person can cover several roles in a small store.

Required access

Before installing, make sure you have:

• A valid VTEX Admin session in the store account.
• A License Manager role with access to the Logistics module. Without it, the Rates module stays blocked: rate writes use the administrator's session, not the app's identity.
• The official VTEX CLI installed and up to date.
• Permission to install apps in the chosen workspace and to modify the app's settings.
• The store's Website ID in Koru Suite, with Koru Shipday active for that site.
• A Shipday account with its API Key (Shipday dashboard → My Account → Integrations → API Credentials).
• At least one shipping policy already configured in VTEX to associate with Shipday.

Koru Shipday does not create a VTEX role of its own. Logistics access is managed with the controls available in VTEX License Manager.

Identifiers you will encounter

Installation with the VTEX CLI

Installation uses the official VTEX CLI. It is a standalone Admin App: it requires no Store Theme changes and no storefront block declarations.

Install in a validation workspace first

If the store has a QA process, install and configure in a development workspace first. Replace the values between braces:

vtex login {store-account}

vtex use {store-account}/{workspace}

vtex whoami

vtex install {vendor}.koru-shipday@0.x

vtex list

Open the app in VTEX Admin

You can open Koru Shipday from the store configuration section in VTEX Admin (side menu) or navigate directly:

https://{workspace}--{store-account}.myvtex.com/admin/koru-shipday

For master, use the account's main Admin domain:

https://{store-account}.myvtex.com/admin/koru-shipday

If the app does not appear in the navigation, check vtex list, reload VTEX Admin, and confirm you are looking at the same account and workspace where you installed it.

Install in master

Once the setup is validated in the corresponding workspace, select master, reconfirm the context, and repeat the installation:

vtex use {store-account}/master
vtex whoami
vtex install {vendor}.koru-shipday@0.x
vtex list

Settings are per installation/workspace. Verify the Website ID, the Shipday API Key, the webhook token, and the enabled policies in the final environment even if you already tested them in another workspace.

Updating and uninstalling

Update

Select the correct account/workspace, confirm it, and install the range again:

vtex whoami
vtex install {vendor}.koru-shipday@0.x
vtex list

After updating, open the app and check the license, the main checks, the enabled policies, and the state of the automations. Do not assume a code update replaces operational validation.

Uninstall

Uninstalling applies to the current workspace:

vtex whoami
vtex uninstall {vendor}.koru-shipday
vtex list

Activation and first access

Get the Website ID

Before first use, Red Clover must activate Koru Shipday for the corresponding website in Koru Suite. The Website ID is obtained from Koru Suite or provided during activation.

The Website ID:

• Identifies the ecommerce store within Koru Suite.
• Is not a password or a secret.
• Must belong to the same VTEX store where you installed the app.
• Is the only Koru identifier the merchant enters manually: the Koru App ID lives in the app's code and cannot be changed from the store.

Connect the store

On first access, the app shows Connect this store to Koru Suite:

The app does not ask for an additional Koru login. The person is already authenticated in VTEX Admin; Koru Suite only validates that the Website ID + Koru Shipday combination has an active license.

Recommended initial setup

Follow this order: each step enables the next, and the two operational modules only unlock once their checks are green.

What enables each module

Rates and Orders do not unlock on their own: they depend on different checks, because they operate with different identities.

When a check fails, the app shows a diagnostic code:

Complete configuration reference

All configuration lives in the VTEX app settings and is managed from the app's Settings screen (or from Admin → Apps → Koru Shipday). Changes are not applied until you press Save changes.

General and license

Shipday connection

Operation

Packages attribute

Automation

Rates module

Replaces the postal-code rate table of one or more shipping policies from a single spreadsheet. It does not create or modify policies, docks, or warehouses: it operates on the freight value table of policies that already exist.

How to use it

Template columns

Validations

What an upload replaces exactly

An upload replaces only the postal codes included in the file. Postal codes not present in the spreadsheet keep their previous rate unchanged: this is not a wipe-and-reload of the whole table.

Backup and rollback

• Before writing to a policy, the app backs up the current rates for the postal codes the upload will touch.
• If the write fails partway through with several policies selected, the app reverts those already applied using that backup.
• The automatic backup is capped at 300 distinct postal codes per upload. A spreadsheet above that cap can still be applied, but the app asks for an explicit acknowledgment: that upload has no backup and cannot be rolled back automatically.
• A postal code with no rate loaded today leaves nothing to back up: the rollback can restore the previous value of a postal code that already existed, not "undo" the creation of a new one.

Upload states

Bulk packages upload

This lives inside Settings, not in its own tab. It loads the packages specification into many SKUs at once, instead of filling it in product by product in the catalog.

Each row is applied on its own: a failing row does not affect the rest, and the result shows how many were applied and how many failed. Maximum 300 rows per upload — a larger spreadsheet is rejected with a request to split it.

Orders module

How orders are detected

The app polls the VTEX OMS for new orders and keeps a marker of how far it has processed, so it does not re-read the same range forever.

• The first run in a workspace looks back 24 hours.
• Each run processes up to 20 pages of 100 orders. If there are more, the marker does not move beyond what was processed and the next run continues from there: no order is lost, the work is just spread across more runs.
• If an order fails while being read, the run stops right there without advancing the marker, so it is not left behind.

When an order is eligible

An order is sent to Shipday when it meets all of these conditions:

ORD-001 is the normal case for a freshly created order: it is re-evaluated on its own in the next run and needs no action.

Order states

Manual retry

Rows in Data error and Permanent error show the Retry button. These are the only two states the app never leaves on its own, by design: looping retries on an order Shipday will keep rejecting fixes nothing.

The retry does not duplicate the order: if a previous attempt ended with an uncertain response, the app first asks Shipday whether the order already exists and, if it finds it, only records the relationship.

What is sent to Shipday

For each order the app sends the VTEX order number (which is what later matches incoming events), the recipient data, the configured pickup location, the total, the items with price and quantity, the normalized payment method, and the calculated package count. Payment data and credentials are not sent.

Events module (tracking and delivery)

Shipday notifies every delivery status change by webhook. The app records every event and reflects only two things in VTEX: the tracking reference and the delivery confirmation.

Configure the webhook

1. Choose a token of up to 32 characters and save it in Settings → Shipday webhook.
2. Copy the URL that same section displays — it looks like this:

https://{store-account}.myvtex.com/_v/public/koru-shipday/webhook/shipday

3. Load the URL and the token in the Shipday dashboard.

What the app does with each event

Results you will see on the screen

Invoicing and retries

To register tracking or confirm delivery, VTEX requires the order to be invoiced already. The app never invoices: it assumes the order already is by the time it reaches Shipday (operational rule: nothing is dispatched without an invoice) and only reads the invoice number.

If it is not invoiced yet, the event is not lost: it stays in Retrying and the tracking retry job tries again every 10 minutes, with a growing wait. If the problem is not transient, the order is flagged for manual review.

Automations

Three automated processes, visible in Overview → Automations:

The technical trigger always runs; what decides whether to act is the configured switch and interval. Reconciliation exists because normal polling never looks at an old order again: it sweeps orders left pending or retrying and reprocesses them, never duplicating an order already created in Shipday.

Run states

The Run now button triggers the same logic manually, without waiting for the schedule, and works even if the automated process is off. It is the recommended way to test a configuration change right away.

Screens

License and security

License validation

Every operational route requires:

1. A valid VTEX Admin session.
2. An active Koru license for the Website ID and Koru Shipday's App ID.

To tolerate transient network or license-service failures, a positive authorization is kept briefly; an explicit revoked-license response blocks the app immediately. The webhook is the exception: with a revoked license or the integration turned off, it responds successfully and discards the event while leaving a record, instead of making Shipday retry forever.

Data and credentials

• The app never asks for or stores the merchant's AppKey/AppToken. To operate on VTEX it uses the logged-in administrator's session (manual actions) or its own app identity (automated processes).
• The app's only secret is the Shipday API Key, stored in the VTEX app settings and never exposed to the browser in plain text.
• The browser never calls VTEX APIs or Shipday directly: everything goes through the app's own routes.
• The Website ID and App ID identify resources, but they are not passwords.
• Order state, events, and upload history are persisted in the app's internal storage, not in Master Data or in VTEX orders.
• Every action carries a correlation identifier that makes it traceable in the logs when support needs it.

Troubleshooting

The app does not appear after installation

1. Run vtex whoami.
2. Confirm the account and workspace.
3. Run vtex list and look for {vendor}.koru-shipday.
4. Reload VTEX Admin.
5. Try the direct URL /admin/koru-shipday on the same domain/workspace.

The license shows as inactive

1. Compare the Website ID with the correct site in Koru Suite.
2. Confirm that Koru Shipday is active for that website.
3. Make sure you did not copy any spaces.
4. Retry the validation.
5. If it persists, report the Website ID, account, and workspace to support, without sending credentials.

Rates is blocked

It is always CFG-001: your user does not have the Logistics role in License Manager. Ask a VTEX administrator to add it and verify the permissions again.

Orders is blocked

Check the four conditions in Settings: a valid Shipday API Key, the app permission in order, Integration active turned on, and at least one shipping policy checked. The notice tells you which one is missing.

The Shipday connection fails

• Confirm the API Key belongs to this Shipday account and has not been revoked.
• If the error is temporary (CFG-004), retry in a few minutes: it is not a configuration problem.
• Remember that Test connection may be testing a value you have not saved yet; the app says so.

No orders are being sent

Check, in this order:

1. That Integration active is on.
2. That Look for new orders automatically is on, or trigger it by hand from Overview.
3. That those orders' shipping policy is checked in Settings.
4. That the orders have approved payment.
5. The Orders screen: the Detail column states the exact reason per order.

An order is stuck in "Data error"

That is a Shipday rejection based on the order's data. Check that the recipient has a complete name, phone, and address, and that the configured pickup location is a readable address. Once fixed, use Retry on that row.

No events arrive from Shipday

1. Confirm the URL loaded in Shipday is the one the app shows for this workspace.
2. Confirm the Shipday token is identical to the one saved in the app (up to 32 characters, no spaces).
3. Check that Integration active is on: with the integration off, events are discarded.
4. Review the Events screen: if there are events with the Ignored result, the webhook is arriving fine and what you see are intermediate states that are not propagated.

The delivery is not reflected in VTEX

Look at the event on the Events screen:

• Retrying with an invoicing reason: the order is not invoiced in VTEX yet. It resolves on its own once invoiced, if automatic tracking retry is enabled.
• Error: the update in VTEX failed. Check that the order exists, is invoiced, and is not cancelled.
• No event at all: the problem is the webhook, not tracking. See the previous point.

The template is rejected even though it looks right

Download the template again from the app and fill it in without reopening the file in another tool. Reopening and re-saving an .xlsx can alter the hidden sheet carrying the version.

Rates do not show up in the simulator

If the upload shows as successful, wait: VTEX can take from minutes to more than a day to propagate new rates. Check the upload state in the Rates module before uploading the file again.

Functional limits

The current version:

• Assumes one order = one shipment: it does not handle multi-seller marketplace orders dispatched in more than one shipment or invoice.
• Uses a single pickup location for the whole account, not one per shipping policy.
• Automatically backs up up to 300 postal codes per rate upload; above that, the upload runs without a backup and requires explicit acknowledgment.
• Applies up to 300 rows per bulk packages upload, with no backup or rollback.
• Processes up to 20 pages of 100 orders per detection run.
• Does not invoice orders in VTEX: it assumes they arrive already invoiced.
• Does not propagate intermediate delivery states or failed deliveries to VTEX: only the tracking reference and the delivery confirmation.
• Does not create or modify shipping policies, docks, warehouses, or carriers.
• Always operates on the VTEX account where it is installed.

Checklist before going live

• Koru Shipday installed in the correct account and workspace.
• Website ID verified and active license confirmed.
• Shipday API Key loaded and Test connection green.
• VTEX permissions verified: the user's Logistics role and the app's policies.
• Webhook URL and token loaded in the Shipday dashboard, for this workspace.
• Pickup location complete and readable.
• Packages attribute created in the catalog, configured in the app, and verified against a sample SKU.
• Enabled shipping policies selected.
• A test rate upload applied and reviewed before a large one.
• Integration active turned on.
• A manual order sync run and reviewed on the Orders screen.
• Automations enabled only after manual validation.
• An owner assigned to review failed orders and events periodically.