# AgendaPro Documentation > Documentation for AgendaPro Append .md to any documentation page URL to get its markdown version. ## Guides - [Primeros pasos con la API v3](https://developers.agendapro.com/docs/getting-started.md): Aprende a autenticarte, hacer tu primera consulta y manejar respuestas con la nueva API pública de AgendaPro. - [Autenticación](https://developers.agendapro.com/docs/authentication.md): Cómo autenticarse con la API v3 de AgendaPro. - [Webhooks](https://developers.agendapro.com/docs/webhooks.md): Recibe notificaciones en tiempo real cuando ocurren eventos en tu cuenta de AgendaPro. ## API Reference - [Connect v3](https://developers.agendapro.com/reference/getting-started-v3.md): Referencia completa de la API pública v3 de AgendaPro. - [List Available Slots](https://developers.agendapro.com/reference/listavailableslots.md): Returns available booking slots for a service at a location on a given date. Results are grouped into a `slots` array and a `metadata` object. The `slots` array contains individual time windows; `metadata` summarises the query. ### Important Notes - Results are scoped to the company associated with the API key. - `location_id` and `start_date` are required. - Requires `bookings:read` scope. ### Errors Dictionary | **Status** | **Error** | **Detail** | **Description** | | --- | --- | --- | --- | | 401 | unauthorized | invalid_api_key | Missing or invalid Bearer token. | | 401 | unauthorized | api_config_inactive | API access is inactive for this company. | | 403 | forbidden | scope_denied | API key lacks `bookings:read` scope. | | 404 | location_not_found | | Location not found or does not belong to the company. | | 429 | rate_limited | burst_limit_exceeded | Per-minute request limit exceeded. | | 429 | rate_limited | daily_quota_exceeded | Daily request quota exceeded. | | 502 | upstream_unavailable | | The upstream service is unavailable. | - [List Bookings](https://developers.agendapro.com/reference/listbookings.md): This endpoint returns a paginated list of bookings for the company. ### Important Notes - Results are scoped to the company associated with the API key. - At least one entity filter is required: `client_id`, `location_id`, `service_id`, or `service_provider_id`. The `start_date`/`end_date` parameters narrow results further but do not satisfy this requirement on their own. - Requires `bookings:read` scope. ### Errors Dictionary | **Status** | **Error** | **Detail** | **Description** | | --- | --- | --- | --- | | 400 | required | params | No entity filter provided. Supply at least one of `client_id`, `location_id`, `service_id`, or `service_provider_id`. | | 401 | unauthorized | invalid_api_key | Missing or invalid Bearer token. | | 401 | unauthorized | api_config_inactive | API access is inactive for this company. | | 403 | forbidden | scope_denied | API key lacks `bookings:read` scope. | | 429 | rate_limited | burst_limit_exceeded | Per-minute request limit exceeded. | | 429 | rate_limited | daily_quota_exceeded | Daily request quota exceeded. | | 502 | upstream_unavailable | | The upstream service is unavailable. | - [Create Booking](https://developers.agendapro.com/reference/createbooking.md): This endpoint creates a new booking. ### Important Notes - Requires `bookings:write` scope. - Notifications (email, SMS, WhatsApp) are disabled for bookings created via the public API. - The `creative_source` is automatically set to `connect`. ### Errors Dictionary | **Status** | **Error** | **Detail** | **Description** | | --- | --- | --- | --- | | 401 | unauthorized | invalid_api_key | Missing or invalid Bearer token. | | 401 | unauthorized | api_config_inactive | API access is inactive for this company. | | 403 | forbidden | scope_denied | API key lacks `bookings:write` scope. | | 429 | rate_limited | burst_limit_exceeded | Per-minute request limit exceeded. | | 429 | rate_limited | daily_quota_exceeded | Daily request quota exceeded. | | 502 | upstream_unavailable | | The upstream service is unavailable. | - [Get Booking](https://developers.agendapro.com/reference/getbooking.md): This endpoint returns a single booking by ID. ### Errors Dictionary | **Status** | **Error** | **Detail** | **Description** | | --- | --- | --- | --- | | 401 | unauthorized | invalid_api_key | Missing or invalid Bearer token. | | 401 | unauthorized | api_config_inactive | API access is inactive for this company. | | 403 | forbidden | scope_denied | API key lacks `bookings:read` scope. | | 404 | not_found | booking | Booking not found. | | 429 | rate_limited | burst_limit_exceeded | Per-minute request limit exceeded. | | 429 | rate_limited | daily_quota_exceeded | Daily request quota exceeded. | | 502 | upstream_unavailable | | The upstream service is unavailable. | - [Update Booking](https://developers.agendapro.com/reference/updatebooking.md): This endpoint updates an existing booking. Only provided fields are updated (partial update). ### Customer policy enforcement Updates are validated against the merchant's customer policy before being applied. If the merchant has disabled edits, the booking is too close to its start time, or it has reached its maximum number of changes, the request is rejected with `422 restricted` and the `detail` field identifies which rule tripped: | **Detail** | **Meaning** | | --- | --- | | `can_edit` | Merchant disabled edits via the customer flow. | | `before_edit_booking` | Booking is within the merchant's pre-start lock window (no edits allowed this close to `start_time`). | | `max_changes` | Booking has reached the merchant's maximum number of changes. | These values are configured by the merchant in **[Configuraciones > Sitio web > Edición y cancelación de reservas en línea](https://app.agendapro.com/company_settings/bookings)**. Clients integrating against this API should surface these conditions to their end users as "the merchant does not allow this change" rather than retrying the request. ### Errors Dictionary | **Status** | **Error** | **Detail** | **Description** | | --- | --- | --- | --- | | 401 | unauthorized | invalid_api_key | Missing or invalid Bearer token. | | 401 | unauthorized | api_config_inactive | API access is inactive for this company. | | 403 | forbidden | scope_denied | API key lacks `bookings:write` scope. | | 404 | not_found | booking | Booking not found. | | 422 | restricted | can_edit | Merchant has disabled edits via the customer flow. | | 422 | restricted | before_edit_booking | Booking is within the merchant's pre-start lock window. | | 422 | restricted | max_changes | Booking has reached the merchant's maximum number of changes. | | 429 | rate_limited | burst_limit_exceeded | Per-minute request limit exceeded. | | 429 | rate_limited | daily_quota_exceeded | Daily request quota exceeded. | | 502 | upstream_unavailable | | The upstream service is unavailable. | - [Cancel Booking](https://developers.agendapro.com/reference/cancelbooking.md): This endpoint cancels a booking. ### Customer policy enforcement Cancellations are validated against the merchant's customer policy before being applied. If the merchant has disabled cancellations, the booking is too close to its start time, or it has reached its maximum number of changes, the request is rejected with `422 restricted` and the `detail` field identifies which rule tripped: | **Detail** | **Meaning** | | --- | --- | | `can_cancel` | Merchant disabled cancellations via the customer flow. | | `before_edit_booking` | Booking is within the merchant's pre-start lock window (no cancellations allowed this close to `start_time`). | | `max_changes` | Booking has reached the merchant's maximum number of changes. | These values are configured by the merchant in **[Configuraciones > Sitio web > Edición y cancelación de reservas en línea](https://app.agendapro.com/company_settings/bookings)**. Clients integrating against this API should surface these conditions to their end users as "the merchant does not allow this cancellation" rather than retrying the request. ### Errors Dictionary | **Status** | **Error** | **Detail** | **Description** | | --- | --- | --- | --- | | 401 | unauthorized | invalid_api_key | Missing or invalid Bearer token. | | 401 | unauthorized | api_config_inactive | API access is inactive for this company. | | 403 | forbidden | scope_denied | API key lacks `bookings:write` scope. | | 404 | not_found | booking | Booking not found. | | 422 | restricted | can_cancel | Merchant has disabled cancellations via the customer flow. | | 422 | restricted | before_edit_booking | Booking is within the merchant's pre-start lock window. | | 422 | restricted | max_changes | Booking has reached the merchant's maximum number of changes. | | 429 | rate_limited | burst_limit_exceeded | Per-minute request limit exceeded. | | 429 | rate_limited | daily_quota_exceeded | Daily request quota exceeded. | | 502 | upstream_unavailable | | The upstream service is unavailable. | - [List Clients](https://developers.agendapro.com/reference/listclients.md): This endpoint returns a paginated list of clients for the company. ### Errors Dictionary | **Status** | **Error** | **Detail** | **Description** | | --- | --- | --- | --- | | 401 | unauthorized | invalid_api_key | Missing or invalid Bearer token. | | 401 | unauthorized | api_config_inactive | API access is inactive for this company. | | 403 | forbidden | scope_denied | API key lacks `clients:read` scope. | | 429 | rate_limited | burst_limit_exceeded | Per-minute request limit exceeded. | | 429 | rate_limited | daily_quota_exceeded | Daily request quota exceeded. | | 502 | upstream_unavailable | | The upstream service is unavailable. | - [Quick Search Clients](https://developers.agendapro.com/reference/quicksearchclients.md): This endpoint returns a small, ranked list of clients matching a free-text query. It searches by name, email, phone, identification number, and record number, and is intended for type-ahead / autocomplete use cases. ### Errors Dictionary | **Status** | **Error** | **Detail** | **Description** | | --- | --- | --- | --- | | 401 | unauthorized | invalid_api_key | Missing or invalid Bearer token. | | 401 | unauthorized | api_config_inactive | API access is inactive for this company. | | 403 | forbidden | scope_denied | API key lacks `clients:read` scope. | | 400 | bad_request | missing_q | Query string `q` is required. | | 429 | rate_limited | burst_limit_exceeded | Per-minute request limit exceeded. | | 429 | rate_limited | daily_quota_exceeded | Daily request quota exceeded. | | 502 | upstream_unavailable | | The upstream service is unavailable. | - [Create Client](https://developers.agendapro.com/reference/createclient.md): This endpoint creates a new client for the company. ### Important Notes - At least one of `last_name`, `email`, or `phone` is required by business logic. - Email is normalized to lowercase. - Phone must follow E.164 format. ### Errors Dictionary | **Status** | **Error** | **Detail** | **Description** | | --- | --- | --- | --- | | 401 | unauthorized | invalid_api_key | Missing or invalid Bearer token. | | 401 | unauthorized | api_config_inactive | API access is inactive for this company. | | 403 | forbidden | scope_denied | API key lacks `clients:write` scope. | | 429 | rate_limited | burst_limit_exceeded | Per-minute request limit exceeded. | | 429 | rate_limited | daily_quota_exceeded | Daily request quota exceeded. | | 502 | upstream_unavailable | | The upstream service is unavailable. | - [Get Client](https://developers.agendapro.com/reference/getclient.md): This endpoint returns a single client by ID. ### Errors Dictionary | **Status** | **Error** | **Detail** | **Description** | | --- | --- | --- | --- | | 401 | unauthorized | invalid_api_key | Missing or invalid Bearer token. | | 401 | unauthorized | api_config_inactive | API access is inactive for this company. | | 403 | forbidden | scope_denied | API key lacks `clients:read` scope. | | 404 | not_found | client | Client not found. | | 429 | rate_limited | burst_limit_exceeded | Per-minute request limit exceeded. | | 429 | rate_limited | daily_quota_exceeded | Daily request quota exceeded. | | 502 | upstream_unavailable | | The upstream service is unavailable. | - [Update Client](https://developers.agendapro.com/reference/updateclient.md): This endpoint updates an existing client. Only provided fields are updated (partial update). ### Errors Dictionary | **Status** | **Error** | **Detail** | **Description** | | --- | --- | --- | --- | | 401 | unauthorized | invalid_api_key | Missing or invalid Bearer token. | | 401 | unauthorized | api_config_inactive | API access is inactive for this company. | | 403 | forbidden | scope_denied | API key lacks `clients:write` scope. | | 404 | not_found | client | Client not found. | | 429 | rate_limited | burst_limit_exceeded | Per-minute request limit exceeded. | | 429 | rate_limited | daily_quota_exceeded | Daily request quota exceeded. | | 502 | upstream_unavailable | | The upstream service is unavailable. | - [Deactivate Client](https://developers.agendapro.com/reference/deactivateclient.md): This endpoint deactivates (soft deletes) a client. ### Errors Dictionary | **Status** | **Error** | **Detail** | **Description** | | --- | --- | --- | --- | | 401 | unauthorized | invalid_api_key | Missing or invalid Bearer token. | | 401 | unauthorized | api_config_inactive | API access is inactive for this company. | | 403 | forbidden | scope_denied | API key lacks `clients:write` scope. | | 404 | not_found | client | Client not found. | | 422 | unprocessable_entity | client_already_deactivated | Client is already deactivated. | | 429 | rate_limited | burst_limit_exceeded | Per-minute request limit exceeded. | | 429 | rate_limited | daily_quota_exceeded | Daily request quota exceeded. | | 502 | upstream_unavailable | | The upstream service is unavailable. | - [List Client Custom Attributes](https://developers.agendapro.com/reference/listclientcustomattributes.md): Returns the custom attribute values for a specific client. These are the values that fill the templates returned by `GET /v3/custom_attributes`. ### Errors Dictionary | **Status** | **Error** | **Detail** | **Description** | | --- | --- | --- | --- | | 401 | unauthorized | invalid_api_key | Missing or invalid Bearer token. | | 401 | unauthorized | api_config_inactive | API access is inactive for this company. | | 403 | forbidden | scope_denied | API key lacks `clients:read` scope. | | 404 | not_found | client | Client not found. | | 429 | rate_limited | burst_limit_exceeded | Per-minute request limit exceeded. | | 429 | rate_limited | daily_quota_exceeded | Daily request quota exceeded. | | 502 | upstream_unavailable | | The upstream service is unavailable. | - [List Custom Attribute Templates](https://developers.agendapro.com/reference/listcustomattributetemplates.md): Returns the custom attribute templates configured for the company. These define which custom attributes can be set on clients. Use template `id` values when setting `custom_attributes` on client create/update. ### Errors Dictionary | **Status** | **Error** | **Detail** | **Description** | | --- | --- | --- | --- | | 401 | unauthorized | invalid_api_key | Missing or invalid Bearer token. | | 401 | unauthorized | api_config_inactive | API access is inactive for this company. | | 403 | forbidden | scope_denied | API key lacks `custom_attributes:read` scope. | | 429 | rate_limited | burst_limit_exceeded | Per-minute request limit exceeded. | | 429 | rate_limited | daily_quota_exceeded | Daily request quota exceeded. | | 502 | upstream_unavailable | | The upstream service is unavailable. | - [List Locations](https://developers.agendapro.com/reference/listlocations.md): This endpoint returns a paginated list of locations for the company. ### Errors Dictionary | **Status** | **Error** | **Detail** | **Description** | | --- | --- | --- | --- | | 401 | unauthorized | invalid_api_key | Missing or invalid Bearer token. | | 401 | unauthorized | api_config_inactive | API access is inactive for this company. | | 403 | forbidden | scope_denied | API key lacks `locations:read` scope. | | 429 | rate_limited | burst_limit_exceeded | Per-minute request limit exceeded. | | 429 | rate_limited | daily_quota_exceeded | Daily request quota exceeded. | | 502 | upstream_unavailable | | The upstream service is unavailable. | - [Get Location](https://developers.agendapro.com/reference/getlocation.md): This endpoint returns a single location by ID. ### Errors Dictionary | **Status** | **Error** | **Detail** | **Description** | | --- | --- | --- | --- | | 401 | unauthorized | invalid_api_key | Missing or invalid Bearer token. | | 401 | unauthorized | api_config_inactive | API access is inactive for this company. | | 403 | forbidden | scope_denied | API key lacks `locations:read` scope. | | 404 | not_found | location | Location not found. | | 429 | rate_limited | burst_limit_exceeded | Per-minute request limit exceeded. | | 429 | rate_limited | daily_quota_exceeded | Daily request quota exceeded. | | 502 | upstream_unavailable | | The upstream service is unavailable. | - [List Services](https://developers.agendapro.com/reference/listservices.md): This endpoint returns a paginated list of services for the company. ### Errors Dictionary | **Status** | **Error** | **Detail** | **Description** | | --- | --- | --- | --- | | 401 | unauthorized | invalid_api_key | Missing or invalid Bearer token. | | 401 | unauthorized | api_config_inactive | API access is inactive for this company. | | 403 | forbidden | scope_denied | API key lacks `services:read` scope. | | 429 | rate_limited | burst_limit_exceeded | Per-minute request limit exceeded. | | 429 | rate_limited | daily_quota_exceeded | Daily request quota exceeded. | | 502 | upstream_unavailable | | The upstream service is unavailable. | - [Get Service](https://developers.agendapro.com/reference/getservice.md): This endpoint returns a single service by ID. ### Errors Dictionary | **Status** | **Error** | **Detail** | **Description** | | --- | --- | --- | --- | | 401 | unauthorized | invalid_api_key | Missing or invalid Bearer token. | | 401 | unauthorized | api_config_inactive | API access is inactive for this company. | | 403 | forbidden | scope_denied | API key lacks `services:read` scope. | | 404 | not_found | service | Service not found. | | 429 | rate_limited | burst_limit_exceeded | Per-minute request limit exceeded. | | 429 | rate_limited | daily_quota_exceeded | Daily request quota exceeded. | | 502 | upstream_unavailable | | The upstream service is unavailable. | - [List Categories](https://developers.agendapro.com/reference/listcategories.md): This endpoint returns a paginated list of service categories for the company, ordered by the `order` field ascending (ties broken by `id` ascending). ### Errors Dictionary | **Status** | **Error** | **Detail** | **Description** | | --- | --- | --- | --- | | 401 | unauthorized | invalid_api_key | Missing or invalid Bearer token. | | 401 | unauthorized | api_config_inactive | API access is inactive for this company. | | 403 | forbidden | scope_denied | API key lacks `categories:read` scope. | | 429 | rate_limited | burst_limit_exceeded | Per-minute request limit exceeded. | | 429 | rate_limited | daily_quota_exceeded | Daily request quota exceeded. | | 502 | upstream_unavailable | | The upstream service is unavailable. | - [List Providers](https://developers.agendapro.com/reference/listproviders.md): This endpoint returns a paginated list of service providers for the company. ### Errors Dictionary | **Status** | **Error** | **Detail** | **Description** | | --- | --- | --- | --- | | 401 | unauthorized | invalid_api_key | Missing or invalid Bearer token. | | 401 | unauthorized | api_config_inactive | API access is inactive for this company. | | 403 | forbidden | scope_denied | API key lacks `providers:read` scope. | | 429 | rate_limited | burst_limit_exceeded | Per-minute request limit exceeded. | | 429 | rate_limited | daily_quota_exceeded | Daily request quota exceeded. | | 502 | upstream_unavailable | | The upstream service is unavailable. | - [Get Provider](https://developers.agendapro.com/reference/getprovider.md): This endpoint returns a single service provider by ID. ### Errors Dictionary | **Status** | **Error** | **Detail** | **Description** | | --- | --- | --- | --- | | 401 | unauthorized | invalid_api_key | Missing or invalid Bearer token. | | 401 | unauthorized | api_config_inactive | API access is inactive for this company. | | 403 | forbidden | scope_denied | API key lacks `providers:read` scope. | | 404 | not_found | provider | Provider not found. | | 429 | rate_limited | burst_limit_exceeded | Per-minute request limit exceeded. | | 429 | rate_limited | daily_quota_exceeded | Daily request quota exceeded. | | 502 | upstream_unavailable | | The upstream service is unavailable. | - [List Sales](https://developers.agendapro.com/reference/listsales.md): This endpoint returns a paginated list of sales for the company. ### Important Notes - Requires `sales:read` scope. - Sales are read-only via the public API. ### Errors Dictionary | **Status** | **Error** | **Detail** | **Description** | | --- | --- | --- | --- | | 401 | unauthorized | invalid_api_key | Missing or invalid Bearer token. | | 401 | unauthorized | api_config_inactive | API access is inactive for this company. | | 403 | forbidden | scope_denied | API key lacks `sales:read` scope. | | 429 | rate_limited | burst_limit_exceeded | Per-minute request limit exceeded. | | 429 | rate_limited | daily_quota_exceeded | Daily request quota exceeded. | | 502 | upstream_unavailable | | The upstream service is unavailable. | - [Get Sale](https://developers.agendapro.com/reference/getsale.md): This endpoint returns a single sale by ID. ### Errors Dictionary | **Status** | **Error** | **Detail** | **Description** | | --- | --- | --- | --- | | 401 | unauthorized | invalid_api_key | Missing or invalid Bearer token. | | 401 | unauthorized | api_config_inactive | API access is inactive for this company. | | 403 | forbidden | scope_denied | API key lacks `sales:read` scope. | | 404 | not_found | sale | Sale not found. | | 429 | rate_limited | burst_limit_exceeded | Per-minute request limit exceeded. | | 429 | rate_limited | daily_quota_exceeded | Daily request quota exceeded. | | 502 | upstream_unavailable | | The upstream service is unavailable. | - [Create Cart](https://developers.agendapro.com/reference/createcart.md): Creates a shopping cart. The cart is the first step of the online payment flow: add items, then create a payment request on the cart to obtain a checkout URL. ### Important Notes - Requires `carts:write` scope. - **Online payments must be enabled for the company** to complete the flow. Carts can be created regardless, but payment request creation fails when online payments are disabled. - The cart always belongs to the authenticated company; any `company_id` sent in the body is ignored. - To sell a service and book it in the same flow, send an item with `item_type: "service"` and a single instance `{ "instance_type": "booking", "reference_id": null, "data": { "start_time": "...", "provider_id": ... } }`. The booking is created automatically when the payment request is created, and released automatically if the payment request expires or is cancelled. - `data.start_time` must be an ISO 8601 datetime in **UTC** (`Z` or `+00:00`, e.g. `2026-08-01T13:00:00Z`). Other offsets are accepted here but rejected when the booking is reserved at payment-request time (`invalid_start_time`). - `data.creative_source` cannot be set: it is always `connect` for the public API (any value sent is overridden). - Carts expire after 24 hours. - Item validation errors (400/422) from platform-sales are passed through unchanged; see the platform-sales carts documentation for the full dictionary. - Business errors proxied from platform-sales use legacy single-key codes (e.g. `cart_not_found`, `invalid_start_time`, `creative_source_not_public`) rather than the `{error, detail}` shape used by connect-level errors (auth, scope, rate limit). ### Errors Dictionary | **Status** | **Error** | **Detail** | **Description** | | --- | --- | --- | --- | | 401 | unauthorized | invalid_api_key | Missing or invalid Bearer token. | | 401 | unauthorized | api_config_inactive | API access is inactive for this company. | | 403 | forbidden | scope_denied | API key lacks `carts:write` scope. | | 400, 422 | *(upstream)* | | Item validation errors from platform-sales are passed through with legacy single-key codes (e.g. `item_invalid_type`, `invalid_start_time`, `creative_source_not_public`); see the platform-sales carts documentation for the full list. | | 429 | rate_limited | burst_limit_exceeded | Per-minute request limit exceeded. | | 429 | rate_limited | daily_quota_exceeded | Daily request quota exceeded. | | 502 | upstream_unavailable | | The upstream service is unavailable. | - [Get Cart](https://developers.agendapro.com/reference/getcart.md): Returns a single cart by ID. Only carts belonging to the authenticated company are visible; other carts return 404. ### Errors Dictionary | **Status** | **Error** | **Detail** | **Description** | | --- | --- | --- | --- | | 401 | unauthorized | invalid_api_key | Missing or invalid Bearer token. | | 401 | unauthorized | api_config_inactive | API access is inactive for this company. | | 403 | forbidden | scope_denied | API key lacks `carts:read` scope. | | 404 | cart_not_found | | Cart not found for this company. | | 429 | rate_limited | burst_limit_exceeded | Per-minute request limit exceeded. | | 429 | rate_limited | daily_quota_exceeded | Daily request quota exceeded. | | 502 | upstream_unavailable | | The upstream service is unavailable. | - [Update Cart](https://developers.agendapro.com/reference/updatecart.md): Updates a cart's items or client. Only carts belonging to the authenticated company can be updated; other carts return 404. ### Important Notes - Requires `carts:write` scope. - Sending `items` replaces the full items array. - Any payment request in `pending` status on the cart is cancelled automatically before applying the update, and on-demand bookings reserved by it are released. - The cart must not be expired and must not have paid or partially paid sales. - Item validation errors (400/422) from platform-sales are passed through unchanged. ### Errors Dictionary | **Status** | **Error** | **Detail** | **Description** | | --- | --- | --- | --- | | 401 | unauthorized | invalid_api_key | Missing or invalid Bearer token. | | 401 | unauthorized | api_config_inactive | API access is inactive for this company. | | 403 | forbidden | scope_denied | API key lacks `carts:write` scope. | | 404 | cart_not_found | | Cart not found for this company. | | 422 | cart_expired | | The cart has expired (older than 24 hours). | | 422 | cart_paid | | The cart already has a paid sale. | | 400, 422 | *(upstream)* | | Item validation errors from platform-sales are passed through with legacy single-key codes (e.g. `item_invalid_type`, `invalid_start_time`, `creative_source_not_public`); see the platform-sales carts documentation for the full list. | | 429 | rate_limited | burst_limit_exceeded | Per-minute request limit exceeded. | | 429 | rate_limited | daily_quota_exceeded | Daily request quota exceeded. | | 502 | upstream_unavailable | | The upstream service is unavailable. | - [Create Payment Request](https://developers.agendapro.com/reference/createpaymentrequest.md): Creates an online payment request for the cart and returns a checkout URL in `params.checkout_url`. Share that URL with the end customer to collect the payment. ### Important Notes - Requires `carts:write` scope. - **Online payments must be enabled for the company**; otherwise the request fails. - The payment channel is always `online`; it cannot be selected through the public API. - Booking reservation errors proxied from platform-sales use legacy single-key codes (e.g. `company_payments_disabled`, `invalid_start_time`, `booking_already_sold`), not the `{error, detail}` shape. - The payment request always covers the full cart total. - When the cart contains service items with on-demand booking instances, the bookings are created and reserved at this point, and `params.expires_at` is set (about 15 minutes): if the payment is not completed by then, the payment request expires and the reserved bookings are released automatically. - Creating a new payment request on a cart cancels any previous `pending` one. ### Errors Dictionary | **Status** | **Error** | **Detail** | **Description** | | --- | --- | --- | --- | | 401 | unauthorized | invalid_api_key | Missing or invalid Bearer token. | | 401 | unauthorized | api_config_inactive | API access is inactive for this company. | | 403 | forbidden | scope_denied | API key lacks `carts:write` scope. | | 404 | cart_not_found | | Cart not found for this company. | | 422 | company_payments_disabled | | Online payments are not enabled for the company or the cart items are not payable online. | | 429 | rate_limited | burst_limit_exceeded | Per-minute request limit exceeded. | | 429 | rate_limited | daily_quota_exceeded | Daily request quota exceeded. | | 502 | upstream_unavailable | | The upstream service is unavailable. | - [Cancel Payment Request](https://developers.agendapro.com/reference/cancelpaymentrequest.md): Cancels a pending payment request. Bookings that were reserved when the payment request was created are released immediately instead of waiting for the expiration timeout. Use this when the customer abandons the checkout or the cart changes. ### Errors Dictionary | **Status** | **Error** | **Detail** | **Description** | | --- | --- | --- | --- | | 401 | unauthorized | invalid_api_key | Missing or invalid Bearer token. | | 401 | unauthorized | api_config_inactive | API access is inactive for this company. | | 403 | forbidden | scope_denied | API key lacks `payment_requests:write` scope. | | 404 | payment_request_not_found | | Payment request not found for this company. | | 422 | payment_request_invalid_status | | The payment request is not in `pending` status. | | 429 | rate_limited | burst_limit_exceeded | Per-minute request limit exceeded. | | 429 | rate_limited | daily_quota_exceeded | Daily request quota exceeded. | | 502 | upstream_unavailable | | The upstream service is unavailable. |