<!-- Extension API v0 — pre-1.0. Interfaces may change without notice until P2 seals the custom-code format. First-party extensions track HEAD. -->

# `order.import`

Import a marketplace order (one per external order number) with its packages — paid, never refused for stock (oversold instead).

- **scope**: `orders:write`
- **storefront-visible** (bumps the catalog generation): no
- **destructive**: no

## Payload

| field | type | required | notes |
|---|---|---|---|
| `orderId` | string (/^ord_[a-zA-Z0-9]{1,32}$/) | yes |  |
| `customerId` | string (/^cus_[a-zA-Z0-9]{1,32}$/) | yes |  |
| `paymentId` | string (/^pay_[a-zA-Z0-9]{1,32}$/) | yes |  |
| `channel` | string (/^[a-z0-9_]{2,24}$/) | yes |  |
| `extensionId` | const "manual" \| string (/^[a-z0-9-]+\.[a-z0-9-]+$/) | yes |  |
| `channelRef` | string (≤64 chars) | yes |  |
| `test` | boolean | yes |  |
| `placedAt` | string | yes |  |
| `email` | string (/^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$/, ≤200 chars) | yes |  |
| `emailNorm` | string (≤200 chars) | yes |  |
| `phone` | string (≤20 chars) | yes |  |
| `billingAddress` | object | yes | canonical-il address (M6 cargo keys on il_plaka) |
| `  name` | string (≤120 chars) | yes |  |
| `  il` | string (≤40 chars) | yes |  |
| `  il_plaka` | string (/^\d{2}$/) | yes |  |
| `  ilce` | string (≤60 chars) | yes |  |
| `  address` | string (≤500 chars) | yes |  |
| `shippingAddress` | object \| null | yes |  |
| `requiresShipping` | boolean | yes |  |
| `lines` | array<object> (≤50) | yes |  |
| `totals` | object | yes |  |
| `  itemsSubtotalKurus` | integer (0..10000000000000) | yes |  |
| `  shippingKurus` | integer (0..10000000000000) | yes |  |
| `  discountKurus` | integer (0..10000000000000) | yes |  |
| `  totalKurus` | integer (0..10000000000000) | yes |  |
| `saleUrl` | string (≤300 chars) | yes |  |
| `externalRef` | string (≤64 chars) | no |  |
| `buyerIdentity` | string (/^\d{11}$/) | no |  |
| `packages` | array<object> (≤20) | yes |  |

### JSON Schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "orderId": {
      "type": "string",
      "pattern": "^ord_[a-zA-Z0-9]{1,32}$"
    },
    "customerId": {
      "type": "string",
      "pattern": "^cus_[a-zA-Z0-9]{1,32}$"
    },
    "paymentId": {
      "type": "string",
      "pattern": "^pay_[a-zA-Z0-9]{1,32}$"
    },
    "channel": {
      "type": "string",
      "pattern": "^[a-z0-9_]{2,24}$"
    },
    "extensionId": {
      "anyOf": [
        {
          "type": "string",
          "const": "manual"
        },
        {
          "type": "string",
          "pattern": "^[a-z0-9-]+\\.[a-z0-9-]+$"
        }
      ]
    },
    "channelRef": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64
    },
    "test": {
      "type": "boolean"
    },
    "placedAt": {
      "type": "string"
    },
    "email": {
      "type": "string",
      "maxLength": 200,
      "format": "email",
      "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
    },
    "emailNorm": {
      "type": "string",
      "maxLength": 200
    },
    "phone": {
      "type": "string",
      "minLength": 1,
      "maxLength": 20
    },
    "billingAddress": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 120
        },
        "il": {
          "type": "string",
          "minLength": 1,
          "maxLength": 40
        },
        "il_plaka": {
          "type": "string",
          "pattern": "^\\d{2}$"
        },
        "ilce": {
          "type": "string",
          "minLength": 1,
          "maxLength": 60
        },
        "address": {
          "type": "string",
          "minLength": 1,
          "maxLength": 500
        }
      },
      "required": [
        "name",
        "il",
        "il_plaka",
        "ilce",
        "address"
      ],
      "additionalProperties": {},
      "description": "canonical-il address (M6 cargo keys on il_plaka)"
    },
    "shippingAddress": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "minLength": 1,
              "maxLength": 120
            },
            "il": {
              "type": "string",
              "minLength": 1,
              "maxLength": 40
            },
            "il_plaka": {
              "type": "string",
              "pattern": "^\\d{2}$"
            },
            "ilce": {
              "type": "string",
              "minLength": 1,
              "maxLength": 60
            },
            "address": {
              "type": "string",
              "minLength": 1,
              "maxLength": 500
            }
          },
          "required": [
            "name",
            "il",
            "il_plaka",
            "ilce",
            "address"
          ],
          "additionalProperties": {},
          "description": "canonical-il address (M6 cargo keys on il_plaka)"
        },
        {
          "type": "null"
        }
      ]
    },
    "requiresShipping": {
      "type": "boolean"
    },
    "lines": {
      "minItems": 1,
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^oln_[a-zA-Z0-9]{1,32}$"
          },
          "productId": {
            "type": "string",
            "pattern": "^prd_[a-zA-Z0-9]{1,32}$"
          },
          "variantId": {
            "type": "string",
            "pattern": "^var_[a-zA-Z0-9]{1,32}$"
          },
          "qty": {
            "type": "integer",
            "minimum": 1,
            "maximum": 99
          },
          "title": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "variantTitle": {
            "type": "string",
            "minLength": 1,
            "maxLength": 120
          },
          "sku": {
            "type": "string",
            "minLength": 1,
            "maxLength": 80
          },
          "unitPriceKurus": {
            "type": "integer",
            "minimum": 0,
            "maximum": 10000000000000
          },
          "lineTotalKurus": {
            "type": "integer",
            "minimum": 0,
            "maximum": 10000000000000
          },
          "compareAtKurus": {
            "type": "integer",
            "minimum": 0,
            "maximum": 10000000000000
          },
          "lowest30dKurus": {
            "type": "integer",
            "minimum": 0,
            "maximum": 10000000000000
          },
          "requiresShipping": {
            "type": "boolean"
          },
          "withdrawalException": {
            "type": "string",
            "maxLength": 40
          },
          "exceptionAvailable": {
            "type": "boolean"
          },
          "taksitCapApplied": {
            "type": "integer",
            "minimum": 0,
            "maximum": 24
          }
        },
        "required": [
          "id",
          "productId",
          "qty",
          "title",
          "unitPriceKurus",
          "lineTotalKurus",
          "requiresShipping"
        ],
        "additionalProperties": false
      }
    },
    "totals": {
      "type": "object",
      "properties": {
        "itemsSubtotalKurus": {
          "type": "integer",
          "minimum": 0,
          "maximum": 10000000000000
        },
        "shippingKurus": {
          "type": "integer",
          "minimum": 0,
          "maximum": 10000000000000
        },
        "discountKurus": {
          "type": "integer",
          "minimum": 0,
          "maximum": 10000000000000
        },
        "totalKurus": {
          "type": "integer",
          "minimum": 0,
          "maximum": 10000000000000
        }
      },
      "required": [
        "itemsSubtotalKurus",
        "shippingKurus",
        "discountKurus",
        "totalKurus"
      ],
      "additionalProperties": false
    },
    "saleUrl": {
      "type": "string",
      "minLength": 1,
      "maxLength": 300
    },
    "externalRef": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64
    },
    "buyerIdentity": {
      "type": "string",
      "pattern": "^\\d{11}$"
    },
    "packages": {
      "minItems": 1,
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^pkg_[a-zA-Z0-9]{1,32}$"
          },
          "externalPackageId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 64
          },
          "externalOrderNo": {
            "type": "string",
            "minLength": 1,
            "maxLength": 64
          },
          "status": {
            "type": "string",
            "minLength": 1,
            "maxLength": 40
          },
          "statusNorm": {
            "type": "string",
            "enum": [
              "new",
              "preparing",
              "invoiced",
              "shipped",
              "delivered",
              "undelivered",
              "cancelled",
              "unsupplied",
              "returned",
              "split"
            ]
          },
          "createdBy": {
            "type": "string",
            "maxLength": 24
          },
          "agreedDeliveryAt": {
            "type": "string"
          },
          "commissionBp": {
            "type": "integer",
            "minimum": 0,
            "maximum": 10000
          },
          "estimate": {
            "default": {},
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {}
          },
          "cargo": {
            "default": {},
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {}
          },
          "lines": {
            "default": [],
            "maxItems": 50,
            "type": "array",
            "items": {
              "type": "object",
              "propertyNames": {
                "type": "string"
              },
              "additionalProperties": {}
            }
          },
          "payload": {
            "default": {},
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {}
          },
          "externalModifiedAt": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "externalPackageId",
          "externalOrderNo",
          "status",
          "statusNorm"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "orderId",
    "customerId",
    "paymentId",
    "channel",
    "extensionId",
    "channelRef",
    "test",
    "placedAt",
    "email",
    "emailNorm",
    "phone",
    "billingAddress",
    "shippingAddress",
    "requiresShipping",
    "lines",
    "totals",
    "saleUrl",
    "packages"
  ],
  "additionalProperties": false
}
```