This guide is for building a custom integration: a service you host and run yourself against the Pipe17 public API. It doesn't cover building or changing connectors in the Pipe17 catalog, which Pipe17 builds and runs. To see what you can configure yourself and what requires Pipe17, see What you can configure and what requires Pipe17.
You can connect any system to Pipe17 by building your own connector against the Pipe17 public API. This guide shows how, using only what is publicly available: the API, its reference docs, and the Pipe17 app.
A custom connector is a small service you host and run. It moves data between your system (a 3PL/WMS, ERP, marketplace or in-house tool) and Pipe17 on a schedule and in response to webhooks. Pipe17 does not run your code, so your connector owns three jobs that a native Pipe17 connector would handle for you:
- Polling Pipe17 and your system for new or changed records.
- Receiving webhooks so it can react quickly instead of waiting for the next poll.
- Keeping state — where each poll left off, which Pipe17 record matches which record in your system, and what has already been sent — so it never skips or duplicates work.
Examples use JavaScript (Node.js 18 or later, built-in fetch, no extra libraries) and curl. The flows are described for a fulfillment provider (3PL/WMS), the most common case; the same patterns apply to any system.
How this guide is organized
| Chapter | What you will do |
|---|---|
| 1. Core concepts | Learn the Pipe17 records your connector reads and writes |
| 2. Getting set up | Create the custom integration, get your keys, make your first call |
| 3. Architecture of your connector | Lay out the parts of your connector |
| 4. Managing state | Design the small database your connector needs |
| 5. Polling Pipe17 | Fetch changes from Pipe17 safely and incrementally |
| 6. Webhooks | Get notified of changes and combine webhooks with polling |
| 7. Implementing the flows | Build locations, products, shipping requests, cancellations, fulfillments, inventory, inbound shipments and returns |
| 8. Errors, retries and exceptions | Handle failures, rate limits and report problems in Pipe17 |
| 9. Testing, go-live and support | Verify end to end and launch |
Before you start you need a Pipe17 sandbox organization with admin access, an environment that can run a long-lived Node.js process and expose an HTTPS endpoint (optional), and a small database (SQLite, Postgres, MySQL or similar).
Getting a sandbox. Pipe17 provides a sandbox organization to anyone building a custom integration. Contact the Pipe17 onboarding or support team to have one provisioned. A sandbox is a regular Pipe17 organization running in sandbox mode, so it uses the same API base URL as production; only the organization and its keys differ. Use it to build, to pull real sample records, and to test.
Code samples. The pipe17-custom-connector-samples.zip file attached to this article includes every script and curl command in this guide, a Postman collection with every call, and a few files that let you run the scripts locally. Follow the README.md file in the zip to try them out.
Need Help?
If you need additional assistance:
- Use Ask Pippen, our AI agent, located at the top of the app page.
- Submit a support request with as much relevant detail as possible. Learn how to submit a request.
We're here to help you succeed with your operations.
Comments
0 comments