Creating Products, Kits, and Variants

The atomic-create principle

The Arcus Products API accepts the complete nested resource graph in a single POST. You express what you want; the API creates every child in one atomic transaction. If any child fails, the entire request rolls back — no orphan products, no partial state.

product_type discriminator

Every product has a product_type that controls which children are valid:

product_type	What it is	Inline children accepted
`physical`	Standalone stockable item	`pricing[]`, `vendors[]`
`service`	Non-stockable service line	`pricing[]`, `vendors[]`
`kit`	Bill-of-materials assembly	`components[]`, `pricing[]`, `vendors[]`
`box`	Packaging unit (also a kit)	`components[]`, `pricing[]`, `vendors[]`
`variant_parent`	Parent with multiple variants	`variants[]`, each variant may include `components[]`, `pricing[]`, `vendors[]`

Only title and product_type are required; a missing one returns 400 missing_required_field with the name in param. The key needs the products:write scope. A few rules apply to every type:

list_price, cost and last_purchase_price cannot be negative. A free item with a price of 0 is fine.
part_number must be unique among your active products; a repeat returns 409.
A service product never tracks inventory, whatever you send for track_inventory.

Full example: variant parent with kit variants

A “Riser Kit” with two kit variants — Dome and Flat — each with their own component assemblies, three qty-break pricing tiers, and a vendor assignment. One POST call.

curl -X POST https://api.arcuserp.com/v1/products \
  -H "Authorization: Bearer ark_live_abc123" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: riser-kit-2026-05-12-001" \
  -d '{
    "title": "Riser Kit",
    "product_type": "variant_parent",
    "description": "Modular riser kit with dome or flat options",
    "variants": [
      {
        "title": "Dome Riser Kit",
        "sku": "RISER-DOME",
        "product_type": "kit",
        "components": [
          {"component_product_id": "prod_stone_uuid", "quantity": 2},
          {"component_product_id": "prod_dome_lid_uuid", "quantity": 1}
        ],
        "pricing": [
          {"pricing_level_id": "pl_default_uuid", "min_quantity": 1,  "list_price": 49.99},
          {"pricing_level_id": "pl_default_uuid", "min_quantity": 5,  "list_price": 44.99},
          {"pricing_level_id": "pl_default_uuid", "min_quantity": 10, "list_price": 39.99}
        ],
        "vendors": [
          {"vendor_id": "acct_acme_uuid", "vendor_sku": "RD-001", "default_unit_cost": 18.00}
        ]
      },
      {
        "title": "Flat Riser Kit",
        "sku": "RISER-FLAT",
        "product_type": "kit",
        "components": [
          {"component_product_id": "prod_stone_uuid", "quantity": 2},
          {"component_product_id": "prod_flat_lid_uuid", "quantity": 1}
        ],
        "pricing": [
          {"pricing_level_id": "pl_default_uuid", "min_quantity": 1,  "list_price": 44.99},
          {"pricing_level_id": "pl_default_uuid", "min_quantity": 5,  "list_price": 39.99},
          {"pricing_level_id": "pl_default_uuid", "min_quantity": 10, "list_price": 34.99}
        ]
      }
    ],
    "vendors": [
      {"vendor_id": "acct_acme_uuid", "vendor_sku": "RISER-PARENT", "default_unit_cost": 15.00}
    ]
  }'

import Arcus from '@arcuserp/sdk';

const arcus = new Arcus({ apiKey: 'ark_live_abc123' });

const product = await arcus.products.create({
  title: 'Riser Kit',
  product_type: 'variant_parent',
  description: 'Modular riser kit with dome or flat options',
  variants: [
    {
      title: 'Dome Riser Kit',
      sku: 'RISER-DOME',
      product_type: 'kit',
      components: [
        { component_product_id: 'prod_stone_uuid', quantity: 2 },
        { component_product_id: 'prod_dome_lid_uuid', quantity: 1 },
      ],
      pricing: [
        { pricing_level_id: 'pl_default_uuid', min_quantity: 1,  list_price: 49.99 },
        { pricing_level_id: 'pl_default_uuid', min_quantity: 5,  list_price: 44.99 },
        { pricing_level_id: 'pl_default_uuid', min_quantity: 10, list_price: 39.99 },
      ],
      vendors: [
        { vendor_id: 'acct_acme_uuid', vendor_sku: 'RD-001', default_unit_cost: 18.00 },
      ],
    },
    {
      title: 'Flat Riser Kit',
      sku: 'RISER-FLAT',
      product_type: 'kit',
      components: [
        { component_product_id: 'prod_stone_uuid', quantity: 2 },
        { component_product_id: 'prod_flat_lid_uuid', quantity: 1 },
      ],
      pricing: [
        { pricing_level_id: 'pl_default_uuid', min_quantity: 1,  list_price: 44.99 },
        { pricing_level_id: 'pl_default_uuid', min_quantity: 5,  list_price: 39.99 },
        { pricing_level_id: 'pl_default_uuid', min_quantity: 10, list_price: 34.99 },
      ],
    },
  ],
  vendors: [
    { vendor_id: 'acct_acme_uuid', vendor_sku: 'RISER-PARENT', default_unit_cost: 15.00 },
  ],
}, {
  headers: { 'Idempotency-Key': 'riser-kit-2026-05-12-001' },
});

console.log(product.data.id);
console.log(product.data.variants[0].pricing[0].list_price); // 49.99 (number, not string)

import arcuserp

client = arcuserp.Arcus(api_key="ark_live_abc123")

product = client.products.create(
    title="Riser Kit",
    product_type="variant_parent",
    description="Modular riser kit with dome or flat options",
    variants=[
        {
            "title": "Dome Riser Kit",
            "sku": "RISER-DOME",
            "product_type": "kit",
            "components": [
                {"component_product_id": "prod_stone_uuid", "quantity": 2},
                {"component_product_id": "prod_dome_lid_uuid", "quantity": 1},
            ],
            "pricing": [
                {"pricing_level_id": "pl_default_uuid", "min_quantity": 1,  "list_price": 49.99},
                {"pricing_level_id": "pl_default_uuid", "min_quantity": 5,  "list_price": 44.99},
                {"pricing_level_id": "pl_default_uuid", "min_quantity": 10, "list_price": 39.99},
            ],
            "vendors": [
                {"vendor_id": "acct_acme_uuid", "vendor_sku": "RD-001", "default_unit_cost": 18.00},
            ],
        },
        {
            "title": "Flat Riser Kit",
            "sku": "RISER-FLAT",
            "product_type": "kit",
            "components": [
                {"component_product_id": "prod_stone_uuid", "quantity": 2},
                {"component_product_id": "prod_flat_lid_uuid", "quantity": 1},
            ],
            "pricing": [
                {"pricing_level_id": "pl_default_uuid", "min_quantity": 1,  "list_price": 44.99},
                {"pricing_level_id": "pl_default_uuid", "min_quantity": 5,  "list_price": 39.99},
                {"pricing_level_id": "pl_default_uuid", "min_quantity": 10, "list_price": 34.99},
            ],
        },
    ],
    vendors=[
        {"vendor_id": "acct_acme_uuid", "vendor_sku": "RISER-PARENT", "default_unit_cost": 15.00},
    ],
    extra_headers={"Idempotency-Key": "riser-kit-2026-05-12-001"},
)

print(product.data.id)
print(product.data.variants[0].pricing[0]["list_price"])  # 49.99 (float, not string)

The response includes the variants, the product-level pricing and vendors hydrated inline. For a kit or box, the components[] you send are created in the same transaction, but the create response does not echo them back; read them with GET /v1/products/{id}/components. Variant components are returned inside each variant, as below.

{
  "data": {
    "id": "prod_abc123",
    "title": "Riser Kit",
    "product_type": "variant_parent",
    "entity_id": "ent_abc",
    "variants": [
      {
        "id": "pv_dome_uuid",
        "title": "Dome Riser Kit",
        "sku": "RISER-DOME",
        "components": [
          { "id": "kc_uuid1", "component_product_id": "prod_stone_uuid", "quantity_per_kit": 2 },
          { "id": "kc_uuid2", "component_product_id": "prod_dome_lid_uuid", "quantity_per_kit": 1 }
        ],
        "pricing": [
          { "id": "pp_uuid1", "pricing_level_id": "pl_default_uuid", "qty_break": 1,  "list_price": 49.99 },
          { "id": "pp_uuid2", "pricing_level_id": "pl_default_uuid", "qty_break": 5,  "list_price": 44.99 },
          { "id": "pp_uuid3", "pricing_level_id": "pl_default_uuid", "qty_break": 10, "list_price": 39.99 }
        ],
        "vendors": [
          { "id": "pv_uuid1", "vendor_id": "acct_acme_uuid", "vendor_sku": "RD-001", "default_unit_cost": 18.00 }
        ]
      }
    ],
    "vendors": [
      { "id": "pv_parent_uuid", "vendor_id": "acct_acme_uuid", "vendor_sku": "RISER-PARENT" }
    ]
  }
}

Qty-break pricing with `pricing_level_id`

Each pricing[] element defines one row in a tiered price book:

Field	Required	Description
`pricing_level_id`	Yes (or `account_id`, or `is_default: true`)	The pricing level this tier applies to. Use `GET /v1/pricing-levels` (scope `pricing_levels:read`) to list available levels; each has an `id` you pass here.
`account_id`	Yes (or `pricing_level_id`, or `is_default: true`)	Account-specific override price instead of a level-based price.
`is_default`	No	When `true`, the tier is the product’s default price for customers with no level or account match, and it can stand alone without a level or account. Creating a new default demotes the previous default tier; the response names it in `demoted_default_policy_id`.
`min_quantity`	No	The minimum order quantity that activates this tier. Defaults to 1. It is stored and returned as `qty_break`.
`list_price`	No	The sell price at this tier.
`sell_price`	No	Explicit sell price (overrides `list_price` if both provided).
`pricing_type`	No	`regular` (the default) or `multiplier`. A multiplier tier takes its factor from `multiplier` or `adjustment`.
`margin_pct`, `adjustment`	No	A target margin or an adjustment amount, for the pricing types that use them.

An active tier is unique for its combination of product, variant, pricing level or account, and qty_break. Sending a second one returns 422 duplicate_pricing_policy_for_scope, with param: "qty_break" and the id of the existing tier in conflicting_policy_id; edit that tier or choose a different level, account or quantity. A pricing level or account that is not in your entity is refused. All money fields (list_price, sell_price, adjustment) are returned as JavaScript numbers (float), not strings.

Idempotency

Include Idempotency-Key: <your-unique-key> on every create call. Replaying the same key within 24 hours returns the original response without re-creating resources.

curl -X POST https://api.arcuserp.com/v1/products \
  -H "Idempotency-Key: order-import-batch-2026-05-12-row-42" \
  ...

Standalone kit (no variants)

curl -X POST https://api.arcuserp.com/v1/products \
  -H "Authorization: Bearer ark_live_abc123" \
  -d '{
    "title": "Dome Lid Assembly",
    "product_type": "kit",
    "sku": "DLA-001",
    "components": [
      {"component_product_id": "prod_dome_uuid", "quantity": 1},
      {"component_product_id": "prod_gasket_uuid", "quantity": 2}
    ],
    "pricing": [
      {"pricing_level_id": "pl_default_uuid", "min_quantity": 1, "list_price": 24.99}
    ]
  }'

Error handling

Validation errors return the exact param path so you know which field in which child failed:

{
  "error": "missing_required_field",
  "code": "missing_required_field",
  "type": "validation_error",
  "hint": "pricing_level_id or account_id is required for each pricing row.",
  "param": "variants[0].pricing[2].pricing_level_id"
}

Transactional rollback: if any child write fails, no rows are written. The response always reflects the full success or full failure state. The param path is prefixed with the child it belongs to, such as variants[0].pricing[2] or vendors[0].

Adding pricing tiers to an existing product

Use POST /v1/products/{id}/pricing to add tiers incrementally after creation:

curl -X POST https://api.arcuserp.com/v1/products/prod_abc123/pricing \
  -H "Authorization: Bearer ark_live_abc123" \
  -d '{
    "pricing_level_id": "pl_wholesale_uuid",
    "min_quantity": 1,
    "list_price": 42.00
  }'

The call needs products:write and returns 201 with the new tier in data: its id, product_id, pricing_level_id, qty_break, pricing_type, list_price, sell_price, is_default, and demoted_default_policy_id (null unless the new tier took over as default). A product that is not in your entity returns 404. Send variant_id to price one variant of a variant parent rather than the parent.

Get Started

Concepts

Guides

SDKs

Collections

Creating Products, Kits, and Variants

The atomic-create principle

product_type discriminator

Full example: variant parent with kit variants

Qty-break pricing with `pricing_level_id`

Idempotency

Standalone kit (no variants)

Error handling

Adding pricing tiers to an existing product

​The atomic-create principle

​product_type discriminator

​Full example: variant parent with kit variants

​Qty-break pricing with pricing_level_id

​Idempotency

​Standalone kit (no variants)

​Error handling

​Adding pricing tiers to an existing product

The atomic-create principle

product_type discriminator

Full example: variant parent with kit variants

Qty-break pricing with `pricing_level_id`

Idempotency

Standalone kit (no variants)

Error handling

Adding pricing tiers to an existing product