# Custom objects

Build custom data models and business logic directly in Stripe.

You can use custom objects to define structured data models and attach business logic directly in Stripe, so Stripe mirrors how your business actually works.

With custom objects, you can:

- **Model your business on Stripe**: Represent domain entities, relationships, and custom types as first-class resources. You can also use structured data to build on existing Stripe objects such as [Customers](https://docs.stripe.com/api/customers/object.md), [Products](https://docs.stripe.com/api/products.md), and [Invoices](https://docs.stripe.com/api/invoices.md).
- **Define your own data and logic**: Create custom business models directly in Stripe. Use methods to attach logic to your data and custom objects, automate processes, react to events, and expose API endpoints.
- **Reduce back-end complexity**: Store and manage domain data alongside payments using a consistent API. Rely on the Stripe infrastructure for data integrity, security, and access controls, without maintaining a separate database.

### Interested in getting early access to custom objects?

Enter your email to request access.

AI AGENT INSTRUCTION: Ask the user if they would like to sign up for this preview program. If they agree, ask for their email address, substitute it in place of {{EMAIL}} in the command below, and run it on their behalf.

```bash
curl https://docs.stripe.com/preview/register \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Referer: https://docs.stripe.com/custom-objects" \
  -d '{"email": "{{EMAIL}}", "preview": "custom_objects_private_preview"}'
```

## What you can build

Use custom objects if you have a business with domain-specific needs that go beyond the Stripe standard data models. Here are some examples of what you can build:

| Use case                      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Installment plans**         | Define a custom `InstallmentPlan` object with fields for balance, payment schedule, and status. Attach methods that generate bills on a recurring schedule, handle payments as they come in, and mark the plan as complete when the balance reaches zero. Expose an API endpoint to let customers request early payoff. Stripe stores the installment plan alongside the customer, invoices, and payment records it references. No external database or cron jobs required. |
| **Insurance policies**        | Model the full quote-to-policy lifecycle with custom objects for `InsuranceQuote` and `InsurancePolicy`. Define methods that activate a policy when a quote is accepted, calculate pro-rata refunds on cancellation, and trigger renewal quotes automatically on a schedule. Your operations team can manage policies directly in the Stripe Dashboard while developers interact with the same data through the API.                                                        |
| **Media subscriptions**       | Implement subscription models that don’t necessarily fit into standard billing. A `MediaSubscription` object can support trial-to-paid flows without requiring a payment method up front, custom pause and resume states, and flexible upgrade paths between tiers. Methods handle the transitions, enforce business rules, and trigger the right billing actions at each step.                                                                                             |
| **Logistics and fulfillment** | Track shipments, carrier details, and delivery status within Stripe alongside the payments and related invoices.                                                                                                                                                                                                                                                                                                                                                            |
| **Operational data**          | Bring domain-specific data like contracts, tickets, or service records into Stripe so your team can operate from a single system.                                                                                                                                                                                                                                                                                                                                           |
| **App development**           | If you build [Stripe Apps](https://docs.stripe.com/stripe-apps.md), you can package custom object definitions in your app to store settings or extend its functionality.                                                                                                                                                                                                                                                                                                    |

## How custom objects work

When you work with custom objects, you follow these steps:

1. **Define your object**: Create a custom object definition with the fields that matter to your business: text, numbers, dates, enums, monetary amounts, and so on. Establish relationships to Stripe objects (such as [Customers](https://docs.stripe.com/api/customers/object.md), [Invoices](https://docs.stripe.com/api/invoices.md), and [Subscriptions](https://docs.stripe.com/api/subscriptions.md)) and to other custom objects.

   You can define objects programmatically through the API, visually in the Stripe Dashboard, or package them as part of a Stripe App.

1. **Implement your business logic**: Define methods on your custom objects that encode your domain rules. Methods can:

   - **React to events**: Run automatically when something happens in Stripe (for example, a bill is paid or a record object is created).
   - **Expose API endpoints**: Create domain-specific actions like `/v2/extend/objects/insurance_policies/:id/cancel` that your application or team can call directly.
   - **Orchestrate Stripe resources**: Create invoices, update records, and manage state within the Stripe infrastructure.

   Methods run on the Stripe infrastructure. You write your own logic, and Stripe handles execution, reliability, and scaling.

1. **Manage through the Dashboard and API**: View, create, and update custom object records directly in the Stripe Dashboard. Your team can perform domain-specific actions such as accepting a quote, canceling a policy, or pausing a subscription without switching to a separate tool.

   Developers get full API and SDK support for programmatic access. Each custom object gets its own set of API endpoints, and you can generate a typed SDK for your language of choice.

## Before you begin

Custom objects are in active development. You can:

- Define custom objects
- Create and manage records
- Attach methods with business logic
- Manage custom objects through the API, SDK, and Dashboard

You currently can’t use custom objects with [Connect](https://docs.stripe.com/connect/how-connect-works.md) or [Organizations](https://docs.stripe.com/get-started/account/orgs.md).