# Order with a custom file

For designers.

Prints your own .3mf or .stl on an order line instead of the variant's design, for example a keychain with a different name for every customer. Custom files are turned on per account: ask [contact@dapi.digital](mailto:contact@dapi.digital). The variant must be a single design, and its production price is what the line costs, so the file should weigh about the same as the design it replaces. Files are not reviewed or re-sliced: they go straight to production as sent.

## What you need

-   `variant` (string, required): The variant to print (`var_...`): yours, active, approved and a single design.
-   `file_name` (string, required): Name of the file to print, ending in `.3mf` or `.stl`, for example `keychain-anna.3mf`.
-   `content_type` (string, required): MIME type of the file: `model/3mf` or `model/stl`.
-   `size_bytes` (integer, required): Size of the file in bytes, up to 1 GiB.
-   `customer` (object, required): The recipient: `name`, `email` and optionally `phone`.
-   `shipping_address` (object, required): Where to ship: `line1`, `city`, `country_code` (ISO alpha-2) and optionally `line2`, `state`, `postal_code`.
-   `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: Start a file upload

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

Reserve an upload for the file to print, with purpose `order_file`. Then send the file bytes to `upload_url` with the returned `method` and `headers`. That transfer goes straight to storage, not to this API, so it is not a step here; do it before the next step.

**Request body**

```json
{
  "purpose": "order_file",
  "file_name": "$inputs.file_name",
  "content_type": "$inputs.content_type",
  "size_bytes": "$inputs.size_bytes"
}
```

Succeeds when:

-   `$statusCode == 201`

Keeps for the next steps:

-   `upload_id`: `$response.body#/id`

## Step 2: Create an order

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

Create and pay the order, the line naming the upload in `file`. Its `items[].custom_file` shows the file. `custom_files_not_enabled` (403) means custom files are not on for your account. `variant_not_orderable` (422) also covers a variant made of several designs; an upload that is unknown, expired, already used or not a real .3mf or .stl is refused with its own 422 code. `payment_failed` (402) means no order was created.

**Parameters**

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

**Request body**

```json
{
  "items": [
    {
      "variant": "$inputs.variant",
      "quantity": 1,
      "file": {
        "upload": "$steps.upload_file.outputs.upload_id"
      }
    }
  ],
  "customer": "$inputs.customer",
  "shipping_address": "$inputs.shipping_address"
}
```

Succeeds when:

-   `$statusCode == 201`

Otherwise:

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

Keeps for the next steps:

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

## As a workflow file

The workflow returns:

-   `order_id`: `$steps.create_order.outputs.order_id`
-   `number`: `$steps.create_order.outputs.number`
-   `total`: `$steps.create_order.outputs.total`

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 `order_with_custom_file` 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/order-with-custom-file. Index of every page: https://public-api.dapi.digital/docs/llms.txt.