DBN API mental model

DBN turns a customer image into a diamond painting kit.

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

Flow A: user provides image only Send the order with the image reference and DBN SKU.
Flow B: user knows what they buy from a preview Generate DBN previews first, then order the selected preview 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 DBN 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, hosted checkout step, or draft asset upload 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 DBN 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/DBN/ SKU format GET /api/v1/products/types/DBN/variants/ available DBN variants Attach customer image with asset_url or draft asset_token

Flow B: Preview => Order

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

line_items[].preview_option_id
GET /api/v1/account/brands/ GET /api/v1/preview/options/ DBN preview option axes 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": "DBN/VF/40X50/COL30/SQRA/W/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 with uploaded image asset

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": "DBN/VF/40X50/COL30/SQRA/W/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"
  }
}

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

Flow B: Preview => Order

Step 1: discover DBN preview options

GET /api/v1/preview/options/?product=DBN 
{
  "products": {
    "DBN": {
      "request_field": "preview_options",
      "axes": [
        {"key": "diamond_type", "options": [{"value": "RNDA"}, {"value": "SQRA"}]},
        {"key": "max_colors", "options": [{"value": 30}, {"value": 50}]},
        {"key": "dither_mode", "options": [{"value": "zigzag"}]},
        {"key": "variant", "options": [{"value": "source"}, {"value": "drama"}]}
      ]
    }
  }
}

Step 2: create preview

POST /api/v1/preview/ (multipart/form-data) 
brand_id=116
products=["DBN"]
comparison_count=2
auto_enhance=true
auto_crop=true
preferred_size="40X50"
preview_options={"DBN":[{"diamond_type":"SQRA","max_colors":30,"dither_mode":"zigzag","variant":"source"},{"diamond_type":"SQRA","max_colors":50,"dither_mode":"zigzag","variant":"drama"}]}

Step 3: fetch purchase options

GET /api/v1/preview/{preview_id}/purchase-options/ 
{
  "preview_id": "00000000-0000-0000-0000-000000000000",
  "status": "COMPLETED",
  "purchase_options": [
    {
      "preview_option_id": "11111111-1111-1111-1111-111111111111",
      "product": "DBN",
      "label": "Square diamonds / approx. 30 colors / standard production",
      "order_line": {
        "sku": "DBN/VF/40X50/COL30/SQRA/W/STD",
        "quantity": 1,
        "preview_option_id": "11111111-1111-1111-1111-111111111111"
      },
      "unit_price": "0.00",
      "currency": "EUR"
    }
  ]
}

Step 4A: create direct order from preview

POST /api/v1/orders/ 
{
  "brand_id": 116,
  "line_items": [
    {
      "sku": "DBN/VF/40X50/COL30/SQRA/W/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 4B: create draft from preview and submit

POST /api/v1/order-drafts/ 
{
  "brand_id": 116,
  "line_items": [
    {
      "sku": "DBN/VF/40X50/COL30/SQRA/W/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": "DBN/VF/..."}
  ]
}
Do
{
  "brand_id": 116,
  "line_items": [
    {
      "sku": "DBN/VF/...",
      "preview_option_id": "1111..."
    }
  ]
}
Purchase option ID Do not invent or submit purchase_option_id. Copy the returned order_line.
Don't
{
  "line_items": [
    {"purchase_option_id": "po_123"}
  ]
}
Do
{
  "line_items": [
    {
      "sku": "DBN/VF/40X50/COL30/SQRA/W/STD",
      "quantity": 1,
      "preview_option_id": "1111..."
    }
  ]
}
Product SKU Use a DBN SKU for DBN orders. DOT SKU examples are not interchangeable.
Don't
{
  "sku": "DOT/VF/40X50/W/BLACK/STD"
}
Do
{
  "sku": "DBN/VF/40X50/COL30/SQRA/W/STD"
}
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": "DBN/VF/...",
  "asset_url": "https://cdn.example.com/photo.jpg",
  "preview_option_id": "1111..."
}
Do
{
  "sku": "DBN/VF/...",
  "asset_url": "https://cdn.example.com/photo.jpg"
}
DBN preview option axes preview_options.DBN[] needs all required DBN axes.
Don't
{
  "preview_options": {
    "DBN": [
      {"variant": "source"}
    ]
  }
}
Do
{
  "preview_options": {
    "DBN": [
      {
        "diamond_type": "SQRA",
        "max_colors": 30,
        "dither_mode": "zigzag",
        "variant": "source"
      }
    ]
  }
}
Testing endpoint as production step Validate endpoints are for dry-run integration checks. They are not required in every live order flow.
Don't
POST /api/v1/orders/validate/
POST /api/v1/orders/
Do
During integration: POST /api/v1/orders/validate/
Production submit:  POST /api/v1/orders/

Full API documentation

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