Skip to main content
POST
/
v1
/
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>",
    "status": "pending",
    "orderType": "standard",
    "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": {
      "status": "pending",
      "method": "stripe",
      "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

TypeDescriptionWhen to use
standardNew subscription orderDefault for new customers or new products
extensionExtend an existing subscriptionCustomer wants to keep device longer
upgradeReplace with a different productCustomer 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:
  1. Existing customer (matching email): Order is linked to existing customer record
  2. 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:
FieldRequiredDescription
contactNameYesPerson to contact at this address
streetAddressYesStreet name and number
cityYesCity name
countryYesCountry name
companyNoCompany name (for business addresses)
buildingInfoNoBuilding, floor, suite details
localityNoNeighborhood or district
adminAreaNoState, province, or region
postalCodeNoZIP 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:
  1. Order created with pending status
  2. Review the order (manual or automated)
  3. Confirm the order (updates to confirmed status)
  4. Create subscriptions for each item using Create Subscription
  5. Order fulfilled when all items have active subscriptions

​
Error Handling

Error CodeCauseSolution
VALIDATION_ERRORMissing required fieldsCheck details for specific field errors
VARIANT_NOT_FOUNDSKU doesn’t existVerify SKU against your product catalog
VARIANT_INACTIVESKU exists but is deactivatedReactivate variant or use different SKU
INVALID_CONTRACT_LENGTHUnsupported contract durationUse a configured contract length (e.g., 12, 24, 36)

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
​
billingAddress
object
required
​
items
object[]
required
Minimum array length: 1
​
orderType
enum<string>
default:standard
Available options:
standard,
extension,
upgrade
​
extensionDetails
object
​
upgradeDetails
object
​
customFields
object
​
shippingAddress
object
​
notes
string

Response

Order created successfully

​
success
enum<boolean>
required
Available options:
true,
false
​
message
string
required
​
orderId
string
required
​
order
object
required