fulfillmenttools
API documentationIncident ManagementFeedback
Developer Docs
Developer Docs
  • Developer docs
  • Getting Started
    • Quickstart
    • Integration tutorial
      • Adding facilities
      • Adding listings to facilities
      • Configuring stocks
      • Carrier configuration
      • Placing orders
      • Checkout options
      • Distributed Order Management System (Routing)
      • Local fulfillment configuration
    • Free trial
  • Technical Basics
    • Access to fulfillmenttools
    • Feature status
    • Available regions
    • Backup policies
  • Connecting to fulfillmenttools
    • Client SDKs
    • commercetools connect
    • OpenID connect
      • Configure Microsoft Entra ID / Azure Active Directory
      • Configure Keycloak
  • API
    • Core concepts
      • Authentication & authorization
      • API Versioning & lifecycle
      • Assign user to jobs
      • Localization
      • Resource timestamps
      • Custom attributes
      • Article attributes
      • Recordable attributes
      • Data update guarantees
      • Rate limits & scaling
      • Retries
      • Performance on test vs. production systems
      • Load testing
    • API calls
      • Postman
      • cURL
      • GraphQL Explorer
    • GraphQL API
    • RESTful API
      • Pagination interface
      • RapiDoc
      • OpenAPI 3.0 Spec
    • Eventing
      • Structure of an event
      • Available events
        • Event flows
      • Eventing example
      • Event export
  • Integration Guides
    • Basics
      • Article categories
      • Audits
      • Facilities
      • Facility groups
      • GDPR configuration
      • Listings
      • Remote configuration
      • Receipts
      • Search
      • Subscribe to events
      • Sticker
      • Stocks
      • Storage locations
      • Tags
      • Users
    • Channel inventory
    • Inbound process
    • Outbound stocks
    • Purchase order
    • Receipt
    • Routing strategy (context-based multi-config DOMS)
    • Show sticker to clients
    • Stow jobs
  • More Integration Guides
    • Carrier management
      • Introduction to carrier configuration
      • Required data when operating carriers
      • Adding & connecting carriers to facilities
      • Custom carrier
    • Configurations for order fulfillment
      • Picking configuration
      • Packing configuration
      • Handover configuration
      • Printing and document configuration
      • Packing container types
      • Parcel tag configuration
      • Headless order fulfillment
      • Short-pick reasons
      • External documents in order fulfillment
      • Service jobs
      • Load units
      • Running sequence
    • DOMS - distributed order management system (routing)
    • External actions
    • Interfacility transfer
    • Notifications
    • Orders
      • Place your first order
      • Ship-from-store orders
      • Click-and-collect orders
      • Locked orders
      • Order with custom services
      • Bundled items in an order
      • Order process status
    • Availability & promising
    • Returns
Powered by GitBook
On this page
  • Semantic Nullability
  • Client Identification
  • Best practices
  • Limitations
  • Query Complexity & Rate Limiting
Edit on GitHub
  1. API

GraphQL API

Last updated 4 months ago

Our GraphQL API is currently in a beta stage. Please check the Limitations section for further information.

Our GraphQL API is reachable under https://{YOUR_TENANT}.graphql.fulfillmenttools.com/graphql. Just Curious? Try it out in our .

Semantic Nullability

The beta API implements the current draft of the GraphQL semantic nullability specification on connections and root-level fields.

Client Identification

In order to help with your support requests and to improve our service, we ask you to provide a client identification token when making calls from your production apps to our GraphQL API. This helps us distinguish between manual queries ( for example via the fulfillmenttools GraphQL Explorer) and your app deployments.

Please provide the client identification token in the following header:

X-User-Agent: {AppName}/{AppVersion}

A sample input to this header could be fft-picking-app/0.22.

If you do not provide a client ID header, you can still use the API as usual. We reserve the right to change the format of client ID header or make client identification mandatory at any time during the beta phase and will notify you if action on your side is necessary.

Best practices

When integrating with our GraphQL API, consider the following best practices to ensure optimal performance and reliability:

  • Fetch Only Necessary Data: Specify the exact fields you need in your queries to minimize payload size and improve performance.

  • Make a single request for each view: Fetch all required data in a single query to reduce latency and improve performance.

  • Use Query Variables: Do not inline your data into the GraphQL Document. Use instead.

  • Handle Errors Gracefully: With semantic nullability, you can easily handle partial results to increase application resilience.

  • Paginate Large Lists: Use pagination techniques like first, last, before, and after to manage large datasets efficiently.

  • Limit Query Complexity: Avoid deeply nested queries or overly complex operations that can impact performance.

  • Stay Updated: Regularly review our API documentation for updates or changes, especially during the beta phase.

Limitations

Query Complexity & Rate Limiting

At the moment, we do not enforce any query complexity or cost limits on the GraphQL API. This will change with the transition to general availability. In the future, we plan to implement query complexity analysis to ensure fair usage.

What You Should Do:

  • Optimize Queries: Begin optimizing your queries now to request only the data you need.

  • Avoid Excessive Nesting: Limit the depth of nested queries to reduce complexity.

  • Prepare for Limits: Be aware that queries exceeding complexity thresholds may be rejected in the future. We will notify you in advance of any changes.

Even with these limits in sight, don't hesitate to group data for the same view in a single query.

The GraphQL API is currently in a beta stage. This means that the API is not yet stable and internal fields or alpha features might change without notice. We are working hard to improve the API and make it generally available as soon as possible. For production use, we recommend restricting api usage to fields and types marked at least as BETA. For further information, please check our guide.

GraphQL Explorer
Variables
API Versioning & lifecycle