Create a temporary booking hold

curl --request POST \
  --url https://api.simplepay.mx/v1/bookable-payments/holds \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "event_type_id": "<string>",
  "starts_at": "2023-11-07T05:31:56Z",
  "event_type_slug": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    event_type_id: '<string>',
    starts_at: '2023-11-07T05:31:56Z',
    event_type_slug: '<string>'
  })
};

fetch('https://api.simplepay.mx/v1/bookable-payments/holds', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.simplepay.mx/v1/bookable-payments/holds"

payload = {
    "event_type_id": "<string>",
    "starts_at": "2023-11-07T05:31:56Z",
    "event_type_slug": "<string>"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "ends_at": "2023-11-07T05:31:56Z",
  "event_type_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "expires_at": "2023-11-07T05:31:56Z",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "object": "<unknown>",
  "product_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "quantity": 2,
  "resource_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "starts_at": "2023-11-07T05:31:56Z",
  "tenant_customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

POST

https://api.simplepay.mx

bookable-payments

holds

Create a temporary booking hold

curl --request POST \
  --url https://api.simplepay.mx/v1/bookable-payments/holds \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "event_type_id": "<string>",
  "starts_at": "2023-11-07T05:31:56Z",
  "event_type_slug": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    event_type_id: '<string>',
    starts_at: '2023-11-07T05:31:56Z',
    event_type_slug: '<string>'
  })
};

fetch('https://api.simplepay.mx/v1/bookable-payments/holds', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.simplepay.mx/v1/bookable-payments/holds"

payload = {
    "event_type_id": "<string>",
    "starts_at": "2023-11-07T05:31:56Z",
    "event_type_slug": "<string>"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "ends_at": "2023-11-07T05:31:56Z",
  "event_type_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "expires_at": "2023-11-07T05:31:56Z",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "object": "<unknown>",
  "product_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "quantity": 2,
  "resource_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "starts_at": "2023-11-07T05:31:56Z",
  "tenant_customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

Uso

Usalo dentro de Bookable Payments para modelar inventario reservado, calcular disponibilidad, crear holds, convertirlos en checkout y confirmar bookings.

Antes de llamar

Tema	Detalle
Metodo	`POST`
Ruta	`/v1/bookable-payments/holds`
Auth	Bearer API key del ambiente correcto.
Scope	`bookings:write`
Idempotencia	Recomendada para cualquier retry. Usa una key deterministica por operacion de negocio.
Guia relacionada	Bookable Payments

Patron recomendado

Ejecuta este endpoint desde backend o job seguro, nunca desde frontend con API keys.
Manda Idempotency-Key cuando el endpoint cree, convierta, reprograme, cancele, capture o reembolse estado.
Confirma inventario final con booking.confirmed o una lectura de booking, no solo con una URL de retorno.
Consulta el bloque OpenAPI de esta pagina para el shape exacto de parametros, body y respuestas.

Ejemplo minimo

terminal

curl -sS -X POST "https://api.simplepay.mx/v1/bookable-payments/holds" \
  -H "Authorization: Bearer $SIMPLEPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-booking-hold_v1" \
  -d '{ ... }'

Errores a manejar

400 indica payload, parametros o estado invalido.
401 o 403 indican API key, ambiente o scopes incorrectos.
409 suele indicar conflicto de estado, duplicado o idempotencia incompatible.
429 y 5xx se pueden reintentar con backoff; en writes conserva la misma idempotency key.

Contrato OpenAPI

El playground, parametros, body y respuestas de abajo salen de /openapi.json. Si el contrato cambia, actualiza la spec y regenera esta pagina.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Idempotency-Key

string

required

Required string length: 8 - 255

Body

application/json

Option 1
Option 2

event_type_id

string

required

starts_at

string<date-time>

required

customer

object

Hide child attributes

customer.id

string<uuid>

customer.customer_id

string<uuid>

customer.external_provider

string

customer.external_id

string

customer.email

string<email>

customer.name

string

customer.phone

string

customer.metadata

object

event_type_slug

string

duration_minutes

integer

Required range: x >= 1

ends_at

string<date-time>

hold_minutes

integer

Required range: 1 <= x <= 120

metadata

object

quantity

integer

Required range: x >= 1

resource_id

string<uuid>

Response

201 - application/json

Booking hold created

ends_at

string<date-time>

event_type_id

string<uuid>

expires_at

string<date-time>

string<uuid>

object

any

product_id

string<uuid>

quantity

integer

Required range: x >= 1

resource_id

string<uuid>

starts_at

string<date-time>

status

enum<string>

Available options:

converted,

expired,

held,

released

tenant_customer_id

string<uuid>

Last modified on June 21, 2026

Reschedule a booking Convert a booking hold into a SimplePay Checkout Session

Overview

Checkout

Payment Links

Refunds

Payment Policy

Products

Catalog

Customer Hub

Bookable: setup

Bookable: resources

Bookable: disponibilidad

Bookable: event types

Bookable: holds y bookings

Webhooks y eventos

Meta

Create a temporary booking hold

Uso

Antes de llamar

Patron recomendado

Ejemplo minimo

Errores a manejar

Contrato OpenAPI

Authorizations

Headers

Body

Response

​Uso

​Antes de llamar

​Patron recomendado

​Ejemplo minimo

​Errores a manejar

​Contrato OpenAPI

Authorizations

Headers

Body

Response

Uso

Antes de llamar

Patron recomendado

Ejemplo minimo

Errores a manejar

Contrato OpenAPI