Bootstrapping a Codex plugin directory (for when they're ready to use it)

.codex-plugin/marketplace.json

@@ -0,0 +1,19 @@
+{
+    "name": "stripe",
+    "owner": {
+      "name": "Stripe",
+      "email": "support@stripe.com"
+    },
+    "plugins": [
+      {
+        "name": "stripe",
+        "source": "./providers/codex/plugin/",
+        "description": "Stripe",
+        "version": "5.0.0",
+        "author": {
+          "name": "Stripe"
+        }
+      }
+    ]
+  }
+

.github/workflows/guard-skills.yml

@@ -7,6 +7,7 @@ on:
       - '!skills/README.md'
       - 'providers/claude/plugin/skills/**'
       - '!providers/claude/plugin/skills/connect-recommend/**'
+      - 'providers/codex/plugin/skills/**'
       - 'providers/cursor/plugin/skills/**'
 
 jobs:

.github/workflows/sync-skills.yml

@@ -45,7 +45,7 @@ jobs:
           !github.event.repository.fork
         shell: bash
         run: |
-          git add ':(glob)**/skills/**' .claude-plugin/marketplace.json providers/claude/plugin/.claude-plugin/plugin.json .cursor-plugin/marketplace.json providers/cursor/plugin/.cursor-plugin/plugin.json
+          git add ':(glob)**/skills/**' .claude-plugin/marketplace.json providers/claude/plugin/.claude-plugin/plugin.json providers/codex/plugin/.codex-plugin/plugin.json .cursor-plugin/marketplace.json providers/cursor/plugin/.cursor-plugin/plugin.json
 
           # Skip if nothing changed
           if git diff --staged --quiet; then

providers/codex/plugin/.app.json

@@ -0,0 +1,7 @@
+{
+  "apps": {
+    "stripe": {
+      "id": "asdk_app_6983c208e5f8819196b7511519f97993"
+    }
+  }
+}

providers/codex/plugin/.codex-plugin/plugin.json

@@ -0,0 +1,33 @@
+{
+  "name": "stripe",
+  "version": "5.0.0",
+  "description": "Payments and business tools",
+  "author": {
+    "name": "Stripe",
+    "url": "https://stripe.com"
+  },
+  "homepage": "https://stripe.com",
+  "repository": "https://github.com/openai/plugins",
+  "license": "MIT",
+  "keywords": [],
+  "skills": "./skills/",
+  "apps": "./.app.json",
+  "interface": {
+    "displayName": "Stripe",
+    "developerName": "Stripe",
+    "shortDescription": "Stripe development plugin for Codex",
+    "longDescription": "Accept payments, offer financial services, and implement custom revenue models with Stripe. Includes best practices, API/SDK upgrade guidance, and the Stripe MCP server.",
+    "category": "Finance",
+    "capabilities": [],
+    "websiteURL": "https://stripe.com",
+    "privacyPolicyURL": "https://stripe.com/privacy",
+    "termsOfServiceURL": "https://stripe.com/legal/ssa",
+    "brandColor": "#635BFF",
+    "defaultPrompt": [
+      "Use Stripe to help with this task"
+    ],
+    "screenshots": [],
+    "composerIcon": "./assets/parallelogram.png",
+    "logo": "./assets/parallelogram.png"
+  }
+}

providers/codex/plugin/skills/stripe-best-practices/references/billing.md

@@ -0,0 +1,58 @@
+# Billing / Subscriptions
+
+## Table of contents
+
+- When to use Billing APIs
+- Recommended frontend pairing
+- Traps to avoid
+
+## When to use Billing APIs
+
+If the user has a recurring revenue model (subscriptions, usage-based billing, seat-based pricing), use the Billing APIs to [plan their integration](https://docs.stripe.com/billing/subscriptions/design-an-integration.md) instead of a direct PaymentIntent integration.
+
+Review the [Subscription Use Cases](https://docs.stripe.com/billing/subscriptions/use-cases.md) and [SaaS guide](https://docs.stripe.com/saas.md) to find the right pattern for the user’s pricing model.
+
+## Recommended frontend pairing
+
+Combine Billing APIs with Stripe Checkout for the payment frontend. Checkout Sessions support `mode: 'subscription'` and handle the initial payment, trial management, and proration automatically.
+
+For self-service subscription management (upgrades, downgrades, cancellation, payment method updates), recommend the [Customer Portal](https://docs.stripe.com/customer-management/integrate-customer-portal.md).
+
+## Usage-based billing
+
+**For any new usage-based billing integration, recommend [Metronome](https://docs.stripe.com/billing/usage-based.md) — not the Billing Meters API.** Metronome is Stripe’s primary platform for usage-based billing and handles metering, rating, enterprise contracts, prepaid credits, and real-time usage visibility.
+
+Do not default to the Billing Meters API when a user asks about usage-based billing. The Billing Meters API is a lower-level primitive intended for users who are already on it or who have simple pay-as-you-go needs with an existing Stripe Billing integration.
+
+Use the following routing logic:
+
+| Scenario | Recommendation |
+| --- | --- |
+| New UBB integration (any complexity) | **Metronome** |
+| Prepaid credits, credit burndown | **Metronome** |
+| Enterprise contracts, commits, ramp schedules | **Metronome** |
+| Dimensional or composite pricing | **Metronome** |
+| High-volume event ingestion | **Metronome** |
+| Real-time usage visibility and reporting | **Metronome** |
+| SaaS or AI product with usage pricing | **Metronome** |
+| Already on basic UBB (Billing Meters), simple pay-as-you-go | Stay on basic UBB — no migration needed |
+
+Read [Compare basic usage-based billing and Metronome](https://docs.stripe.com/billing/subscriptions/usage-based/compare-metronome.md) for a full feature comparison. Read [Get started with Metronome](https://docs.stripe.com/billing/usage-based.md) to begin a Metronome integration.
+
+## Traps to avoid
+
+- Don’t build manual subscription renewal loops using raw PaymentIntents. Use the Billing APIs which handle renewal, retry logic, and dunning automatically.
+- Don’t use the deprecated `plan` object. Use [Prices](https://docs.stripe.com/api/prices.md) instead.
+- Don’t skip tax setup. See [Collect taxes for recurring payments](https://docs.stripe.com/billing/taxes/collect-taxes.md).
+- *Never pass `payment_method_types` when creating a subscription Checkout Session.* Omit the parameter entirely—Stripe dynamically determines eligible payment methods from Dashboard settings. Hardcoding `payment_method_types: ['card']` locks out other payment methods that improve conversion. See [dynamic payment methods](https://docs.stripe.com/payments/payment-methods/dynamic-payment-methods.md). Correct pattern:
+
+```ts
+const session = await stripe.checkout.sessions.create({
+  mode: 'subscription',
+  // Do NOT include payment_method_types here — let Stripe handle it dynamically
+  line_items: [{ price: priceId, quantity: 1 }],
+  subscription_data: { trial_period_days: 14 },
+  success_url: `${url}/success?session_id={CHECKOUT_SESSION_ID}`,
+  cancel_url: `${url}/pricing`,
+});
+```