API v1 preview

Cancel an order

POST/api/v1/orders/{order_id}/cancel

Overview

Cancel an awaiting-payment or confirmed order. Production dispatch is not enabled. If other active orders use its paid mesh repair, cancel those dependent orders first; otherwise 409 cancellation_unavailable is returned. Successful cancellation of a paid order refunds the full amount, including shipping; refunds can complete asynchronously. Repeated cancellation returns 409. After a lost response, retrieve the existing order.

Requires orders:write.

Order and payment guide Errors and retries

Request

#!/usr/bin/env bash
# Bash + curl + jq. Requires orders:write.
set -euo pipefail
: "${API_BASE_URL:?Set API_BASE_URL}"
: "${OTTOMFG_API_KEY:?Set OTTOMFG_API_KEY}"
: "${ORDER_ID:?Set ORDER_ID}"
# Optional key; this example saves one for safe retries within 24 hours.
: "${CANCEL_REQUEST_KEY:?Set a saved key for this request}"
body=$(jq -n  '{}')
result=$(curl --fail-with-body --silent --show-error --max-time 60 -X POST "${API_BASE_URL%/}/api/v1/orders/$ORDER_ID/cancel" \
  -H "Authorization: Bearer $OTTOMFG_API_KEY" \
  -H "Idempotency-Key: $CANCEL_REQUEST_KEY" \
  -H "Content-Type: application/json" --data "$body") || { printf '%s\n' "$result"; exit 1; }
printf '%s\n' "$result" | jq .

Set API_BASE_URL and OTTOMFG_API_KEY. Save request keys before creating an order or starting payment; reuse the same key and body on retry. See the guide for permissions and recovery.

Order setup and recovery

Parameters

order_id path · required

Public order ID returned in id; pass unchanged.

Immutable order ID and customer reference: OM- followed by eight uppercase Crockford Base32 characters. Pass it unchanged; there is no separate order-number field.

string

Idempotency-Key header · optional

Account, method and path scoped retry key, retained for 24 hours from first use. Same body replays the original successful status and body. A changed body returns 409 idempotency_key_reused; an in-flight request returns 409 idempotency_request_in_progress with Retry-After. Retry transient failures with the same key and body.

string

Request body

application/json

reason string · optional

Optional customer explanation.

Max length: 1000

Responses

HTTP status

Cancelled order.

200 response

JSON

{
  "id": "OM-XMF1NT2E",
  "created_at": "2026-09-18T18:00:00.000000Z",
  "quote_id": "quote_6c82bd3e319b4bb099310d54a761879e",
  "currency": "usd",
  "items": [
    {
      "model_id": "MD-739YQ549",
      "quantity": 2,
      "unit_price": 3000,
      "subtotal": 6000,
      "repair": {
        "required": false,
        "applied": false,
        "reason": null,
        "status": "not_applied",
        "fee": 0,
        "covered_by_order_id": null
      },
      "longest_dimension_mm": 100,
      "dimensions_mm": {
        "x": 50,
        "y": 100,
        "z": 40
      }
    }
  ],
  "shipping_address": {
    "name": "Alex Example",
    "company": "Example Retail",
    "line1": "123 Example Street",
    "city": "Seattle",
    "state": "WA",
    "postal_code": "98101",
    "country": "US"
  },
  "buyer": {
    "company": "Example Store",
    "email": "orders@example.com"
  },
  "shipping_option": {
    "id": "shipopt_6c82bd3e319b4bb099310d54a761879e",
    "name": "Standard",
    "totals": {
      "subtotal": 6000,
      "shipping": 1000,
      "total": 7000
    },
    "estimated_transit_business_days": {
      "min": 3,
      "max": 5
    },
    "estimated_delivery": null
  },
  "external_id": "checkout-123",
  "purchase_order_number": "PO-2026-0042",
  "metadata": {
    "project": "launch"
  },
  "updated_at": "2026-09-18T18:01:00.000000Z",
  "status": "cancelled",
  "events": [
    {
      "id": "evt_00000000000000000000000000000001",
      "sequence": 1,
      "type": "order.created",
      "at": "2026-09-18T18:00:00.000000Z",
      "reason": null,
      "data": {
        "status": "awaiting_payment"
      }
    },
    {
      "id": "evt_0000000000000000000000000000000c",
      "sequence": 2,
      "type": "order.cancelled",
      "at": "2026-09-18T18:01:00.000000Z",
      "reason": null,
      "data": {
        "previous_status": "awaiting_payment",
        "status": "cancelled"
      }
    }
  ],
  "estimated_ship_date": null,
  "estimated_delivery": null,
  "hold": null,
  "payment": {
    "status": "cancelled",
    "amount": 7000,
    "currency": "usd",
    "method": null,
    "paid_at": null,
    "receipt_url": null
  },
  "shipment": null,
  "pricing_version": "pv_2026_09_a",
  "preparation": {
    "status": "completed",
    "items": [
      {
        "model_id": "MD-739YQ549",
        "status": "completed",
        "longest_dimension_mm": 100
      }
    ]
  },
  "expires_at": null
}

Returns the Order object.

Response headers

X-Request-ID

Request identifier for support. Send X-Request-ID with 8–64 ASCII letters, digits or hyphens to reuse that value; otherwise the server generates a UUID4 hex value. Include the returned X-Request-ID in support requests. Do not put secrets or account IDs in this value.

Idempotent-Replayed

Present when the original successful response is replayed.

Errors

HTTP	Code	What to do
400 Bad Request	`invalid_argument`	A field, query parameter or header is invalid. Fix the field named in details, then send the request again.
401 Unauthorized	`unauthenticated`	The API key is missing, invalid or revoked. Send a valid business API key in Authorization: Bearer.
403 Forbidden	`permission_denied`	The key lacks the endpoint's scope, or payments lack spending consent. Check the scope listed on the endpoint.
404 Not Found	`order_not_found`	No order with this ID exists in the account. Check the ID.
409 Conflict	`cancellation_unavailable`	The order can no longer be cancelled, or other orders rely on its paid repair. Retrieve it to see its status.
409 Conflict	`idempotency_key_reused`	This Idempotency-Key was already used with a different body. Retry the original body, or use a new key for a new operation.
409 Conflict	`idempotency_request_in_progress`	A request with this Idempotency-Key is still running. Wait Retry-After seconds, then retry the same key and body.
413 Content Too Large	`request_too_large`	The JSON body is over this endpoint's size limit. Send a smaller body.
415 Unsupported Media Type	`unsupported_media_type`	The body is not JSON. Send Content-Type: application/json.
429 Too Many Requests	`resource_exhausted`	A rate or account limit was reached. Wait at least Retry-After seconds, then retry.
500 Internal Server Error	`internal`	The server failed unexpectedly. Retry with backoff; contact support with X-Request-ID if it persists.
503 Service Unavailable	`unavailable`	A required service is briefly unavailable. Retry with backoff, reusing the same Idempotency-Key.

Idempotent requests

API v1 preview