Push Model

Prices as Code version 3.1.0+ introduces a new "Push Model" as the default behavior. This guide will explain what the Push Model is, why it's beneficial, and how to use it effectively.

What is the Push Model?

The Push Model refers to synchronization behavior where:

This is different from the previous default behavior (now called "Write-Back Model") where provider IDs would be written back to your configuration file after synchronization.

Benefits of the Push Model

1. Multi-Environment Support

The same configuration file can be used to push to different environments (development, staging, production) without ID conflicts. Each environment will have its own set of IDs maintained by the provider, but your configuration remains consistent.

# Push to development environment
STRIPE_SECRET_KEY=sk_dev_... npx prices-as-code prices.yml

# Push to production environment (same config file)
STRIPE_SECRET_KEY=sk_prod_... npx prices-as-code prices.yml

2. Provider Limitations

Many providers (like Stripe) don't allow setting IDs programmatically. The Push Model acknowledges this limitation and works with the provider's system rather than trying to maintain two sources of truth.

3. Clean Configuration

Your configuration files remain clean and focused on the business logic of your pricing structure, without being cluttered with provider-specific technical details like IDs that change between environments.

4. CI/CD Friendly

The Push Model works better with CI/CD pipelines, as each deployment can push the same configuration to a specific environment without needing to track environment-specific configuration files.

Using the Push Model

The Push Model is now the default behavior. Simply use Prices as Code as you normally would:

npx prices-as-code prices.yml

Using with JavaScript/TypeScript API

import { pac } from 'prices-as-code';

async function syncPricing() {
  const result = await pac({
    configPath: './pricing.ts',
    providers: [
      {
        provider: 'stripe',
        options: {
          secretKey: process.env.STRIPE_SECRET_KEY,
        }
      }
    ],
    // writeBack defaults to false (Push Model)
  });
  
  console.log('Sync result:', result);
}

Using the Legacy Write-Back Model

If you prefer the previous behavior where IDs are written back to your configuration file, you can enable the "Write-Back Model":

Using the CLI

npx prices-as-code prices.yml --write-back

Using the JavaScript/TypeScript API

import { pac } from 'prices-as-code';

const result = await pac({
  configPath: './pricing.ts',
  providers: [
    {
      provider: 'stripe',
      options: {
        secretKey: process.env.STRIPE_SECRET_KEY,
      }
    }
  ],
  writeBack: true  // Enable Write-Back Model
});

Metadata for Provider References

Even though provider IDs aren't written back to your configuration, you can still use the metadata field to store useful information that can help you reference specific products and prices:

const config = {
  products: [
    {
      provider: 'stripe',
      name: 'Premium Plan',
      metadata: {
        key: 'premium',  // Use this for consistent references
        displayOrder: 2
      }
    }
  ],
  prices: [
    {
      provider: 'stripe',
      name: 'Premium Monthly',
      unitAmount: 1999,
      currency: 'usd',
      type: 'recurring',
      recurring: {
        interval: 'month'
      },
      productKey: 'premium',  // Reference the product by key
      metadata: {
        planCode: 'premium_monthly'  // Use this for app logic
      }
    }
  ]
};

This approach allows your application code to reference products and prices by their metadata rather than by provider-specific IDs, maintaining consistency across environments.

Migration Guide

If you're upgrading from a previous version and were relying on IDs being written back to your configuration:

  1. Update your application to use metadata keys instead of direct provider IDs where possible
  2. Use the --write-back flag temporarily if needed during migration
  3. Gradually adopt the Push Model pattern for better multi-environment support

Next Steps