canonical: https://jentic.com/apis/fulfillment.com/fulfillment

# Fulfillment.com APIv2

Fulfillment.com (FDC) is a 4PL fulfilment provider whose v2 REST API lets merchants submit and track orders, manage returns, query inventory, and reconcile accounting from their warehouse network. The API exposes 15 endpoints covering orders, returns, tracking, inventory, accounting, and a simple OAuth2 access-token flow. Status codes are six digits and are documented in the spec to track an order from received through shipped to returned. Authentication uses OAuth2 bearer tokens and an x-api-key header.

## For AI agents

Submit and track ecommerce orders through the Fulfillment.com warehouse network, manage returns, and read inventory and accounting data.

## Scope

Does not handle storefronts, payments, or marketing - use for warehouse order submission, tracking, returns, inventory, and accounting only.

## Capabilities

- Submit a new order to the Fulfillment.com warehouse network for pick, pack, and ship
- Update an existing order's status or cancel it before dispatch
- Track an order through the FDC fulfilment lifecycle using documented status codes
- List and update returns processed against the merchant account
- Query current and full inventory levels across FDC facilities
- Pull accounting data for billing reconciliation
- Authenticate via OAuth2 access tokens with refresh-token rotation

## Use cases

### Direct-to-Consumer Order Submission

When a Shopify or custom storefront takes an order, an integration calls POST /orders on the FDC API with the order line items, ship-to address, and merchant order ID. FDC validates the address, allocates inventory, and returns an FDC order ID. Subsequent calls to GET `/orders/{id}` return a six-digit status code that maps the order through processing, fulfilment, and shipped.

Example prompt: Create an FDC order with merchantOrderId 'WEB-123', one SKU at quantity 2, and a US ship-to address

### Returns Reconciliation

When a customer initiates a return, FDC records it under /returns. A reconciliation script calls GET /returns daily to pull the latest entries and PUT /returns to update merchant-side disposition. This keeps the merchant order management system aligned with what FDC has physically received.

Example prompt: Call GET /returns for the last 7 days and update each return's disposition via PUT /returns

### Inventory Visibility

Before allowing checkout on a SKU, the storefront calls GET /inventory to confirm units are available. For low-frequency dashboards, GET `/inventory/full` pulls the entire merchant inventory snapshot. Combined with order status this gives the merchant a real-time view of stock and fulfilment posture across FDC facilities.

Example prompt: Call GET /inventory for SKU ABC-001 and return current available units

### Tracking and Status Updates

Once an order is shipped, GET /track returns carrier tracking metadata and PUT `/orders/{id}/ship` updates the order to shipped state with departDate. The combination of status codes and tracking lets the merchant power 'where is my order?' surfaces and customer notifications.

Example prompt: Call GET /track for order id 12345 and return the carrier and tracking number

### Agent-Driven Fulfilment Operations

An AI agent fields a merchant question like 'what's the status of order WEB-123?' and resolves the FDC order ID, fetches `/orders/{id}`, /track, and any returns. With Jentic the OAuth2 flow happens behind the scenes - the agent gets a scoped result and never handles the client_secret.

Example prompt: Search Jentic for 'check fulfillment order status', load GET `/orders/{id}`, and execute against the merchant order ID

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/orders` | Submit a new order to FDC |
| GET | `/orders/{id}` | Retrieve order status and details |
| PUT | `/orders/{id}/status` | Update an order's status |
| PUT | `/orders/{id}/ship` | Mark an order as shipped |
| GET | `/track` | Retrieve carrier tracking metadata |
| GET | `/inventory` | Query current inventory levels |
| POST | `/oauth/access_token` | Generate or refresh an OAuth2 access token |

## Key resources

- **Orders** — Submit, retrieve, update, cancel, and ship orders
- **Returns** — List and update returns processed against the account
- **Inventory** — Query current and full inventory levels across facilities
- **Tracking** — Retrieve carrier tracking metadata for shipped orders
- **Accounting** — Pull billing-reconciliation data for orders
- **OAuth** — Generate and refresh OAuth2 access tokens

## Why Jentic

- **Setup:** Wiring Fulfillment.com by hand means running the OAuth2 password token exchange against `/oauth/access_token`, also sending an x-api-key header, and refreshing the token yourself against the api.fulfillment.com host. Through Jentic you install once, import Fulfillment.com from the API Directory, store the client credentials and key once, and your agent calls it while Jentic runs the token exchange.
- **Permission scoping:** Fulfillment.com puts the order id in the URL path (`/orders/{id}`), so you limit the agent to the operations it needs, such as submitting an order or tracking one. You choose which operations it may call, so changing order status or marking it shipped is not included unless you add it.
- **Credential handling:** Your Fulfillment.com client credentials and API key are stored once, encrypted, by your own Jentic One instance, and the OAuth2 exchange runs at execution time. The secrets and rotated access token never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'submit a fulfillment order' or 'track a fulfillment order', and Jentic returns the matching POST /orders or GET /track operation with its input schema so the agent calls the right endpoint without studying the status-code table in the reference docs.

## Related APIs

- **ShipStation** — Multi-carrier shipping platform that pairs with 4PL fulfilment
- **ShipBob** — Direct-to-consumer 4PL with a similar order and inventory API
- **Shippo** — Shipping rates and label generation across carriers
- **Shopify** — Storefront platform that submits orders downstream to fulfilment

## FAQ

### What authentication does the Fulfillment.com APIv2 use?

FDC uses OAuth2 bearer tokens generated through POST `/oauth/access_token`, plus an x-api-key header. Implicit and password grant types are supported and refresh tokens rotate access. Through Jentic the client_id, client_secret, and API key are stored in your Jentic One instance.

### Can I submit a new order through the Fulfillment.com API?

Yes. POST /orders with merchantOrderId, line items, and a ship-to address. FDC validates the address, allocates stock, and returns the FDC order id. Use GET `/orders/{id}` to retrieve the resulting status.

### What are the rate limits for the Fulfillment.com API?

FDC does not publish a fixed rate limit but documents that bulk submission should be paced and that idempotency on merchantOrderId protects against duplicates. Treat 5 to 10 calls per second as a polite ceiling and back off on 429 responses.

### How do I track an order's shipment through Jentic?

Search Jentic for 'track a fulfillment.com order', load the GET /track schema, and execute with the order id. The response includes carrier and tracking number once FDC has assigned them at the dispatchDate milestone.

### What do the six-digit FDC status codes mean?

FDC status codes are formatted as state, stage, and detail (for example 020601 means 'Fulfillment In Progress / Label Printed'). The spec lists every code so that integrations can map status to human-readable messaging without guessing.

### Can I cancel an order after it has dispatched?

No. FDC documents that orders cannot be cancelled once they enter dispatch. Use DELETE `/orders/{id}` only before dispatchDate is set; afterwards a recall must go through the FDC account executive rather than the API.

### Can I limit what my agent is allowed to do with the Fulfillment.com API?

Yes. Jentic One is self-hosted by you, so your own rules decide which Fulfillment.com operations and credentials the agent may use. You can allow it to only submit an order (POST /orders) or track one (GET /track) while withholding operations like updating status (PUT `/orders/{id}/status`) or marking an order shipped (PUT `/orders/{id}/ship`) unless you explicitly add them. Because the order id lives in the URL path, you scope the agent to exactly the endpoints it needs, and the stored client credentials and API key run the OAuth2 exchange at execution time without entering the agent's context.