Type of Change

• Bugfix
• New feature
• Enhancement
• Refactoring
• Dependency updates
• Documentation
• CI/CD

Additional Changes

• This PR modifies the API contract
• This PR modifies the database schema
• This PR modifies application configuration/environment variables

Description

Introduce Subscriptions as a first-class entity in the router.
This PR adds a subscription table, Diesel models, storage interfaces, and query helpers to create, fetch, and update subscription entries keyed by (merchant_id, customer_id, subscription_id).

What’s included

Database (PostgreSQL)

• New table: subscription
• Columns:
  • id VARCHAR(128) PRIMARY KEY
  • subscription_id VARCHAR(128) NULL
  • billing_processor VARCHAR(128) NULL
  • payment_method_id VARCHAR(128) NULL
  • mca_id VARCHAR(128) NULL
  • client_secret VARCHAR(128) NULL
  • merchant_id VARCHAR(64) NOT NULL
  • customer_id VARCHAR(64) NOT NULL
  • metadata JSONB NULL
  • created_at TIMESTAMP NOT NULL
  • modified_at TIMESTAMP NOT NULL
• Indexes:
  • CREATE UNIQUE INDEX merchant_customer_subscription_unique_index ON subscription (merchant_id, customer_id, subscription_id);

Migrations

• up.sql creates the table + unique index
• down.sql drops the table

Diesel models & schema

• crates/diesel_models/src/schema.rs: subscription table mapping
• crates/diesel_models/src/subscription.rs:
  • SubscriptionNew (insert)
  • Subscription (read)
  • SubscriptionUpdate (update: subscription_id, payment_method_id, modified_at)
• Query functions: crates/diesel_models/src/query/subscription.rs
  • SubscriptionNew::insert
  • Subscription::find_by_merchant_id_customer_id_subscription_id
  • Subscription::update_subscription_entry

Router storage interface

• Trait: SubscriptionInterface (crates/router/src/db/subscription.rs)
  • insert_subscription_entry
  • find_by_merchant_id_customer_id_subscription_id
  • update_subscription_entry
• Implemented for Store, KafkaStore (delegates), and MockDb (stubbed)

Wiring

• Re-exports in crates/router/src/types/storage.rs and module plumbing in db.rs, diesel_models/src/lib.rs, query.rs.

Motivation and Context

Subscriptions are often provisioned/managed outside Payments, but Payments needs a lightweight mapping to:

• Track billing processor and connector meta (mca_id, client_secret)
• Attach or rotate payment_method_id per subscription
• Support idempotent reads keyed by merchant & customer context

This schema enables upstream orchestration to store/retrieve subscription context without coupling to payment flows.

API / Contract / Config Impact

• DB schema change: ✅ (new table + unique index)
• API contract: ❌ (no external API changes in this PR)
• Config/env: ❌

Testing

can't be performed, as in this PR we only have created the tables and not used it anywhere in the upcoming micro-prs, this will be used. however I have used it myself by making code changes, here are the screenshots.

Checklist

• I formatted the code cargo +nightly fmt --all
• I addressed lints thrown by cargo clippy
• I reviewed the submitted code
• I added unit tests for my changes where possible