MCP integration guide
Everything to build a JSON integration with Orderful, in the order you need it.
Everything to build a JSON integration with Orderful, in the order you need it. It does not cover X12 files. Ask your AI app for one topic at a time, or read it here.
The get_integration_guide tool returns one section of this page by its topic:
concepts: the terms you need before you build.authentication: get an API key and make a first call.send: create an outbound transaction.receive: get inbound JSON transactions and acknowledge them.validate: check a transaction before and after you send it.test_go_live: test with your partner, then go live.errors: what common statuses and failures mean.
Concepts
Your organization has one or more EDI accounts. Each account has an ISA ID and a qualifier. Together they identify you to trading partners. Orderful creates them when you join. You can find them on the EDI Accounts page.
A trading partnership is your connection with one partner. It holds relationships. A relationship is a directional data connection for one transaction type, inbound or outbound, such as an 850 purchase order sent to you.
A guideline defines what a transaction must contain. A partner that defines guidelines is the Leader. A partner that follows them is the Follower. The role is relative, so you can be Leader to one partner and Follower to another.
A communication channel connects Orderful to your system. Inbound channels bring data in and outbound channels send it out. For a JSON integration you will mostly use HTTP polling or an HTTP webhook. AS2 and SFTP are also supported.
A stream is test or live. A relationship that is still testing accepts only test stream transactions.
Related tools: list_partnerships, list_relationships, browse_edi_reference.
Docs: Orderful terms, Understand the ISA ID and qualifier, Relationship statuses
Authentication
The Orderful API uses an API key. In the Orderful portal, open Settings, then API Credentials under Organization Settings, and copy your API token. Keep it out of version control and client-side code.
Send the key in the orderful-api-key header, with Content-Type: application/json. The base URL is https://api.orderful.com in the US and https://api-eu.orderful.com in the EU.
To check the connection, list your transactions with GET /v3/transactions?limit=5. A JSON response with a list of items means it works.
Some calls need an API version header. For example, sending an acknowledgment uses orderful-api-version: v4. The API reference says which version each endpoint needs.
This MCP server does not use the API key. It signs you in with OAuth.
Related tools: list_transactions, get_api_reference.
Docs: Quick start
Send a transaction
Create one transaction per request. Post to the transactions endpoint with a JSON body. Sending uses API v4, so include the orderful-api-version: v4 header.
The body needs:
type, with a name such as850_PURCHASE_ORDERstream,testorlivemessage, with your transaction datasender, with itsisaIdreceiver, with itsisaId
Find ISA IDs under Relationships in Orderful.
The transaction must match a configured relationship. A test transaction needs at least one relationship for that direction. Success returns status 201 and the transaction ID.
The JSON size limit is 100 MB.
You can also upload a .json file in Orderful.
For the exact fields and responses of each call, use get_api_reference. Before you send, check the content with validate_edi_transaction. After you send, check it with get_transaction_detail.
Related tools: get_api_reference, get_guideline_requirements, validate_edi_transaction, get_transaction_detail.
Docs: Create a transaction, Create a Transaction API reference
Receive transactions
Inbound transactions arrive on an inbound communication channel. Choose how your system gets them: polling, or an HTTP webhook.
With polling, create an inbound Poller channel in Orderful. Your system calls the polling bucket with its API key. Each item holds the transaction and a delivery link. Approve or fail each delivery so it leaves the bucket. Poll on a schedule, and every 5 to 10 minutes for high volume. A response holds at most 100 transactions or 200 MB.
To browse what you received, use list_transactions with direction inbound. It returns up to 50 per call, newest first.
Then acknowledge. Your system sends the acknowledgment with the Acknowledgment API, with status ACCEPTED or REJECTED. Turn on Send acknowledgment on the inbound relationship. An acknowledgment can be sent only once, and accepting or rejecting cannot be undone.
For email alerts, open Settings, then Notifications, in Orderful.
Related tools: list_transactions, get_transaction_detail.
Docs: Inbound poller API, Listing transactions, Acknowledge a transaction, Subscribe to transaction notifications
Validate
Orderful checks each transaction against the guideline and workflow requirements, and runs your rules. The validation status is Processing, Valid or Invalid.
Before you send: get_guideline_requirements shows what a relationship requires. validate_edi_transaction checks a transaction against a guideline set and lists the problems. It takes Orderful JSON.
After you send: get_transaction_detail shows the status and the issues. For an inbound mapping failure, open the transaction in Orderful and check the Validation Errors tab.
Common causes of Invalid: date formats, missing fixed values such as a vendor number, wrong qualifiers, segments the partner requires that are not sent, and loops that do not match the partner's structure.
To fix an outbound transaction, use the Rules Engine for small data changes. Use your connector for bigger changes such as adding segments or restructuring. Then check that it validates.
Related tools: get_guideline_requirements, validate_edi_transaction, get_transaction_detail.
Docs: Fix an invalid transaction, Transaction statuses
Test and go live
- Get an example payload from Integration Assistance in Orderful for your relationship. The values are placeholders, so replace them.
- Create a test transaction by file upload, API or outbound channel. It must match a configured relationship.
- Check the validation status. If it is Invalid, open it and read the issues.
- Do scenario testing. Work through the scenario checklist for the partnership. If you send first, create the test transaction, link it by transaction ID and send it. The step turns green when your partner accepts. If your partner sends first, ingest their transaction and acknowledge it.
- Agree a go-live time with your partner outside Orderful. Then, in Relationships, change the status from Go live ready to Live.
Relationship statuses: Setup, then Testing, where only test stream transactions are allowed. Go live ready means the scenario checklists are done or skipped. Live allows test and live transactions, and can be set back to Go live ready.
To see what is still open and what blocks go-live, use get_partnership_status. To record the target date, use update_partnership.
Related tools: get_partnership_status, get_relationship_details, update_partnership.
Docs: Test and go live as a Leader, Test and go live as a Follower, Relationship statuses
Common statuses and errors
Validation: Processing means checks are running. Valid needs no action. Invalid means it failed a requirement, so see Validate.
Delivery: Pending, Sent, Delivered or Failed. Failed means the receiver's channel did not receive it. Check the channel on the relationship with get_relationship_details.
Acknowledgment: Accepted needs no action. Accepted with errors means the partner can process it, but fix the flagged errors in future transactions. Rejected means the partner cannot process it, so send a corrected transaction. A transaction not acknowledged within the set time becomes Overdue.
Acknowledgment API errors: 404 usually means the orderful-api-version: v4 header is missing. 403 means the sender tried to acknowledge, and only the receiver can. 400 means it was already accepted or rejected.
Rate limits: every API endpoint is rate limited, and limits differ by endpoint. Each response carries x-ratelimit-limit, x-ratelimit-remaining and x-ratelimit-reset headers. Over the limit, the API returns HTTP 429 with a Retry-After header giving the seconds to wait. Build your integration to wait that long and retry.
For anything else, call search_orderful_docs with the error text.
Related tools: list_transactions, get_transaction_detail, get_relationship_details, search_orderful_docs.
Docs: Transaction statuses, Acknowledge a transaction, Fix an invalid transaction, Best practices
Updated 7 days ago

