Create Product - FlexPortal

Create a product

curl --request POST \
  --url https://api-eu.flexportal.io/v1/products \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Tenant-ID: <tenant-id>' \
  --data '
{
  "productSku": "MACBOOK-PRO-16-M3",
  "name": "MacBook Pro 16\" M3 Pro",
  "category": "Laptops",
  "brand": "Apple",
  "specification": {
    "processor": "Apple M3 Pro",
    "memory": "18GB",
    "storage": "512GB SSD",
    "display": "16.2-inch Liquid Retina XDR"
  },
  "status": "active",
  "variants": [
    {
      "variantSku": "MACBOOK-PRO-16-M3-A",
      "variantName": "Grade A - Like New",
      "grade": "A",
      "listPrice": 2499,
      "acquisitionCost": 1800,
      "pricing": [
        {
          "contractLength": 12,
          "monthlyPrice": 149.99
        },
        {
          "contractLength": 24,
          "monthlyPrice": 99.99
        },
        {
          "contractLength": 36,
          "monthlyPrice": 79.99
        }
      ]
    },
    {
      "variantSku": "MACBOOK-PRO-16-M3-B",
      "variantName": "Grade B - Good",
      "grade": "B",
      "listPrice": 2199,
      "acquisitionCost": 1500,
      "pricing": [
        {
          "contractLength": 12,
          "monthlyPrice": 129.99
        },
        {
          "contractLength": 24,
          "monthlyPrice": 89.99
        },
        {
          "contractLength": 36,
          "monthlyPrice": 69.99
        }
      ]
    }
  ]
}
'

{
  "success": true,
  "message": "<string>",
  "productId": "<string>",
  "productSku": "<string>",
  "variantResults": [
    {
      "variantSku": "<string>"
    }
  ]
}

POST

products

Create a product

curl --request POST \
  --url https://api-eu.flexportal.io/v1/products \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Tenant-ID: <tenant-id>' \
  --data '
{
  "productSku": "MACBOOK-PRO-16-M3",
  "name": "MacBook Pro 16\" M3 Pro",
  "category": "Laptops",
  "brand": "Apple",
  "specification": {
    "processor": "Apple M3 Pro",
    "memory": "18GB",
    "storage": "512GB SSD",
    "display": "16.2-inch Liquid Retina XDR"
  },
  "status": "active",
  "variants": [
    {
      "variantSku": "MACBOOK-PRO-16-M3-A",
      "variantName": "Grade A - Like New",
      "grade": "A",
      "listPrice": 2499,
      "acquisitionCost": 1800,
      "pricing": [
        {
          "contractLength": 12,
          "monthlyPrice": 149.99
        },
        {
          "contractLength": 24,
          "monthlyPrice": 99.99
        },
        {
          "contractLength": 36,
          "monthlyPrice": 79.99
        }
      ]
    },
    {
      "variantSku": "MACBOOK-PRO-16-M3-B",
      "variantName": "Grade B - Good",
      "grade": "B",
      "listPrice": 2199,
      "acquisitionCost": 1500,
      "pricing": [
        {
          "contractLength": 12,
          "monthlyPrice": 129.99
        },
        {
          "contractLength": 24,
          "monthlyPrice": 89.99
        },
        {
          "contractLength": 36,
          "monthlyPrice": 69.99
        }
      ]
    }
  ]
}
'

{
  "success": true,
  "message": "<string>",
  "productId": "<string>",
  "productSku": "<string>",
  "variantResults": [
    {
      "variantSku": "<string>"
    }
  ]
}

Overview

Create a new product with one or more variants. Products are the foundation of your subscription catalog—they define what customers can subscribe to, at what prices, and with what configurations.

This endpoint uses upsert behavior: if a product with the same productSku already exists, it will be updated instead of creating a duplicate.

Common Use Cases

New Product Launch

Add new products to your catalog when expanding your offering

Integration Sync

Sync products from your e-commerce platform or inventory system

Catalog Migration

Migrate products from another subscription platform

Partner Catalog

Onboard products from new suppliers or partners

Minimal Request Example

Create a simple product with one variant:

{
  "productSku": "MACBOOK-PRO-16",
  "name": "MacBook Pro 16\"",
  "specification": "Apple Silicon laptop",
  "category": "Laptops",
  "brand": "Apple",
  "variants": [
    {
      "variantSku": "MACBOOK-PRO-16-M3-BASE",
      "variantName": "M3 Pro, 18GB RAM, 512GB SSD",
      "grade": "A",
      "listPrice": 2499.00,
      "acquisitionCost": 1800.00,
      "pricing": [
        { "contractLength": 12, "monthlyPrice": 159.00 },
        { "contractLength": 24, "monthlyPrice": 129.00 },
        { "contractLength": 36, "monthlyPrice": 109.00 }
      ]
    }
  ]
}

Complete Request Example

Product with multiple variants for different configurations:

{
  "productSku": "MACBOOK-PRO-16",
  "name": "MacBook Pro 16\"",
  "specification": "Apple Silicon laptop",
  "category": "Laptops",
  "brand": "Apple",
  "description": "Professional laptop for creative and development work",
  "images": ["https://example.com/images/macbook-pro-16.jpg"],
  "variants": [
    {
      "variantSku": "MACBOOK-PRO-16-M3-18GB-SILVER",
      "variantName": "M3 Pro, 18GB RAM, 512GB SSD",
      "grade": "A",
      "colorName": "Silver",
      "listPrice": 2499.00,
      "acquisitionCost": 1800.00,
      "pricing": [
        { "contractLength": 6, "monthlyPrice": 199.00 },
        { "contractLength": 12, "monthlyPrice": 159.00 },
        { "contractLength": 24, "monthlyPrice": 129.00 },
        { "contractLength": 36, "monthlyPrice": 109.00 }
      ]
    },
    {
      "variantSku": "MACBOOK-PRO-16-M3MAX-64GB-BLACK",
      "variantName": "M3 Max, 64GB RAM, 1TB SSD",
      "grade": "A",
      "colorName": "Space Black",
      "listPrice": 3999.00,
      "acquisitionCost": 2800.00,
      "pricing": [
        { "contractLength": 6, "monthlyPrice": 319.00 },
        { "contractLength": 12, "monthlyPrice": 249.00 },
        { "contractLength": 24, "monthlyPrice": 199.00 },
        { "contractLength": 36, "monthlyPrice": 169.00 }
      ]
    },
    {
      "variantSku": "MACBOOK-PRO-16-M3-18GB-SILVER-B",
      "variantName": "M3 Pro, 18GB RAM, 512GB SSD",
      "grade": "B",
      "colorName": "Silver",
      "listPrice": 2499.00,
      "acquisitionCost": 1500.00,
      "pricing": [
        { "contractLength": 12, "monthlyPrice": 139.00 },
        { "contractLength": 24, "monthlyPrice": 109.00 },
        { "contractLength": 36, "monthlyPrice": 89.00 }
      ]
    }
  ]
}

Product Fields

Field	Required	Description
`productSku`	Yes	Unique product identifier (parent SKU)
`name`	Yes	Display name
`specification`	Yes	Product specification/description
`category`	Yes	Product category (e.g., “Laptops”, “Phones”)
`brand`	Yes	Brand/manufacturer
`description`	No	Detailed product description
`images`	No	Array of product image URLs
`variants`	Yes	Array of variant configurations

Variant Fields

Field	Required	Description
`variantSku`	Yes	Unique variant SKU (used in orders)
`variantName`	Yes	Variant name/specification
`grade`	Yes	Condition: A, B, C, D, or E
`colorName`	No	Color option
`listPrice`	No	MSRP/retail price
`acquisitionCost`	No	Your cost to acquire
`pricing`	Yes	Array of pricing tiers (see below)

Pricing Array Format

Each pricing tier in the pricing array:

Field	Required	Description
`contractLength`	Yes	Contract duration in months (e.g., 12, 24, 36)
`monthlyPrice`	Yes	Monthly subscription price
`setupFee`	No	One-time setup fee
`discount`	No	Discount object with `type` (“percentage” or “fixed”) and `value`

Pricing Strategy

Set monthly prices based on your cost recovery goals:

// Example: Target 100% cost recovery in 24 months
const acquisitionCost = 1800;
const targetMonths = 24;
const marginPercent = 0.10; // 10% margin

const monthlyPrice = (acquisitionCost / targetMonths) * (1 + marginPercent);
// = 82.50/month for 24-month contract

Use shorter contract lengths for higher monthly prices (faster cost recovery) and longer contracts for lower monthly prices (better customer value).

Variant SKU Best Practices

Create predictable, searchable SKUs:

{PRODUCT}-{SPEC}-{CONFIG}-{GRADE}

Examples:
- MACBOOK-PRO-16-M3PRO-18GB-SILVER-A
- IPAD-PRO-12-M2-256GB-WIFI-B
- EBIKE-VANMOOF-S5-DARK-A

Upsert Behavior

When you create a product with an existing productSku:

Product fields are updated with new values
Existing variants (matching SKU) are updated
New variants (new SKU) are added
Missing variants (not in request) remain unchanged

To remove a variant, use the variant status update endpoint to set it to inactive. Variants are never automatically deleted.

Error Handling

Error Code	Cause	Solution
`VALIDATION_ERROR`	Missing required fields	Check `details` array for specific errors
`DUPLICATE_SKU`	Variant SKU already exists on different product	Use unique SKUs per variant
`INVALID_PRICING`	Pricing array is invalid	Each tier needs `contractLength` (integer) and `monthlyPrice` (number)

List Products - Browse catalog
Get Product - View product details
Update Product - Modify existing product
Import CSV - Bulk import products

Authorizations

Authorization

string

header

required

API key obtained from FlexPortal dashboard

Headers

Tenant-ID

string

required

Your tenant identifier

Body

application/json

productSku

string

required

Minimum string length: 1

name

string

required

Minimum string length: 1

specification

string

required

Minimum string length: 1

Response

Product created

success

enum<boolean>

required

Available options:

true

message

string

required

productId

string

required

productSku

string

required

operation

enum<string>

required

Available options:

created,

updated

variantResults

object[]

required

Show child attributes

List Variants Update Product

​Overview

​Common Use Cases

New Product Launch

Integration Sync

Catalog Migration

Partner Catalog

​Minimal Request Example

​Complete Request Example

​Product Fields

​Variant Fields

​Pricing Array Format

​Pricing Strategy

​Variant SKU Best Practices

​Upsert Behavior

​Error Handling

​Related Endpoints

Authorizations

Headers

Body

Response

Overview

Common Use Cases

Minimal Request Example

Complete Request Example

Product Fields

Variant Fields

Pricing Array Format

Pricing Strategy

Variant SKU Best Practices

Upsert Behavior

Error Handling

Related Endpoints