GraphQL Interface - Open Logistics Specification

The specification has two interfaces over one object model:

Interface	For	Covers	Endpoint
REST Interface	Integrators: shippers, platforms, partners, devices and agents	Each module’s public workflows and actions: rate, purchase, void, book, close, track, inject, generate, verify	`https://{host}/v1/…`, in the REST Interface tab
GraphQL Interface	Internal tools: implementer dashboards, operations consoles, carrier and network member administration, data teams	CRUD over every domain object (shipments, trackers, pickups, manifests, products, fleet, routes, catalog, invoices…), plus the back-office operations that exist only here	`POST https://{host}/graphql`

Both interfaces return the same canonical objects with the same field names, IDs, enums and metadata namespaces. A Shipment from query { shipment(id:) } is the object GET /v1/shipments/{id} returns. CRUD operations available on both interfaces behave identically: same validation, same state rules, same events.

Conventions

Authentication and scopes are the same as REST (Conventions §3): Authorization: Bearer …, Shipping-Version, and Shipping-Account to act for a connected or member account. Each field requires the scope of its REST counterpart (shipments:write for createShipment, catalog:write for createService).
Idempotency. Mutations that create or act accept the Idempotency-Key header, with the same rules as Conventions §8. Fields that spend money are flagged on their page.
Errors use the standard GraphQL errors[], and extensions carries the REST error object: extensions.type, extensions.code (the Conventions §9 registry), extensions.param, extensions.request_id.
Lists return { data, has_more } with limit, startingAfter and endingBefore arguments, mirroring REST cursor pagination.
Events. Mutations emit the same webhook events as their REST counterparts. Subscribing over GraphQL (subscription { events(types: […]) }) is an optional capability (graphql.subscriptions).
Schema. The full SDL is published at graphql/schema.graphql, and implementers SHOULD serve introspection to authenticated clients.

Every field below has its own page with arguments, return fields and request, variables and response examples. Module chapters describe the behavior.

Accounts

Field	Kind	What it does
`accounts`	query	List accounts
`createAccount`	mutation	Create a child account
`account`	query	Retrieve a Account
`updateAccount`	mutation	Update a Account
`accountGet`	query	Retrieve the current account
`suspendAccount`	mutation	Suspend an account
`reactivateAccount`	mutation	Reactivate an account
`closeAccount`	mutation	Close an account
`identityProviders`	query	List identity providers
`createIdentityProvider`	mutation	Register an identity provider
`identityProvider`	query	Retrieve a IdentityProvider
`updateIdentityProvider`	mutation	Update a IdentityProvider
`deleteIdentityProvider`	mutation	Delete a IdentityProvider
`verifyDomainIdentityProvider`	mutation	Verify a domain
`testIdentityProvider`	mutation	Test sign-in
`memberships`	query	List memberships
`membership`	query	Retrieve a Membership
`updateMembership`	mutation	Update a Membership
`deleteMembership`	mutation	Delete a Membership
`invitations`	query	List invitations
`createInvitation`	mutation	Invite a member
`invitation`	query	Retrieve a Invitation
`revokeInvitation`	mutation	Revoke an invitation
`roles`	query	List roles
`createRole`	mutation	Create a custom role
`role`	query	Retrieve a Role
`updateRole`	mutation	Update a Role
`deleteRole`	mutation	Delete a Role
`apiKeys`	query	List api keys
`createApiKey`	mutation	Create an API key
`apiKey`	query	Retrieve a ApiKey
`updateApiKey`	mutation	Update a ApiKey
`deleteApiKey`	mutation	Delete a ApiKey
`rollApiKey`	mutation	Roll an API key

Apps

Field	Kind	What it does
`apps`	query	List apps
`createApp`	mutation	Register a carrier OAuth app
`app`	query	Retrieve a App
`updateApp`	mutation	Update a App
`deleteApp`	mutation	Delete a App
`rotateSecretApp`	mutation	Rotate a dynamic app’s client secret

Batches

Field	Kind	What it does
`createBatche`	mutation	Create a batch
`batche`	query	Retrieve a batch

Billing

Field	Kind	What it does
`invoices`	query	List invoices
`invoice`	query	Retrieve a Invoice
`usageRecords`	query	List usage records
`createUsageRecord`	mutation	Report usage
`usageRecord`	query	Retrieve a UsageRecord
`usageSummaries`	query	Usage summary per meter
`balance`	query	Retrieve the prepaid balance
`balanceTransactions`	query	List balance transactions
`paymentMethods`	query	List payment methods
`paymentMethod`	query	Retrieve a PaymentMethod
`deletePaymentMethod`	mutation	Delete a PaymentMethod
`payments`	query	List payments
`payment`	query	Retrieve a Payment
`createInvoice`	mutation	Create a draft invoice
`updateInvoice`	mutation	Update a Invoice
`finalizeInvoice`	mutation	Invoice: finalize
`sendInvoice`	mutation	Invoice: send
`voidInvoice`	mutation	Invoice: void
`markUncollectibleInvoice`	mutation	Invoice: mark_uncollectible
`importInvoice`	mutation	Import invoices from a file
`reconciliations`	query	List reconciliations
`createReconciliation`	mutation	Reconcile an invoice
`reconciliation`	query	Retrieve a Reconciliation
`resolveReconciliation`	mutation	Resolve a reconciliation line
`meters`	query	List meters
`createMeter`	mutation	Create a meter
`meter`	query	Retrieve a Meter
`updateMeter`	mutation	Update a Meter
`pricePlans`	query	List price plans
`createPricePlan`	mutation	Create a price plan
`pricePlan`	query	Retrieve a PricePlan
`updatePricePlan`	mutation	Update a PricePlan
`billingProfile`	query	Retrieve the billing profile
`updateBillingProfile`	mutation	Update the billing profile
`refundPayment`	mutation	Refund a payment
`reconcileStatementPayment`	mutation	Reconcile an ISO 20022 camt.053 statement
`payouts`	query	List payouts
`payout`	query	Retrieve a Payout

Carriers

Field	Kind	What it does
`carriers`	query	List carriers
`carrier`	query	Retrieve a carrier

Catalog

Field	Kind	What it does
`createServiceAvailability`	mutation	Check serviceability
`services`	query	List services
`createService`	mutation	Create a service
`service`	query	Retrieve a CatalogService
`updateService`	mutation	Update a CatalogService
`deleteService`	mutation	Delete a draft service
`publishService`	mutation	Publish a service
`serviceVersions`	query	List service versions
`options`	query	List options
`createOption`	mutation	Create a option
`option`	query	Retrieve a CatalogOption
`updateOption`	mutation	Update a CatalogOption
`deleteOption`	mutation	Delete a draft option
`publishOption`	mutation	Publish a option
`optionVersions`	query	List option versions
`packagings`	query	List packagings
`createPackaging`	mutation	Create a packaging
`packaging`	query	Retrieve a Packaging
`updatePackaging`	mutation	Update a Packaging
`deletePackaging`	mutation	Delete a draft packaging
`publishPackaging`	mutation	Publish a packaging
`packagingVersions`	query	List packaging versions
`zones`	query	List zones
`createZone`	mutation	Create a zone
`zone`	query	Retrieve a Zone
`updateZone`	mutation	Update a Zone
`deleteZone`	mutation	Delete a draft zone
`publishZone`	mutation	Publish a zone
`zoneVersions`	query	List zone versions
`matchZone`	mutation	Match an address to zones

Connections

Field	Kind	What it does
`connections`	query	List connections
`createConnection`	mutation	Create a credentials-based connection
`connection`	query	Retrieve a Connection
`updateConnection`	mutation	Update a Connection
`deleteConnection`	mutation	Delete a Connection
`createConnectSession`	mutation	Start an OAuth/OIDC connect flow
`connectSession`	query	Retrieve a connect session

Consolidation

Field	Kind	What it does
`consolidations`	query	List consolidations
`createConsolidation`	mutation	Create a consolidation
`consolidation`	query	Retrieve a Consolidation
`updateConsolidation`	mutation	Update a Consolidation
`addConsolidation`	mutation	Consolidation: add
`removeConsolidation`	mutation	Consolidation: remove
`closeConsolidation`	mutation	Consolidation: close
`sealConsolidation`	mutation	Consolidation: seal
`breakSealConsolidation`	mutation	Consolidation: break_seal
`loadConsolidation`	mutation	Consolidation: load
`unloadConsolidation`	mutation	Consolidation: unload
`deconsolidateConsolidation`	mutation	Consolidation: deconsolidate
`labelConsolidation`	mutation	Generate a consolidation label
`consolidationContents`	query	List contents
`conveyances`	query	List conveyances
`createConveyance`	mutation	Create a conveyance
`conveyance`	query	Retrieve a Conveyance
`updateConveyance`	mutation	Update a Conveyance
`closeConveyance`	mutation	Conveyance: close
`departConveyance`	mutation	Conveyance: depart
`arriveConveyance`	mutation	Conveyance: arrive
`cancelConveyance`	mutation	Conveyance: cancel
`conveyanceManifest`	query	Conveyance manifest

Data Network

Field	Kind	What it does
`participants`	query	List participants
`createParticipant`	mutation	Register a participant (DID)
`participant`	query	Retrieve a Participant
`records`	query	List records
`createRecord`	mutation	Write a record
`anchor`	query	Retrieve an anchor
`accessGrants`	query	List access grants
`createAccessGrant`	mutation	Grant access
`accessGrant`	query	Retrieve a AccessGrant
`attestations`	query	List attestations
`createAttestation`	mutation	Create an attestation
`attestation`	query	Retrieve a Attestation
`createDataset`	mutation	Create a dataset extract
`timeline`	query	End-to-end timeline
`createIdentifierLink`	mutation	Link identifiers
`milestoneDefinition`	query	Milestone definition set
`accessPolicies`	query	List access policies
`createAccessPolicy`	mutation	Create an access policy
`accessPolicy`	query	Retrieve a AccessPolicy
`updateAccessPolicy`	mutation	Update a AccessPolicy

Document Uploads

Field	Kind	What it does
`documentUploads`	query	List document uploads
`createDocumentUpload`	mutation	Submit customs documents to a carrier
`documentUpload`	query	Retrieve a DocumentUpload
`updateDocumentUpload`	mutation	Update a DocumentUpload

Events

Field	Kind	What it does
`events`	query	List events
`event`	query	Retrieve an event

Files

Field	Kind	What it does
`files`	query	List files
`createFile`	mutation	Upload a file
`file`	query	Retrieve a File
`deleteFile`	mutation	Delete a File

Fleet

Field	Kind	What it does
`routeRunPositions`	query	List positions
`createRouteRunPosition`	mutation	Report positions
`vehicles`	query	List vehicles
`createVehicle`	mutation	Create a vehicle
`vehicle`	query	Retrieve a Vehicle
`updateVehicle`	mutation	Update a Vehicle
`deleteVehicle`	mutation	Delete a Vehicle
`vehiclePosition`	query	Latest vehicle position
`drivers`	query	List drivers
`createDriver`	mutation	Create a driver
`driver`	query	Retrieve a Driver
`updateDriver`	mutation	Update a Driver
`deleteDriver`	mutation	Delete a Driver
`optimizations`	query	List optimizations
`createOptimization`	mutation	Optimize runs
`optimization`	query	Retrieve a Optimization
`commitOptimization`	mutation	Commit proposed runs

Inbound

Field	Kind	What it does
`inboundEvents`	query	List inbound events
`createInboundEvent`	mutation	Inject canonical events
`inboundEvent`	query	Retrieve a InboundEvent

Injection

Field	Kind	What it does
`asns`	query	List asns
`createAsn`	mutation	Create an advance shipping notice
`asn`	query	Retrieve a Asn
`updateAsn`	mutation	Update a Asn

Integrations

Field	Kind	What it does
`integrations`	query	List integrations
`integration`	query	Retrieve an integration
`createAddressValidation`	mutation	Validate an address
`addressValidation`	query	Retrieve an address validation
`createInsuranceQuote`	mutation	Quote insurance
`coverages`	query	List coverages
`createCoverage`	mutation	Buy coverage
`coverage`	query	Retrieve a Coverage
`claims`	query	List claims
`createClaim`	mutation	Submit a claim
`claim`	query	Retrieve a Claim
`updateClaim`	mutation	Update a Claim
`createIntegration`	mutation	Onboard a federated provider

Inventory

Field	Kind	What it does
`fulfillmentOrders`	query	List fulfillment orders
`createFulfillmentOrder`	mutation	Create a fulfillment order
`searchFulfillmentOrders`	query	Search fulfillment orders
`fulfillmentOrder`	query	Retrieve a FulfillmentOrder
`updateFulfillmentOrder`	mutation	Update a FulfillmentOrder
`storageLocations`	query	List storage locations
`createStorageLocation`	mutation	Create a storage location
`storageLocation`	query	Retrieve a StorageLocation
`updateStorageLocation`	mutation	Update a StorageLocation
`deleteStorageLocation`	mutation	Delete a StorageLocation
`importStorageLocation`	mutation	Import a facility layout
`thresholdsInventory`	mutation	Set low-stock thresholds
`stock`	query	List stock
`stockGet`	query	Retrieve a Stock
`stockMovements`	query	List stock movements
`createStockMovement`	mutation	Record a stock movement
`stockMovement`	query	Retrieve a StockMovement
`allocateFulfillmentOrder`	mutation	Fulfillment order: allocate
`releaseToPickFulfillmentOrder`	mutation	Fulfillment order: release_to_pick
`packFulfillmentOrder`	mutation	Fulfillment order: pack
`shipFulfillmentOrder`	mutation	Ship a fulfillment order
`waves`	query	List waves
`createWave`	mutation	Release a wave
`wave`	query	Retrieve a Wave
`inventoryCounts`	query	List inventory counts
`createInventoryCount`	mutation	Start a count
`inventoryCount`	query	Retrieve a InventoryCount
`linesInventoryCount`	mutation	Add count lines
`completeInventoryCount`	mutation	Complete a count

IoT

Field	Kind	What it does
`deviceEvents`	query	List device events
`createDeviceEvent`	mutation	Ingest device events
`devices`	query	List devices
`createDevice`	mutation	Register a device
`device`	query	Retrieve a Device
`updateDevice`	mutation	Update a Device
`deleteDevice`	mutation	Delete a Device
`certificateDevice`	mutation	Issue a device certificate
`tokenDevice`	mutation	Issue a device token
`attachDevice`	mutation	Attach a device
`detachDevice`	mutation	Detach a device
`deactivateDevice`	mutation	Deactivate a device

Jobs

Field	Kind	What it does
`jobs`	query	List jobs
`createJob`	mutation	Start a job
`job`	query	Retrieve a Job
`jobSchedules`	query	List job schedules
`createJobSchedule`	mutation	Create a job schedule
`jobSchedule`	query	Retrieve a JobSchedule
`updateJobSchedule`	mutation	Update a JobSchedule
`deleteJobSchedule`	mutation	Delete a JobSchedule
`pauseJobSchedule`	mutation	Job schedule: pause
`resumeJobSchedule`	mutation	Job schedule: resume
`runNowJobSchedule`	mutation	Job schedule: run_now

Manifests

Field	Kind	What it does
`manifests`	query	List manifests
`createManifest`	mutation	Create (close out) one or more manifests
`manifest`	query	Retrieve a Manifest
`updateManifest`	mutation	Update a Manifest

Network

Field	Kind	What it does
`networkMembers`	mutation	List a carrier member
`pauseMember`	mutation	Pause a carrier member
`delistMember`	mutation	Delist a carrier member
`interlineAgreements`	query	List interline agreements
`createInterlineAgreement`	mutation	Propose an interline agreement
`interlineAgreement`	query	Retrieve a InterlineAgreement
`updateInterlineAgreement`	mutation	Update a InterlineAgreement
`signInterlineAgreement`	mutation	Sign an interline agreement
`suspendInterlineAgreement`	mutation	Suspend an interline agreement
`terminateInterlineAgreement`	mutation	Terminate an interline agreement
`ledgerEntries`	query	List ledger entries
`ledgerEntry`	query	Retrieve a LedgerEntry
`settlements`	query	List settlements
`settlement`	query	Retrieve a Settlement
`closeSettlement`	mutation	Close a settlement
`disputeSettlement`	mutation	Dispute settlement entries
`serviceLevels`	query	List service levels
`createServiceLevel`	mutation	Define a service level
`serviceLevel`	query	Retrieve a NetworkServiceLevel
`updateServiceLevel`	mutation	Update a NetworkServiceLevel
`deleteServiceLevel`	mutation	Delete a NetworkServiceLevel

Pickup Schedules

Field	Kind	What it does
`pickupSchedules`	query	List pickup schedules
`createPickupSchedule`	mutation	Create a pickup schedule
`pickupSchedule`	query	Retrieve a PickupSchedule
`updatePickupSchedule`	mutation	Update a PickupSchedule

Pickups

Field	Kind	What it does
`pickups`	query	List pickups
`createPickup`	mutation	Book a pickup
`searchPickups`	query	Search pickups
`pickup`	query	Retrieve a Pickup
`updatePickup`	mutation	Update a Pickup

Pricing

Field	Kind	What it does
`rateSheets`	query	List rate sheets
`createRateSheet`	mutation	Create a rate sheet
`rateSheet`	query	Retrieve a RateSheet
`updateRateSheet`	mutation	Update a RateSheet
`deleteRateSheet`	mutation	Delete a draft rate sheet
`publishRateSheet`	mutation	Publish a rate sheet
`simulateRateSheet`	mutation	Simulate prices
`rateSheetVersions`	query	List rate sheet versions
`importRateSheet`	mutation	Import a rate sheet
`rateSheetExport`	query	Export a rate sheet
`surcharges`	query	List surcharges
`createSurcharge`	mutation	Create a surcharge
`surcharge`	query	Retrieve a Surcharge
`updateSurcharge`	mutation	Update a Surcharge
`deleteSurcharge`	mutation	Delete a Surcharge
`scheduleSurcharge`	mutation	Add a schedule entry
`pricingRules`	query	List pricing rules
`createPricingRule`	mutation	Create a pricing rule
`pricingRule`	query	Retrieve a PricingRule
`updatePricingRule`	mutation	Update a PricingRule
`deletePricingRule`	mutation	Delete a PricingRule

Products

Field	Kind	What it does
`products`	query	List products
`createProduct`	mutation	Create a product
`searchProducts`	query	Search products
`product`	query	Retrieve a Product
`updateProduct`	mutation	Update a Product
`deleteProduct`	mutation	Delete an unreferenced product

Rates

Field	Kind	What it does
`createRate`	mutation	Get live rates
`rateQuote`	query	Retrieve a rate quote

Routes

Field	Kind	What it does
`facilities`	query	List facilities
`createFacility`	mutation	Create a facility
`facility`	query	Retrieve a Facility
`updateFacility`	mutation	Update a Facility
`deleteFacility`	mutation	Delete a Facility
`routes`	query	List routes
`createRoute`	mutation	Create a route
`route`	query	Retrieve a Route
`updateRoute`	mutation	Update a Route
`deleteRoute`	mutation	Delete a Route
`activateRoute`	mutation	Activate a route
`deactivateRoute`	mutation	Deactivate a route
`createRouteStop`	mutation	Insert a stop
`updateRouteStop`	mutation	Update a stop
`deleteRouteStop`	mutation	Remove a stop
`reorderRouteStop`	mutation	Reorder stops
`routeLegs`	query	List legs
`updateRouteLeg`	mutation	Update a leg
`routeRuns`	query	List route runs
`createRouteRun`	mutation	Create a route run
`routeRun`	query	Retrieve a RouteRun
`updateRouteRun`	mutation	Update a RouteRun
`dispatchRouteRun`	mutation	Dispatch a route run
`startRouteRun`	mutation	Start a route run
`completeRouteRun`	mutation	Complete a route run
`cancelRouteRun`	mutation	Cancel a route run
`assignRouteRun`	mutation	Assign a route run
`unassignRouteRun`	mutation	Unassign a route run
`optimizeRouteRun`	mutation	Optimize a route run
`arriveRouteRunStop`	mutation	Stop: arrive
`completeRouteRunStop`	mutation	Stop: complete
`failRouteRunStop`	mutation	Stop: fail
`skipRouteRunStop`	mutation	Stop: skip
`departRouteRunLeg`	mutation	Leg: depart
`arriveRouteRunLeg`	mutation	Leg: arrive
`replanShipmentJourney`	mutation	Replan a journey

Shipments

Field	Kind	What it does
`shipments`	query	List shipments
`createShipment`	mutation	Create a shipment (draft, or purchase with `purchase: true`)
`searchShipments`	query	Search shipments
`shipment`	query	Retrieve a Shipment
`updateShipment`	mutation	Update a Shipment
`deleteShipment`	mutation	Delete a draft shipment

Templates

Field	Kind	What it does
`documents`	query	List documents
`document`	query	Retrieve a Document
`deleteDocument`	mutation	Delete a standalone document
`documentJobs`	query	List document jobs
`createDocumentJob`	mutation	Create a document job
`documentJob`	query	Retrieve a DocumentJob
`labelSpecs`	query	List label specs
`labelSpec`	query	Retrieve a LabelSpec
`documentIngestions`	query	List document ingestions
`documentIngestion`	query	Retrieve a DocumentIngestion
`documentTemplates`	query	List document templates
`createDocumentTemplate`	mutation	Create a document template
`documentTemplate`	query	Retrieve a DocumentTemplate
`updateDocumentTemplate`	mutation	Update a DocumentTemplate
`deleteDocumentTemplate`	mutation	Delete a draft template
`publishDocumentTemplate`	mutation	Publish a template
`previewDocumentTemplate`	mutation	Preview a template
`validateDocumentTemplate`	mutation	Validate a template
`documentTemplateVersions`	query	List template versions
`createLabelSpec`	mutation	Create a label spec
`updateLabelSpec`	mutation	Update a LabelSpec
`publishLabelSpec`	mutation	Publish a label spec

Tracking

Field	Kind	What it does
`trackers`	query	List trackers
`createTracker`	mutation	Create a tracker
`searchTrackers`	query	Search trackers
`tracker`	query	Retrieve a Tracker
`updateTracker`	mutation	Update a Tracker
`deleteTracker`	mutation	Discard a tracker

Trade

Field	Kind	What it does
`classifications`	query	List classifications
`createClassification`	mutation	Classify items
`classification`	query	Retrieve a Classification
`complianceScreenings`	query	List compliance screenings
`createComplianceScreening`	mutation	Screen parties and goods
`complianceScreening`	query	Retrieve a ComplianceScreening
`landedCosts`	query	List landed costs
`createLandedCost`	mutation	Quote landed cost
`landedCost`	query	Retrieve a LandedCost
`tariff`	query	Look up a tariff line
`dutyCollections`	query	List duty collections
`dutyCollection`	query	Retrieve a DutyCollection

Webhooks

Field	Kind	What it does
`webhookEndpoints`	query	List webhook endpoints
`createWebhookEndpoint`	mutation	Create a webhook endpoint
`webhookEndpoint`	query	Retrieve a WebhookEndpoint
`updateWebhookEndpoint`	mutation	Update a WebhookEndpoint
`deleteWebhookEndpoint`	mutation	Delete a WebhookEndpoint

​Conventions

​Accounts

​Apps

​Batches

​Billing

​Carriers

​Catalog

​Connections

​Consolidation

​Data Network

​Document Uploads

​Events

​Files

​Fleet

​Inbound

​Injection

​Integrations

​Inventory

​IoT

​Jobs

​Manifests

​Network

​Pickup Schedules

​Pickups

​Pricing

​Products

​Rates

​Routes

​Shipments

​Templates

​Tracking

​Trade

​Webhooks