API Reference — OC Shipping

Authentication

Every request must include your API credentials. Two formats are supported. Credentials are generated in the Account → API Keys section of the web portal.

Method 1 — Explicit Headers (recommended)

X-App-Id: oxc_live_a1b2c3d4e5f6g7h8
X-App-Secret: your_secret_here

Method 2 — Bearer Token

Authorization: Bearer oxc_live_a1b2c3d4e5f6g7h8:your_secret_here

curl example

curl https://app.oxford-chase.com/api/v1/account \
  -H "X-App-Id: oxc_live_a1b2c3d4e5f6g7h8" \
  -H "X-App-Secret: your_secret_here"

Keep your App Secret confidential. It is shown only once at creation time. If compromised, revoke the key and generate a new one from the portal.

App IDs are environment-specific. Production keys begin with oxc_live_; UAT keys begin with oxc_uat_. The suffix is 16 lowercase alphanumeric characters.

Shipment ID Format

All shipment IDs follow the format OCS-YYMM-NNNN-NNNC where YYMM is the two-digit year and month, followed by a sequential number, and a Luhn check digit. Example: OCS-2603-0042-7187. IDs are safe to read over the phone and uniquely identify a shipment. Dashes and spaces are optional in all API calls — OCS26030042187 and OCS 2603 0042 7187 resolve to the same shipment.

Errors

All errors follow a standard envelope:

{
  "error": {
    "code":    "insufficient_balance",
    "message": "Insufficient credit balance to purchase this label"
  }
}

HTTP Status	code	When it occurs
401	`unauthorized`	Missing, invalid, or revoked API credentials; inactive account
402	`insufficient_balance`	Not enough credit to purchase the label
403	`forbidden`	Action not permitted via API
404	`not_found`	Shipment or resource not found
404	`label_not_found`	Label PDF not yet available for this shipment
422	`invalid_request`	Missing or malformed required parameters
422	`carrier_rejected`	Carrier refused the request (invalid address, unsupported route, etc.)
422	`warehouse_not_approved`	The `from.zip` is not an approved sender location for your account — see Create
422	`not_cancellable`	Shipment status does not allow cancellation
422	`carrier_cancel_failed`	Carrier could not cancel (sync cancel only)
503	`carrier_unavailable`	Carrier API is temporarily unreachable

Shipment Statuses

Status	Meaning
`created`	Label purchased and PDF available. Not yet scanned by carrier.
`in_transit`	Carrier has scanned the package and it is moving.
`delivered`	Carrier confirmed delivery.
`cancellation_pending`	Cancel requested asynchronously; refund not yet posted.
`cancelled`	Label voided and credit refunded.
`creating_failed`	Carrier rejected the label request. Credit has been automatically refunded.
`error`	An unexpected error occurred. Contact support if credit was not refunded.

Carriers

Active carriers: gofo, dmx, and uniuni are available. Pass a specific carrier value in quote and create requests to limit results, or omit it to fetch quotes across all configured carriers.

carrier value	Name	Route	Status
`gofo`	GOFO Express	China → US	Active
`dmx`	DMX Smart	US domestic (supported origin lanes only)	Active
`uniuni`	UniUni	US domestic	Active

GET/shipments

List your account's shipments. Supports filtering and pagination.

Query Parameters

Parameter		Description
`status`	optional	Filter by status (e.g. `created`, `in_transit`, `delivered`)
`carrier`	optional	Filter by carrier (e.g. `gofo`)
`from_date`	optional	Start date — `YYYY-MM-DD`
`to_date`	optional	End date — `YYYY-MM-DD`
`reference`	optional	Filter by your reference ID (exact match)
`page`	optional	Page number (default: 1)
`per_page`	optional	Results per page (default: 50, max: 100)

Response

{
  "shipments": [
    {
      "ocs_id":          "OCS-2603-0042-7187",
      "tracking_number": "GOFO123456789US",
      "carrier":         "gofo",
      "service":         "GOFO Parcel Pickup",
      "status":          "in_transit",
      "reference":       "ORDER-8821",
      "cost_cents":      1580,
      "created_at":      "2026-03-20T14:32:00Z"
    }
  ],
  "total_count":      42,
  "total_cost_cents": 66360,
  "page":             1,
  "per_page":         50
}

curl example

curl "https://app.oxford-chase.com/api/v1/shipments?status=in_transit&from_date=2026-03-01" \
  -H "X-App-Id: oxc_live_a1b2c3d4e5f6g7h8" \
  -H "X-App-Secret: your_secret_here"

POST/shipments/quote

Get rate quotes for a shipment. No label is created and no charge is made.

Request Body

Field		Type	Description
`from`	required	object	Shipper address — see address fields below
`to`	required	object	Recipient address — see address fields below
`dimensions`	required	object	Package dimensions — see fields below
`carrier`	optional	string	Filter to a specific carrier. Omit to get all available quotes.

Address Object Fields (from / to)

Field		Description
`name`	required	Full name or company name
`phone`	required	Phone number
`street1`	required	Street address line 1
`street2`	optional	Street address line 2 (apt, suite, etc.)
`city`	required	City
`state`	required	State/province code (e.g. `CA`, `TX`)
`zip`	required	ZIP / postal code
`country`	required	ISO country code (e.g. `US`, `CN`)

Dimensions Object Fields

Field		Description
`length`	required	Length in inches
`width`	required	Width in inches
`height`	required	Height in inches
`weight_oz`	required	Weight in ounces

Response

[
  {
    "carrier":    "gofo",
    "service":    "GOFO Parcel Pickup",
    "rate_cents": 1580,
    "currency":   "USD",
    "est_days":   7
  }
]

curl example

curl -X POST https://app.oxford-chase.com/api/v1/shipments/quote \
  -H "X-App-Id: oxc_live_a1b2c3d4e5f6g7h8" \
  -H "X-App-Secret: your_secret_here" \
  -H "Content-Type: application/json" \
  -d '{
    "from": {
      "name": "Oxford Chase Shipping",
      "phone": "4045550100",
      "street1": "2875 N Berkeley Lake Rd NW",
      "street2": "Suite 12",
      "city": "Duluth",
      "state": "GA",
      "zip": "30096",
      "country": "US"
    },
    "to": {
      "name": "Jane Smith",
      "phone": "2125550199",
      "street1": "456 Park Ave",
      "city": "New York",
      "state": "NY",
      "zip": "10022",
      "country": "US"
    },
    "dimensions": {
      "length": 12,
      "width": 8,
      "height": 4,
      "weight_oz": 32
    }
  }'

Possible errors

invalid_request — missing required field
carrier_unavailable — carrier API unreachable

POST/shipments/create

Purchase a shipping label. Credit is debited immediately. Returns the label URL and remaining balance.

Sender ZIP validation: The from.zip must match either an Oxford Chase warehouse location or a location approved for your account. Quotes (POST /quote) are unrestricted — only label creation enforces this check. Invalid ZIPs return 422 warehouse_not_approved. View your approved sender ZIPs on the My Account page under Oxford Chase Warehouses and Your Locations.

Request Body

Field		Type	Description
`from`	required	object	Shipper address (same fields as quote)
`to`	required	object	Recipient address
`dimensions`	required	object	Package dimensions
`carrier`	required	string	Carrier code — e.g. `"gofo"`, `"dmx"`, or `"uniuni"`
`service`	required	string	Service name returned by quote — e.g. `"GOFO Parcel Pickup"`, `"USPSGA-ZIHUI-91745"`, or `"domestic"`
`reference`	optional	string	Your internal order/reference ID. Searchable on the shipments list.
`metadata`	optional	object	Arbitrary JSON data stored with the shipment and returned in GET responses. Two keys have special meaning: `label_reference` prints in the Reference field on the label face (overrides `reference`); `label_sku` prints below the barcode (SKU / product info).
`items`	optional	array	Package item details sent to the carrier (GOFO and DMX only). If omitted, a default "General Merchandise" declaration is used. Each object: `name_en` (string, required per item), `name_zh` (string), `sku` (string), `qty` (integer), `unit_value` (decimal, USD), `unit_weight_oz` (decimal).

Response 201 Created

{
  "ocs_id":          "OCS-2603-0042-7187",
  "tracking_number": "GOFO123456789US",
  "carrier_order_number": "GOFO-ORDER-8821",
  "carrier":         "gofo",
  "service":         "GOFO Parcel Pickup",
  "cost_cents":      1580,
  "currency":        "USD",
  "balance_cents":   48420,
  "label_url":       "https://app.oxford-chase.com/api/v1/shipments/OCS-2603-0042-7187/label",
  "status":          "created",
  "created_at":      "2026-03-26T14:32:00Z"
}

curl example

curl -X POST https://app.oxford-chase.com/api/v1/shipments/create \
  -H "X-App-Id: oxc_live_a1b2c3d4e5f6g7h8" \
  -H "X-App-Secret: your_secret_here" \
  -H "Content-Type: application/json" \
  -d '{
    "from": {
      "name": "Oxford Chase Shipping",
      "phone": "4045550100",
      "street1": "2875 N Berkeley Lake Rd NW",
      "street2": "Suite 12",
      "city": "Duluth",
      "state": "GA",
      "zip": "30096",
      "country": "US"
    },
    "to": {
      "name": "Jane Smith",
      "phone": "2125550199",
      "street1": "456 Park Ave",
      "city": "New York",
      "state": "NY",
      "zip": "10022",
      "country": "US"
    },
    "dimensions": { "length": 12, "width": 8, "height": 4, "weight_oz": 32 },
    "carrier": "gofo",
    "service": "GOFO Parcel Pickup",
    "reference": "ORDER-8821",
    "metadata": {
      "label_reference": "PO-98821",
      "label_sku":       "SKU-WIDGET-XL",
      "warehouse_bin":   "A-14"
    },
    "items": [
      { "name_en": "T-Shirt", "name_zh": "T恤", "sku": "SKU-001", "qty": 2, "unit_value": 15.00, "unit_weight_oz": 4.0 },
      { "name_en": "Hat",     "name_zh": "帽子", "sku": "SKU-002", "qty": 1, "unit_value": 12.00, "unit_weight_oz": 2.0 }
    ]
  }'

Possible errors

invalid_request — missing required field
insufficient_balance — not enough credit
warehouse_not_approved — from.zip is not an approved sender location for your account
carrier_rejected — carrier refused the request (check addresses and dimensions)
carrier_unavailable — carrier API unreachable

GET/shipments/:ocs_id

Retrieve full details for a single shipment.

Path Parameter

Parameter		Description
`ocs_id`	required	Any one of: OCS Shipping ID (e.g. `OCS-2603-0042-7187`), carrier tracking number (e.g. USPS/GOFO/UniUni tracking number), or carrier order number (e.g. DMX shipment ID). OCS ID is preferred — use tracking/order number when you don't have it.

Response

{
  "ocs_id":          "OCS-2603-0042-7187",
  "tracking_number": "GOFO123456789US",
  "carrier_order_number": "GOFO-ORDER-8821",
  "carrier":         "gofo",
  "service":         "GOFO Parcel Pickup",
  "status":          "in_transit",
  "reference":       "ORDER-8821",
  "cost_cents":      1580,
  "created_at":      "2026-03-26T14:32:00Z",
  "updated_at":      "2026-03-27T09:10:00Z",
  "from_address":    { "name": "Oxford Chase Warehouse", "street1": "123 Logistics Blvd", ... },
  "to_address":      { "name": "Jane Smith", "street1": "456 Park Ave", ... },
  "dimensions":      { "length": 12, "width": 8, "height": 4, "weight_oz": 32 },
  "label_url":       "https://app.oxford-chase.com/api/v1/shipments/OCS-2603-0042-7187/label",
  "tracking_events": [ { "timestamp": "2026-03-27T09:10:00Z", "description": "In transit — Los Angeles, CA", "event_code": "201" } ],
  "metadata":        { "sku": "WIDGET-XL", "warehouse_bin": "A-14" }
}

curl example

curl https://app.oxford-chase.com/api/v1/shipments/OCS-2603-0042-7187 \
  -H "X-App-Id: oxc_live_a1b2c3d4e5f6g7h8" \
  -H "X-App-Secret: your_secret_here"

GET/shipments/:ocs_id/label

Download the label PDF. Returns a 302 redirect to a signed download URL — pass -L in curl or enable redirect-following in your HTTP client.

The :ocs_id segment accepts an OCS Shipping ID, carrier tracking number, or carrier order number — same as Get Shipment.

Response

302 redirect to a time-limited signed URL for the PDF file.

curl example

curl -L -o label.pdf \
  https://app.oxford-chase.com/api/v1/shipments/OCS-2603-0042-7187/label \
  -H "X-App-Id: oxc_live_a1b2c3d4e5f6g7h8" \
  -H "X-App-Secret: your_secret_here"

Possible errors

label_not_found — PDF not yet generated for this shipment
not_found — shipment does not exist

GET/shipments/:ocs_id/tracking

Get the latest tracking status and event history. Events are refreshed automatically every 30 minutes. Use last_tracked_at to check data freshness.

The :ocs_id segment accepts an OCS Shipping ID, carrier tracking number, or carrier order number — same as Get Shipment.

Response

{
  "ocs_id":               "OCS-2603-0042-7187",
  "tracking_number":      "GOFO123456789US",
  "carrier_order_number": "GOFO-ORDER-8821",
  "carrier":              "gofo",
  "status":               "in_transit",
  "last_tracked_at":      "2026-03-27T09:15:00Z",
  "tracking_events": [
    { "timestamp": "2026-03-26T18:00:00Z", "description": "Departed origin facility",        "event_code": "100" },
    { "timestamp": "2026-03-27T09:10:00Z", "description": "In transit — Los Angeles, CA",    "event_code": "201" }
  ]
}

curl example

curl https://app.oxford-chase.com/api/v1/shipments/OCS-2603-0042-7187/tracking \
  -H "X-App-Id: oxc_live_a1b2c3d4e5f6g7h8" \
  -H "X-App-Secret: your_secret_here"

POST/shipments/:ocs_id/cancel

Cancel a label and refund the charge to your credit balance. Only shipments in created or in_transit status can be cancelled.

The :ocs_id segment accepts an OCS Shipping ID, carrier tracking number, or carrier order number — use whichever identifier you have available.

By default, cancellation is asynchronous — the request is queued and processed in the background. The shipment transitions to cancellation_pending and the refund posts shortly after. Pass sync=true to cancel synchronously and receive the refund amount in the response immediately.

Query Parameters

Parameter		Description
`sync`	optional	Pass `true` to cancel synchronously. Default: async.

Response — Async (default)

{
  "ocs_id":         "OCS-2603-0042-7187",
  "status":         "cancellation_pending",
  "refunded_cents": null
  // Poll GET /shipments/:ocs_id until status == "cancelled" for refund confirmation
}

Response — Sync (?sync=true)

{
  "ocs_id":         "OCS-2603-0042-7187",
  "status":         "cancelled",
  "refunded_cents": 1580,
  "balance_cents":  50000
}

curl examples

# Async (default)
curl -X POST https://app.oxford-chase.com/api/v1/shipments/OCS-2603-0042-7187/cancel \
  -H "X-App-Id: oxc_live_a1b2c3d4e5f6g7h8" \
  -H "X-App-Secret: your_secret_here"

# Sync — refund confirmed in response
curl -X POST "https://app.oxford-chase.com/api/v1/shipments/OCS-2603-0042-7187/cancel?sync=true" \
  -H "X-App-Id: oxc_live_a1b2c3d4e5f6g7h8" \
  -H "X-App-Secret: your_secret_here"

Possible errors

not_cancellable — shipment is not in a cancellable status
carrier_cancel_failed — carrier refused the cancel (sync only)
carrier_unavailable — carrier API unreachable (sync only)

GET/account

Retrieve your account information, current credit balance, and recent transaction history.

Response

{
  "account": {
    "name":               "Acme Imports LLC",
    "rate_tier":          "silver",
    "billing_mode":       "prepaid",
    "credit_limit_cents": 0
    // credit_limit_cents is relevant for credit_line billing mode
  },
  "balance_cents":  48420,
  "currency":       "USD",
  "recent_transactions": [
    {
      "id":               101,
      "amount_cents":     -1580,
      "transaction_type": "label_purchase",
      "memo":             "Label OCS-2603-0042-7187",
      "created_at":       "2026-03-26T14:32:00Z"
    },
    {
      "id":               100,
      "amount_cents":     50000,
      "transaction_type": "top_up",
      "memo":             "Credit top-up",
      "created_at":       "2026-03-25T10:00:00Z"
    }
  ]
}

Rate tiers

rate_tier	Description
`bronze`	Standard rate
`silver`	Volume rate
`gold`	Premium negotiated rate
`custom`	Custom rate — contact Oxford Chase for details

Billing modes

billing_mode	Description
`prepaid`	Balance must be positive before purchasing labels. Top up via the portal.
`credit_line`	Balance can go negative up to `credit_limit_cents`. Invoiced periodically.

curl example

curl https://app.oxford-chase.com/api/v1/account \
  -H "X-App-Id: oxc_live_a1b2c3d4e5f6g7h8" \
  -H "X-App-Secret: your_secret_here"

Changelog

All notable API changes. Non-breaking additions (new optional fields, new endpoints) do not increment the version.

Date	Version	Change
2026-04-26	v1	Enhanced tracking response. `GET /shipments/:ocs_id/tracking` now returns two additional top-level fields: `carrier_order_number` (useful for DMX shipments where the USPS tracking number may be blank on fresh labels) and `last_tracked_at` (ISO8601 timestamp of the last background poll — use this to gauge data freshness). Each event in `tracking_events` now includes an `event_code` field: the carrier-native semantic code (e.g. `"201"` for GOFO, `"O12"` for DMX, `"DELIVERED"` for UniUni). Use this for programmatic status detection without string-matching descriptions. Events are now returned in chronological order (oldest first) for all carriers.
2026-04-25	v1	Flexible shipment lookup. The `:ocs_id` path segment on `GET /shipments/:ocs_id`, `/label`, `/tracking`, and `POST /cancel` now accepts a carrier tracking number or carrier order number in addition to the OCS Shipping ID. Useful when you have the carrier-assigned tracking number but not the OCS ID. Enhanced cancellation resilience. The cancel endpoint now automatically tries all available carrier identifiers (DMX supports cancel by shipment ID, USPS tracking number, or reference ID; UniUni falls back to an internal order number if the tracking-number path is unavailable).
2026-04-22	v1	Added the `uniuni` carrier to the active carrier list and updated UAT notes to reflect carrier-specific test lanes. `POST /shipments/create` now returns `carrier_order_number` when available, and shipment detail examples now document that field. For UniUni, `carrier_order_number` may be blank when the carrier response does not include a distinct order identifier.
2026-04-10	v1	Newly created App IDs are now environment-specific: production uses `oxc_live_`, UAT uses `oxc_uat_`, and both formats use a 16-character lowercase alphanumeric suffix. UAT examples and notes now reflect the current GOFO UAT test lane: ship-from ZIP `90058` and ship-to ZIP `36804`.
2026-03-26	v1	Initial release. Endpoints: list shipments, quote, create, get, label, tracking, cancel, account. Cancel supports `?sync=true` for immediate refund confirmation. Account response includes `credit_limit_cents`.
2026-04-05	v1	Sender ZIP validation on label create. `POST /shipments/create` now requires `from.zip` to match either an Oxford Chase warehouse location or a location approved for your account. Unapproved ZIPs return `422 warehouse_not_approved`. Quotes (`POST /shipments/quote`) remain unrestricted. View your approved sender ZIPs on the My Account page. The Oxford Chase ATL warehouse (ZIP 30096, Duluth GA) is available to all accounts automatically.
2026-03-27	v1	Added `creating_failed` and `error` shipment statuses. `creating_failed`: carrier rejected label — credit is automatically refunded. `error`: unexpected failure — contact support if credit was not refunded. Shipment IDs migrated to human-readable format `OCS-YYMM-NNNN-NNNC`. Existing `ocs_` IDs remain valid. Added `metadata.label_reference` (prints in the Reference field on the label face) and `metadata.label_sku` (prints below the barcode). Both are optional — `label_reference` falls back to `reference` if omitted.

Breaking changes will always be introduced as a new API version (/api/v2/) with advance notice by email.