DOT API mental model

DOT turns a customer image into a dot painting kit.

Choose the API flow by the experience your B2B integration needs to provide.

Flow A: user provides image only Send the order with the image reference and DOT SKU.
Flow B: user knows what they buy from a preview Generate DOT previews first, then order the selected option.
Open exact API schema Jump to payloads

Two choices, one clear path

Choose the user experience first, then choose how the order is submitted. Testing endpoints are dry-run tools during integration, not a separate product flow.

1. Flow A or Flow B Flow A sends a DOT SKU with the image. Flow B creates previews first and orders the selected preview option.
2. Direct order or Draft + submit Direct order is one submit call. Draft + submit is for integrations that need a cart/review step before final submission.

Choose the user experience

This choice decides what data goes into line_items[]. It does not decide whether you submit as a draft or direct order.

Flow A: Order + image

For integrations where checkout or purchase happens first and MGE receives the DOT SKU plus customer image for production.

line_items[].asset_url
or asset_token from draft asset upload
GET /api/v1/account/brands/ GET /api/v1/products/types/DOT/ SKU format GET /api/v1/products/types/DOT/variants/ available DOT variants Attach customer image with asset_url or draft asset_token

Flow B: Preview => Order

For richer storefronts where the user chooses from generated previews before checkout. More user experience, more integration work.

line_items[].preview_option_id
GET /api/v1/account/brands/ POST /api/v1/preview/ GET /api/v1/preview/{preview_id}/ GET /api/v1/preview/{preview_id}/purchase-options/ Copy returned order_line into line_items[]

Choose the submission mode

After the line item is built from either source mode, submit it using one production path. Use test endpoints during integration checks.

Direct order

Use when the integration is ready to create the order in one request.

POST /api/v1/orders/
Testing tool
TEST POST /api/v1/orders/validate/

Draft + submit

Use when the integration needs a cart, review, asset upload, or checkout step before final submission.

POST /api/v1/order-drafts/ PATCH /api/v1/order-drafts/{id}/ POST /api/v1/order-drafts/{id}/submit/
Draft asset options for Flow A
POST /api/v1/order-drafts/{id}/assets/ upload image, returns asset_token POST /api/v1/order-drafts/{id}/assets/from-url/ register URL, returns asset_token
Preview option for Flow B
GET /api/v1/preview/{preview_id}/purchase-options/ returns order_line Use order_line.preview_option_id in line_items[]
Testing tool
TEST POST /api/v1/order-drafts/{id}/validate/

Payload examples

Flow A: Order + image

Create direct order with image URL

POST /api/v1/orders/ 
{
  "brand_id": 116,
  "line_items": [
    {
      "sku": "DOT/VF/40X50/W/BLACK/STD",
      "quantity": 1,
      "asset_url": "https://cdn.example.com/customer-photo.jpg",
      "asset_params": {
        "source_width": 3000,
        "source_height": 4000,
        "crop_mode": "auto_allowed"
      }
    }
  ],
  "shipping": {
    "name": "Customer Name",
    "email": "[email protected]",
    "phone": "+65 0000 0000",
    "street": "123 Example Street",
    "city": "Singapore",
    "zip": "000000",
    "country": "SG"
  }
}

Create draft order with uploaded image

POST /api/v1/order-drafts/ 
{
  "brand_id": 116,
  "line_items": []
}

POST /api/v1/order-drafts/{id}/assets/ (multipart/form-data)
[email protected]

PATCH /api/v1/order-drafts/{id}/
{
  "brand_id": 116,
  "line_items": [
    {
      "sku": "DOT/VF/40X50/W/BLACK/STD",
      "quantity": 1,
      "asset_token": "22222222-2222-2222-2222-222222222222",
      "asset_params": {
        "source_width": 3000,
        "source_height": 4000,
        "crop_mode": "auto_allowed"
      }
    }
  ],
  "shipping": {
    "name": "Customer Name",
    "email": "[email protected]",
    "phone": "+65 0000 0000",
    "street": "123 Example Street",
    "city": "Singapore",
    "zip": "000000",
    "country": "SG"
  }
}

Flow B: Preview => Order

Step 1: create preview

POST /api/v1/preview/ (multipart/form-data) 
brand_id=116
products=["DOT"]
comparison_count=1
auto_enhance=true
auto_crop=true
preferred_size="40X50"
preview_options={"DOT":[{"variant":"source"},{"variant":"drama"}]}

Step 2: fetch purchase options

GET /api/v1/preview/{preview_id}/purchase-options/ 
{
  "preview_id": "00000000-0000-0000-0000-000000000000",
  "purchase_options": [
    {
      "preview_option_id": "11111111-1111-1111-1111-111111111111",
      "order_line": {
        "sku": "DOT/VF/40X50/W/BLACK/STD",
        "quantity": 1,
        "preview_option_id": "11111111-1111-1111-1111-111111111111"
      },
      "unit_price": "0.00",
      "currency": "EUR"
    }
  ]
}

Step 3A: create direct order from preview

POST /api/v1/orders/ 
{
  "brand_id": 116,
  "line_items": [
    {
      "sku": "DOT/VF/40X50/W/BLACK/STD",
      "quantity": 1,
      "preview_option_id": "11111111-1111-1111-1111-111111111111"
    }
  ],
  "shipping": {
    "name": "Customer Name",
    "email": "[email protected]",
    "phone": "+65 0000 0000",
    "street": "123 Example Street",
    "city": "Singapore",
    "zip": "000000",
    "country": "SG"
  }
}

Step 3B: create draft from preview

POST /api/v1/order-drafts/ 
{
  "brand_id": 116,
  "line_items": [
    {
      "sku": "DOT/VF/40X50/W/BLACK/STD",
      "quantity": 1,
      "preview_option_id": "11111111-1111-1111-1111-111111111111"
    }
  ],
  "shipping": {
    "name": "Customer Name",
    "email": "[email protected]",
    "phone": "+65 0000 0000",
    "street": "123 Example Street",
    "city": "Singapore",
    "zip": "000000",
    "country": "SG"
  }
}

POST /api/v1/order-drafts/{id}/submit/

Common mistakes

Preview option placement preview_option_id belongs inside the selected line item.
Don't
{
  "brand_id": 116,
  "preview_option_id": "1111...",
  "line_items": [
    {"sku": "DOT/VF/..."}
  ]
}
Do
{
  "brand_id": 116,
  "line_items": [
    {
      "sku": "DOT/VF/...",
      "preview_option_id": "1111..."
    }
  ]
}
Purchase option selection There is no submitted purchase_option_id. Copy the returned order_line.
Don't
{
  "line_items": [
    {"purchase_option_id": "po_123"}
  ]
}
Do
{
  "line_items": [
    {
      "sku": "DOT/VF/...",
      "quantity": 1,
      "preview_option_id": "1111..."
    }
  ]
}
Address field names Use MGE order fields, not storefront field names.
Don't
{
  "shipping": {
    "line1": "123 Example Street",
    "postal_code": "000000"
  }
}
Do
{
  "shipping": {
    "street": "123 Example Street",
    "zip": "000000"
  }
}
Source fields One line item uses one artwork source.
Don't
{
  "sku": "DOT/VF/...",
  "asset_url": "https://cdn.example.com/photo.jpg",
  "preview_option_id": "1111..."
}
Do
{
  "sku": "DOT/VF/...",
  "asset_url": "https://cdn.example.com/photo.jpg"
}

Full API documentation

This page is the visual DOT guide. Use Swagger for the full auto-updating endpoint schemas.