# Pipe17 API

> Pipe17 is the enterprise Order Operations Platform that unifies commerce after
> the buy button. This REST API (OpenAPI 3.0.1, spec version 3.0.540)
> exposes orders, fulfillments, inventory, products, purchases, returns, and the
> connector layer that moves them between systems.

Base URL (production): `https://api-v3.pipe17.com/api/v3`
Authentication: send an API key in the `X-Pipe17-Key` header on every request.
Exception: `POST /convert` authenticates with the `x-api-key` header against `https://schema.pipe17.com` — see [Convert](https://apidoc.pipe17.com/specs/convert.json).
Scope: 167 paths / 318 operations across 51 resource groups.

## Machine-readable specs

- [Operation index (JSON)](https://apidoc.pipe17.com/specs/index.json): every operationId with its method, path, tag, and slice. Fetch this first to locate an endpoint.
- [Full OpenAPI spec (JSON)](https://apidoc.pipe17.com/public.json): complete spec, all 318 operations. Prefer a slice below unless you need cross-cutting search.
- [Full OpenAPI spec (YAML)](https://apidoc.pipe17.com/public.yaml): same content, YAML.

## Resource slices

Each slice is a self-contained OpenAPI 3.0.1 document carrying only the schemas its own
operations reference, so it can be read without the full spec. For order flow start with
[Orders](https://apidoc.pipe17.com/specs/orders.json), [Fulfillments](https://apidoc.pipe17.com/specs/fulfillments.json), [Shipping Requests](https://apidoc.pipe17.com/specs/shipping-requests.json),
[Inventory](https://apidoc.pipe17.com/specs/inventory.json) and [Products](https://apidoc.pipe17.com/specs/products.json); when diagnosing a stuck
record start with [Exceptions](https://apidoc.pipe17.com/specs/exceptions.json) and [Event Log](https://apidoc.pipe17.com/specs/event-log.json).

- [Accounts](https://apidoc.pipe17.com/specs/accounts.json): `/accounts`, 3 operations
- [Api Keys](https://apidoc.pipe17.com/specs/api-keys.json): `/apikey`, 6 operations
- [Appeasement Codes](https://apidoc.pipe17.com/specs/appeasement-codes.json): `/appeasement_codes`, 5 operations
- [Appeasements](https://apidoc.pipe17.com/specs/appeasements.json): `/appeasements`, 4 operations
- [Arrivals](https://apidoc.pipe17.com/specs/arrivals.json): `/arrivals`, 7 operations. Operations about Arrival Notifications
- [Automation Rules](https://apidoc.pipe17.com/specs/automation-rules.json): `/automation_rules`, 5 operations. Operations around Automation Rules. An automation rule contains filters and actions that determine when and how to execute automation actions. An automation rule always belongs to an automation.
- [Automation Runs](https://apidoc.pipe17.com/specs/automation-runs.json): `/automation_runs`, 5 operations. Operations around Automation Runs. An automation run captures the history of an automation being executed on an entity.
- [Automations](https://apidoc.pipe17.com/specs/automations.json): `/automations`, 6 operations. Operations around Automations. An automation is the highest level entity of the Automation Engine.
- [Catalog Products](https://apidoc.pipe17.com/specs/catalog-products.json): `/catalog_products`, 5 operations
- [Catalogs](https://apidoc.pipe17.com/specs/catalogs.json): `/catalogs`, 5 operations
- [Connectors](https://apidoc.pipe17.com/specs/connectors.json): `/connectors`, 5 operations
- [Contacts](https://apidoc.pipe17.com/specs/contacts.json): `/contacts`, 5 operations
- [Convert](https://apidoc.pipe17.com/specs/convert.json): `/convert`, 1 operation
- [Custom Objects](https://apidoc.pipe17.com/specs/custom-objects.json): `/custom_objects`, 5 operations
- [Customers](https://apidoc.pipe17.com/specs/customers.json): `/customers`, 7 operations
- [Cycle Count Entries](https://apidoc.pipe17.com/specs/cycle-count-entries.json): `/cycle_count_entries`, 4 operations
- [Cycle Counts](https://apidoc.pipe17.com/specs/cycle-counts.json): `/cycle_counts`, 10 operations
- [Delivery Promises](https://apidoc.pipe17.com/specs/delivery-promises.json): `/delivery_promises`, 2 operations. Immutable delivery promises for orders.
- [Event Log](https://apidoc.pipe17.com/specs/event-log.json): `/events`, 5 operations
- [Exceptions](https://apidoc.pipe17.com/specs/exceptions.json): `/exceptions`, 6 operations
- [Fulfillments](https://apidoc.pipe17.com/specs/fulfillments.json): `/fulfillments`, 7 operations. When shipments gets fulfilled, a Fulfillment object is created within Pipe17
- [Integrations](https://apidoc.pipe17.com/specs/integrations.json): `/integrations`, 8 operations
- [Inventory](https://apidoc.pipe17.com/specs/inventory.json): `/inventory`, 5 operations
- [Invoices](https://apidoc.pipe17.com/specs/invoices.json): `/invoices`, 7 operations
- [Labels](https://apidoc.pipe17.com/specs/labels.json): `/labels`, 9 operations
- [Location Groups](https://apidoc.pipe17.com/specs/location-groups.json): `/location_groups`, 6 operations
- [Locations](https://apidoc.pipe17.com/specs/locations.json): `/locations`, 7 operations
- [Mappings](https://apidoc.pipe17.com/specs/mappings.json): `/mappings`, 4 operations
- [Notes](https://apidoc.pipe17.com/specs/notes.json): `/notes`, 5 operations
- [Order Statement Transactions](https://apidoc.pipe17.com/specs/order-statement-transactions.json): `/statement_transactions`, 6 operations
- [Order Statements](https://apidoc.pipe17.com/specs/order-statements.json): `/statements`, 6 operations
- [Orders](https://apidoc.pipe17.com/specs/orders.json): `/orders`, 9 operations
- [Organizations](https://apidoc.pipe17.com/specs/organizations.json): `/organizations`, 9 operations
- [Payments](https://apidoc.pipe17.com/specs/payments.json): `/payments`, 5 operations. Operations about Payment Transactions
- [Products](https://apidoc.pipe17.com/specs/products.json): `/products`, 7 operations
- [Purchases](https://apidoc.pipe17.com/specs/purchases.json): `/purchases`, 7 operations. Operations about Purchase Orders
- [Receipts](https://apidoc.pipe17.com/specs/receipts.json): `/receipts`, 6 operations
- [Returns](https://apidoc.pipe17.com/specs/returns.json): `/returns`, 7 operations
- [Roles](https://apidoc.pipe17.com/specs/roles.json): `/roles`, 5 operations. Operations about User Roles
- [Schedules](https://apidoc.pipe17.com/specs/schedules.json): `/schedules`, 8 operations
- [Shipment Boxes](https://apidoc.pipe17.com/specs/shipment-boxes.json): `/shipment_boxes`, 6 operations
- [Shipping Methods](https://apidoc.pipe17.com/specs/shipping-methods.json): `/shipping_methods`, 7 operations
- [Shipping Requests](https://apidoc.pipe17.com/specs/shipping-requests.json): `/shipping_requests`, 16 operations. Operations with shipping requests. The obsolete `/shipments` path will be supported along with `/shipping_requests` until further notice.
- [Stores](https://apidoc.pipe17.com/specs/stores.json): `/stores`, 10 operations
- [Suppliers](https://apidoc.pipe17.com/specs/suppliers.json): `/suppliers`, 7 operations
- [Trackings](https://apidoc.pipe17.com/specs/trackings.json): `/trackings`, 5 operations. Operations about Fulfillment Tracking `(- unused, reserved for future use)`
- [Transfers](https://apidoc.pipe17.com/specs/transfers.json): `/transfers`, 7 operations. Operations about Transfer Orders
- [User Preferences](https://apidoc.pipe17.com/specs/user-preferences.json): `/userpreferences`, 3 operations
- [Users](https://apidoc.pipe17.com/specs/users.json): `/users`, 8 operations
- [Waves](https://apidoc.pipe17.com/specs/waves.json): `/waves`, 10 operations. Operations about Waves - Wave fulfillment for grouping shipment requests
- [Webhooks](https://apidoc.pipe17.com/specs/webhooks.json): `/webhooks`, 5 operations

## API conventions

These apply across list endpoints and are not repeated per operation:

- Pagination: `count` (page size, default 100) and `skip` (offset, default 0). Responses carry a `pagination` object with `pageIndex` (1-based), `pageSize`, `pages`, `total`, `first`, `last`, `outOfBounds`. Pass `pagination=disabled` to omit it.
- Field selection: `keys` takes a comma-separated list of top-level fields. Each operation documents its own default set — the default is not "all fields".
- Sorting: `order` takes comma-separated top-level fields, default `createdAt`.
- Time filters: `since` / `until` on `createdAt`, `updatedSince` / `updatedUntil` on `updatedAt`, all RFC 3339 date-times. Many resources add status-specific pairs (for example `deletedSince` / `deletedUntil`).
- Soft deletes: records are soft-deleted; pass `deleted=true` to include them.
- Multi-org: `orgKey` selects the organization when a key spans more than one.

## Error responses

Each operation documents a single `default` response for failures rather than enumerating
status codes, so the list below is the contract. Every error body shares one envelope:

- `code` (integer, always present): Copy of HTTP status
- `success` (boolean, always present): Always false
- `conflict` (object): Details of the conflicting state, when the failure is a 409. The shape depends on the endpoint — a duplicate-key failure carries the offending keys, while /shipping_requests/{id}/request-labels carries `labels` (the labels the shipment already holds), `existingExtLabelIds` (the extLabelIds already claimed) or `refundedExtLabelIds` (extLabelIds belonging to refunded labels, which cannot be reused).
- `errors` (array of string): Error detail
- `message` (string): Error message
- `vendorCode` (string): Vendor-specific error code passed through from a downstream connector/carrier (e.g. EasyPost "SHIPMENT.REFUND.UNAVAILABLE"). Present only when the failure originated at the vendor.

Status codes an operation can return:

- `400` — validation failure. `errors` names what was wrong with the request. Not retryable unchanged.
- `401` — missing or unrecognised API key. Produced by the authorizer before the operation runs, so the body is not the envelope above.
- `403` — authenticated but not permitted: the key lacks the entity/method permission, or the record belongs to another organization. Once a key has been accepted, this — not `401` — is what an authorization failure looks like.
- `404` — no such record, or it is soft-deleted and `deleted=true` was not passed.
- `405` — the path exists but that variant is not implemented, for example a soft delete on a resource that only supports hard delete.
- `409` — duplicate key. `conflict` carries the conflicting fields.
- `429` — usage-plan rate limit, applied at the gateway before the operation runs. Retry with backoff.
- `500`, `502`, `503` — server or downstream failure. `vendorCode` carries the downstream code when the failure originated at a connector or carrier. Retry `502` and `503` with backoff.
- `402` and `415` occur narrowly — a delinquent account on shipment creation, an unsupported content type. Treat any unlisted 4xx as not retryable.

Batch writes need care. A create or update that accepts an array returns `202` with a
per-item array (`orders`, `shipments`, and so on) whose entries carry their own `status` and
`message`, so a `202` does not mean every item succeeded — check the per-item status, not the
HTTP code alone. When a single-item batch fails, the response is the envelope above with that
same per-item array beside it.

## Optional

- [Pipe17 company and product map](https://pipe17.com/llms.txt): what Pipe17 does, the integration catalog, and customer stories. Use it for anything that is not an API question.
- [API reference (browser UI)](https://apidoc.pipe17.com/): Stoplight Elements viewer. Client-rendered — fetch the specs above instead of scraping this page.
- [Pipe17 product site](https://pipe17.com)
- [Terms of service](https://pipe17.com/terms-of-service)
- [License](https://apidoc.pipe17.com/pipe17-api-license.html)