Configure Stripe Products — www.iaptic.com

This guide explains how to configure your products and prices in Stripe to work seamlessly with iaptic.

flowchart LR
    subgraph Stripe Dashboard
        A["Create Product and Metadata"]:::highlight
        C["Configure Price(s)"]:::highlight
    end
    subgraph Iaptic
        D["Fetch Product & Price Data"]
    end
    subgraph Your Application
        E["Consume Product Info"]
    end
    A --> C
    C --> D
    D --> E
    
    classDef highlight stroke-width:2px;

Define Product Types

iaptic supports three primary product types:

Subscriptions (recurring payments)
Consumables (one-time purchases)
Non-Consumables (permanent one-time purchases)

Important: A product must be either subscription-only or one-time-only. Mixed pricing types are not supported by iaptic.

Stripe Metadata for Product Types

Add the following metadata in Stripe to categorize your products:

{
  "product_type": "paid subscription" | "consumable" | "non consumable"
}

If no type is specified:
- Products with recurring prices default to "paid subscription."
- Products with one-time prices default to "consumable."

Add Product Information

Use metadata to store additional, product-specific fields. These fields help iaptic—and your own application—know more about the product's features and usage limits.

Example metadata:

{
  "tier": "basic" | "premium" | "enterprise",
  "max_users": "5" | "unlimited",
  "features": "backup,api,support",
  "can_purchase": "true" | "false"
}

You will be able to retrieve product details (including metadata) from Iaptic in your code.

Tip: Keep metadata values as simple, consistent strings. Label your keys clearly so your team knows how each field is used.

Configure Prices

You can configure either subscription (recurring) or one-time prices in the Stripe Dashboard. Remember not to mix recurring and one-time prices on the same product.

Subscription Prices

To set up subscription pricing in Stripe:

Navigate to Products: Go to "Products" in your Stripe Dashboard.
Select a Product: Choose (or create) the product that should be sold on a subscription basis.
Add / Edit the Price: Click "Add Price" (or "Edit Price" if you already have one).
Select Pricing Model: Under "Pricing model," choose "Recurring."
Billing Details: Specify the billing interval (e.g., monthly or yearly) and the currency (e.g., USD).
Amount: Enter the price in the smallest currency unit (for USD, this is cents).
Save: Click "Save" to confirm your subscription price.

Note: Subscriptions are perfect for ongoing services or memberships where the user pays repeatedly over time.

One-time Prices

For a one-time purchase:

Navigate to Products: Go to "Products" in your Stripe Dashboard.
Select a Product: Pick (or create) a product intended for one-time purchases.
Add / Edit the Price: Click "Add Price."
Select Pricing Model: Under "Pricing model," choose "One-time."
Currency & Amount: Choose the currency (e.g., USD) and enter the price in the smallest currency unit.
Save: Click "Save" to finalize the one-time price.

Note: One-time prices work great for consumables (like credits) or non-consumable purchases (like lifetime access or permanent membership).

Control Visibility

Sometimes, you need to hide certain products from appearing in your app's catalog. You can achieve this in several ways:

Archive in Stripe
Archive to completely remove a product from your live catalog, in the Dashboard:
- Navigate to "Products"
- Select the product you want to archive
- Click "Archive"
Use Metadata
Add "can_purchase": "false" to prevent the product from appearing in your app's UI:
```
{
  "can_purchase": "false"
}
```
The app will still be able to get information about the product, but it will not be visible to the user. It's useful especially if you have active subscribers on this product: you can then show them information about their plan.

Client-side Filtering
Dynamically filter out hidden products user can purchase:

const availableProducts = products.filter(
  p => p.metadata?.can_purchase === 'true'
);

Example Configurations

Premium Subscription

Create a "Premium Plan" product with subscription pricing, with the following metadata:

{
  "metadata": {
    "product_type": "paid subscription",
    "tier": "premium",
    "features": "all",
    "max_users": "unlimited",
    "can_purchase": "true"
  }
}

Configure subscription prices in Stripe (e.g., monthly and yearly):

Monthly: $9.99/month
Yearly: $99.90/year

Credit Pack (Consumable)

Create a "1000 Credits" product for a one-time purchase, with the following metadata:

{
  "metadata": {
    "product_type": "consumable",
    "credits": "1000",
    "can_purchase": "true"
  }
}

Set a single one-time price in Stripe (e.g., $4.99).

Best Practices

Product Types
- Keep product types consistent based on how you plan to sell them (one-time vs. subscription).
- Avoid mixing subscription and one-time prices in a single product.
- Use explicit types in metadata to help your code handle them properly.
Metadata
- Standardize metadata keys across all products (e.g., tier, features, max_users).
- Document your metadata schema so team members know what each field does.
- Use string values for maximum compatibility.
Prices
- Normalize currency usage (smallest currency unit: e.g., cents for USD).
- Consider regional pricing if relevant to your market.
- Test trial periods carefully (for subscriptions).
Visibility
- Archive obsolete products to keep them out of the catalog.
- Toggle can_purchase in metadata to quickly hide/show products.
- Test your visibility workflow in development.

Troubleshooting

Product Not Appearing

Ensure the product is active in Stripe.
Check "can_purchase" is set to "true".
Make sure the price is set and active.
Verify product type and pricing logic.
Confirm there are no mixed price types.

Invalid Product Type

Double-check metadata spelling (e.g., "paid subscription" vs. "consumable").
Verify you haven't mixed subscription and one-time prices.
If corrupted, archive and re-create the product.

Price Issues

Confirm currency code (e.g., "usd").
Check the amount is in the smallest unit (cents).
Ensure the price is active in Stripe.
Validate recurring.interval is set correctly.

Testing Your Catalog

Before going live, we recommend thoroughly testing your Stripe product catalog and iaptic integration:

Check Product Types
- Ensure "product_type" metadata is correct ("paid subscription", "consumable", or "non consumable").
- Avoid accidental mixed pricing.
Verify Metadata
- Any custom fields (e.g., "can_purchase") should appear in your iaptic API responses.
- Properly "Save" changes in Stripe.
Confirm Visibility
- Archive products no longer in use.
- Fine-tune client-side filters using metadata.
- Make sure the product is marked "active" in Stripe if you want it available.
Test Purchases
- Use Stripe's Test Cards to simulate success/failure scenarios.
- Check that iaptic's getPurchases() reflects newly purchased items or subscriptions.
Webhook Validation
- If using Stripe webhooks with iaptic's validator, confirm events appear in Stripe Webhooks.
- Look for 2xx responses in your logs.

Common Issues

Product Type Mismatch

Ensure "product_type" is spelled correctly.
Confirm only one pricing model (recurring or one-time) is configured.

Missing Metadata

Remember to click "Save" in the Stripe Dashboard.
Keep metadata values simple—avoid nested objects.
Stripe imposes character limits on metadata fields.

Visibility Problems

Check product is "Active".
"can_purchase" must be "true" to show in your store.
Verify your front-end or iaptic filtering logic.

Price Issues

Enter the correct amount in cents (for USD).
Double-check the recurring.interval if it's a subscription.
Make sure one pricing approach (recurring or one-time) is used.

Additional Support

For further help:

Visit Iaptic's Webhook Documentation for purchase validation.
Refer to the Stripe Products API for advanced product setup.
Contact Iaptic Support if you need personalized assistance.