Email the customer a link to add a payment method

POST

/v1/customers/{customer_id}/payment-methods/send-setup-email

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

• Local development

Creates a Stripe Checkout setup link (as setup-session does) and queues an email with it to the customer’s primary email. The link is never sent to the CC list. The card details go from the customer’s browser to Stripe; Hardcount does not see them. The card is saved when Stripe reports the setup succeeded.

At most one call per customer per minute when the server has Redis configured. The minute starts at any call whose body is accepted, including one that then fails, so a second call within it returns 429 cooldown_active with a Retry-After header. Without Redis there is no cooldown.

The send is written to the audit log.

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

note

Optional text shown at the top of the email. At most 2000 bytes (UTF-8) after trimming whitespace.

string

Example ^generated

{
  "note": "example"
}

Responses

202

Email queued.

Media typeapplication/json

object

to

required

The address the email was sent to.

string

subject

required

string

Example ^generated

{
  "to": "example",
  "subject": "example"
}

400

The body is not valid JSON. Nothing was sent.

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"
  }
}

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

Nothing was sent. email_not_configured: this server has no SMTP set up, and no setup link was created. stripe_not_connected: Stripe is not connected for this mode. Like any other call that gets this far, it starts the one-minute cooldown.

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

note_too_long (more than 2000 bytes), missing_email (the customer has no email), or 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"
  }
}

429

This endpoint was called for this customer less than a minute ago (cooldown_active).

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"
  }
}

Headers

Retry-After

integer

Seconds to wait.

500

The setup session could not be created. No email was queued.

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"
  }
}

502

The email could not be queued (email_enqueue_failed), or Stripe refused to create the setup session with a message it is safe to show (provider_error). Retry.

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"
  }
}

503

Email sending is not set up on this server (email_unavailable).

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"
  }
}