This page consolidates every Piano-to-Stripe mapping reference in one place: the conceptual entity/architecture mapping (which Piano concept corresponds to which Stripe object) and the field-level data mapping used when syncing Stripe data back into Piano.
Entity and architecture mapping
It is important to understand the difference between Stripe native Product catalog entities and Piano API level integration with Stripe Billing. Stripe provides more flexibility and functionality only via APIs which are used to map and integrate Piano term and subscription specifics. As per the mapping table below, you will notice that Piano term context is mapped to multiple entities instead of being represented as 1:1 term to price, therefore no Stripe catalog native price IDs are created or used, instead priceIDs are set via API which Stripe interface shows as "archived". This is expected system behavior on API level integrations.
|
CORE ENTITY MAPPING |
|||
|
Piano Entity |
Stripe Entity |
Mapping Strategy |
1:1 Relationship |
|
Piano App |
Stripe Account |
Connected Account |
Yes |
|
Piano User |
Stripe Customer |
1:1 with multi-currency exception |
Multi-currency = Multiple Customers in Stripe |
|
Piano Subscription |
Stripe Subscription + Schedule |
Subscription Schedules with phases |
Yes |
|
Piano Term |
Stripe Price data |
Piano-native pricing generating price_data |
Yes |
|
Piano Resource |
Stripe Product |
Resource mapping to product |
Yes |
|
Piano Transaction |
Stripe PaymentIntent |
Invoice for billing, PaymentIntent for payments only |
Yes |
|
Piano Payment Method |
Stripe Payment Method |
Direct mapping + BYOP via out-of-band for non-Stripe methods |
Yes + BYOP |
|
BILLING ARCHITECTURE MAPPING |
|||
|
Piano Billing Concept |
Stripe Billing Concept |
Implementation Pattern |
Technical Approach |
|
Payment Terms |
Subscription Schedules |
Phase-based billing with schedule API |
Multi-phase schedules for complex billing |
|
Dynamic Terms |
Subscription Schedules |
Multiple phases with dynamic price_data generation |
Piano calculates pricing → Dynamic price_data → Schedule phases |
|
Shared Terms |
Subscription Schedules |
Shared subscription management |
Master subscription with shared access |
|
Gift Terms |
Stripe Invoice |
Stripe Invoice with purchase-date service period |
Stripe Invoice with purchase-date service period for revenue recognition, Piano manages gift redemption |
|
Promotions |
Invoice Net amount line Item (Discounts) |
Piano-native promotion engine with Stripe invoice net amount |
Piano calculates discounts → Apply as discounted line items in Stripe invoices |
|
Trial Periods |
Subscription Schedule Phases |
Trial phases in schedules with price_data |
Piano trial logic → $0 price_data → Paid phase transition |
|
Grace Periods |
Smart Retries + Piano Access Control |
Stripe Smart Retries + Piano access extension |
Dual system coordination |
|
Renewals |
Subscription Billing Cycles |
Stripe controlled renewal billing |
Piano renewal tax rate check → New price_data → Stripe billing → Finalize invoice |
|
Upgrades/Downgrades |
Subscription Schedule Modifications |
Piano-calculated proration + price_data + Subscription Schedule Phase |
Piano determines new pricing → price_data updates → Stripe Schedule Update (2:1 mapping on Piano subscriptions to Stripe) |
|
DATA ARCHITECTURE & SYNCHRONIZATION |
|||
|
Data Flow |
Synchronization Strategy |
Technical Implementation |
Consistency Model |
|
Piano → Stripe |
Real-time price_data Generation |
Piano pricing engine → Dynamic price_data → Stripe APIs |
Piano single source of truth |
|
Stripe → Piano |
Webhook Processing |
Stripe webhook consumption |
Strong consistency for critical events, metadata filtering to ensure only Piano actions are processed |
|
Catalog Sync |
Piano Master |
Piano terms → Stripe Products and Price_data |
Piano-driven catalog with Stripe Product creation and Metadata |
|
Subscription Sync |
Bi-directional |
Real-time status + pricing synchronization |
Piano pricing authority + Stripe billing execution |
|
Metadata Management |
Rich Metadata Strategy |
Extensive use of Stripe metadata for Piano context |
Metadata-driven context for product revenue recognition needs |
Data mapping from Stripe to Piano
Piano subscription object
|
Stripe source |
Stripe source description |
Piano destination |
|
id field of Stripe subscription object. |
Unique identifier for the subscription object. |
stripe_subscription_id field of Piano subscription object. |
|
ended_at field of Stripe subscription object. |
If the subscription has ended, the date the subscription ended. |
end_date field of Piano subscription object. |
Piano payment object
|
Stripe source |
Stripe source description |
Piano destination |
|
id field of Stripe invoice object. |
Unique identifier for the invoice object. |
stripe_invoice_id field of Piano payment object. |
|
created field of Stripe invoice object. |
Time at which the invoice object was created. Measured in seconds since the Unix epoch. |
tx_stamp field of Piano payment object. |
|
currency field of Stripe invoice object. |
The code of the currency used to pay for the invoice object. |
currency field of Piano payment object. |
|
total field of Stripe invoice object. |
The total amount after discounts and taxes paid for the invoice object. |
amount field of Piano payment object. |
|
total_excluding_taxes field of Stripe invoice object. |
The amount representing the total amount of the invoice excluding all taxes. |
pre_tax_amount field of Piano payment object. |