The Blueprint System

Blueprints are the beating heart of the ShipGenius OMS. Every order that enters the system -- from any connected integration -- is evaluated against your blueprint configuration to determine how it gets fulfilled and how it moves through its lifecycle. Understanding blueprints is essential to getting the most out of the OMS.

What Is a Blueprint?

A Blueprint is a complete fulfillment configuration that defines how an order should be processed from the moment it arrives in ShipGenius through to shipment. Each blueprint is made up of sub-blueprints, each responsible for a different aspect of the fulfillment process.

A parent blueprint consists of the following sub-blueprint types:

• Fulfillment Blueprint (required): Defines how the order moves through the fulfillment lifecycle. Controls cartonization, facility routing, priority level, packslip generation, packslip template, and pickup instructions.
• Shipping Blueprint (required): Controls everything related to how a shipment is created. Address validation rules, parcel reference fields, carrier-specific pickup configuration for FedEx and DHL Express, USPS address handling, and whether next-business-day pickup services are allowed.
• Customs Blueprint (optional): Sets customs information on orders that require it for international shipments. Configures incoterms, duties and taxes prepaid status, export reason, AES exemption, ITAR license or exemption numbers, USMCA applicability, and comments. Each field has an overwrite flag so you control whether the blueprint can overwrite customs data that already exists on the order.
• Analytics Blueprint (coming soon): Will gather order data for reporting and analysis purposes.

Fulfillment and Shipping sub-blueprints are required on every parent blueprint. Customs is optional -- domestic-only blueprints that never touch international orders don't need one. A Billing Blueprint for 3PL accounts is also planned for a future release.

How Blueprint Priority Works

When an order arrives in ShipGenius from a connected integration, the system needs to determine which blueprint applies to it. This is done through the Blueprint Priority system -- an ordered list of blueprints paired with selection criteria, evaluated from top to bottom until a match is found.

Priority evaluation happens in three stages, in this order:

1. Marketplace-Specific Priorities

Each integration has its own priority list. When an order comes in from that integration, the system works through the list top to bottom, testing each entry's selection criteria against the order. The first match wins -- that blueprint is applied and evaluation stops. If no entry in the marketplace list matches, evaluation moves to the next stage.

2. Global Priorities

If you have global blueprint priorities configured in your OMS settings, they are evaluated next using the same top-to-bottom matching logic. Global priorities apply across all integrations on your account, making them useful for catch-all rules that should fire regardless of which channel an order came from.

3. Default Blueprint (Fallback)

Every integration has a default blueprint configured at setup. If an order doesn't match any marketplace-specific or global priority, the default blueprint is used. It is strongly recommended to set your default blueprint to an ERROR type blueprint rather than a real fulfillment blueprint. This ensures that orders which slip through all your filters are flagged for review rather than silently processed with the wrong configuration.

Selection Criteria (Filters)

Each priority entry in your list is paired with a selection criteria -- a filter expression that defines the conditions an order must meet for that blueprint to be selected. If an entry has no selection criteria, it acts as a catch-all and will always match.

ShipGenius has a full-featured filter builder you can use to construct these expressions without writing raw syntax. Filters can be built against:

• Order fields: notes, address information, carrier service, external shipping cost, and other order-level data
• Order line fields: quantity, price, and other line-level data
• Item fields: SKU, dimensions, pricing, consumables, customs information, and other item-level data

Example filter expressions:

• order.external_shipping_cost > 50 -- matches orders where the customer paid more than $50 for shipping
• order_line.item.sku starts_with "XL" -- matches orders containing items with SKUs starting with XL
• order.notes contains "priority" -- matches orders with priority in the notes field

An important constraint: you can only filter on data that exists on the order at the time it arrives in ShipGenius. Shipment and Package entities are created during the fulfillment process -- they don't exist yet when blueprint selection runs, so you cannot filter on them. Stick to order, order line, and item data for your selection criteria.

Blueprint Actions (Coming Soon)

A future release will add an actions list to each blueprint priority entry. When a blueprint is matched, the system will also execute a configurable set of actions on the order -- switching carrier, reassigning facility, updating order fields, or other operations. This will make the blueprint system even more powerful as a fully automated order routing and modification engine.

A Practical Example

Here's what a typical blueprint priority configuration might look like for a business shipping both domestically and internationally:

• Priority 1 -- Blueprint: International DDU. Selection Criteria: DDU International Orders. Matches all international orders where duties are unpaid.
• Priority 2 -- Blueprint: International DDP. Selection Criteria: DDP International Orders. Matches all international orders where duties are prepaid.
• Priority 3 -- Blueprint: Domestic Standard. Selection Criteria: Domestic Orders. Matches all domestic orders.
• Priority 4 -- Blueprint: Domestic Standard. Selection Criteria: None (always matches). A catch-all before falling to the default.
• Default Blueprint: Default Error. Applied to anything that reaches this point -- flags the order for review.

The system evaluates top to bottom. An international DDU order matches Priority 1 immediately and stops. A domestic order skips Priorities 1 and 2, matches Priority 3, and stops. Priority 4 with no criteria acts as a safety net before the error fallback.

Best Practices

• Order from most specific to least specific. Put highly specific filters at the top (e.g. VIP customers ordering hazmat products) and broad catch-alls lower (e.g. all domestic orders). If a broad filter is above a specific one, the broad filter will match first and the specific one will never fire.
• Use a no-criteria entry as your catch-all before the default. A priority entry with no selection criteria always matches. Place one near the bottom of your list to catch anything your specific filters miss, rather than relying on the default blueprint.
• Set your default blueprint to an ERROR type. Orders that reach the default have matched nothing in your priority list. You want to know about those -- not have them silently processed with a fallback configuration that may not be appropriate.
• Test your filters before going live. Create test orders that match your intended criteria and verify the right blueprint is selected before enabling an integration for live traffic.
• Use the Customs Blueprint only where needed. Domestic blueprints don't need a customs configuration -- only attach one to blueprints that will handle international orders.

FAQs

Do I need to create a separate blueprint for every scenario?

Not necessarily. The same blueprint can appear multiple times in your priority list with different selection criteria. For example, you might use the same Domestic Standard blueprint for both a specific domestic filter and a catch-all entry -- the blueprint configuration is shared, only the selection criteria differs.

What happens if no blueprint matches and I have no default set?

Every integration requires a default blueprint to be configured. The system will not let you save an integration without one. Always set the default to an ERROR type blueprint so unmatched orders surface for review rather than processing incorrectly.

Can I use global priorities and marketplace-specific priorities together?

Yes. Marketplace-specific priorities are evaluated first. If nothing matches there, global priorities run next. If nothing matches there either, the integration's default blueprint is applied.

Can I filter on customs information to route international orders?

Yes. Item-level customs information is present on the order when it arrives and is available for filtering. This is how you'd build filters like DDU International Orders or DDP International Orders as shown in the example above.

What is the Customs Blueprint's overwrite behavior?

Each field in a Customs Blueprint has a corresponding allow_overwrite flag. If an order already has customs data set on a field and the overwrite flag is off, the blueprint will not touch that field. This lets you set defaults while respecting customs data that came in from the external system.

Is the Analytics Blueprint available yet?

Not yet. Analytics Blueprints are coming soon. When released, they will allow you to define what order data is collected for reporting and analysis purposes.