Create Order - FlexPortal

Create an order

curl --request POST \
  --url https://api-eu.flexportal.io/v1/orders \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Tenant-ID: <tenant-id>' \
  --data '
{
  "orderType": "standard",
  "customer": {
    "email": "sarah.johnson@acmecorp.com",
    "firstName": "Sarah",
    "lastName": "Johnson",
    "company": "Acme Corporation",
    "phone": "+1-555-123-4567",
    "customerType": "business"
  },
  "billingAddress": {
    "contactName": "Sarah Johnson",
    "company": "Acme Corporation",
    "streetAddress": "123 Business Park Drive",
    "city": "San Francisco",
    "adminArea": "CA",
    "postalCode": "94105",
    "country": "US"
  },
  "shippingAddress": {
    "contactName": "Sarah Johnson",
    "company": "Acme Corporation",
    "streetAddress": "123 Business Park Drive",
    "city": "San Francisco",
    "adminArea": "CA",
    "postalCode": "94105",
    "country": "US"
  },
  "items": [
    {
      "sku": "MACBOOK-PRO-16-M3",
      "quantity": 5,
      "contractLength": 24
    },
    {
      "sku": "DELL-U2722D-MONITOR",
      "quantity": 5,
      "contractLength": 24
    }
  ],
  "notes": "IT department refresh - Q1 2025"
}
'

{
  "success": true,
  "message": "<string>",
  "orderId": "<string>",
  "order": {
    "orderId": "<string>",
    "tenantId": "<string>",
    "customer": {
      "customerId": "<string>",
      "email": "jsmith@example.com",
      "firstName": "<string>",
      "lastName": "<string>",
      "company": "<string>",
      "phone": "<string>",
      "customerType": "individual"
    },
    "billingAddress": {
      "contactName": "<string>",
      "streetAddress": "<string>",
      "city": "<string>",
      "country": "<string>",
      "company": "<string>",
      "buildingInfo": "<string>",
      "locality": "<string>",
      "adminArea": "<string>",
      "postalCode": "<string>"
    },
    "shippingAddress": {
      "contactName": "<string>",
      "streetAddress": "<string>",
      "city": "<string>",
      "country": "<string>",
      "company": "<string>",
      "buildingInfo": "<string>",
      "locality": "<string>",
      "adminArea": "<string>",
      "postalCode": "<string>"
    },
    "items": [
      {
        "sku": "<string>",
        "productName": "<string>",
        "quantity": 2,
        "unitPrice": 1,
        "contractLength": 123,
        "productId": "<string>",
        "productImageUrl": "<string>",
        "variantId": "<string>",
        "listPrice": 1,
        "listPriceSource": "unknown",
        "acquisitionCost": 1,
        "acquisitionCostSource": "unknown",
        "listPriceOverride": 1,
        "acquisitionCostOverride": 1,
        "usedListPriceAsAcquisition": false,
        "rentalIds": [],
        "rentalStatus": "pending"
      }
    ],
    "totals": {
      "subtotal": 1,
      "total": 1,
      "currency": "<string>",
      "totalDevices": 2,
      "taxAmount": 0
    },
    "rentalProgress": {
      "totalDevices": 1,
      "rentedDevices": 1
    },
    "rentalIds": [
      "<string>"
    ],
    "createdAt": "<string>",
    "updatedAt": "<string>",
    "createdBy": "<string>",
    "payment": {
      "transactionId": "<string>",
      "paidAmount": 1,
      "manuallyMarked": false
    },
    "customFields": {},
    "billingGroupId": "<string>",
    "trackingNumber": "<string>",
    "shippedAt": "<string>",
    "notes": "<string>",
    "extensionDetails": {
      "originalOrderId": "<string>",
      "extensionMonths": 123,
      "previousEndDate": "<string>",
      "newEndDate": "<string>",
      "reason": "<string>"
    },
    "upgradeDetails": {
      "previousDevice": "<string>",
      "previousSerialNumber": "<string>",
      "previousMonthlyAmount": 123,
      "previousRentalId": "<string>",
      "upgradeReason": "<string>"
    }
  }
}

POST

orders

Create an order

curl --request POST \
  --url https://api-eu.flexportal.io/v1/orders \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Tenant-ID: <tenant-id>' \
  --data '
{
  "orderType": "standard",
  "customer": {
    "email": "sarah.johnson@acmecorp.com",
    "firstName": "Sarah",
    "lastName": "Johnson",
    "company": "Acme Corporation",
    "phone": "+1-555-123-4567",
    "customerType": "business"
  },
  "billingAddress": {
    "contactName": "Sarah Johnson",
    "company": "Acme Corporation",
    "streetAddress": "123 Business Park Drive",
    "city": "San Francisco",
    "adminArea": "CA",
    "postalCode": "94105",
    "country": "US"
  },
  "shippingAddress": {
    "contactName": "Sarah Johnson",
    "company": "Acme Corporation",
    "streetAddress": "123 Business Park Drive",
    "city": "San Francisco",
    "adminArea": "CA",
    "postalCode": "94105",
    "country": "US"
  },
  "items": [
    {
      "sku": "MACBOOK-PRO-16-M3",
      "quantity": 5,
      "contractLength": 24
    },
    {
      "sku": "DELL-U2722D-MONITOR",
      "quantity": 5,
      "contractLength": 24
    }
  ],
  "notes": "IT department refresh - Q1 2025"
}
'

{
  "success": true,
  "message": "<string>",
  "orderId": "<string>",
  "order": {
    "orderId": "<string>",
    "tenantId": "<string>",
    "customer": {
      "customerId": "<string>",
      "email": "jsmith@example.com",
      "firstName": "<string>",
      "lastName": "<string>",
      "company": "<string>",
      "phone": "<string>",
      "customerType": "individual"
    },
    "billingAddress": {
      "contactName": "<string>",
      "streetAddress": "<string>",
      "city": "<string>",
      "country": "<string>",
      "company": "<string>",
      "buildingInfo": "<string>",
      "locality": "<string>",
      "adminArea": "<string>",
      "postalCode": "<string>"
    },
    "shippingAddress": {
      "contactName": "<string>",
      "streetAddress": "<string>",
      "city": "<string>",
      "country": "<string>",
      "company": "<string>",
      "buildingInfo": "<string>",
      "locality": "<string>",
      "adminArea": "<string>",
      "postalCode": "<string>"
    },
    "items": [
      {
        "sku": "<string>",
        "productName": "<string>",
        "quantity": 2,
        "unitPrice": 1,
        "contractLength": 123,
        "productId": "<string>",
        "productImageUrl": "<string>",
        "variantId": "<string>",
        "listPrice": 1,
        "listPriceSource": "unknown",
        "acquisitionCost": 1,
        "acquisitionCostSource": "unknown",
        "listPriceOverride": 1,
        "acquisitionCostOverride": 1,
        "usedListPriceAsAcquisition": false,
        "rentalIds": [],
        "rentalStatus": "pending"
      }
    ],
    "totals": {
      "subtotal": 1,
      "total": 1,
      "currency": "<string>",
      "totalDevices": 2,
      "taxAmount": 0
    },
    "rentalProgress": {
      "totalDevices": 1,
      "rentedDevices": 1
    },
    "rentalIds": [
      "<string>"
    ],
    "createdAt": "<string>",
    "updatedAt": "<string>",
    "createdBy": "<string>",
    "payment": {
      "transactionId": "<string>",
      "paidAmount": 1,
      "manuallyMarked": false
    },
    "customFields": {},
    "billingGroupId": "<string>",
    "trackingNumber": "<string>",
    "shippedAt": "<string>",
    "notes": "<string>",
    "extensionDetails": {
      "originalOrderId": "<string>",
      "extensionMonths": 123,
      "previousEndDate": "<string>",
      "newEndDate": "<string>",
      "reason": "<string>"
    },
    "upgradeDetails": {
      "previousDevice": "<string>",
      "previousSerialNumber": "<string>",
      "previousMonthlyAmount": 123,
      "previousRentalId": "<string>",
      "upgradeReason": "<string>"
    }
  }
}

Overview

Create a new subscription order for a customer. Orders capture the customer’s intent to subscribe to products—they don’t immediately create active subscriptions. After an order is created and confirmed, you’ll use the Create Subscription endpoint to fulfill order items.

Orders are the starting point for the subscription lifecycle. Think of them as “checkout transactions” that need to be fulfilled by creating subscriptions and assigning assets.

Order Types

Type	Description	When to use
`standard`	New subscription order	Default for new customers or new products
`extension`	Extend an existing subscription	Customer wants to keep device longer
`upgrade`	Replace with a different product	Customer wants a better/different device

Common Use Cases

E-commerce Integration

Create orders from your checkout flow when customers complete a subscription purchase

Sales Tool

Build internal tools for sales teams to create orders during customer calls

B2B Portal

Let business customers place bulk orders through a self-service portal

Migration

Import historical orders when migrating from another subscription platform

Minimal Request Example

The simplest order needs customer info, billing address, and at least one item:

{
  "customer": {
    "email": "john@example.com",
    "firstName": "John",
    "lastName": "Smith"
  },
  "billingAddress": {
    "contactName": "John Smith",
    "streetAddress": "123 Main Street",
    "city": "Amsterdam",
    "country": "Netherlands"
  },
  "items": [
    {
      "sku": "MACBOOK-PRO-16-M3",
      "quantity": 1
    }
  ]
}

The sku must match an active product variant in your catalog. The system automatically looks up pricing based on the variant’s configured rates.

Complete Request Example

For business customers with full details:

{
  "orderType": "standard",
  "customer": {
    "email": "procurement@acmecorp.com",
    "firstName": "Sarah",
    "lastName": "Johnson",
    "company": "Acme Corporation",
    "phone": "+31612345678",
    "customerType": "business"
  },
  "billingAddress": {
    "contactName": "Finance Department",
    "company": "Acme Corporation",
    "streetAddress": "456 Business Park",
    "buildingInfo": "Building A, 3rd Floor",
    "city": "Rotterdam",
    "postalCode": "3011 AA",
    "country": "Netherlands"
  },
  "shippingAddress": {
    "contactName": "Sarah Johnson",
    "company": "Acme Corporation",
    "streetAddress": "789 Office Plaza",
    "city": "Amsterdam",
    "postalCode": "1012 AB",
    "country": "Netherlands"
  },
  "items": [
    {
      "sku": "MACBOOK-PRO-16-M3",
      "quantity": 5,
      "contractLength": 24
    },
    {
      "sku": "IPAD-PRO-12-M2",
      "quantity": 3,
      "contractLength": 12
    }
  ],
  "customFields": {
    "purchaseOrderNumber": "PO-2025-001234",
    "costCenter": "IT-DEV-001"
  },
  "notes": "Rush delivery requested - new employee onboarding"
}

Customer Handling

When you create an order:

Existing customer (matching email): Order is linked to existing customer record
New customer: A new customer record is created automatically

The customer’s customerId is returned in the order response and can be used for future orders.

Address Fields

Both billingAddress and shippingAddress support these fields:

Field	Required	Description
`contactName`	Yes	Person to contact at this address
`streetAddress`	Yes	Street name and number
`city`	Yes	City name
`country`	Yes	Country name
`company`	No	Company name (for business addresses)
`buildingInfo`	No	Building, floor, suite details
`locality`	No	Neighborhood or district
`adminArea`	No	State, province, or region
`postalCode`	No	ZIP or postal code

If shippingAddress is not provided, the billingAddress will be used for shipping.

Custom Fields

Use customFields to store additional data specific to your business:

{
  "customFields": {
    "purchaseOrderNumber": "PO-2025-001234",
    "siebelId": "ACC-789456",
    "salesRep": "jane.doe@company.com",
    "department": "Engineering"
  }
}

Custom fields can be used for:

Purchase order numbers
CRM/ERP reference IDs
Cost centers or department codes
Sales attribution

Configure custom fields in Dashboard → Settings to make them searchable and filterable.

What Happens Next

After creating an order:

Order created with pending status
Review the order (manual or automated)
Confirm the order (updates to confirmed status)
Create subscriptions for each item using Create Subscription
Order fulfilled when all items have active subscriptions

Error Handling

Error Code	Cause	Solution
`VALIDATION_ERROR`	Missing required fields	Check `details` for specific field errors
`VARIANT_NOT_FOUND`	SKU doesn’t exist	Verify SKU against your product catalog
`VARIANT_INACTIVE`	SKU exists but is deactivated	Reactivate variant or use different SKU
`INVALID_CONTRACT_LENGTH`	Unsupported contract duration	Use a configured contract length (e.g., 12, 24, 36)

List Orders - View all orders
Get Order - Get order details
Create Subscription - Fulfill order items
List Products - Find valid SKUs

Authorizations

Authorization

string

header

required

API key obtained from FlexPortal dashboard

Headers

Tenant-ID

string

required

Your tenant identifier

Body

application/json

customer

object

required

Show child attributes

billingAddress

object

required

Show child attributes

items

object[]

required

Minimum array length: 1

Show child attributes

orderType

enum<string>

default:standard

Available options:

standard,

extension,

upgrade

extensionDetails

object

Show child attributes

upgradeDetails

object

Show child attributes

customFields

object

Show child attributes

shippingAddress

object

Show child attributes

notes

string

Response

Order created successfully

success

enum<boolean>

required

Available options:

true

message

string

required

orderId

string

required

order

object

required

Show child attributes

Get Order Cancel Order

​Overview

​Order Types

​Common Use Cases

E-commerce Integration

Sales Tool

B2B Portal

Migration

​Minimal Request Example

​Complete Request Example

​Customer Handling

​Address Fields

​Custom Fields

​What Happens Next

​Error Handling

​Related Endpoints

Authorizations

Headers

Body

Response

Overview

Order Types

Common Use Cases

Minimal Request Example

Complete Request Example

Customer Handling

Address Fields

Custom Fields

What Happens Next

Error Handling

Related Endpoints