top of page

OMS / WMS / eCommerce Platform Integration Guide

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

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.


Creating an API Key

To obtain API credentials:

  1. Create a business account at https://lite.shipgeni.us/.

  2. Navigate to the Connected Apps section in your account dashboard.

  3. Create a new app, which will generate:

    • A Development API Key

    • A Production API Key

Note: Keys are environment-specific and will only function in their respective environments.

Request Headers

headers = {
	"Content-Type": "application/json",
	"Authorization": "Bearer YOUR-API-KEY"
}

API Endpoints

Use these endpoints depending on your development or production workflow.


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

  • 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/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:


a. 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.

Note: 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.

b. 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

🔍 Get Rates

Use the getRate query to retrieve real-time shipping rates based on origin, destination, and packaging.


🚚 Create Shipment / Purchase Label

Use the create_shipment mutation to generate and purchase a shipping label.


📦 Bulk Rate & Ship

Use a single mutation to get rates and ship based on delivery requirements (e.g. deliver-by date, time-in-transit).


🧾 Manifests and Voids

  • void_label mutation to cancel a shipment

  • create_manifest to batch shipments for carrier pickup


📬 Address + Package Management

  • Create, view, and manage saved addresses and packaging profiles

  • Not recommended for platforms that already manage these entities internally


🚚 Tracking & Validation

  • Query shipment status and tracking info

  • Address validation and classification via built-in mutation


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 API are also available in the UI

  • Both environments (UI + API) are synced

This means seamless access to created data regardless of the interaction method.


Flexibility in Implementation

The ShipGenius API allows platforms to:

  • Query and store full data returned from our GraphQL responses

  • Only retain select data and direct customers to the ShipGenius UI for management

  • Mix and match the above strategies

All shipment data is persistently stored in our system by default, so replication is optional.

Ready to Integrate?

  1. Start by reviewing the API reference.

  2. Register a development app and test against the sandbox environment.

  3. Determine whether your integration model is customer- or platform-centric.

  4. Begin implementing key workflows (rates, label purchase, tracking, etc).

Need help? Email us at development@shipgeni.us

bottom of page