Simple Custom Service Order

In this example we focus on custom services. For details regarding Ship-from-Store orders look at the Ship-from-Store use-case. Custom Services add services to orders or order lines which are executed after picking. This could be shortening of pants, an engraving of a watch or an appointment for an eye test at an optician.

Custom Service

In this use-case we choose the example of engraving a text to the backside of a watch. This service needs additional information to be completed:

• the text you want to engrave

• the font you want to engrave (font is optional)

The custom service must be created in the fulfillmenttools platform. You can think of the custom service resource as a blue print. In this blue print you can configure the additional information and orders can reference the custom service.

This example creates the custom service described above:

curl -sSL -X POST 'https://your.api.fulfillmenttools.com/api/customservices' \
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "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
      }
    ],
    "customAttributes": {
      "actionId": "b1eef2b0-1d5c-4819-bddc-b562beb14838"
    }
  }'

Some details on the example:

• each created custom service has a id which is used in an order to reference the defined custom service.

• executionTimeInMin: how long does the service take (we use the value for calculating target times)

• An item processed in a service with itemsReturnable set to true cannot be retured since it is comumed by the service.

• The itemsRequired attribute sets that this service must be used together with order line items

• The additionalInformation configures the parameters we need to fulfill the service. These parameters can be optional or mandatory furthermore, you can specify the valueType e.g STRING, BOOLEAN or DATE. Furthermore, each additional information item has an id which is used for referencing the additional information when creating an order.

• The customAttributes field is a JSON object that carries information that might be relevant to the Custom Service. The form and content of this object is completely free, but its JSON serialized size is limited. Check out the Custom Attributes section for more details.

Ship-from-Store Order

Now that we have configured a custom service we can create an order which references the custom service. So we create an order containing the watch and references the custom service:

curl -sSL -X POST 'https://your.api.fulfillmenttools.com/api/orders' \
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "consumer": {
      "addresses": [
        {
          "salutation": "Mr.",
          "firstName": "Test",
          "lastName": "Customer",
          "street": "Domstr.",
          "houseNumber": "20",
          "postalCode": "50668",
          "city": "Köln",
          "country": "DE"
        }
      ],
      "email": "[e-mail]"
    },
    "orderDate": "2023-03-06T17:30:00Z",
    "status": "OPEN",
    "tenantOrderId": "order-111",
    "orderLineItems": [
      {
        "quantity": 1,
        "article": {
          "tenantArticleId": "11187222",
          "title": "Watch",
          "imageUrl": "https://loremflickr.com/320/240/watch"
        }
      }
    ],
    "customServices": [
      {
        "customServiceDefinition": {
          "customServiceRef": "f4eba7c2-21ce-4926-a862-230f57651ec3",
          "additionalInformation": [
            {
              "additionalInformationRef": "e233c255-d5db-4e7a-b5e6-890cf28a8c26",
              "value": "Test Customer"
            },
            {
              "additionalInformationRef": "f8665135-780f-4fa9-b441-0dd5d0b59aa6",
              "value": "My Awesome Font"
            }
          ]
        },
        "customServiceItems": [],
        "articleItems": [
          {
            "tenantArticleRef": "11187222",
            "quantity": 1
          }
        ]
      }
    ]
  }'

Some details on the example:

• in customServices you can add multiple entries, each entry groups together different services and eaches

• the engravement service needs additionalInformation which are referenced by a additionalInformationRef

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

• customServices can also be nested to represent service hierarchies / processing steps

Reference

• Full specification of the orders endpoint in our fulfillmenttools API