Integrating the ShipGenius API into Your Platform

This guide walks through everything you need to integrate the ShipGenius API into an Order Management System, Warehouse Management System, ERP, or eCommerce platform. It covers authentication, endpoints, rate restrictions, onboarding models, and the key API workflows you'll use day to day.

API Reference

The full GraphQL schema — all queries, mutations, and type definitions — is available at https://lite.shipgeni.us/developer/api-reference. That reference is the authoritative source for field names, input types, and return shapes. This guide covers concepts and workflows; the reference covers the specifics.

Creating an API Key

To get API credentials, create a business account at https://lite.shipgeni.us/ and navigate to the Connected Apps section of your account dashboard. Create a new app and ShipGenius will generate two keys: a Development API Key for use against the sandbox environment, and a Production API Key for live shipments. Keys are environment-specific and will not work outside their respective environment.

Request Headers

All API requests require the following 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 the sandbox endpoint for all development and testing. Switch to the production endpoint only when you're ready to go live.

Legal Restrictions on Carrier Rates

ShipGenius maintains direct carrier contracts with USPS and UPS that provide access to discounted rates under specific pricing programs. These agreements come with strict rules about how those rates can be displayed and used by integrating platforms.

What You Cannot Do

When using ShipGenius carrier credentials, you may not:

• Display a shipping rate higher than the rate field returned by the ShipGenius API.
• Add a margin directly to the returned rate and present that modified amount to the customer.
• Misrepresent the carrier rate in any way that violates USPS or UPS pricing guidelines.

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

What You Can Do

If your platform needs to build in margins or flexible pricing, you have two compliant options:

• Use your own carrier account: Connect UPS, FedEx, or USPS accounts under your own negotiated contracts. You are free to mark up or modify rates on your own credentials.
• Pass the ShipGenius rate through and charge a separate service fee: You may add a clearly itemized handling or service fee at checkout as long as the shipping rate itself is not modified.

For questions about rate presentation or to discuss a custom commercial agreement or white-label structure, contact integrations@shipgeni.us.

Onboarding Models

There are two primary models for how your platform can onboard customers onto ShipGenius.

Customer-Centric Account Creation

Each end user creates their own ShipGenius account and manages their own billing, carrier credentials, API keys, and shipment history. Your platform interacts with the ShipGenius API using each customer's production API key. This model is well suited for platforms similar to EasyPost integrations where each shipper operates independently.

Under this model, customers are billed directly by ShipGenius for each label. Bring-your-own-carrier shipments are charged a flat fee starting at $0.06 per label, which can be tiered based on payment history and weekly shipment volume.

Platform-Centric Billing

The platform holds a single ShipGenius account and routes all rate requests and label creation through its own credentials. The platform pays per-label fees and handles customer billing however it sees fit. This model is a good fit for white-label solutions or flat-rate shipping platforms.

ShipGenius offers tiered pricing for platforms bringing significant volume under this model. Reach out to integrations@shipgeni.us to discuss.

Key API Workflows

Get Rates

Use the getRate query to retrieve real-time shipping rates based on origin address, destination address, and package details. This is typically the first step in a checkout or label creation flow.

Create a Shipment and Purchase a Label

Use the create_shipment mutation to generate and purchase a shipping label. This returns the label file along with tracking information and the final rate charged.

Bulk Rate and Ship

A single mutation handles getting rates and purchasing a label in one step based on delivery requirements such as a deliver-by date or maximum transit time. Useful for high-volume workflows where you want to automatically select the best service.

Void a Label

Use the void_label mutation to cancel a shipment and reverse the label charge. For BYO carrier accounts, the carrier-side void is handled directly with your carrier.

Create a Manifest

Use the create_manifest mutation to batch shipments together for a scheduled carrier pickup. Required for some USPS service types and useful for high-volume UPS operations.

Address and Package Management

ShipGenius provides mutations to create, view, and manage saved addresses and packaging profiles. If your platform already manages these entities internally, you can skip this and pass address and package data inline with each rate or label request.

Tracking and Address Validation

You can query shipment status and tracking information directly through the API. Address validation and classification is also available as a built-in mutation — useful for catching bad addresses before a label is purchased.

How Authorization Works

All API requests are scoped to the ShipGenius account that owns the API key. Labels, addresses, packages, and other data created via the API are also visible in the ShipGenius UI under that account — both environments stay in sync. This means your customers can log into ShipGenius and see everything created through your integration, and vice versa. Replicating data to your own database is optional since ShipGenius stores all shipment data persistently.

Flexibility in Implementation

The ShipGenius API is designed to be flexible. You can query and store the full data returned from GraphQL responses in your own database, rely entirely on the ShipGenius UI for data management and only use the API for label creation, or mix both approaches. There's no requirement to replicate data — use as much or as little of the API surface as your integration needs.

Getting Started

• Review the API reference at https://lite.shipgeni.us/developer/api-reference.
• Register a development app and test against the sandbox environment.
• Decide whether your integration model is customer-centric or platform-centric.
• Implement the key workflows relevant to your platform — rates, label purchase, tracking, and voids are the most common starting points.

For integration support, reach out to development@shipgeni.us.