# Choose the materials to print a quote in

For integrators.

Every extruder slot your file prints with needs a catalog material, and the print farm loads each one into its slot. When the quote is `ready`, `suggested_materials` lists those slots with the nearest catalog material to the colour and filament type in your file. Then either:

-   **Use the suggestions**: order with `use_suggested_materials: true`. Check `match` first: `approximate` means the catalog has nothing close to that colour (or the file gave none).
-   **Choose your own**: list the catalog (`color_hex` and `filament_type` help you match) and send `materials` as `[{ "slot": 2, "material": "mat_..." }]`, one entry for every slot in `suggested_materials`, no more and no fewer. A plain list of ids also works when the slots are 1, 2, 3... with no gaps.

This recipe orders in `wallet` mode; `checkout` mode takes the same `materials` and `use_suggested_materials` per line.

## What you need

-   `quote_id` (string, required): The quote to print (`qte_...`), from `quote_model_file`.
-   `use_suggested_materials` (boolean, required): True to print in the suggested materials; false to send your own in `materials`.
-   `materials` (array of object): Only when `use_suggested_materials` is false: `{ "slot": 1, "material": "mat_..." }` for every slot listed in the quote `suggested_materials`.
-   `quantity` (integer, required): How many units to print.
-   `shipping_address` (object, required): Where to ship: `line1`, `city`, `country_code` (ISO alpha-2) and optionally `line2`, `state`, `postal_code`.
-   `customer` (object, required): The recipient: `name`, `email` and optionally `phone`.
-   `idempotency_key` (string, required): A unique string for this attempt, for example a UUID. Send the same value when you retry, so the write happens once.

## Step 1: Get a quote

[GET `/v2/quotes/{id}`](https://public-api.dapi.digital/docs/reference/quotes.md#get_quote)

Read the quote. Once it is `ready`, `suggested_materials` has one entry per slot the file prints with: the `slot`, the `file_color` and `file_filament_type` your file gives it, the suggested `material` and how close the `match` is. It is null on quotes created before suggestions existed: send `materials` for those.

**Parameters**

```json
{
  "path id": "$inputs.quote_id"
}
```

Succeeds when:

-   `$statusCode == 200`
-   `$response.body#/status == 'ready'`

Otherwise:

-   `still_processing`: retry after 5 seconds, at most 120 times, when `$response.body#/status == 'processing'`.
-   `quote_failed`: stop the workflow when `$response.body#/status == 'failed'`.

Keeps for the next steps:

-   `suggested_materials`: `$response.body#/suggested_materials`

## Step 2: Order prints of your quotes

[POST `/v2/integrator/orders`](https://public-api.dapi.digital/docs/reference/integrator-orders.md#create_integrator_order)

Order in the suggested materials. `suggestions_unavailable` (422) means the quote has none: order with your own `materials` instead.

**Parameters**

```json
{
  "header Idempotency-Key": "$inputs.idempotency_key"
}
```

**Request body**

```json
{
  "mode": "wallet",
  "items": [
    {
      "quote": "$inputs.quote_id",
      "quantity": "$inputs.quantity",
      "use_suggested_materials": true
    }
  ],
  "shipping_address": "$inputs.shipping_address",
  "customer": "$inputs.customer"
}
```

Succeeds when:

-   `$statusCode == 201`

Otherwise:

-   `retry_server_error`: retry after 5 seconds, at most 3 times, when `$statusCode >= 500`.
-   `payment_failed`: stop the workflow when `$statusCode == 402`.
-   `material_slots_mismatch_or_not_orderable`: stop the workflow when `$statusCode == 422`.

Keeps for the next steps:

-   `order_id`: `$response.body#/id`
-   `number`: `$response.body#/number`
-   `material_slots`: `$response.body#/items/0/material_slots`
-   `total`: `$response.body#/charges/total`

## Step 3: List catalog materials

[GET `/v2/materials`](https://public-api.dapi.digital/docs/reference/materials.md#list_materials)

List the catalog to pick a material per slot. Each material has `color_hex` and `filament_type` to compare with the `file_color` and `file_filament_type` of each slot.

Succeeds when:

-   `$statusCode == 200`

Keeps for the next steps:

-   `materials`: `$response.body#/data`

## Step 4: Order prints of your quotes

[POST `/v2/integrator/orders`](https://public-api.dapi.digital/docs/reference/integrator-orders.md#create_integrator_order)

Order with one material per slot. `material_slots_mismatch` (422) means the slots sent are not the ones the file prints with: `details.expected_slots` lists them. `material_not_allowed` (422) names a material that is not in the catalog.

**Parameters**

```json
{
  "header Idempotency-Key": "$inputs.idempotency_key"
}
```

**Request body**

```json
{
  "mode": "wallet",
  "items": [
    {
      "quote": "$inputs.quote_id",
      "quantity": "$inputs.quantity",
      "materials": "$inputs.materials"
    }
  ],
  "shipping_address": "$inputs.shipping_address",
  "customer": "$inputs.customer"
}
```

Succeeds when:

-   `$statusCode == 201`

Otherwise:

-   `retry_server_error`: retry after 5 seconds, at most 3 times, when `$statusCode >= 500`.
-   `payment_failed`: stop the workflow when `$statusCode == 402`.
-   `material_slots_mismatch_or_not_orderable`: stop the workflow when `$statusCode == 422`.

Keeps for the next steps:

-   `order_id`: `$response.body#/id`
-   `number`: `$response.body#/number`
-   `material_slots`: `$response.body#/items/0/material_slots`
-   `total`: `$response.body#/charges/total`

## As a workflow file

Values starting with `$` are filled in as you go: `$inputs.x` is something you provide, `$steps.s.outputs.o` is a value an earlier step returned, and `$response.body#/path` a field of this response.

This recipe is the workflow `set_up_order_materials` of [arazzo.json](https://public-api.dapi.digital/docs/arazzo.json), an [Arazzo 1.0](https://spec.openapis.org/arazzo/latest.html) document that tools and AI agents can follow step by step.

---

3DAPI API Docs. This page on the web: https://public-api.dapi.digital/docs/guides/set-up-order-materials. Index of every page: https://public-api.dapi.digital/docs/llms.txt.