Create Product Variant

Create a new product variant for a product in your easycart store.

Request

POST /products/{id}/variants

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Product UUID

Request Body

Parameter	Type	Required	Description
type	string	Yes	Variant type ("one_time" or "recurring")
name	string	No	Variant name (max 255 characters)
recurring_options	object	No	Recurring options (required if type is "recurring")
recurring_options.interval	string	No	Recurring interval ("day", "week", "month", "year")
recurring_options.interval_count	integer	No	Number of intervals between charges
amount	integer	Yes	Price in cents (minimum 0)
trial_period_days	integer	No	Trial period in days (min: 0, recurring variants only)
active_cycles	integer	No	Number of billing cycles (min: 1, recurring only)
is_hidden	boolean	No	Hide variant from checkout (default: false)
quantity	integer	No	Inventory limit (min: 0, null = unlimited)
has_quantity	boolean	No	Enable quantity selector (default: false)
old_price	integer	No	Strike-through price in cents (min: 0)
active_from	string	No	Start selling date (ISO 8601)
active_until	string	No	End selling date (ISO 8601, must be >= active_from)
tax_behavior	string	No	Tax handling ("inclusive" or "exclusive")

Example Request

curl -X POST "https://cart.easy.tools/api/v1/products/550e8400-e29b-41d4-a716-446655440000/variants" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "one_time",
    "name": "250g Package",
    "amount": 1999,
    "old_price": 2499,
    "quantity": 100,
    "has_quantity": true
  }'

curl -X POST "https://cart.easy.tools/api/v1/products/550e8400-e29b-41d4-a716-446655440000/variants" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "recurring",
    "name": "Monthly Subscription - 250g",
    "recurring_options": {
      "interval": "month",
      "interval_count": 1
    },
    "amount": 1799,
    "trial_period_days": 14,
    "active_cycles": 12,
    "tax_behavior": "inclusive"
  }'

Response

Success Response (201)

Returns the created product variant.

{
  "id": "550e8400-e29b-41d4-a716-446655440002",
  "type": "one_time",
  "recurring_options": null,
  "name": "250g Package",
  "amount": 1999
}

{
  "id": "550e8400-e29b-41d4-a716-446655440003",
  "type": "recurring",
  "recurring_options": {
    "interval": "month",
    "interval_count": 1
  },
  "name": "Monthly Subscription - 250g",
  "amount": 1799
}

Response Fields

Field	Type	Nullable	Description
id	string	No	Unique identifier for the product variant (UUID)
type	string	No	Variant type ("one_time" or "recurring")
recurring_options	object	Yes	Recurring options (null for one-time variants)
recurring_options.interval	string	No	Recurring interval ("day", "week", "month", "year")
recurring_options.interval_count	integer	No	Number of intervals between charges
name	string	Yes	Variant name
amount	integer	No	Price in cents

Error Responses

Product Not Found (404)

{
  "message": "Product with ID 550e8400-e29b-41d4-a716-446655440000 not found"
}

Validation Error (422)

{
  "message": "The given data was invalid.",
  "errors": {
    "type": [
      "The type field is required."
    ],
    "recurring_options": [
      "The recurring options field is required when type is recurring."
    ],
    "amount": [
      "The amount field is required."
    ]
  }
}