External information lookup

External information lookup enables the retrieval of externally maintained data during the webshop or checkout process.

The system evaluates a predefined table and returns the values of a specific row based on a provided payload.

This mechanism supports use cases where customer-facing information must differ from internally calculated values while remaining fully configurable and deterministic.

Concept

External information lookup is based on the following concepts:

• A table that contains externally maintained data.

• A lookup request that provides input values as a payload.

• A row evaluation that matches the payload against the table definition.

• A response that returns values from the matched row.

The table acts as a rule-based mapping between input parameters and output values that that a webshop or checkout implementation can consume.

Example use case

In many scenarios, the shipping costs charged to an end customer differ from the actual shipping costs incurred by the merchant.

Typical examples include:

• Free shipping for the end customer once a specific cart value is exceeded, while the merchant continues to pay the full shipping costs.

• Flat-rate shipping fees for customers (for example, a fixed amount per order), while the merchant's shipping costs follow a dynamic pricing structure based on weight, volume, or packaging units.

In such cases, the internally calculated shipping costs remain relevant for fulfillment and cost accounting, but they must not be exposed to the customer.

With external information lookup, fulfillmenttools can:

• Send packaging or shipping units calculated during checkout as a payload.

• Evaluate these values against a predefined external table.

• Return the shipping costs that should be charged to the customer.

The returned values typically differ from the internally calculated shipping costs that fulfillmenttools determines dynamically on the platform.

Functional behavior

The system behaves as follows:

1. A lookup request is triggered from any point in the webshop or checkout flow.

2. The request includes a payload that represents calculated values, such as packaging units or shipment characteristics.

3. The system evaluates the payload against the configured table.

4. If a matching row is found, the system returns the values defined for that row.

5. The returned data can be used to display or apply customer-facing information, such as shipping costs.

Typical integration points

The external information lookup can be integrated at various points, including:

• Webshop product detail pages.

• Shopping cart views.

• Checkout steps where shipping costs are calculated or displayed.

• Custom frontend logic that requires externalized business rules.

Scope and limitations

The feature is designed for lookup-based evaluation and doesn't replace internal fulfillmenttools cost calculation logic.

It complements existing calculations by providing a controlled way to expose alternative values to external systems.

The following limits apply to the size and structure of the external information table:

• A maximum of 20 definitions per document is supported.

• Each document can contain up to 1,500 items.

• Each definition value is limited to 150 characters.

These limits ensure consistent lookup performance and predictable evaluation behavior across all integrations.

Get a lookup record by its ID

get

Retrieves a single lookup record using its unique identifier.

Authorizations

BearerToken

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

recordIdstringRequired

Responses

200

Successfully retrieved the lookup record.

application/json

LookupRecord

attributeDefinitionsall ofRequired

Map of attribute definitions that specify the type for each attribute.

object · LookupAttributeDefinitionsOptional

LookupAttributeDefinitions

createdstring · date-timeOptional

The date when the record was created.

idstringRequired

lastModifiedstring · date-timeOptional

The date when the record was last modified.

tenantRecordIdstring · min: 1 · max: 20Optional

Tenant-specific identifier for the lookup record.

versionnumberRequired

The version of the record.

401

Your user is not allowed to operate against this API instance

application/json

403

Your user, although recognized, is not authorized to use this

application/json

404

The requested entity was not found

application/json

get

/api/lookuprecords/{recordId}

HTTPcURLJavaScriptPython

GET /api/lookuprecords/{recordId} HTTP/1.1
Host: your-tenant-name.api.fulfillmenttools.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "attributeDefinitions": {},
  "created": "2026-03-02T20:29:10.503Z",
  "id": "text",
  "items": [
    {
      "id": "text",
      "values": [
        {
          "attributeId": "text",
          "attributeValue": "text"
        }
      ]
    }
  ],
  "lastModified": "2026-03-02T20:29:10.503Z",
  "tenantRecordId": "text",
  "version": 1
}

Updates a whole lookup record by its ID

put

Updates a single lookup record.

Authorizations

BearerToken

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

recordIdstringRequired

Body

application/json

LookupRecordForUpdate

attributeDefinitionsall ofRequired

Map of attribute definitions that specify the type for each attribute.

object · LookupAttributeDefinitionsOptional

LookupAttributeDefinitions

tenantRecordIdstring · min: 1 · max: 20Optional

Tenant-specific identifier for the lookup record.

versionnumberRequired

The version of the record.

Responses

200

Successfully updated the lookup record.

application/json

LookupRecord

attributeDefinitionsall ofRequired

Map of attribute definitions that specify the type for each attribute.

object · LookupAttributeDefinitionsOptional

LookupAttributeDefinitions

createdstring · date-timeOptional

The date when the record was created.

idstringRequired

lastModifiedstring · date-timeOptional

The date when the record was last modified.

tenantRecordIdstring · min: 1 · max: 20Optional

Tenant-specific identifier for the lookup record.

versionnumberRequired

The version of the record.

401

Your user is not allowed to operate against this API instance

application/json

403

Your user, although recognized, is not authorized to use this

application/json

404

The requested entity was not found

application/json

put

/api/lookuprecords/{recordId}

HTTPcURLJavaScriptPython

PUT /api/lookuprecords/{recordId} HTTP/1.1
Host: your-tenant-name.api.fulfillmenttools.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 133

{
  "attributeDefinitions": {},
  "items": [
    {
      "values": [
        {
          "attributeId": "text",
          "attributeValue": "text"
        }
      ]
    }
  ],
  "tenantRecordId": "text",
  "version": 1
}

{
  "attributeDefinitions": {},
  "created": "2026-03-02T20:29:10.503Z",
  "id": "text",
  "items": [
    {
      "id": "text",
      "values": [
        {
          "attributeId": "text",
          "attributeValue": "text"
        }
      ]
    }
  ],
  "lastModified": "2026-03-02T20:29:10.503Z",
  "tenantRecordId": "text",
  "version": 1
}

Get all lookup records

get

Retrieves all lookup records.

Authorizations

BearerToken

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Responses

200

Successfully retrieved the lookup records.

application/json

LookupRecord

attributeDefinitionsall ofRequired

Map of attribute definitions that specify the type for each attribute.

object · LookupAttributeDefinitionsOptional

LookupAttributeDefinitions

createdstring · date-timeOptional

The date when the record was created.

idstringRequired

lastModifiedstring · date-timeOptional

The date when the record was last modified.

tenantRecordIdstring · min: 1 · max: 20Optional

Tenant-specific identifier for the lookup record.

versionnumberRequired

The version of the record.

401

Your user is not allowed to operate against this API instance

application/json

403

Your user, although recognized, is not authorized to use this

application/json

404

The requested entity was not found

application/json

get

/api/lookuprecords

HTTPcURLJavaScriptPython

GET /api/lookuprecords HTTP/1.1
Host: your-tenant-name.api.fulfillmenttools.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "attributeDefinitions": {},
  "created": "2026-03-02T20:29:10.503Z",
  "id": "text",
  "items": [
    {
      "id": "text",
      "values": [
        {
          "attributeId": "text",
          "attributeValue": "text"
        }
      ]
    }
  ],
  "lastModified": "2026-03-02T20:29:10.503Z",
  "tenantRecordId": "text",
  "version": 1
}

Create a lookup record by its ID

post

Creates a single lookup record.

Authorizations

BearerToken

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

LookupRecordForCreation

attributeDefinitionsall ofRequired

Map of attribute definitions that specify the type for each attribute.

object · LookupAttributeDefinitionsOptional

LookupAttributeDefinitions

tenantRecordIdstring · min: 1 · max: 20Optional

Tenant-specific identifier for the lookup record.

Responses

200

Successfully created the lookup record.

application/json

LookupRecord

attributeDefinitionsall ofRequired

Map of attribute definitions that specify the type for each attribute.

object · LookupAttributeDefinitionsOptional

LookupAttributeDefinitions

createdstring · date-timeOptional

The date when the record was created.

idstringRequired

lastModifiedstring · date-timeOptional

The date when the record was last modified.

tenantRecordIdstring · min: 1 · max: 20Optional

Tenant-specific identifier for the lookup record.

versionnumberRequired

The version of the record.

401

Your user is not allowed to operate against this API instance

application/json

403

Your user, although recognized, is not authorized to use this

application/json

404

The requested entity was not found

application/json

post

/api/lookuprecords

HTTPcURLJavaScriptPython

POST /api/lookuprecords HTTP/1.1
Host: your-tenant-name.api.fulfillmenttools.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 121

{
  "attributeDefinitions": {},
  "items": [
    {
      "values": [
        {
          "attributeId": "text",
          "attributeValue": "text"
        }
      ]
    }
  ],
  "tenantRecordId": "text"
}

{
  "attributeDefinitions": {},
  "created": "2026-03-02T20:29:10.503Z",
  "id": "text",
  "items": [
    {
      "id": "text",
      "values": [
        {
          "attributeId": "text",
          "attributeValue": "text"
        }
      ]
    }
  ],
  "lastModified": "2026-03-02T20:29:10.503Z",
  "tenantRecordId": "text",
  "version": 1
}

Delete a lookup record by its ID

delete

Deletes a single lookup record using its unique identifier.

Authorizations

BearerToken

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

recordIdstringRequired

Responses

200

Successfully deleted the lookup record.

application/json

LookupRecord

attributeDefinitionsall ofRequired

Map of attribute definitions that specify the type for each attribute.

object · LookupAttributeDefinitionsOptional

LookupAttributeDefinitions

createdstring · date-timeOptional

The date when the record was created.

idstringRequired

lastModifiedstring · date-timeOptional

The date when the record was last modified.

tenantRecordIdstring · min: 1 · max: 20Optional

Tenant-specific identifier for the lookup record.

versionnumberRequired

The version of the record.

401

Your user is not allowed to operate against this API instance

application/json

403

Your user, although recognized, is not authorized to use this

application/json

404

The requested entity was not found

application/json

delete

/api/lookuprecords/{recordId}

HTTPcURLJavaScriptPython

DELETE /api/lookuprecords/{recordId} HTTP/1.1
Host: your-tenant-name.api.fulfillmenttools.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "attributeDefinitions": {},
  "created": "2026-03-02T20:29:10.503Z",
  "id": "text",
  "items": [
    {
      "id": "text",
      "values": [
        {
          "attributeId": "text",
          "attributeValue": "text"
        }
      ]
    }
  ],
  "lastModified": "2026-03-02T20:29:10.503Z",
  "tenantRecordId": "text",
  "version": 1
}

List all record items (search cached for 5 minutes)

post

This part of the API is in Beta status. For details please check the api-release-life-cycle documentation. Search for LookupRecordItem

Authorizations

BearerToken

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

LookupRecordItemSearchPayload

afterstringOptional

The cursor to start after for forward pagination. The value is provided in the pageInfo.endCursor field of the response. Cannot be used with before or last.

beforestringOptional

The cursor to start before for backward pagination. The value is provided in the pageInfo.startCursor field of the response. Cannot be used with after or size (first).

lastnumber · min: 1 · max: 250Optional

Number of items to return for backward pagination. Cannot be used with 'size' (first). Default: 20.

sizenumber · min: 1 · max: 250Optional

Number of items to return for forward pagination. Cannot be used with 'last'. Default: 20.

startAfterIdstringOptionalDeprecated

The ID to start after. Deprecated, use after with the value provided in pageInfo.endCursor instead.

Responses

200

Your search result

application/json

LookupRecordItemPaginatedResult

totalnumberOptional

The total number of items matching the search criteria. Only filled, if withTotal is set to true in the search options.

401

Your user is not allowed to operate against this API instance

application/json

403

Your user, although recognized, is not authorized to use this

application/json

post

/api/lookuprecorditems/search

HTTPcURLJavaScriptPython

POST /api/lookuprecorditems/search HTTP/1.1
Host: your-tenant-name.api.fulfillmenttools.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 2243

{
  "after": "text",
  "before": "text",
  "last": 1,
  "options": {
    "withTotal": true
  },
  "query": {
    "and": [
      {
        "and": [
          {
            "and": "[Circular Reference]",
            "id": {
              "eq": "text",
              "in": [
                "text"
              ],
              "notEq": "text",
              "notIn": [
                "text"
              ]
            },
            "or": "[Circular Reference]",
            "recordRef": {
              "eq": "text",
              "in": [
                "text"
              ],
              "notEq": "text",
              "notIn": [
                "text"
              ]
            },
            "tenantRecordId": {
              "eq": "text",
              "in": [
                "text"
              ],
              "notEq": "text",
              "notIn": [
                "text"
              ]
            },
            "values": {
              "contains": {
                "attributeId": {
                  "eq": "text",
                  "in": [
                    "text"
                  ],
                  "notEq": "text",
                  "notIn": [
                    "text"
                  ]
                },
                "attributeValue": {
                  "eq": "text",
                  "in": [
                    "text"
                  ],
                  "notEq": "text",
                  "notIn": [
                    "text"
                  ]
                }
              }
            }
          }
        ],
        "id": {
          "eq": "text",
          "in": [
            "text"
          ],
          "notEq": "text",
          "notIn": [
            "text"
          ]
        },
        "or": [
          {
            "and": "[Circular Reference]",
            "id": {
              "eq": "text",
              "in": [
                "text"
              ],
              "notEq": "text",
              "notIn": [
                "text"
              ]
            },
            "or": "[Circular Reference]",
            "recordRef": {
              "eq": "text",
              "in": [
                "text"
              ],
              "notEq": "text",
              "notIn": [
                "text"
              ]
            },
            "tenantRecordId": {
              "eq": "text",
              "in": [
                "text"
              ],
              "notEq": "text",
              "notIn": [
                "text"
              ]
            },
            "values": {
              "contains": {
                "attributeId": {
                  "eq": "text",
                  "in": [
                    "text"
                  ],
                  "notEq": "text",
                  "notIn": [
                    "text"
                  ]
                },
                "attributeValue": {
                  "eq": "text",
                  "in": [
                    "text"
                  ],
                  "notEq": "text",
                  "notIn": [
                    "text"
                  ]
                }
              }
            }
          }
        ],
        "recordRef": {
          "eq": "text",
          "in": [
            "text"
          ],
          "notEq": "text",
          "notIn": [
            "text"
          ]
        },
        "tenantRecordId": {
          "eq": "text",
          "in": [
            "text"
          ],
          "notEq": "text",
          "notIn": [
            "text"
          ]
        },
        "values": {
          "contains": {
            "attributeId": {
              "eq": "text",
              "in": [
                "text"
              ],
              "notEq": "text",
              "notIn": [
                "text"
              ]
            },
            "attributeValue": {
              "eq": "text",
              "in": [
                "text"
              ],
              "notEq": "text",
              "notIn": [
                "text"
              ]
            }
          }
        }
      }
    ],
    "id": {
      "eq": "text",
      "in": [
        "text"
      ],
      "notEq": "text",
      "notIn": [
        "text"
      ]
    },
    "or": [
      {
        "and": "[Circular Reference]",
        "id": {
          "eq": "text",
          "in": [
            "text"
          ],
          "notEq": "text",
          "notIn": [
            "text"
          ]
        },
        "or": "[Circular Reference]",
        "recordRef": {
          "eq": "text",
          "in": [
            "text"
          ],
          "notEq": "text",
          "notIn": [
            "text"
          ]
        },
        "tenantRecordId": {
          "eq": "text",
          "in": [
            "text"
          ],
          "notEq": "text",
          "notIn": [
            "text"
          ]
        },
        "values": {
          "contains": {
            "attributeId": {
              "eq": "text",
              "in": [
                "text"
              ],
              "notEq": "text",
              "notIn": [
                "text"
              ]
            },
            "attributeValue": {
              "eq": "text",
              "in": [
                "text"
              ],
              "notEq": "text",
              "notIn": [
                "text"
              ]
            }
          }
        }
      }
    ],
    "recordRef": {
      "eq": "text",
      "in": [
        "text"
      ],
      "notEq": "text",
      "notIn": [
        "text"
      ]
    },
    "tenantRecordId": {
      "eq": "text",
      "in": [
        "text"
      ],
      "notEq": "text",
      "notIn": [
        "text"
      ]
    },
    "values": {
      "contains": {
        "attributeId": {
          "eq": "text",
          "in": [
            "text"
          ],
          "notEq": "text",
          "notIn": [
            "text"
          ]
        },
        "attributeValue": {
          "eq": "text",
          "in": [
            "text"
          ],
          "notEq": "text",
          "notIn": [
            "text"
          ]
        }
      }
    }
  },
  "size": 1
}

{
  "lookupRecordItems": [
    {
      "id": "text",
      "recordRef": "text",
      "tenantRecordId": "text",
      "values": {
        "attributeId": "text",
        "attributeValue": "text"
      }
    }
  ],
  "pageInfo": {
    "endCursor": "text",
    "hasNextPage": true,
    "hasPreviousPage": true,
    "startCursor": "text"
  },
  "total": 1
}