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

# Orderful EDI API

Jentic publishes the only available OpenAPI specification for Orderful EDI API, keeping it validated and agent-ready. Orderful is a cloud-based EDI platform that connects retailers, suppliers, and 3PLs through a single API for exchanging trading-partner documents such as purchase orders, ASNs, invoices, and acknowledgments. The API exposes 14 endpoints covering transaction lifecycle, delivery tracking, format conversion between EDI X12 and JSON, label generation, and trading partner relationships. It removes the need to operate VANs or AS2 connections by handling routing, validation, and acknowledgments centrally.

## For AI agents

Send and receive EDI transactions, track delivery status, and convert between EDI and JSON formats across retail and supply-chain trading partners.

## Scope

Does not handle payment settlement, carrier rate shopping, or warehouse management - use for EDI document exchange and trading partner workflows only.

## Capabilities

- Submit outbound EDI transactions like 850 purchase orders or 856 ASNs to trading partners via POST /transactions
- Track delivery state of an EDI transaction and confirm partner-side approval through GET `/transactions/{id}/delivery`
- Send 997 functional acknowledgments back to trading partners using POST `/transactions/{id}/acknowledgment`
- Pull the inbox of inbound transactions awaiting processing through GET /inbox
- Convert EDI X12 payloads into Orderful JSON and back via POST /convert without running a separate translator
- Generate UCC-128 shipping labels tied to an outbound shipment with POST /labels
- List active trading partner relationships and supported transaction sets through GET /relationships

## Use cases

### Retail Drop-Ship EDI Onboarding

Suppliers selling through Walmart, Target, or Amazon Vendor Central can use Orderful to exchange 850 purchase orders, 855 acknowledgments, 856 ASNs, and 810 invoices without standing up their own EDI translator or VAN. Orderful handles partner mapping and acknowledgment workflows, and the API lets engineering teams plug EDI directly into ERP or OMS systems.

Example prompt: Submit a POST /transactions with an 856 ASN payload referencing PO 4501234567, then poll GET `/transactions/{id}/delivery` until status becomes approved.

### EDI to JSON Format Conversion

Teams that store data as JSON in their warehouse or order management system can call POST /convert to translate inbound X12 documents into structured JSON, and outbound JSON back into compliant X12. This avoids embedding an X12 parser into application code and keeps validation rules in Orderful.

Example prompt: POST a raw X12 850 string to /convert and parse the returned JSON to extract line items and ship-to address.

### Functional Acknowledgment Automation

Trading partners require timely 997 functional acknowledgments confirming receipt of EDI documents. Agents can listen for inbound transactions through GET /inbox, validate them, and POST `/transactions/{id}/acknowledgment` to send back the 997 within the contractually required SLA window, avoiding chargebacks.

Example prompt: Iterate over GET /inbox results and POST `/transactions/{id}/acknowledgment` with status accepted for each successfully validated transaction.

### Agent-Driven EDI Operations via Jentic

AI agents that handle order operations can send and reconcile EDI documents through Jentic without learning the X12 standard. Jentic exposes Orderful operations by intent (send purchase order, check delivery, acknowledge receipt) and isolates the API key in the vault.

Example prompt: Use Jentic to search 'send an EDI purchase order to a trading partner', load the schema for POST /transactions, and execute with a generated 850 payload.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/transactions` | Submit an outbound EDI transaction |
| GET | `/transactions` | List transactions with filters |
| GET | `/transactions/{id}/delivery` | Check delivery status of a transaction |
| POST | `/transactions/{id}/acknowledgment` | Send a 997 functional acknowledgment |
| GET | `/inbox` | List inbound transactions awaiting processing |
| POST | `/convert` | Convert between X12 EDI and JSON |
| POST | `/labels` | Generate UCC-128 shipping labels |
| GET | `/relationships` | List trading partner relationships |

## Key resources

- **Transactions** — Send, retrieve, and inspect EDI transactions and their messages
- **Delivery** — Track and update delivery status for outbound EDI transactions
- **Acknowledgments** — Send and retrieve 997 functional acknowledgments
- **Inbox** — List inbound transactions awaiting processing
- **Convert** — Translate between X12 EDI and JSON
- **Labels** — Generate shipping labels tied to EDI shipments
- **Relationships** — List trading partner relationships

## Why Jentic

- **Setup:** Wiring the Orderful EDI API by hand means setting up its orderful-api-key header auth and parsing X12 transaction and acknowledgment payloads yourself. Through Jentic you install once, import Orderful from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** You choose which Orderful operations the agent may call, so you can limit it to the operations it needs, such as listing transactions or reading a transaction's delivery status, while sending a new transaction or posting an acknowledgment stays out of the allowed set unless you add them.
- **Credential handling:** Your Orderful API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'send an EDI purchase order' or 'list recent transactions', and Jentic returns the matching Orderful operation with its input schema so the agent calls the right endpoint without parsing X12 documentation.

## Related APIs

- **Stedi Core API** — Stedi is another modern EDI platform offering X12 translation and trading partner management.
- **ShipStation API** — ShipStation handles carrier rating, label printing, and shipment tracking that pairs with EDI 856/940 flows.
- **Square API** — Square exposes order, inventory, and payment data that often feeds the same OMS that consumes EDI documents.

## FAQ

### Why is there no official OpenAPI spec for Orderful EDI API?

Orderful does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Orderful EDI API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Orderful EDI API use?

The API uses an API key passed in a request header (ApiKeyAuth scheme). Through Jentic, the key is stored encrypted in the vault and never enters the agent's context - Jentic injects it at execution time.

### Can I send an 856 ASN through the Orderful EDI API?

Yes. POST /transactions with the ASN payload identified by transaction set 856 and the relevant trading partner relationship. Status is then tracked through GET `/transactions/{id}/delivery.`

### What are the rate limits for the Orderful EDI API?

The OpenAPI spec does not declare numeric rate limits. Orderful's documentation notes throttling on bulk transaction submission - check docs.orderful.com for current per-account limits before running large batches.

### How do I convert X12 EDI to JSON through Jentic?

Search Jentic for 'convert EDI to JSON', load the schema for POST /convert, and execute with the raw X12 string. The response contains the structured JSON representation Orderful uses internally.

### Does the Orderful EDI API generate shipping labels?

Yes. POST /labels generates UCC-128 carton labels tied to an outbound transaction. The label is returned as a printable artifact you can attach to your fulfillment workflow.

### Can I limit what my agent is allowed to do with the Orderful EDI API?

Yes. Because you run Jentic One yourself, your own rules decide which Orderful operations and credentials the agent may use. You can allow read-only calls such as listing transactions with GET /transactions or checking delivery status with GET `/transactions/{id}/delivery`, while write operations like submitting a transaction with POST /transactions or posting a 997 acknowledgment with POST `/transactions/{id}/acknowledgment` stay out of the allowed set unless you add them. This lets the operator scope exactly what the agent can call against your trading-partner data.