{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"24a413ca-60be-418f-b43c-6900692f9ee6","name":"Luxana Custom API","description":"# Luxana Custom API Documentation\n\n## Authentication\nAll requests require a Bearer token in the Authorization header:\n```\nAuthorization: Bearer lux-YOUR_API_TOKEN\n```\n\n## Base URL\n\n**Production:**\n```\nhttps://api.luxana.my\n```\n\n**Note:** All endpoints automatically include `/custom-api` prefix.\n\n## Rate Limits\n- Default: 60 requests/minute\n- 1000 requests/day\n\n## Endpoints\n\n### 1. Create Order\n**POST** `/v1/orders`\n\nCreate a new order in the Luxana system.\n\n---\n\n## Field Reference\n\n### Required Fields\n| Field | Type | Description | Example |\n|-------|------|-------------|----------|\n| `name` | string | Customer full name | \"John Doe\" |\n| `phone` | string | Customer phone (auto-formatted for MY) | \"60123456789\" or \"0123456789\" |\n| `address` | string | Street address | \"123 Main St\" |\n| `postcode` | string | Postal code | \"50000\" |\n| `city` | string | City name | \"Kuala Lumpur\" |\n| `state` | string | State (full name or code) | \"Selangor\" or \"SGR\" |\n| `country` | string | Country code (ISO 2-letter) | \"MY\", \"SG\", \"BN\" |\n| `items` | array | Order items (at least 1) | See Items section |\n| `selling_price` | number | Total order price | 150.00 |\n\n### Optional Fields\n| Field | Type | Description | Default | Example |\n|-------|------|-------------|---------|----------|\n| `address_2` | string | Additional address info | null | \"Unit 5A\" |\n| `email` | string | Customer email | null | \"john@example.com\" |\n| `payment_method` | string | Payment method (see enum) | Auto-detected by country | \"cod\" |\n| `shipping_method` | string | Shipping method (see enum) | Auto-detected by country | \"ninjavan\" |\n| `shipping_cost` | number | Shipping fee | 0 | 10.00 |\n| `cod_cost` | number | COD fee | 0 | 5.00 |\n| `awb_note` | string | Note for courier/AWB | null | \"Fragile - Handle with care\" |\n| `private_note` | string | Internal note | null | \"Customer prefers morning delivery\" |\n| `source_order_id` | string | Your external order reference | null | \"YOUR-ORDER-123\" |\n| `transaction_id` | string | Payment transaction ID | null | \"TXN-456789\" |\n\n---\n\n## Enums Reference\n\n### Payment Methods\n```json\n[\n  \"cod\",           // Cash on Delivery\n  \"cash\",          // Cash payment\n  \"bank_transfer\", // Bank transfer\n  \"billplz\",       // Billplz gateway\n  \"bizappay\",      // BizAppay gateway\n  \"chip\",          // Chip payment\n  \"chip_qr\",       // Chip QR code\n  \"chip_atome\",    // Chip Atome\n  \"chip_wallet\",   // Chip Wallet\n  \"chip_cc\",       // Chip Credit Card\n  \"toyyibpay\",     // ToyyibPay gateway\n  \"stripe\",        // Stripe\n  \"foc\"            // Free of Charge\n]\n```\n\n### Shipping Methods\n```json\n[\n  \"ninjavan\",      // Ninja Van\n  \"posmalaysia\",   // Pos Malaysia\n  \"jnt\",           // J&T Express\n  \"dhl\",           // DHL\n  \"aramex\",        // Aramex\n  \"redlyexpress\",  // Redly Express\n  \"self_pickup\"    // Self Pickup\n]\n```\n\n### States (Malaysia)\nAccepts **full name** or **code**:\n\n| Code | Full Name | Code | Full Name |\n|------|-----------|------|------------|\n| JHR | Johor | PHG | Pahang |\n| KDH | Kedah | PNG | Penang |\n| KTN | Kelantan | PRK | Perak |\n| MLK | Melaka | PLS | Perlis |\n| NSN | Negeri Sembilan | SBH | Sabah |\n| SGR | Selangor | SWK | Sarawak |\n| TRG | Terengganu | KUL | Kuala Lumpur |\n| PJY | Putrajaya | LBN | Labuan |\n\n### Countries\n```json\n[\n  \"MY\",  // Malaysia (default)\n  \"SG\",  // Singapore\n  \"BN\"   // Brunei\n]\n```\n\n---\n\n## Currency Handling\n\nCurrency is automatically determined by the `country` field and converted based on your company's currency rate settings.\n\n---\n\n## Items Array\n\nEach item must have:\n\n| Field | Type | Required | Description | Example |\n|-------|------|----------|-------------|----------|\n| `sku` | string | ✅ Yes | Product SKU (must exist in your catalog) | \"VA1\" |\n| `quantity` | number | ✅ Yes | Quantity (must be > 0) | 2 |\n\n**Example:**\n```json\n\"items\": [\n  { \"sku\": \"VA1\", \"quantity\": 2 },\n  { \"sku\": \"IM1\", \"quantity\": 1 }\n]\n```\n\n**Notes:**\n- SKU must exist in your product catalog (products or bundles)\n- Bundles are supported and automatically expanded\n- Stock is NOT validated at order creation\n\n---\n\n## Response Format\n\n### Success Response (201 Created)\n```json\n{\n  \"success\": true,\n  \"message\": \"Order created successfully\",\n  \"provider\": \"Luxana API v1\",\n  \"data\": {\n    \"order_id\": 141600,\n    \"status\": \"new\",\n    \"selling_price\": 150,\n    \"foreign_selling_price\": null,\n    \"currency\": \"MYR\",\n    \"exchange_rate_used\": 1,\n    \"created_at\": \"2025-10-31T08:12:05.803Z\",\n    \"source_order_id\": \"YOUR-ORDER-123\"\n  }\n}\n```\n\n### Error Responses\n\n**400 Bad Request** - Missing/invalid fields:\n```json\n{\n  \"success\": false,\n  \"error\": \"Missing required fields: name, phone, address, postcode, city, state, country\"\n}\n```\n\n**400 Bad Request** - Invalid SKU:\n```json\n{\n  \"success\": false,\n  \"error\": \"Item validation failed\",\n  \"message\": \"SKU \\\"INVALID\\\" not found in products or bundles\"\n}\n```\n\n**401 Unauthorized** - Invalid/missing token:\n```json\n{\n  \"success\": false,\n  \"error\": \"Invalid or expired token\"\n}\n```\n\n**403 Forbidden** - Insufficient permissions:\n```json\n{\n  \"success\": false,\n  \"error\": \"Insufficient permissions\",\n  \"message\": \"This API key does not have \\\"orders:write\\\" permission\"\n}\n```\n\n**429 Too Many Requests** - Rate limit exceeded:\n```json\n{\n  \"success\": false,\n  \"error\": \"Rate limit exceeded (per minute)\",\n  \"retry_after\": 45\n}\n```\n\n**500 Internal Server Error** - Server error:\n```json\n{\n  \"success\": false,\n  \"error\": \"Failed to create order\",\n  \"message\": \"Error details...\"\n}\n```\n\n---\n\n## Country-Specific Defaults\n\n### Malaysia (MY)\n- Payment & shipping methods: Based on your Luxana settings\n- Currency: `MYR`\n- Phone format: Auto-adds `60` prefix\n\n### Singapore (SG)\n- Payment & shipping methods: Based on your Luxana settings\n- Currency: `SGD` → converted to `MYR`\n\n### Brunei (BN)\n- Payment & shipping methods: Based on your Luxana settings\n- Currency: `BND` → converted to `MYR`\n\n---\n\n## Important Notes\n\n1. **Phone Formatting**: Malaysian phones are auto-formatted (0123456789 → 60123456789)\n2. **Currency Auto-Detection**: Currency is determined by `country` field (MY→MYR, SG→SGD, BN→BND)\n3. **Shipping Costs**: If not provided, calculated automatically based on your company's shipping settings\n4. **COD Costs**: If not provided, calculated automatically based on your company's COD settings\n5. **Product Total**: Automatically calculated as: `selling_price - shipping_cost - cod_cost`\n6. **Order Status**: All orders start with `new` status\n7. **Bundles**: Automatically expanded into individual items\n8. **Stock**: NOT validated at order creation (validated during fulfillment)\n\n---\n\n## Getting Your API Token\n\n1. Log in to Luxana dashboard\n2. Go to **Settings** → **Integrations** → **Custom API**\n3. Click **Create Integration**\n4. Copy your API token (starts with `lux-`)\n5. Store securely - cannot be retrieved later\n\n---\n\n## Testing\n\nUse the health check endpoint to verify API availability:\n\n**GET** `/v1/health`\n\nNo authentication required.\n\n**Response:**\n```json\n{\n  \"success\": true,\n  \"message\": \"Custom API is running\",\n  \"version\": \"1.0.0\",\n  \"timestamp\": \"2025-10-31T08:12:05.803Z\"\n}\n```","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"41483551","team":7608174,"collectionId":"24a413ca-60be-418f-b43c-6900692f9ee6","publishedId":"2sB3Wny3SG","public":true,"publicUrl":"https://documenter-api.postman.tech/view/41483551/2sB3Wny3SG","privateUrl":"https://go.postman.co/documentation/41483551-24a413ca-60be-418f-b43c-6900692f9ee6","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"documentationLayout":"classic-double-column","customisation":{"metaTags":[{"name":"description","value":""},{"name":"title","value":""}],"appearance":{"default":"light","themes":[{"name":"dark","logo":"https://content.pstmn.io/1db86167-0184-4d81-ab34-ed54aebfdfc9/bHV4YW5hbG9nb2JsYWNrLnBuZw==","colors":{"top-bar":"212121","right-sidebar":"303030","highlight":"FF6C37"}},{"name":"light","logo":"https://content.pstmn.io/1db86167-0184-4d81-ab34-ed54aebfdfc9/bHV4YW5hbG9nb2JsYWNrLnBuZw==","colors":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"}}]}},"version":"8.12.10","publishDate":"2025-10-31T12:38:15.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"","description":""},"logos":{"logoLight":"https://content.pstmn.io/1db86167-0184-4d81-ab34-ed54aebfdfc9/bHV4YW5hbG9nb2JsYWNrLnBuZw==","logoDark":"https://content.pstmn.io/1db86167-0184-4d81-ab34-ed54aebfdfc9/bHV4YW5hbG9nb2JsYWNrLnBuZw=="}},"statusCode":200},"environments":[],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/13ee6ca94ca2c1a83b229dc107f72c743eb1a70b4f2c9813670e09741647a11e","favicon":""},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"}],"canonicalUrl":"https://documenter.gw.postman.com/view/metadata/2sB3Wny3SG"}