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
    • Address formats for specific carriers
    • Basics
      • Article categories
      • Audits
      • Custom services & bundled line items
      • Facilities
      • Facility groups
      • GDPR configuration
      • Listings
      • Orders
        • Order types
        • Order status
      • Remote configuration
      • Receipts
      • Search
      • Subscribe to events
      • Sticker
      • Stocks
      • Storage locations
      • Tags
      • Users
    • Channel inventory
    • Facility discounts
    • Inbound process
    • Outbound stocks
    • Purchase order
    • Receipt
    • Routing strategy
    • 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
    • Availability & promising
    • Returns
Powered by GitBook
On this page
  • Create custom service
  • Custom service facility connection
  • Custom service example
  • Bundled items
Edit on GitHub
  1. Integration Guides
  2. Basics

Custom services & bundled line items

Last updated 1 day ago

To get more information about what a custom service is, visit the .

More Custom Service-API information can be found here:

More Service Job-API information can be found here:

Custom services can be defined in the fulfillmenttools platform by the /api/customservices API and then used at order creation if a custom service connection for the target facility is available (/api/facilities/{facilityId}/customservices API). A custom service in the order will be presented as a service job in the operational process.

A service could be a shortening of pants, an engraving of a watch, or an appointment for an eye test at an optician. Furthermore, services can be combined so that one service must be executed after the other.

Create custom service

To create a custom service, use POST /api/facilities/{facilityId}/customservices. In the following example body, an engraving service is created:

{
  "status": "ENABLED",
  "nameLocalized": {
    "en_US": "Engraving Service"
  },
  "descriptionLocalized": {
    "en_US": "This service engraves a given item with a required text and a an optional font. If no font is given please use the font Comic Sans."
  },
  "executionTimeInMin": 60,
  "itemsReturnable": false,
  "itemsRequired": "MANDATORY",
  "additionalInformation": [
    {
      "nameLocalized": {
        "en_US": "Text"
      },
      "descriptionLocalized": {
        "en_US": "The text which should be used for the engraving"
      },
      "valueType": "STRING"
    },
    {
      "nameLocalized": {
        "en_US": "Font"
      },
      "descriptionLocalized": {
        "en_US": "The font which should be used for the engraving"
      },
      "valueType": "STRING",
      "isMandatory": false
    }
  ]
}

Custom service facility connection

To make a custom service available in a facility, use the POST api/facilities/{facilityId}/customservices/{customServiceId} endpoint. The following body will make the custom service with {customServiceId} in facility with {facilityId} available:

{
  "executionTimeInMin": 100,
  "status": "ACTIVE"
}

Custom service example

In this use case, we want to engrave a watch and assemble an alternative wristband. Therefore, we need to add two custom services to the order. Ensure that the custom services and facility connections are available.

Here is the body of an order with two custom services that must be done one after another:

{
  "consumer": {
    "addresses": [
      {
        "salutation": "Mr.",
        "firstName": "Test",
        "lastName": "Customer",
        "street": "Domstr.",
        "houseNumber": "20",
        "postalCode": "50668",
        "city": "Köln",
        "country": "DE"
      }
    ],
    "email": "customer@mail.com"
  },
  "orderDate": "2025-03-06T17:30:00Z",
  "status": "OPEN",
  "tenantOrderId": "order-4711",
  "orderLineItems": [
    {
      "quantity": 1,
      "article": {
        "tenantArticleId": "article-id-watch",
        "title": "Watch",
        "imageUrl": "https://loremflickr.com/320/240/watch"
      }
    },
    {
      "quantity": 1,
      "article": {
        "tenantArticleId": "article-id-wristband",
        "title": "wristband",
        "imageUrl": "https://loremflickr.com/320/240/wristband"
      }
    }
  ],
  "customServices": [
    {
      "customServiceDefinition": {
        "customServiceRef": "wristband-shortening-custom-service-ref"
      },
      "articleItems": [
        {
          "tenantArticleRef": "article-id-wristband",
          "quantity": 1
        }
      ],
      "customServiceItems": [
        {
          "customServiceDefinition": {
            "customServiceRef": "engraving-custom-service-ref",
            "additionalInformation": [
              {
                "additionalInformationRef": "e233c255-d5db-4e7a-b5e6-890cf28a8c26",
                "value": "Test Customer"
              },
              {
                "additionalInformationRef": "f8665135-780f-4fa9-b441-0dd5d0b59aa6",
                "value": "My Awesome Font"
              }
            ]
          },
          "customServiceItems": [],
          "articleItems": [
            {
              "tenantArticleRef": "article-id-watch",
              "quantity": 1
            }
          ]
        }
      ]
    }
  ]
}

Some details:

  • Custom service with engraving-custom-service-ref will be executed first

  • Custom service with wristband-shortening-custom-service-ref get the result of engraving-custom-service-ref

  • Each article item can only be present once in the customServices

Bundled items

To ensure that items are not split into different pick jobs or routed to different facilities, bundled items can be used. Items can be isBundled via the custom service concept by adding items to a custom service and defining it as bundled within the order. The line items that should be bundled must be part of the orderLineItems within the order:

"customServices": [
  {
    "customServiceDefinition": {
      "isBundled": true
    },
    "articleItems": [
      {
        "tenantArticleRef": "32168",
        "quantity": 1
      }, {
        "tenantArticleRef": "31851",
        "quantity": 1
      }
    ],
    "customServiceItems": []
  }
]
info page about custom services
REST API documentation - Custom Services
REST API documentation - Service Jobs