Get Product Variant

Retrieve a specific product variant from your store, including archived variants (status: archived). Lists stay published-only — see Status.

Unpublished overlay variants are not returned here — use Get Product Draft Variant.

Request

GET /product-variants/{id}

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Product variant UUID

Query Parameters

Parameter	Type	Required	Default	Description
include	string	No	—	custom_fields expands the stored override array. Unknown tokens are ignored. See Custom Fields.

Example Request

curl -X GET "https://cart.easy.tools/api/v1/product-variants/d91c65aa-b221-4aa4-b626-cf0d8a198749" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response

Success Response (200)

Returns a single product variant.

{
  "id": "d91c65aa-b221-4aa4-b626-cf0d8a198749",
  "status": "published",
  "type": "one_time",
  "recurring_options": null,
  "name": "250g Package",
  "amount": 1999,
  "currency": "usd",
  "checkout_url": "https://cart.easy.tools/checkout/premium-coffee?plan=price_123",
  "custom_id": "SKU-250G",
  "is_hidden": false,
  "trial_period_days": null,
  "active_cycles": null,
  "cancel_early": false,
  "keep_access_after_expiring": false,
  "allow_multiple_subscriptions": false,
  "active_days": 365,
  "quantity": 100,
  "has_quantity": true,
  "old_price": 29,
  "active_from": "2026-01-01T00:00:00+00:00",
  "active_until": "2026-12-31T23:59:59+00:00",
  "access_until": null,
  "show_active_until_counter": true,
  "tax_behavior": "exclusive",
  "refund_days": 14,
  "redirect_url": "https://mysite.com/thank-you",
  "redirect_time": 5,
  "file": {
    "name": "Product Guide.pdf",
    "url": "https://mysite.com/files/guide.pdf",
    "download_url": "https://cart.easy.tools/api/v1/product-files/b8d4e6a2-51c7-4f39-9e0b-3a7c2d18f5e6/download?expires=1749384000&signature=abc123"
  },
  "files": [
    {
      "name": "Product Guide.pdf",
      "url": "https://mysite.com/files/guide.pdf",
      "download_url": "https://cart.easy.tools/api/v1/product-files/b8d4e6a2-51c7-4f39-9e0b-3a7c2d18f5e6/download?expires=1749384000&signature=abc123"
    },
    {
      "name": "Quick Start.pdf",
      "url": "https://mysite.com/files/quick-start.pdf",
      "download_url": "https://cart.easy.tools/api/v1/product-files/2e9b5c71-8d40-4a6f-b312-7f5a9c04d8e3/download?expires=1749384000&signature=abc123"
    }
  ],
  "invoice_remarks": "Thank you for your purchase!",
  "has_shipping": false,
  "delivery_enabled": false,
  "delivery_service": null,
  "delivery_address_optional": true,
  "delivery_options": null,
  "shipping_phone_required": false,
  "phone_tooltip": null,
  "mandatory_consent": null,
  "optional_consent": null,
  "digital_consent": null,
  "newsletter_consent": null,
  "newsletter_consent_required": false,
  "newsletter_discount": null,
  "vat_rate": null,
  "gtu_code": null,
  "flat_rate": null,
  "exempt_tax_kind": null,
  "tax_category": null,
  "dashboard_header": null,
  "long_description": null,
  "cta_text": null,
  "cta_url": null,
  "credits": null,
  "show_net_price": false,
  "pay_what_you_want": null,
  "purchase_button_text": null,
  "upsells": [],
  "custom_fields": null
}

{
  "id": "e903c6d6-163e-4080-a99a-4ee5a1e4f17a",
  "status": "published",
  "type": "recurring",
  "recurring_options": {
    "interval": "month",
    "interval_count": 1
  },
  "name": "Monthly Subscription - 250g",
  "amount": 1799,
  "currency": "usd",
  "checkout_url": null,
  "custom_id": null,
  "is_hidden": false,
  "trial_period_days": 14,
  "active_cycles": 12,
  "cancel_early": true,
  "keep_access_after_expiring": false,
  "allow_multiple_subscriptions": false,
  "active_days": null,
  "quantity": null,
  "has_quantity": false,
  "old_price": null,
  "active_from": null,
  "active_until": null,
  "access_until": null,
  "show_active_until_counter": null,
  "tax_behavior": "exclusive",
  "refund_days": null,
  "redirect_url": null,
  "redirect_time": null,
  "file": null,
  "files": [],
  "invoice_remarks": null,
  "has_shipping": false,
  "delivery_enabled": false,
  "delivery_service": null,
  "delivery_address_optional": true,
  "delivery_options": null,
  "shipping_phone_required": false,
  "phone_tooltip": null,
  "mandatory_consent": null,
  "optional_consent": null,
  "digital_consent": null,
  "newsletter_consent": null,
  "newsletter_consent_required": false,
  "newsletter_discount": null,
  "vat_rate": null,
  "gtu_code": null,
  "flat_rate": null,
  "exempt_tax_kind": null,
  "tax_category": null,
  "dashboard_header": null,
  "long_description": null,
  "cta_text": null,
  "cta_url": null,
  "credits": null,
  "show_net_price": false,
  "pay_what_you_want": null,
  "purchase_button_text": null,
  "upsells": [],
  "custom_fields": null
}

An archived variant returns the same shape with status: archived. Lists and nested product variants omit it.

Response Fields

Field	Type	Nullable	Description
id	string	No	Unique identifier for the product variant (UUID)
status	string	No	Variant lifecycle (published or archived). Independent of product status and of is_hidden. See Status.
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 display name
amount	integer	No	Price in minor units
currency	string	No	Lowercase ISO currency code (e.g. "usd"). A variant inherits its product's currency. Immutable after create — see Immutable price fields.
checkout_url	string	Yes	Direct checkout URL for this variant (the product checkout URL with the variant preselected). Null until the variant is synced to Stripe. May still be present when status is archived — the variant is not sellable.
custom_id	string	Yes	External identifier for integration with other systems
is_hidden	boolean	No	Whether variant is hidden from checkout page. Independent of status — see Status.
trial_period_days	integer	Yes	Trial period in days before first charge (recurring only)
active_cycles	integer	Yes	Number of billing cycles for payment plans (null = unlimited)
cancel_early	boolean	No	Whether customers can cancel before active_cycles complete
keep_access_after_expiring	boolean	No	Whether access is kept after subscription ends
allow_multiple_subscriptions	boolean	No	Whether customers can have multiple concurrent subscriptions
active_days	integer	Yes	Access duration in days (null = unlimited)
quantity	integer	Yes	Available inventory limit (null = unlimited)
has_quantity	boolean	No	Whether quantity selector is enabled on checkout
old_price	integer	Yes	Struck-through compare-at price in major currency units (79 = 79.00 PLN). Unlike amount, which is in minor units (e.g. cents). See Price units.
active_from	string	Yes	Start selling date (ISO 8601 format)
active_until	string	Yes	Stop selling date (ISO 8601 format)
access_until	string	Yes	Fixed access-expiry date (ISO 8601 format). When set, active_until is never later than this date — see Access expiry modes
show_active_until_counter	boolean	Yes	Whether countdown timer is shown on checkout
tax_behavior	string	Yes	Tax behavior ("inclusive" or "exclusive")
refund_days	integer	Yes	Refund period in days (null = use product default)
redirect_url	string	Yes	Post-purchase redirect URL (null = use product default)
redirect_time	integer	Yes	Redirect delay in seconds (null = use product default)
file	object	Yes	First variant-specific downloadable file (null if none). Mirrors the first entry of files.
file.name	string	No	Display name shown in customer portal
file.url	string	No	The file's stored location, and the value to send back when writing files. A file uploaded to your store is not publicly readable at this URL — follow download_url for the contents. A file attached by link carries that URL exactly as it was provided.
file.download_url	string	Yes	A temporary signed link to download the file. It needs no Authorization header and expires about an hour after the read. null on a file that exists only on an unpublished overlay.
files	array	No	All variant-specific downloadable files (up to 5, empty if none). Each entry has name, url, and download_url.
invoice_remarks	string	Yes	Additional notes included on invoices
has_shipping	boolean	No	Stored flag for address collection on this variant. Checkout ORs this with the product — see Checkout overrides.
delivery_enabled	boolean	No	Stored flag for parcel delivery on this variant. Checkout ORs this with the product.
delivery_service	string	Yes	Carrier slug stored on this variant. null inherits the product unless this variant has delivery_enabled: true.
delivery_address_optional	boolean	No	Whether the delivery address is optional on this variant
delivery_options	object	Yes	Parcel package stored on this variant. See Delivery Options Object.
shipping_phone_required	boolean	No	Stored flag for a required shipping phone. Checkout ORs this with the product.
phone_tooltip	string	Yes	Helper text for the shipping phone field. null inherits the product.
mandatory_consent	string	Yes	Mandatory checkout consent label. null inherits the product.
optional_consent	string	Yes	Optional checkout consent label. null inherits the product.
digital_consent	string	Yes	Digital-content consent label. null inherits the product.
newsletter_consent	string	Yes	Newsletter opt-in label. null inherits the product.
newsletter_consent_required	boolean	No	Whether the newsletter opt-in is required on this variant
newsletter_discount	object	Yes	Discount stored on this variant. See Newsletter Discount Object. null inherits the product.
vat_rate	string	Yes	VAT rate stored on this variant. null inherits the product at checkout, not 0%. See Checkout overrides.
gtu_code	integer	Yes	GTU code 1–13 stored on this variant. null inherits the product.
flat_rate	number	Yes	Flat-rate tax percent stored on this variant. null inherits the product.
exempt_tax_kind	string	Yes	Exemption basis stored on this variant. null inherits the product.
tax_category	string	Yes	Tax category slug stored on this variant. Distinct from tax_behavior.
dashboard_header	string	Yes	Self-service portal header stored on this variant. Empty or null inherits the product.
long_description	string	Yes	Self-service portal body stored on this variant (max 500 characters).
cta_text	string	Yes	Self-service portal call-to-action label stored on this variant.
cta_url	string	Yes	Self-service portal call-to-action URL stored on this variant.
credits	integer	Yes	QR credits stored on this variant. null inherits the product, not zero. Maximum 4294967295.
show_net_price	boolean	No	Whether checkout shows the net price.
pay_what_you_want	object	Yes	Pay-what-you-want settings. See Pay What You Want Object. null means off.
purchase_button_text	string	Yes	Checkout purchase-button label (pay-what-you-want and lead magnet). Sibling of pay_what_you_want.
upsells	array	No	Same-product checkout upgrades. Always present ([] when none). See Upsell Object.
custom_fields	array	Yes	Checkout custom-field override. Always present. null unless include=custom_fields. Empty array means inherit the product collection. A non-empty array wholesale-replaces it for this price. See Custom Fields.

Read download_url — not url — to fetch a file's contents, and request the variant again for a fresh link rather than storing it. See Downloadable files.

note

The singular file field is kept for backward compatibility and always mirrors the first entry of files. For variants with multiple downloadable files, read files to get the complete list.

Error Responses

Bad Request (400)

{
  "message": "Invalid product variant ID"
}

Not Found Error (404)

{
  "message": "Product variant with ID d4e7a2c9-1b8f-4a3d-8c6e-7f2b9d5a1e63 not found"
}