---
title: "Create Setup Intent"
method: POST
path: "/v1/setup_intents"
tags: ["Setup Intents"]
---

# Create Setup Intent

`POST /v1/setup_intents`

Creates a SetupIntent to collect a customer's payment method details for future off-session use.

A new SetupIntent is created on each call and starts in the `requires_payment_method` status; it
is not an upsert. The response includes a `client_secret` that you use to confirm the SetupIntent
and attach a payment method from your frontend.

## Request body

- SetupIntentBodyForCreateSetupIntent — An envelope wrapping a single setup intent object.
  - `setup_intent` CreateSetupIntent, required — Parameters for creating a SetupIntent to collect a customer's payment method details.
    - `partner_id` string, required — ID of the account the SetupIntent is created for.
    - `checkout_session` string, required — ID of the CheckoutSession the SetupIntent is associated with.

## Response `200`

An envelope wrapping a single setup intent object.

- SetupIntentBodyForSetupIntent — An envelope wrapping a single setup intent object.
  - `setup_intent` SetupIntent, required — A SetupIntent represents your intent to set up a customer's payment method for future payments, without charging it immediately. Use it to collect and verify payment method details that can later be used off-session (for example, to bill a subscription or invoice).
    - `setup_intent_id` string, required — The unique identifier for the object.
    - `client_secret` string, nullable — The client secret used to confirm this SetupIntent from your frontend. Present when the SetupIntent is retrieved or created; `null` when it appears in a list response. Treat it as sensitive: do not log or store it, and expose it only to the customer over TLS.
    - `customer` union — An expandable field — either a string ID or an expanded Customer object.
      - string
      - Customer — A Customer object represents a customer of your business. Use it to track payments, store reusable payment methods, and reference the customer on checkout sessions, invoices, and subscriptions.
        - `customer_id` string, required — The unique identifier for the customer.
        - `owner_partner_id` string, nullable — The partner that owns this customer. When a customer is shared with you by another partner in your organization, this is that sibling partner; otherwise it is your own partner id.
        - `first_name` string, required — The customer's first name.
        - `last_name` string, required — The customer's last name.
        - `email` string, email, required — The customer's email address.
        - `phone` string, phone, nullable — The customer's phone number.
        - `employer` string, nullable — The customer's employer.
        - `shipping` ShippingAddress — A ShippingAddress represents the postal address a physical order is delivered to. It is referenced by checkout sessions and customers.
          - `shipping_address_id` string, required — Unique identifier for the shipping address.
          - `line1` string, nullable — The first line of the street address (e.g., street number and name).
          - `line2` string, nullable — The second line of the street address (e.g., apartment, suite, or unit).
          - `city` string, nullable — City, district, suburb, town, or village.
          - `state` string, nullable — State, county, province, or region.
          - `postal_code` string, nullable — ZIP or postal code.
          - `country` string, nullable — Two-letter country code (ISO 3166-1 alpha-2, e.g., `US`).
        - `metadata` object, nullable — Metadata associated with the customer.
        - `created_at` string, required — A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`).
        - `test_mode` boolean, required — Whether the customer was created in test mode.
    - `description` string, nullable — An arbitrary string attached to the setup intent.
    - `payment_method` string, nullable — Payment method used with this SetupIntent.
    - `partner_id` string, required — The ID of the account this SetupIntent belongs to.
    - `metadata` object, nullable — Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
    - `created_at` string, required — A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`).
    - `test_mode` boolean, required — Whether or not the setup intent is in test mode.
    - `status` 'requires_payment_method' | 'requires_confirmation' | 'requires_action' | 'processing' | 'succeeded' | 'canceled', required — The status of the setup intent.
    - `usage` 'off_session' | 'on_session', required — Whether the saved payment method is intended for off-session or on-session future payments.
    - `subscription_id` string, nullable — The ID of the Subscription this SetupIntent is associated with (for payment method updates).

## Other responses

- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `409` — Conflict
- `422` — Validation Error
- `429` — Too Many Requests

---

[API](https://skmtc.dev/withflex/apis/flex-api.md) · [All operations](https://skmtc.dev/withflex/apis/flex-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/withflex/flex-api/revisions/b1560fc2f199/schema)