> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bookingshake.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Update a payment

> Partially update a payment by its document ID. Only the fields provided in the body are modified; omitted fields are left unchanged.

The body follows the same contract as the response: `amount` in integer cents, dates as `YYYY-MM-DD` (interpreted in `Europe/Paris`), and `status` verbatim. The `received_date` and `due_date` fields accept `null` to clear them.

Updating a payment automatically emits the `payment.updated` webhook. Security deposits (holds) are out of scope and return `404`.



## OpenAPI

````yaml /api-reference/bookingshake-openapi.json patch /payments/{id}
openapi: 3.0.3
info:
  title: BookingShake API
  description: >-
    The BookingShake API allows you to programmatically create and manage
    events, bookings, and related resources. Integrate BookingShake with your
    applications to automate event creation, retrieve booking sources, spaces,
    statuses, and custom fields.


    **Rate Limiting:** All endpoints are rate limited per API key. POST
    /events/create allows 10 requests per minute, while GET endpoints allow 60
    requests per minute. Rate limit information is provided in response headers
    (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset).
  version: 1.0.0
  contact:
    name: BookingShake Support
    email: support@bookingshake.com
    url: https://bookingshake.com
servers:
  - url: https://api.bookingshake.io/api
    description: Production server
security:
  - bearerAuth: []
tags:
  - name: Events
    description: Create and manage events and bookings
  - name: Resources
    description: Retrieve booking sources, spaces, and statuses
  - name: Fields
    description: Retrieve available custom and default fields
  - name: Invoices
    description: Retrieve issued invoices
  - name: Payments
    description: Retrieve payments
  - name: Contacts
    description: Retrieve contacts (people)
  - name: Products
    description: Retrieve the venue product catalog
paths:
  /payments/{id}:
    patch:
      tags:
        - Payments
      summary: Update a payment
      description: >-
        Partially update a payment by its document ID. Only the fields provided
        in the body are modified; omitted fields are left unchanged.


        The body follows the same contract as the response: `amount` in integer
        cents, dates as `YYYY-MM-DD` (interpreted in `Europe/Paris`), and
        `status` verbatim. The `received_date` and `due_date` fields accept
        `null` to clear them.


        Updating a payment automatically emits the `payment.updated` webhook.
        Security deposits (holds) are out of scope and return `404`.
      operationId: updatePayment
      parameters:
        - name: id
          in: path
          required: true
          description: >-
            Payment document ID (the `id` field carried by the payment.*
            webhooks).
          schema:
            type: string
          example: payment-789
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePaymentRequest'
            example:
              status: paid
              received_date: '2026-06-10'
              amount: 90000
      responses:
        '200':
          description: >-
            Payment updated successfully. Returns the full payment in its
            post-update state.
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
              description: Maximum requests allowed per minute (30 for this endpoint)
            X-RateLimit-Remaining:
              schema:
                type: integer
              description: Requests remaining in the current window
            X-RateLimit-Reset:
              schema:
                type: integer
              description: Unix timestamp when the rate limit resets
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: success
                  data:
                    $ref: '#/components/schemas/Payment'
              example:
                message: success
                data:
                  id: payment-789
                  amount: 90000
                  status: paid
                  name: Acompte 30%
                  method: Virement bancaire
                  received_date: '2026-06-10'
                  due_date: '2026-06-15'
                  created_at: 1749549600000
                  updated_at: 1749722400000
                  invoice_id: file-456
                  invoice_number: FAC-2026-0021
                  quote_id: quote-123
                  booking_id: booking-abc
        '400':
          description: >-
            Bad request - invalid token, missing payment id, empty/invalid body,
            no updatable fields, or a field that fails validation (e.g. unknown
            status, non-integer amount, malformed date).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: 'status must be one of: waiting, paid, canceled'
        '404':
          description: >-
            Payment not found. Returned when the payment does not exist, belongs
            to another venue, or is a security deposit (hold).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: not found
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: error
      security:
        - bearerAuth: []
components:
  schemas:
    UpdatePaymentRequest:
      type: object
      description: >-
        Fields that can be updated on a payment. All fields are optional
        (partial update): only the fields present in the body are modified. Same
        conventions as the response - `amount` in integer cents, dates as
        `YYYY-MM-DD` in the `Europe/Paris` timezone. At least one field must be
        provided.
      minProperties: 1
      additionalProperties: false
      properties:
        name:
          type: string
          maxLength: 255
          description: Payment label
          example: Acompte 30%
        amount:
          type: integer
          minimum: 0
          description: Amount in integer cents
          example: 90000
        status:
          type: string
          enum:
            - waiting
            - paid
            - canceled
          example: paid
        method:
          type: string
          maxLength: 255
          description: Payment method, verbatim label
          example: Virement bancaire
        received_date:
          type: string
          format: date
          nullable: true
          description: Date the payment was received, YYYY-MM-DD. Pass null to clear.
          example: '2026-06-10'
        due_date:
          type: string
          format: date
          nullable: true
          description: Date the payment is expected, YYYY-MM-DD. Pass null to clear.
          example: '2026-06-15'
    Payment:
      type: object
      description: >-
        A payment. Identical to the `data` block of the payment.* webhooks.
        Amount is integer cents; dates are `YYYY-MM-DD` strings in the
        `Europe/Paris` timezone; timestamps are Unix milliseconds; missing
        values are explicit `null`.
      properties:
        id:
          type: string
          description: Unique payment ID
        amount:
          type: integer
          nullable: true
          description: Amount in integer cents
        status:
          type: string
          nullable: true
          enum:
            - waiting
            - paid
            - canceled
        name:
          type: string
          nullable: true
          description: Payment label as entered by the user
        method:
          type: string
          nullable: true
          description: >-
            Payment method, verbatim label (not a normalized enum); appears in
            the venue locale language. Do not build logic on exact values.
        received_date:
          type: string
          nullable: true
          description: Date the payment was received, YYYY-MM-DD
        due_date:
          type: string
          nullable: true
          description: Date the payment is expected, YYYY-MM-DD
        created_at:
          type: integer
          nullable: true
          description: Creation timestamp, Unix milliseconds
        updated_at:
          type: integer
          nullable: true
          description: Last update timestamp, Unix milliseconds
        invoice_id:
          type: string
          nullable: true
          description: ID of the linked invoice (matches the invoice document id)
        invoice_number:
          type: string
          nullable: true
          description: Number of the linked invoice, denormalized for convenience
        quote_id:
          type: string
          nullable: true
          description: ID of the linked quote
        booking_id:
          type: string
          nullable: true
          description: >-
            Opaque correlation key of the booking, shared by all payments and
            invoices of the same booking
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
          description: Error message describing what went wrong
          example: invalid token
    RateLimitResponse:
      type: object
      properties:
        message:
          type: string
          description: Error message
          example: Rate limit exceeded
        data:
          type: object
          properties:
            limit:
              type: integer
              description: Maximum requests allowed per window
              example: 10
            window:
              type: string
              description: Time window duration
              example: 60 seconds
            remaining:
              type: integer
              description: Requests remaining (always 0 on rate limit error)
              example: 0
            resetAt:
              type: string
              format: date-time
              description: ISO 8601 timestamp when the limit resets
              example: '2025-11-17T14:30:00.000Z'
            retryAfter:
              type: integer
              description: Seconds to wait before retrying
              example: 45
  responses:
    RateLimitExceeded:
      description: Rate limit exceeded - too many requests
      headers:
        X-RateLimit-Limit:
          schema:
            type: integer
          description: Maximum requests allowed per minute
        X-RateLimit-Remaining:
          schema:
            type: integer
          description: Requests remaining (always 0 on 429)
        X-RateLimit-Reset:
          schema:
            type: integer
          description: Unix timestamp when the rate limit resets
        Retry-After:
          schema:
            type: integer
          description: Seconds to wait before retrying
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimitResponse'
          example:
            message: Rate limit exceeded
            data:
              limit: 60
              window: 60 seconds
              remaining: 0
              resetAt: '2025-11-17T14:30:00.000Z'
              retryAfter: 45
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        Bearer authentication using your BookingShake API key. Retrieve your API
        key from Settings > Integrations in your BookingShake dashboard.

````