Create a link for the customer to add a payment method

POST

/v1/customers/{customer_id}/payment-methods/setup-session

curl --request POST \
  --url http://localhost:8080/v1/customers/example/payment-methods/setup-session \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "return_url": "example" }'

• Local development

Returns a Stripe Checkout URL in setup mode (card only, no charge) for you to give to the customer. Creates the Stripe customer on first use. When the customer finishes, Stripe sends them to return_url with ?status=success or ?status=cancel added. The card is saved when Stripe reports the setup succeeded. The link is written to the audit log; if the audit row cannot be written, no link is returned.

Authorizations

• BearerAuth

Parameters

Path Parameters

customer_id

required

string

Header Parameters

Idempotency-Key

string

Makes the call safe to retry. Send a unique value (a UUID works) and the same value on every retry. For 24 hours, a repeat with the same key, method, path and body gets the first response again, with an Idempotent-Replayed: true header, instead of running again. The error cases are in docs/api-surface.md. The usage routes do not take it: each usage event carries its own idempotency_key.

Request Body

Media typeapplication/json

object

return_url

Where Stripe sends the customer afterwards. Defaults to the dashboard’s setup-complete page.

string

Example ^generated

{
  "return_url": "example"
}

Responses

201

Setup link created.

Media typeapplication/json

object

url

required

Stripe Checkout URL. Expires on Stripe’s schedule (about 24 hours).

string

session_id

required

Stripe Checkout Session ID.

string

Example ^generated

{
  "url": "example",
  "session_id": "example"
}

404

Customer not found.

Media typeapplication/json

object

error

object

type

One of invalid_request_error, authentication_error, rate_limit_error or api_error. Every error the API answers has this shape, including an unknown path (404, code route_not_found) and a method the path does not take (405, code method_not_allowed, with an Allow header). The few exceptions are listed in docs/api-surface.md.

string

code

string

message

string

request_id

string

param

The request field the error is about. Sent only when the error names one. A request body may hold only the fields its operation lists, spelled and cased as listed: any other field, or one the server sets (such as id), is refused with 422 and param naming it. An operation with no request body lists no fields: send no body, {} or null. The Stripe and Postmark webhooks and the LiteLLM callback take their sender’s body as it comes.

string

Example

{
  "error": {
    "type": "invalid_request_error"
  }
}

409

stripe_not_connected: Stripe is not connected for this mode. Connect it under Settings.

Media typeapplication/json

object

error

object

type

One of invalid_request_error, authentication_error, rate_limit_error or api_error. Every error the API answers has this shape, including an unknown path (404, code route_not_found) and a method the path does not take (405, code method_not_allowed, with an Allow header). The few exceptions are listed in docs/api-surface.md.

string

code

string

message

string

request_id

string

param

The request field the error is about. Sent only when the error names one. A request body may hold only the fields its operation lists, spelled and cased as listed: any other field, or one the server sets (such as id), is refused with 422 and param naming it. An operation with no request body lists no fields: send no body, {} or null. The Stripe and Postmark webhooks and the LiteLLM callback take their sender’s body as it comes.

string

Example

{
  "error": {
    "type": "invalid_request_error"
  }
}

422

The body has an unknown field (param names it).

Media typeapplication/json

object

error

object

type

One of invalid_request_error, authentication_error, rate_limit_error or api_error. Every error the API answers has this shape, including an unknown path (404, code route_not_found) and a method the path does not take (405, code method_not_allowed, with an Allow header). The few exceptions are listed in docs/api-surface.md.

string

code

string

message

string

request_id

string

param

The request field the error is about. Sent only when the error names one. A request body may hold only the fields its operation lists, spelled and cased as listed: any other field, or one the server sets (such as id), is refused with 422 and param naming it. An operation with no request body lists no fields: send no body, {} or null. The Stripe and Postmark webhooks and the LiteLLM callback take their sender’s body as it comes.

string

Example

{
  "error": {
    "type": "invalid_request_error"
  }
}