Order with custom services

• Simple Custom Service use-case

• Complex Custom Service user-case

Simple Custom Service Use Case

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

Complex Custom Service Use Case

In the simple custom service order use-case we introduced custom services. 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. In this use-case we show how to combine multiple (dependent) custom services.

Custom Service

In this use-case we want to put an engraving to a watch and furthermore assembly an alternative wristband. Therefore, we need to Introduce two custom services to the fulfillmenttools platform.

Engraving Custom Service

Engraving a text to the backside of a watch needs additional information:

• 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
      }
    ]
  }'

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.

Wristband Assembly Custom Service

Let's assume that we want to add the service assembling a wristband to a watch to the fulfillmenttools platform:

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": "Wristband Assembly Service"
    },
    "descriptionLocalized": {
      "en_US": "This services assembles a given wristband to a given watch"
    },
    "executionTimeInMin": 15,
    "itemsReturnable": true,
    "itemsRequired": "MANDATORY",
    "additionalInformation": []
  }'

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

• We don't have any additionalInformation for this custom service

Ship-from-Store Order

Now that we have configured the two custom services we can create an order which references the two services. So we create an order containing the watch, the wristband and references the custom services in a hierarchical manner. We want to first do the engraving and afterwards assembly the wristband. An request to create such an order with custom services could look like this:

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": "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": "960d1104-9390-4961-bce3-a8860498a251"
        },
        "articleItems": [
          {
            "tenantArticleRef": "article-id-wristband",
            "quantity": 1
          }
        ],
        "customServiceItems": [
          {
            "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": "article-id-watch",
                "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 (customServiceRef f4eba7c2-21ce-4926-a862-230f57651ec3) needs additionalInformation which are referenced by a additionalInformationRef

• the wristband assemply service (customServiceRef f4eba7c2-21ce-4926-a862-230f57651ec3) takes the result of the engravement service and the wristband article

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

Reference

Full specification of the orders endpoint in our fulfillmenttools API