Skip to main content

​
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_typeWhat it isInline children accepted
physicalStandalone stockable itempricing[], vendors[]
serviceNon-stockable service linepricing[], vendors[]
kitBill-of-materials assemblycomponents[], pricing[], vendors[]
boxPackaging unit (also a kit)components[], pricing[], vendors[]
variant_parentParent with multiple variantsvariants[], each variant may include components[], pricing[], vendors[]

​
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_ent_wss_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_ent_wss_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_ent_wss_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 every child hydrated inline: 
{
  "data": {
    "id": "prod_abc123",
    "title": "Riser Kit",
    "product_type": "variant_parent",
    "entity_id": "ent_wss_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:
FieldRequiredDescription
pricing_level_idYes (or account_id)The pricing level this tier applies to. Use GET /v1/pricing-levels to list available levels.
account_idYes (or pricing_level_id)Account-specific override price instead of a level-based price.
min_quantityNoThe minimum order quantity that activates this tier. Defaults to 1. Each tier must have a unique min_quantity within the same pricing_level_id scope.
list_priceNoThe sell price at this tier.
sell_priceNoExplicit sell price (overrides list_price if both provided).
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_ent_wss_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.

​
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_ent_wss_abc123" \
  -d '{
    "pricing_level_id": "pl_wholesale_uuid",
    "min_quantity": 1,
    "list_price": 42.00
  }'