Admin Guide
This guide covers what an administrator needs to know to get the Starshipit integration running against your Fishbowl database, and how it behaves day to day. There’s no in-app screen for this tool — it’s a background service that moves orders and shipment information between Fishbowl and Starshipit automatically, so this guide is about setup and configuration rather than day-to-day operation.
Installation & Setup
Section titled “Installation & Setup”Setup and deployment of the Starshipit integration is performed by ILC — there is no self-service install today. Contact ILC to get it provisioned for your Fishbowl database and Starshipit account. The integration is deployed per Fishbowl database — if your organization runs more than one and wants the integration on additional ones, that’s a separate provisioning step.
Before ILC can install the integration, your organization needs to provide:
- Remote access to your Fishbowl server environment
- An active Starshipit account
- Starshipit API keys (ILC can retrieve these on your behalf if you provide your Starshipit login credentials)
Assuming access and credentials are available, most standard installations are completed and live within 1–2 business days of approval.
Installation touches two independent pieces — the background integration itself, and a Fishbowl plugin that adds both the Get Rates and Flush Pending Ships buttons. After install is complete your Fishbowl Advanced server needs a restart to take effect. From there, ILC runs an initial connection test for the integration and will have you log in to Fishbowl Advanced as the admin user.
Everything from here on — approving the connection, confirming custom fields, and configuring the Get Rates plugin — needs admin (or equivalent) access, so it’s most efficient to handle all of it in the same sitting:
- Approve the integration’s connection: Settings module > Integrated Apps tab > click the approve icon next to the pending request. Until this is approved, the integration can enrich orders but can’t write shipment updates back into Fishbowl (mark a shipment Shipped, write tracking/cost/carrier).
- Confirm the required custom fields exist — see Required Custom Fields below.
- Configure the Get Rates plugin, if your team uses it — see Configuring the Get Rates Plugin below.
- Run Flush Pending Ships once to start it — see Flush Pending Ships below.
Required Custom Fields
Section titled “Required Custom Fields”The integration reads and writes the following Fishbowl custom fields. Confirm these exist with these exact names and types before going live — if a field required for shipping (like Sent To StarShipIT) is missing, an order simply won’t be picked up rather than raising a visible error. ILC can create these for you as part of setup — this isn’t something you typically need to configure yourself, but it’s documented here so you know what to look for if something isn’t syncing.
| Module | Field Name | Type | Purpose |
|---|---|---|---|
| Ship | Sent To StarShipIT | Checkbox | Marks whether an order has already been pushed to Starshipit. Orders where this is checked are skipped on subsequent runs. |
| Ship | StarShipIT Order ID | Text | The Starshipit order ID, written back after creation. |
| Ship | Shipping Amount | Text | Shipping cost, written back once the shipment is priced in Starshipit. |
| Ship | StarShipIT Shipped Carrier | Text | Carrier name, written back once shipped. |
| Ship | Dangerous Goods | Checkbox | Marks a shipment as containing dangerous goods. |
| Ship | StarShipIT Ship Pending | Checkbox | Marks a shipment that couldn’t be closed out automatically and is waiting on the Flush Pending Ships process — see Flush Pending Ships below. |
| SO | Delivery Instructions | Long Text | Passed through to Starshipit as delivery instructions, alongside any Sales Order note. |
| SO | Signature Required | Checkbox | If checked, Starshipit requires a signature on delivery, and Authority to Leave / Safe Drop are not applied to that order. |
| Product | Product Country of Origin | Drop-Down List | Country of origin for customs/tariff purposes. The drop-down list (“COO”) ILC provisions by default only seeds a couple of starter countries — confirm the full list you need is populated before relying on this for international shipments. |
| Product | HS Code | Text | Tariff/HS code passed through to Starshipit for customs. |
| Product | Dangerous Goods | Checkbox | Marks a product as dangerous goods (in addition to the Ship-level field above). |
Two additional custom fields the integration recognizes if present, remapped to Starshipit’s Authority to Leave / Safe Drop metadata:
| Fishbowl Field Name | Maps To |
|---|---|
| Authority To Leave | ATL |
| Safe Drop | SAFEDROP |
If both Authority to Leave and Safe Drop are set on the same order, Authority to Leave takes precedence. If Signature Required is checked, neither is applied, regardless of what’s set on the order — see Data Behavior Notes for more on how these interact.
Configuring the Get Rates Plugin
Section titled “Configuring the Get Rates Plugin”If your team uses the Get Rates button (see the User Guide), it has its own settings screen under Integration > StarShipIT in Fishbowl, available once the plugin is installed and the Fishbowl server has restarted.
| Field | What it’s for |
|---|---|
| API Key | Your Starshipit API key. A “Generate API Key” link on this screen takes you to the right page in Starshipit to create one. |
| Shipping Product | The Fishbowl Part that represents a “shipping charge” line item — this is what gets added to a Sales Order when a rate is selected. Only non-inventory/service-type parts appear in this list. |
| Issue Order | If checked, the Sales Order is automatically issued after a shipping line is added via Get Rates. |
| Rate Markup | If checked, lets you add either a percentage or a flat dollar amount on top of the raw carrier rate before it’s shown to your team or added to the order. |
| Table Rates / Contract Rates | Selects which Starshipit rate mode to request — your own negotiated contract rates, or Starshipit’s published table rates. |
Note that the underlying API connection details beyond the API Key (the base API URL and a subscription key used for the connection) aren’t exposed on this screen — those are handled by ILC as part of setup, not something you’ll need to change here.
If your rate markup isn’t calculating the way you expect on a shipping line item — particularly if your organization isn’t on a flat 10% tax rate — contact ILC so we can confirm the markup is being applied correctly for your tax setup.
Flush Pending Ships
Section titled “Flush Pending Ships”Occasionally a shipment can get stuck: dispatched in Starshipit, but Fishbowl isn’t able to mark it Shipped automatically. If this happens, a Flush Pending Ships button — delivered in the same plugin file as Get Rates — is available in the Shipping module.
The first time it’s installed, click Flush Pending Ships once. That first click is what starts its background schedule; after that, it keeps running on its own every couple of minutes with no further action needed.
From then on, clicking it tells you how many shipments are currently stuck and offers to run a fix immediately. This runs safely on Fishbowl’s server, so it won’t compete with your team for a login seat. Since it’s already running automatically in the background, you generally won’t need to click it again after that first time — it’s there for cases where you want a stuck shipment fixed right away rather than waiting for the next automatic pass.
If you’re seeing shipments stuck in this state regularly, contact ILC — that’s worth investigating rather than relying on the flush as a permanent workaround.
How Orders Are Sent to Starshipit
Section titled “How Orders Are Sent to Starshipit”An order becomes eligible once it reaches an Entered or Packed status in Fishbowl and its Sent To StarShipIT custom field is unchecked (see Required Custom Fields). Once sent successfully, Sent To StarShipIT is checked and StarShipIT Order ID is filled in — the integration won’t send it again.
If an order with the same order number already exists in Starshipit (for example, if it was sent by a previous run that didn’t get to update Fishbowl’s custom fields), the integration detects this and marks Fishbowl as sent using the existing Starshipit order, rather than creating a duplicate.
The integration checks for new orders to send once per hour during business hours (8am–5pm, Monday–Friday), and also responds in near real time to certain Fishbowl events as they happen — so most orders sync well within that hourly window rather than waiting for it. The hourly check exists as a catch-all in case an event-driven send doesn’t fire.
How Shipment Data Comes Back to Fishbowl
Section titled “How Shipment Data Comes Back to Fishbowl”The integration can update Fishbowl — tracking number, shipping cost, carrier, and Shipped status — once a shipment reaches any combination of these Starshipit events:
- Printed — a shipping label has been printed.
- Manifested — the shipment has been manifested with the carrier.
- Shipped — the shipment has been dispatched.
By default, Printed and Shipped trigger the Fishbowl update; Manifested does not. If your workflow needs a different combination — for example, updating Fishbowl only once a shipment is fully manifested — contact ILC to have this adjusted.
Once one of those events fires, the integration writes back to Fishbowl:
- Tracking number and package weight/dimensions (via Fishbowl’s tracking import).
- Shipping cost, into the
Shipping Amountcustom field. - Carrier name, into the
StarShipIT Shipped Carriercustom field. - The shipment is marked Shipped in Fishbowl.
If a Starshipit order is deleted and replaced with a new one (Starshipit does this internally in some cases, such as a label reprint under a new order), the integration detects the replacement and updates StarShipIT Order ID to the new order automatically — no manual correction needed.
Like outbound orders, shipment updates are checked once per hour during business hours, with near-real-time checks for certain events in between — so most updates land well within that hourly window.
Order Archiving
Section titled “Order Archiving”Once a Fishbowl sales order is Closed, the integration checks whether the corresponding Starshipit order is still sitting in an unshipped state, and if so, archives it in Starshipit. This runs as part of the same hourly cycle described above.
Data Behavior Notes
Section titled “Data Behavior Notes”A few things worth knowing about how data is handled:
Dangerous goods and Authority to Leave / Safe Drop are mutually adjusted, not independently applied. See Required Custom Fields above — Signature Required overrides both ATL and Safe Drop, and ATL takes precedence over Safe Drop if both are checked.
Kit component pricing. If a line item on an order is a kit component with no price of its own, the integration calculates an average price for it from the parent kit’s price, so Starshipit always receives a non-zero item value.
Multi-line shipping addresses. If a destination address’s street field spans multiple lines in Fishbowl, the integration treats the first line as the building/unit and the remaining lines as the street — this is a Fishbowl-address-format accommodation, not something you need to configure.
How Updates Work
Section titled “How Updates Work”Because the integration runs as ILC-hosted code in Azure rather than software installed on your own server, you can’t change its code or configuration yourself — not even a small tweak like which shipment events trigger a Fishbowl update or which custom fields are used. To request a change, contact ILC with what you need; we’ll confirm whether it’s possible, then deploy it.
Once ILC deploys a change, it’s live and running within seconds — there’s nothing for you to install, update, or restart to receive it.
Support
Section titled “Support”Setup questions, access issues, or anything not covered here — see FAQ / Troubleshooting or contact support directly.