Custom Fulfillment Integration

The Custom Fulfillment Integration connects a warehouse management system, 3PL, or other fulfillment service to Endless through the GraphQL API. It gives the connected system controlled access to fulfillment work, shipment and tracking updates, cancellations, and supported inventory workflows.

This guide explains the integration's role, setup, and recommended operating model. The API reference is the source of truth for available operations, arguments, fields, types, and response shapes.

When to use it

Use a Custom Fulfillment Integration when a warehouse or fulfillment provider needs a bespoke connection to Endless. Common uses include:

• sending fulfillment work to a warehouse management system or 3PL
• returning shipment, carton, carrier, and tracking information to Endless
• synchronizing inventory for connected buildings
• coordinating cancellation or unship workflows
• retrieving the product and order information required to fulfill an order

This integration is intended for warehouse execution. It does not own sales order editing. Use a Custom Sales Integration for an external order source, a Custom Product Integration for catalog management, or a Custom Data Integration when a system only needs to read data.

The API reference is the source of truth

Use this guide to understand the workflow and use the API reference to build against the current schema. Confirm every operation, state transition, required input, enum, and return field there before implementing it.

Decide how fulfillment is managed

Before building the connection, define the responsibilities of the warehouse system and Endless:

• which buildings the integration fulfills for
• when work is ready to be sent to the warehouse
• which fulfillment lifecycle and inventory updates the service will report
• how external fulfillment and shipment identifiers are stored
• how cartons, carriers, services, tracking numbers, and partial shipments are mapped
• how cancellations, unships, failures, and late updates are handled
• how the systems reconcile missed or conflicting changes

The fulfillment integration acts as the fulfillment service for work assigned to it. It can operate that Fulfillment Order and return lifecycle and Shipment updates, but it does not manage unrelated Sales Order details or Fulfillment Orders assigned elsewhere. Keep sales, fulfillment, and inventory responsibilities explicit so two systems do not compete to update the same operational state.

Create the integration

You need permission to manage integrations for your company.

1. In Endless, open Integrations.
2. Select Add integration.
3. Under Custom Integrations, select Custom Fulfillment.
4. Give the integration a name that identifies the warehouse system or provider.
5. Select Create & generate credentials.
6. Save the generated credentials in a password manager or secrets vault before closing the window.

Endless generates an access token, API key, and API secret. The access token is the credential used to authenticate the GraphQL requests described in this guide. The API key and API secret are only displayed when the integration is created or its credentials are regenerated, so save all three values when they are shown.

Create a separate integration for each fulfillment system when practical. This keeps building assignments, credentials, external identifiers, and troubleshooting separate.

Connect buildings

Connect the integration to the buildings it will service in Endless. This association tells Endless which fulfillment integration is responsible for work at those buildings and limits the operational workflow to the intended facilities.

Complete and verify building assignments before processing live fulfillments. If a fulfillment is not available to the expected integration, check its building and integration assignment before changing the API request.

Connect to the GraphQL API

Send GraphQL requests as HTTP POST requests to the endpoint shown with the integration. The production endpoint is:

https://api.endlesscommerce.com/graphql

Include these headers with every request:

Header	Value
Content-Type	application/json
X-EC-Access-Token	The integration's access token
X-Company-Id	Your Endless company ID or handle

Do not add Bearer before the value in X-EC-Access-Token.

Test the connection

Use a schema-independent query to check the endpoint, credentials, and company context:

curl --request POST \
  --url https://api.endlesscommerce.com/graphql \
  --header 'Content-Type: application/json' \
  --header 'X-EC-Access-Token: YOUR_ACCESS_TOKEN' \
  --header 'X-Company-Id: YOUR_COMPANY_ID' \
  --data '{"query":"query ConnectionCheck { __typename }"}'

A successful response includes "__typename": "Query". This confirms the connection, but it does not validate a particular fulfillment operation or building assignment.

Build the fulfillment workflow

A reliable fulfillment integration usually follows this sequence:

1. Retrieve fulfillment work assigned to the connected integration and building.
2. Send the work to the external warehouse and store its stable external identifier.
3. Confirm accepted work using the operation and state documented by the API.
4. Report progress, exceptions, shipments, cartons, carrier services, and tracking as they occur.
5. Apply supported inventory updates according to the agreed source-of-truth model.
6. Reconcile open fulfillments and inventory periodically to find missed updates.

Do not infer state transitions from names alone. Fulfillment operations have business rules and prerequisites; follow the current API reference and test each transition in a non-production workflow before processing live orders.

Make updates and retries safe

Use stable external identifiers for fulfillments and shipments. Store the Endless and external identifiers together before moving to the next step.

Network failures can happen after Endless accepts an update but before the external system receives the response. Before retrying, check the current fulfillment state. A retry must not duplicate a shipment, tracking number, carton, or inventory change.

Handle updates that arrive late or out of order. Do not move a fulfillment backward or overwrite newer shipment information unless the API documents that transition.

Reconcile inventory deliberately

Decide whether Endless or the external warehouse is authoritative for each inventory quantity and location. Use the inventory operations documented for the integration's workflow, process updates incrementally, and run a periodic comparison to detect drift.

Inventory synchronization and fulfillment updates should be independently retryable. A failure in one should not cause the other to be applied twice.

Handle errors and responses

GraphQL responses can contain data, errors, or both. Always inspect errors before marking work successful. Record enough context to identify the integration, building, fulfillment, external identifier, operation, request time, and sanitized response.

Never log the access token, API key, API secret, or unnecessary customer information. Treat validation and state-transition errors as signals to inspect the current record, not as requests to retry indefinitely.

Protect and rotate credentials

Store credentials in a secrets vault or password manager and use them only from a trusted server or data platform. Never place them in browser code, source control, logs, or support messages.

To rotate credentials, open the integration in Endless and select Regenerate credentials. The previous credentials stop working immediately, so deploy the new access token to the connected system as part of the same change.

Troubleshooting

Problem	What to check
The request is unauthorized	Confirm that X-EC-Access-Token contains the access token with no Bearer prefix and that the credentials have not been regenerated.
The connection test works but fulfillment work is missing	Confirm that the integration is connected to the expected building and that the fulfillment is assigned there.
A fulfillment update is rejected	Compare the operation with the API reference and check the fulfillment's current state and required preceding steps.
Shipments or tracking are duplicated	Store stable external identifiers and check the current state before retrying an update.
Inventory does not match the warehouse	Confirm the inventory source-of-truth decision, locations, checkpoints, and most recent successful sync.
Cancellations do not reach the warehouse	Verify the cancellation workflow in both systems and reconcile open work rather than assuming delivery.

Getting help

Endless Support can help with access, credentials, company scope, building assignments, and behavior that does not match the current API reference. Designing mappings, warehouse workflows, reconciliation, or a production connector is the responsibility of your technical team or implementation partner.

When reporting an API problem, include the integration name, building, fulfillment identifier, external identifier, request time and time zone, GraphQL operation name, sanitized query and variables, company handle, and the error response. Never include credentials.