Partner API Documentation
Paste into your AI agent and start building.
Before you can use the Alien Order Gateway API, you need to complete the following steps:
Register as a customer on our main website:
https://www.alienmilling.com/account/register
After creating your account, send an email to Saro to request API partner access. Include:
Once approved, you will receive:
The Alien Order Gateway API allows manufacturing partners to submit orders and receive fulfillment updates.
| Base URL | https://www.alienswagger.com |
|---|---|
| Protocol | HTTPS Required |
| Content Type | application/json |
| Rate Limit | 100 requests/minute, 1000 requests/hour |
The API enforces strict security controls to protect partner data:
Authorization: Bearer <token>All API requests require a Bearer token in the Authorization header.
Authorization: Bearer aln_your_api_token_here
Submit a new manufacturing order.
{
"partner_order_ref": "CUSTOMER-123-BATCH",
"shipping_address": {
"name": "Dr. John Smith",
"company": "Smile Dental Clinic",
"address1": "123 Main Street",
"address2": "Suite 100",
"city": "Los Angeles",
"province": "CA",
"postal_code": "90210",
"country": "US",
"phone": "+1-555-123-4567"
},
"line_items": [
{
"case_id": "John Doe #1234",
"product_id": "zirconia-crown",
"quantity": 1,
"shade": "A2",
"finishing_option_id": "high-polish",
"tooth_numbers": [14],
"notes": "Upper right molar",
"files": [
{ "url": "https://storage.com/case1/upper_scan.stl", "name": "case1_upper.stl" },
{ "url": "https://storage.com/case1/lower_scan.stl", "name": "case1_lower.stl" }
]
},
{
"case_id": "Jane Smith #5678",
"product_id": "zirconia-crown",
"quantity": 2,
"shade": "B1",
"tooth_numbers": [8, 9],
"notes": "Front teeth veneers",
"files": [
{ "url": "https://storage.com/case2/scan.stl", "name": "case2_scan.stl" }
]
}
]
}
| Field | Type | Required | Description |
|---|---|---|---|
partner_order_ref |
string | Optional | Your internal order reference |
shipping_address.name |
string | Required | Recipient name |
shipping_address.company |
string | Optional | Company/clinic name |
shipping_address.address1 |
string | Required | Street address |
shipping_address.address2 |
string | Optional | Apt, suite, unit, etc. |
shipping_address.city |
string | Required | City |
shipping_address.province |
string | Required | State/province code |
shipping_address.postal_code |
string | Required | ZIP/postal code |
shipping_address.country |
string | Required | ISO 2-letter country code |
line_items[].case_id |
string | Required | Your identifier for this case (patient name, ID, etc.) — appears on printed RX |
line_items[].product_id |
string | Required | Product ID from catalog |
line_items[].quantity |
number | Required | Number of units (≥ 1) |
line_items[].shade |
string | Conditional | Required if product has shades |
line_items[].finishing_option_id |
string | Optional | Finishing option ID |
line_items[].design_option_id |
string | Optional | Design service option ID (see Design Service) |
line_items[].tooth_numbers |
number[] | Optional | Specific tooth numbers |
line_items[].notes |
string | Optional | Special instructions for this case |
line_items[].files |
array | Required | Files for this case (STL scans, photos, etc.) |
line_items[].files[].url |
string | Required | Publicly accessible URL (http/https) |
line_items[].files[].name |
string | Optional | Filename hint |
Attach files to each line item (case). Files are organized in separate folders per case:
"line_items": [
{
"case_id": "Patient Name #123",
"product_id": "zirconia-crown",
"quantity": 1,
"shade": "A2",
"files": [
{ "url": "https://storage.com/case1/scan.stl", "name": "upper_arch.stl" }
]
}
]
Files are automatically renamed to include case details: {LineItem}_{CaseID}_{Shade}_{ToothNumbers}_{Filename}.ext
| Constraint | Value |
|---|---|
| Max files per order | 100 |
| Max file size | 100 MB per file |
| Download timeout | 5 minutes per file |
| Allowed types | STL, OBJ, PLY, 3MF, PDF, JPG, PNG, TIFF, ZIP |
{
"status": "success",
"alien_order_ref": "ALN-20240115-X7K9M2",
"files_queued": 3
}
The files_queued field indicates how many files are queued for download. Files are processed asynchronously after the order is created.
{
"status": "error",
"errors": [
"Line item 0: Invalid product_id 'invalid-sku'",
"Line item 1: Invalid shade 'ZZ' for product 'zirconia-crown'"
]
}
Some products offer optional design services for cases that require professional CAD/CAM design work. If your case requires design, you must select a design option and include the appropriate files.
Select a design option when:
When requesting design service, please include the following files with your case:
| File Type | Required | Description |
|---|---|---|
| Upper Arch Scan | Required | STL/PLY scan of the upper arch |
| Lower Arch Scan | Required | STL/PLY scan of the lower arch |
| Bite Registration | Recommended | Bite scan or bite registration photos |
| Scan Body (if applicable) | Conditional | For implant cases, include scan body scan |
| Photos | Optional | Shade reference photos, existing restorations |
{
"partner_order_ref": "DESIGN-CASE-001",
"shipping_address": { ... },
"line_items": [
{
"case_id": "Patient Smith #1234",
"product_id": "zirconia-crown",
"quantity": 1,
"shade": "A2",
"design_option_id": "full-design",
"tooth_numbers": [14],
"notes": "Please match existing crown on #15",
"files": [
{ "url": "https://storage.com/case/upper_arch.stl", "name": "upper_arch.stl" },
{ "url": "https://storage.com/case/lower_arch.stl", "name": "lower_arch.stl" },
{ "url": "https://storage.com/case/bite.stl", "name": "bite_registration.stl" },
{ "url": "https://storage.com/case/shade_photo.jpg", "name": "shade_reference.jpg" }
]
}
]
}
Products may offer different finishing options that affect the final appearance and surface quality of the restoration. When available, you can specify a finishing option for each line item.
| Option | Description | Best For |
|---|---|---|
| Standard | Basic finish with no additional polishing | Cases where you will do final finishing in-house |
| High Polish | Mirror-like polished surface | Anterior restorations, visible areas |
| Stain & Glaze | Custom staining and glazing for natural appearance | High-aesthetic anterior cases, matching adjacent teeth |
{
"partner_order_ref": "FINISH-CASE-001",
"shipping_address": { ... },
"line_items": [
{
"case_id": "Patient Jones #5678",
"product_id": "zirconia-crown",
"quantity": 1,
"shade": "A1",
"finishing_option_id": "stain-glaze",
"tooth_numbers": [8],
"notes": "Central incisor - please match shade to adjacent #9",
"files": [
{ "url": "https://storage.com/case/upper.stl", "name": "upper_arch.stl" },
{ "url": "https://storage.com/case/lower.stl", "name": "lower_arch.stl" },
{ "url": "https://storage.com/case/shade.jpg", "name": "shade_photo.jpg" }
]
}
]
}
You can specify both a design option and a finishing option for the same line item:
{
"case_id": "Patient Brown #9999",
"product_id": "zirconia-crown",
"quantity": 1,
"shade": "B1",
"design_option_id": "full-design",
"finishing_option_id": "high-polish",
"tooth_numbers": [14],
"files": [ ... ]
}
If you have multiple cases ready, batch them into a single order instead of submitting each one separately — every order carries its own shipping charge, so one order with several cases ships for the price of one.
When a new case is ready in your system, don't immediately call the API. Instead:
Here's a complete example of an order with 3 cases from the same customer, each with different products and their own files:
{
"partner_order_ref": "CUSTOMER-456-BATCH",
"shipping_address": {
"name": "Dr. Sarah Johnson",
"company": "Downtown Dental",
"address1": "500 Market Street",
"address2": "Suite 200",
"city": "San Francisco",
"province": "CA",
"postal_code": "94105",
"country": "US",
"phone": "+1-415-555-1234"
},
"line_items": [
{
"case_id": "Alice Johnson #1001",
"product_id": "zirconia-crown",
"quantity": 1,
"shade": "A2",
"finishing_option_id": "high-polish",
"tooth_numbers": [14],
"notes": "Upper right first premolar, patient prefers natural look",
"files": [
{ "url": "https://storage.example.com/case1/upper_arch.stl", "name": "upper_arch.stl" },
{ "url": "https://storage.example.com/case1/lower_arch.stl", "name": "lower_arch.stl" }
]
},
{
"case_id": "Bob Williams #1002",
"product_id": "pfm-crown",
"quantity": 2,
"shade": "B1",
"tooth_numbers": [8, 9],
"notes": "Central incisors, match existing laterals",
"files": [
{ "url": "https://storage.example.com/case2/anterior_scan.stl", "name": "anterior_scan.stl" },
{ "url": "https://storage.example.com/case2/photo.jpg", "name": "shade_reference.jpg" }
]
},
{
"case_id": "Carol Davis #1003",
"product_id": "zirconia-bridge",
"quantity": 1,
"shade": "A3",
"finishing_option_id": "stain-glaze",
"tooth_numbers": [18, 19, 20],
"notes": "Lower left bridge, pontic at #19",
"files": [
{ "url": "https://storage.example.com/case3/full_arch.stl", "name": "full_arch.stl" }
]
}
]
}
Files are automatically renamed to include case details for easy identification:
orders/Partner-Name/ALN-20240115-X7K9M2/
├── 1_Alice_Johnson_1001_A2_14_upper_arch.stl
├── 1_Alice_Johnson_1001_A2_14_lower_arch.stl
├── 2_Bob_Williams_1002_B1_8-9_anterior_scan.stl
├── 2_Bob_Williams_1002_B1_8-9_shade_reference.jpg
└── 3_Carol_Davis_1003_A3_18-19-20_full_arch.stl
Filename format: {LineItem}_{CaseID}_{Shade}_{ToothNumbers}_{OriginalFilename}.ext
A shipping fee is added to each order, based on the rates configured for your account. Because the fee is charged per order, batching multiple cases into one order is the easiest way to reduce shipping costs — see Batching Cases to Save on Shipping.
Retrieve the product catalog for reference. Use this to get valid product IDs, shades, finishing options, and current list prices.
price values are current list prices fetched live at the time of your request, and may change between calls. A null price means no charge is configured for that option. Partner-specific discounts are not reflected here - they are applied at invoicing.
{
"products": [
{
"id": "zirconia-crown",
"name": "Zirconia Crown",
"description": "High-strength zirconia crown",
"category": "crowns",
"price": 129.00,
"shades": ["A1", "A2", "A3", "A3.5", "B1", "B2", "C1", "D2"],
"finishing_options": [
{ "id": "standard", "name": "Standard Finish", "price": null },
{ "id": "high-polish", "name": "High Polish", "price": 15.00 },
{ "id": "stain-glaze", "name": "Stain & Glaze", "price": 25.00 }
],
"design_options": [
{ "id": "full-design", "name": "Full Design Service", "price": 35.00 },
{ "id": "design-review", "name": "Design Review Only", "price": null }
],
"metadata": {
"material": "Zirconia",
"translucency": "High",
"strengthMPa": 1200,
"yttriumContent": "3Y"
}
}
]
}
When configured, the gateway will send updates to your webhook endpoints. All webhooks are signed with HMAC-SHA256 for security.
Content-Type: application/json
X-Alien-Signature: <HMAC-SHA256 hex digest>
X-Alien-Timestamp: <ISO 8601 timestamp>
Verify webhooks by computing HMAC-SHA256 of the raw request body using your webhook secret:
const crypto = require('crypto');
function verifyWebhook(rawBody, signature, secret) {
const computed = crypto
.createHmac('sha256', secret)
.update(rawBody, 'utf8')
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(computed),
Buffer.from(signature)
);
}
// Express middleware example
app.post('/webhook', express.raw({ type: '*/*' }), (req, res) => {
const signature = req.headers['x-alien-signature'];
const isValid = verifyWebhook(req.body, signature, WEBHOOK_SECRET);
if (!isValid) {
return res.status(401).send('Invalid signature');
}
const payload = JSON.parse(req.body);
// Process webhook...
res.status(200).send('OK');
});
Sent when an order is shipped and tracking information is available.
{
"event_type": "tracking.created",
"timestamp": "2024-01-15T10:30:00Z",
"data": {
"alien_order_ref": "ALN-20240115-X7K9M2",
"partner_order_ref": "PO-12345",
"carrier": "FedEx",
"tracking_number": "794644790198",
"tracking_url": "https://www.fedex.com/fedextrack/?trknbr=794644790198",
"shipped_at": "2024-01-15T10:30:00Z"
}
}
Sent when order status changes (if status webhook URL is configured).
{
"event_type": "order.status_changed",
"timestamp": "2024-01-15T09:00:00Z",
"data": {
"alien_order_ref": "ALN-20240115-X7K9M2",
"partner_order_ref": "PO-12345",
"previous_status": "pending",
"status": "in_production"
}
}
| Status | Description |
|---|---|
pending |
Order received and validated |
validated |
Order accepted and scheduled for production |
in_production |
Order is being manufactured (auto-transitions during business hours: Mon-Fri 8am-2pm PST) |
shipped |
Order has been shipped (tracking info sent via webhook) |
delivered |
Order has been delivered |
cancelled |
Order was cancelled |
| Status | Meaning |
|---|---|
| 400 | Bad Request - Validation errors in request body |
| 401 | Unauthorized - Invalid or missing API token |
| 403 | Forbidden - Partner account is inactive |
| 429 | Too Many Requests - Rate limit exceeded |
| 500 | Internal Server Error - Contact support |
{
"status": "error",
"message": "Unauthorized"
}
{
"status": "error",
"message": "Access denied"
}
{
"status": "error",
"message": "Rate limit exceeded"
}