Product Metadata

Product Types Overview

While Stripe doesn't have a product type per say, as the same "product" can have both recurring and one-time prices, iaptic's Stripe integration requires you to fix the type of product to one of the following:

Type	Description	Use Case
paid subscription	Recurring payment	SaaS, memberships
consumable	One-time purchase, can buy multiple	Credits, tokens
non_consumable	One-time purchase, permanent	Lifetime access

Note
If no explicit product_type is set as metadata:

• Recurring prices default to a subscription (paid subscription).
• One-time prices default to a consumable.

Knowing the type will allow IapticJS to know how to handle the product, for instance consumables can be purchased multiple times, while non-consumable products can only be purchased once. Subscription products cannot be purchased while there's an active one.

Important:

• Mixed pricing (a single product with both recurring and one-time prices) is not supported.

To force the type of product, you can set the product_type metadata:

metadata: {
  product_type: 'paid subscription' | 'consumable' | 'non_consumable';
}

Feature Flags

Another use of metadata is to define feature flags. This is useful if you want to offer a product with different features, and let the user choose which features they want to purchase. Below is a list of examples of how you can define feature flags:

Standard Features

metadata: {
  features: string  // Comma-separated list
}

// Examples:
'api,backup,support'
'basic,advanced,pro'
'all'                // All features enabled

Usage Limits

metadata: {
  limits: {
    storage:  string, // e.g., '50GB'
    requests: string, // e.g., '1000/day'
    users:    string, // e.g., '5'
    projects: string   // e.g., '10'
  }
}

Visibility Control

Product Visibility

metadata: {
  can_purchase: 'true' | 'false'  // Control visibility
}

Best Practices

1. Product Types

   • Use explicit product types
   • Don't mix subscription and one-time prices
   • Keep types consistent

2. Metadata

   • Use string values for all metadata
   • Keep keys consistent
   • Document custom fields

3. Pricing

   • Use lowest currency unit (cents/pence)
   • Consider regional pricing
   • Plan trial periods carefully

4. Features

   • Use clear feature names
   • Document feature flags
   • Plan upgrade paths