# Custom services

A custom service is an entity that contains all the information about an offered service. It must be bound to a facility and serves as a blueprint for creating [service jobs](/documentation/by-pillar/store-operations/services/service-jobs.md).

An example of a custom service is the adjustment of a shirt by adding embroidery to the collar and sleeves, as shown in the example below. Upon creation, the custom service is available for use at the tenant level.

A custom service can also reference another custom service (for instance, when one service requires another to be performed first), forming a chain of up to 15 dependent services.

Because custom services might have varying availability or execution times across different facilities, a facility custom service connection must be established before the service can be employed. This process is described in the [Facility custom service connection](#facility-custom-service-connection) section.

The maximum amount of allowed custom services in status ACTIVE is **100**.

{% hint style="info" %}
Orders that are split by routing decisions keep the items of a custom service together and won't be split.
{% endhint %}

## Working with custom services

{% hint style="info" %}
For detailed endpoint information, refer to the [Custom Services API reference](https://fulfillmenttools.github.io/fulfillmenttools-api-reference-ui/#post-/api/customservices).
{% endhint %}

### Create a custom service

To create a custom service, execute the following `POST` request with the JSON body:

```http
POST https://{YOUR-TENANT-NAME}.api.fulfillmenttools.com/api/customservices
```

```json
{
  "status": "ACTIVE",
  "nameLocalized": {
    "en_US": "Shirt initials embroidery",
    "de_DE": "Hemd Initialien Bestickung"
  },
  "descriptionLocalized": {
    "en_US": "The desired initials are embroidered on the collar and sleeve.",
    "de_DE": "Die gewünschten Initialien werden am Kragen und Ärmel eingestickt."
  },
  "executionTimeInMin": 60,
  "itemsReturnable": false,
  "itemsRequired": "MANDATORY",
  "additionalInformation": [
    {
      "nameLocalized": {
        "en_US": "Number of threads",
        "de_DE": "Anzahl der Fäden"
      },
      "descriptionLocalized": {
        "en_US": "This value indicates how many threads should be used for the embroidery",
        "de_DE": "Dieser Wert gibt an, wie viele Fäden bei der Stickerei genutzt werden sollen"
      },
      "valueType": "NUMBER",
      "isMandatory": true
    },
    {
      "nameLocalized": {
        "en_US": "Color",
        "de_DE": "Farbe"
      },
      "descriptionLocalized": {
        "en_US": "Color of the embroidery",
        "de_DE": "Die Farbe der Stickerei"
      },
      "valueType": "NUMBER",
      "isMandatory": true
    }
  ],
  "customAttributes": {
    "actionId": "b1eef2b0-1d5c-4819-bddc-b562beb14838"
  }
}
```

### Update a custom service

To update a custom service, send a `PATCH` request with the fields to be changed in the request body:

```http
PATCH https://{YOUR-TENANT-NAME}.api.fulfillmenttools.com/api/customservices/{customServiceId}
```

```json
{
  "status": "INACTIVE"
}
```

## Custom service additional information

A custom service can contain additional information, which is managed through dedicated API endpoints.

{% hint style="warning" %}
You can only add up to maximum 15 additional information to a custom service.
{% endhint %}

{% hint style="info" %}
For detailed endpoint information, see the [Custom Service Additional Information API reference](https://fulfillmenttools.github.io/fulfillmenttools-api-reference-ui/#post-/api/customservices/-customServiceId-/additionalinformation).
{% endhint %}

### Add or change additional information

To add or change additional information for a custom service, use the following `POST` and `PUT` requests with the relevant data in the body:

```http
POST https://{YOUR-TENANT-NAME}.api.fulfillmenttools.com/api/customservices/{customServiceId}/additionalinformation
```

```http
PUT https://{YOUR-TENANT-NAME}.api.fulfillmenttools.com/api/customservices/{customServiceId}/additionalinformation/{additionalInformationId}
```

```json
{
  "nameLocalized": {
    "en_US": "Thread Material",
    "de_DE": "Faden Material"
  },
  "descriptionLocalized": {
    "en_US": "Material of the thread",
    "de_DE": "Material des Fadens"
  },
  "valueType": "STRING"
}
```

### Delete additional information

To delete additional information from a custom service, execute the following `DELETE` request:

```http
DELETE https://{YOUR-TENANT-NAME}.api.fulfillmenttools.com/api/customservices/{customServiceId}/additionalinformation/{additionalInformationId}
```

## Facility custom service connection

To employ a custom service, it must be bound to a specific facility. This binding is established by creating a facility custom service connection.

{% hint style="info" %}
For detailed endpoint information, see the [Facility Custom Service Connection API reference](https://fulfillmenttools.github.io/fulfillmenttools-api-reference-ui/#get-/api/facilities/-facilityId-/customservices).
{% endhint %}

### Create or update a facility custom service connection

To create a connection that enables a custom service in a facility, execute a `POST` request. To update an existing connection, use a `PATCH` request.

```http
POST https://{YOUR-TENANT-NAME}.api.fulfillmenttools.com/api/facilities/{facilityId}/customservices/{customServiceId}
```

```json
{
  "executionTimeInMin": 90,
  "status": "ACTIVE"
}
```

### Delete a facility custom service connection

```http
DELETE https://{YOUR-TENANT-NAME}.api.fulfillmenttools.com/api/facilities/{facilityId}/customservices/{customServiceId}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.fulfillmenttools.com/documentation/by-pillar/store-operations/services/custom-services.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.