Connect JTL to the hub

A JTL Fulfillment Network (JTL FFN) connection lets the hub, Balta Labs, hand shipments to your JTL fulfiller and read tracking, product, and stock information back. Connecting the account does not send anything. Shipments start only after you add a location and switch its workflows to Active in Fulfillment → Setup.

Before you begin

• Create a JTL app and have its client ID and client secret ready. See Create a JTL app.
• Use a JTL account with the Merchant role that has signed in to the FFN portal once.
• Connect weclapp. Orders and shipments come from it. See Connect weclapp.
• You need the Connections permission in the workspace, and the Fulfillment permission for the setup.

Authorize the account

1. Open Settings → Connections, select Add account, and choose JTL FFN. You can also select Add provider under Fulfillment & notifications.
2. In the Connect JTL Fulfillment Network dialog, check under Before you continue that the callback URL is the one saved in your JTL app.
3. Under Environment, choose Production for your live account or Sandbox for JTL’s test system.
4. Enter the Client ID and Client secret of your JTL app.
5. Optionally enter a Connection name. Without one, the hub uses the JTL account name.
6. Select Continue to JTL.
7. Sign in at JTL with the merchant account you want to connect.
8. Review the requested access and allow it.
9. JTL sends you back to Balta Labs, which confirms the result.

Finish without a long break. Each attempt is valid for 10 minutes and only in the browser where it started. If it runs out, start again from step 1.

Choose the right JTL account

Balta Labs connects the account you sign in with at JTL, which need not be the account that owns the app. If your browser is already signed in to JTL, JTL may reuse that session. If it is not the merchant account you want, sign out at JTL first and start again.

Balta Labs keeps one connection per JTL account and environment. Authorizing an account that is already connected updates its connection instead of adding a duplicate. To connect another merchant account, select Add account again.

The success screen

When Balta Labs has saved and verified the account, it shows JTL connected successfully! with the Account, the Connection, and the Environment. Check that the account is the one you intended.

A countdown then continues to fulfillment setup after five seconds. Select Continue now to go at once, or Stay here to stop the countdown. After a reconnection, the screen shows JTL reconnected successfully! and returns you to the connection instead.

If the authorization did not finish, the screen shows a title such as Permissions are missing, followed by What happened and What to do. Select Try again to restart, or Read the troubleshooting guide to open the matching section of Fix JTL connection errors.

Check the connection

In Settings → Connections, the account appears under Fulfillment & notifications. Its card shows the health and when it was last checked:

• Not checked: no test has run since the account was added or changed.
• Working: the last test or JTL request worked.
• Check failed: the last test or request failed. The card shows JTL’s message. The authorization is kept; fix the cause and test again.
• Reconnect needed: JTL no longer accepts the authorization. Reconnect the account as described below.

Select Test to check the account now. The test only reads from JTL. Select Details to see the Account, What the hub can do, and the Reference lists of Warehouses and Shipping methods, each with its ID and, under Fulfiller, the fulfiller it belongs to. The location dialog offers the same choices. Edit shows the JTL account, its environment, the app client ID, and when it was authorized. You can also rename the connection there.

The card also reminds you that the account is not used for shipments until a location is switched on, and links to Open fulfillment setup.

Set up the location

A location is a weclapp warehouse operated by a fulfillment provider account. Add one for each warehouse that JTL serves:

1. Open Fulfillment → Setup. If the page shows Start with weclapp, choose your weclapp connection and select Save and continue.
2. Under Locations, select Add location.
3. Enter a Name.
4. Under weclapp warehouse, pick the warehouse whose shipments JTL handles, or type its ID.
5. Under Provider account, choose the JTL account. The dialog then loads the account’s choices.
6. Under Warehouse at JTL, choose the warehouse. This fills the Fulfiller ID and the Fulfiller warehouse ID; both stay editable. If the dialog says The account’s choices could not be loaded. Enter the IDs instead., type both IDs yourself, or select Test on the account card to find the cause.
7. Under Shipping methods, select Add carrier for each weclapp carrier and choose its FFN shipping method ID from the suggestions. They only include that fulfiller’s shipping methods and show each method’s name under its ID. A shipment whose carrier has no mapping goes to JTL with its standard shipping type, and the hub records a warning.
8. Select Save location.
9. Under Sync, select Start syncing if nothing is syncing yet.

Every workflow of a new location starts Off. A JTL location has these workflows:

• Dispatch: hands released shipments to JTL.
• Tracking: writes tracking numbers back to weclapp.
• Catalog: sends articles, images, and product authorizations to JTL.
• Stock check: compares the weclapp stock with JTL.
• Inbound: announces incoming deliveries to JTL.

Each workflow has one of three modes:

• Off: nothing happens.
• Shadow: the hub decides and records what it would do. It writes nothing to JTL or weclapp.
• Active: the hub does the work.

Workflows are configured in Fulfillment → Setup. Use Shadow to inspect decisions, then enable Active when ready. Changes to or from Active require confirmation. See Connect fulfillment providers for setup and monitoring.

Reconnect an account

Reconnect when the card shows Reconnect needed, or after you replaced the app’s client secret at JTL.

1. Open Settings → Connections and find the account under Fulfillment & notifications.
2. Select Reconnect on its card.
3. Leave Client ID and Client secret blank to keep the stored app credentials, or enter the new ones.
4. Select Reconnect with JTL.
5. Sign in with the same JTL account as before and allow access.
6. On JTL reconnected successfully!, check the account. Then select Test on the card.

A reconnect stays in the account’s environment. If you sign in with a different JTL account, the hub shows A different account was used and leaves the connection unchanged. To connect another account, add it as a new connection.

How access stays valid

JTL access tokens last about 30 minutes. The hub renews them automatically, and every renewal replaces the refresh token. You do not need to do anything. If JTL refuses a renewal, for example because access was revoked, the card shows Reconnect needed, and the hub cannot work with the account until you reconnect it. Afterwards, check Fulfillment → Operations for items that failed in the meantime.