Testing in the sandbox

The sandbox is a separate deployment of the ShipGenius API with its own database, its own accounts, and its own API keys. It runs the same schema, resolvers, validation and permission checks as production. Build and verify your integration here first.

https://api.sandbox.lite.shipgeni.us/graphql

1. Create a Sandbox Account

Sign up at sandbox.lite.shipgeni.us. It is a separate account from your production one — the two share no data, and credentials from one do not work on the other.

Once you are in, create an app on the Apps page. The app is issued a single key, for the environment that created it — an app created here gets a SANDBOX key, and the same app created on production gets a PRODUCTION key. There is no key to choose between.

2. Confirm the Key Works

Keys are bound to the environment that issued them. A sandbox key sent to the production endpoint is rejected, and a production key sent to the sandbox endpoint is rejected the same way. Both failures return 401.

Run ping before you debug anything else:

query {
    ping {
        name
        permissions
        ip_address
        current_datetime
    }
}

A working key returns your app name and the permissions it was granted. If you get a 401, check that the key and the host belong to the same environment.

3. Fund a Test Balance

Sandbox billing runs against Stripe in test mode. No money moves, and no real payment method is accepted. Add credits on the Billing page using Stripe's test instruments:

Instrument	Value	Result
Card	4242 4242 4242 4242	Succeeds
Card	4000 0000 0000 0002	Declines
Card	4000 0025 0000 3155	Requires 3-D Secure
Bank account	Routing 110000000, account 000123456789	ACH transfer

For cards, use any future expiry date, any CVC, and any postal code.

The declining card is worth spending time on. Label purchase fails on an insufficient balance, and testing that path in the sandbox is cheaper than discovering it in production.

4. Carrier Accounts

Every carrier call from the sandbox goes to that carrier's own test environment — wwwcie.ups.com for UPS, apis-tem.usps.com for USPS, apis-sandbox.fedex.com for FedEx, and the equivalent for the rest.

You can ship without registering anything: UPS, USPS and FedEx fall back to ShipGenius house test accounts. DHL, Passport and UniUni have no house account, so those carriers need credentials of your own.

Register carrier credentials on the Carrier Accounts page. This is a dashboard task, not an API one — there is no operation for it.

Register only carrier test credentials. Production carrier credentials do not authenticate against a carrier's test environment, so they will not work, and the sandbox is a public environment that should not hold your production secrets.

5. What Differs From Production

Requests are slower. Carrier test environments respond more slowly than their production counterparts, and the sandbox runs on smaller infrastructure. Timings measured here are not a guide to production latency.

Labels are not postage. Carrier test environments return labels stamped with a non-shipping watermark. The label is a real artifact produced by a real carrier call, and it cannot be used to ship a parcel.

Rates are synthetic. Carrier test environments return placeholder numbers. Do not use sandbox rates to compare carriers or to model margin.

Rate limits are tighter. See the next section.

Carrier validation is genuine. Addresses, dimensions and service availability are checked by the carrier, not by us. If UPS rejects an address format in the sandbox, it rejects it in production.

6. Rate Limits

Limit	Applies to
60 requests per minute	Each API key, or the calling IP address when no key is present
3 account signups per hour	Each IP address

Exceeding a limit returns 429 with a RATE_LIMIT error code and a Retry-After header in seconds. Wait for the interval the header names; retrying sooner keeps the bucket full and pushes the next allowed request further out.

Reading the schema at /static/schema.gql and reading these docs are not rate limited.

7. Sandbox Data Is Temporary

Sandbox data is disposable and is wiped without notice. Accounts, shipments, labels and carrier registrations can all disappear between sessions.

Write your integration so that it does not depend on a record surviving:

• Create the data each test run needs at the start of that run.
• Store identifiers on your side, and treat a missing record as an expected outcome rather than an error.
• Do not point a continuous integration pipeline at the sandbox and expect it to stay green.

8. The Schema Changes Without Notice

The sandbox runs ahead of production. New fields and fixes appear here first, and a schema change can break a query that worked yesterday.

Fetch the current schema whenever you need to confirm what is deployed:

GET https://api.sandbox.lite.shipgeni.us/static/schema.gql

If a change breaks you, tell us at info@shipgeni.us with the operation you were running. Breakage in the sandbox is the signal working as intended, and we will correct it.

9. Not Available in the Sandbox

• Marketplace integrations. eBay, Shopify and Wix cannot be connected.
• Two-factor authentication. Sandbox accounts are password only.
• Uptime commitments. The sandbox shares infrastructure with our development environment and can be restarted or briefly unavailable during the working day.

10. Moving to Production

An integration built against the sandbox needs two changes to run against production: the endpoint host, and a key issued by production.

https://api.lite.shipgeni.us/graphql

Create the app again on your production account to get that key — a sandbox key is never valid against production.

Everything else — operations, field names, error codes, the extensions payload — is identical.

Setting up the production account itself, including registering live carrier credentials, is dashboard onboarding rather than an integration step, and none of it changes the calls you have already written.