OMS / WMS / eCommerce Platform Integration Guide

This guide provides a detailed walkthrough for integrating the ShipGenius API into your platform, whether it is an Order Management System (OMS), Warehouse Management System (WMS), ERP, or an eCommerce solution.

If you are connecting a marketplace ShipGenius already supports, such as Shopify or Infoplus, you do not need to build against the API at all -- see the Marketplace Integrations article instead.

API Documentation and Reference

All GraphQL queries, mutations, and type definitions are available at https://lite.shipgeni.us/developer/api-reference. This is your go-to resource for the complete API schema, and it includes worked guides for each stage of an integration.

Creating an API Key

To obtain API credentials:

• Create a business account at https://lite.shipgeni.us/.
• Navigate to the Apps section in your account dashboard.
• Create a new app, which generates a Development API Key and a Production API Key.

Keys are environment-specific and will only function in their respective environments. Each key is scoped to the app it belongs to, so create a separate app for each system you connect. Keys can be regenerated or revoked at any time.

Request Headers

Content-Type: application/json

Authorization: Bearer YOUR-API-KEY

API Endpoints

• Production: https://api.lite.shipgeni.us/graphql
• Sandbox / Development: https://sandbox.api.lite.shipgeni.us/graphql

Use these endpoints depending on your development or production workflow. Build against Sandbox first -- it simulates real carrier behaviour without generating real labels or real charges. Send the ping query to confirm your credentials work and to see which permissions the key carries.

Legal Restrictions on Carrier Rates

ShipGenius maintains direct contractual relationships with USPS and UPS, which grant us access to discounted shipping rates under specific carrier pricing programs: USPS ShipGenius Provided Rates and UPS ShipGenius Provided Rates.

Under the terms of our agreements with these carriers, you may not modify, inflate, markup, or resell ShipGenius-provided USPS or UPS rates. These rates are strictly non-resellable under our carrier contracts and must be passed through as-is. Integrating platforms are prohibited from charging a different price than what our API returns in the rate field for shipments using our carrier credentials.

What You Can Do

If your platform wishes to include handling fees, profit margins, or flexible pricing models, you may:

• Use your own carrier account: connect and ship via UPS, FedEx, or USPS carrier accounts under your own negotiated contract. You are free to markup or modify those rates.
• Pass our rate through and charge a separate service fee: you may itemize a separate handling or service fee at checkout, as long as the actual shipping rate is not modified.

What You Cannot Do

• Display a higher shipping rate than returned by our API while using ShipGenius carrier credentials.
• Add a margin directly to the rate returned by our system and send that modified amount to the customer.
• Misrepresent the carrier rate in a way that violates USPS or UPS pricing guidelines.

These terms are enforced contractually with USPS and UPS. Violations may result in immediate suspension of API access and permanent revocation of carrier services.

If you have further questions about rate presentation, or you would like to discuss a custom commercial agreement or a white-label usage structure, please reach out to integrations@shipgeni.us.

Onboarding Clients

There are two primary models for onboarding your customers.

Customer-Centric Account Creation

• The end user creates a ShipGenius Lite account.
• They manage their own billing, carrier credentials, API keys, and shipment history.
• Your platform interacts with our API using their production API key.
• Ideal for platforms similar to EasyPost integrations.

Customers using this model are billed directly by ShipGenius for each label. Bring-your-own-carrier (BYOC) shipments are charged a flat fee starting at $0.06 per label. This can be tiered based on a strong payment history and volume of shipments per week.

Platform-Centric Billing

• The platform holds the only ShipGenius account.
• All rate requests and label creation are routed through the platform's credentials.
• The platform pays per-label fees and can pass these to customers as desired.
• Good for white-label solutions or flat-rate shipping platforms.

We offer tiered pricing for platforms bringing significant volume.

Key Functionality

ShipGenius sits between your system and the carriers. Your platform stays the system of record for what a customer bought; ShipGenius rate shops across carriers, buys the label, and hands back tracking. It currently supports FedEx, UPS, USPS, DHL, DHL Express, Passport, and UniUni.

Sync Your Catalogue

Items are the products you ship, and ShipGenius needs them before it can rate anything accurately. Every item needs dimensions and a weight -- carriers price on both, and an item missing them will either fail to rate or rate wrongly, which is the most common cause of a cost difference discovered after the fact. Item aliases map your platform's identifiers to ShipGenius SKUs so neither system has to change its own. Customs information can be attached to an item once rather than supplied on every international order.

Get Rates

Use the shipping.rate query to retrieve real-time rates based on origin, destination, and packaging. Rates come from your own connected carrier accounts, so nothing prices correctly until at least one is set up.

Create Shipment and Purchase Label

Use the shipping.create_shipments mutation to generate and purchase shipping labels. It accepts a list, so a batch of labels is one call.

Bulk Rate and Ship

Use shipping.rate_and_ship to rate and buy in a single call based on delivery requirements such as a deliver-by date or time in transit. This is one fewer round trip per order once you trust your routing setup.

Automated Routing

If you would rather not choose a carrier service per order, configure Blueprints and Rate Groups once in the account and let every order flow through them. A Rate Group compares its member services at fulfillment time and selects the cheapest or the fastest; a Blueprint decides which orders get which treatment. Neither requires anything from your integration beyond a well-formed order. If your own system already decides how things ship, set the carrier service on the order directly and skip this layer.

Voids

Use shipping.void_shipment, or shipping.void_shipments for a batch, to cancel a shipment and reclaim the label cost. Labels can only be voided within a limited window after purchase, so build the void path in from the start rather than treating it as an edge case.

Address and Package Management

Create, view, and manage saved addresses and packaging profiles. This is not recommended for platforms that already manage these entities internally.

Tracking and Validation

Query shipment status and tracking information with shipping.tracking.get_tracking. Validate and classify addresses with address.validation.check before shipping, or validate the addresses already on your orders with validate_order_address.

Reconciliation and Reporting

Search takes filter expressions rather than fixed parameters, so you can ask for exactly the set you want -- unshipped orders older than two days, or every shipment on a given carrier last week -- and page through the results. Relative time filters are evaluated when the query runs, so a saved filter stays correct instead of freezing to the day it was written. For accounting, data exports produce a file rather than a paged response; they run asynchronously and are polled.

How Authorization Works

All UI and API requests are scoped to the Shipper Account that owns the API key. Any labels, addresses, and packages created via the API are also available in the UI, and both environments stay in sync. This means seamless access to created data regardless of the interaction method.

Flexibility in Implementation

The ShipGenius API allows platforms to query and store the full data returned from our GraphQL responses, to retain only select data and direct customers to the ShipGenius UI for management, or to mix the two strategies. All shipment data is persistently stored in our system by default, so replication is optional.

Where Integrations Usually Go Wrong

• Items without dimensions or weight. Everything downstream prices off them.
• Reading the HTTP status instead of the per-order success flag. Bulk order creation returns a result per order, so a response can arrive with no errors and a 200 status while individual orders inside it failed. Each result carries its own success flag and error message; that flag is the real outcome.
• Polling a data export for done without also checking failed. An export that reports done can still have failed, and reading only the done flag hands you an incomplete file with no indication anything went wrong.
• No void path, so cancellations quietly cost money.
• Building against Production instead of Sandbox and buying real labels during testing.

Ready to Integrate?

• Start by reviewing the API reference.
• Register a development app and test against the Sandbox environment.
• Determine whether your integration model is customer-centric or platform-centric.
• Begin implementing key workflows: rates, label purchase, tracking, and reconciliation.

Need help? Email us at development@shipgeni.us.