---
title: "Update a Checkout"
method: PATCH
path: "/checkouts/{id}"
tags: ["Checkouts"]
---

# Update a Checkout

`PATCH /checkouts/{id}`

## Request

- Base URL: `https://api.justifi.ai/v1`
- URL: `https://api.justifi.ai/v1/checkouts/{id}`
- Auth: none declared. Required headers: `Authorization`
- TypeScript: <https://skmtc.dev/justifi/apis/justifi-api-documentation/docs/checkouts/:id/patch.ts> (a function with typed inputs; its response is checked against the schema)

Change a checkout's amount or description

## Path parameters

- `id` string, uuid, required

## Headers

- `Authorization` string, required

## Request body

- object
  - `amount` number: amount to charge in cents, must be an integer greater than 50 (equivalent to $0.50)
  - `description` string: your meaningful description of the checkout (e.g. an order number or other value from your system)
  - `statement_descriptor` string: description of the payment that will be available on the account's bank statement, must have between 5-22 alphanumeric characters and can include dash or underscore
  - `metadata` object: any useful information you'd like to store alongside this checkout; when you update metadata, any previous metadata will be overwritten
  - `application_fees` object: (card/ach and card present only, not available for bnpl) sets a custom application fee amount that applies to this payment, instead of relying on application fee rates configured at the platform account level. Must be greater than zero.
    - `card` object
      - `amount` number: custom application fee amount that applies to card payment method.
    - `bank_account` object
      - `amount` number: custom application fee amount that applies to bank account payment method.
  - `payment` object: Overrides the information saved on the Payment when a checkout is paid via JustiFi card/ach payment
    - `description` string: Overrides the default payment description of "Checkout [checkout id]"
    - `metadata` object: Adds metadata to the payment record
    - `expedited` boolean: settlement priority of the payment, only applies to ACH payments
    - `fees` Fee[]: *Recommended for new integrations.* Fees to apply to the payment. See [Enhanced Fee Management](#section/Enhanced-Fee-Management) for full documentation. Each fee object specifies: - `type`: `processing_fee` or `platform_fee` (required) - `amount`: Fee amount in cents (required) Cannot be used together with `application_fees`. > **Note:** The `fees` array will be empty in the create response. Fees are processed asynchronously — subscribe to payment webhook events (recommended) to receive the full fee details, or poll with a subsequent Get Payment request. > **CAD Payments:** This parameter is not available for CAD payments. Fees for Canadian dollar payments are determined during merchant onboarding and are not configurable via the API. See [Canadian Payments](https://docs.justifi.tech/payments/canadianPayments) for details.
      - `type` 'processing_fee' | 'platform_fee', required: The type of fee: - `processing_fee`: Fees related to payment processing costs - `platform_fee`: Fees for your platform's services
      - `amount` integer, required: Fee amount in cents

## Response `200`

Checkout update was successful

- object
  - `id` string, uuid: the object id, also found in the data object
  - `type` string: the object type, or array of objects
  - `data` object: the attributes for the object
    - `id` string, uuid: unique checkout id
    - `account_id` string, uuid: id of the account associated with the checkout
    - `platform_account_id` string, uuid: id of the platform account associated with the checkout
    - `payment_intent_id` string, uuid: id of the payment intent associated with the checkout
    - `payment_amount` number: the amount charged in cents
    - `payment_currency` 'USD' | 'CAD'
    - `payment_description` string: your custom description of the payment if passed in the `payment` property during checkout creation, otherwise "Checkout [checkout id]"
    - `payment_methods` unknown[]: if `payment_method_group_id` was provided, list of payment methods contained in that payment method group
      - unknown
    - `payment_method_group_id` string, uuid: id of payment method group used for checkout, if provided
    - `status` 'created' | 'completed' | 'attempted' | 'expired': status of the checkout
    - `mode` 'test' | 'live': mode of the checkout
    - `successful_payment_id` string, uuid: payment id, if this checkout was paid for successfully
    - `statement_descriptor` string: description of the payment that will be available on the account's bank statement
    - `metadata` object
    - `application_fees` object: **Deprecated**: Use the `fees` object instead for granular control over fee types and selective refunds. **New integrations** should use `payment.fees` instead for selective refund support. See [Enhanced Fee Management](#section/Enhanced-Fee-Management).
      - `card` object
        - `amount` unknown
      - `bank_account` object
        - `amount` unknown
    - `payment_settings` object: payment configuration information for the checkout
    - `payment` object: data passed to the `payment` property during checkout creation, or null
      - `description` string: your meaningful description of the payment (e.g. an order number or other value from your system)
      - `metadata` object: any useful custom information stored alongside this payment
      - `expedited` boolean: settlement priority of the payment, defaults to false
      - `fees` Fee[]: Array of fee objects specifying the fees to be applied when the checkout is completed. See [Enhanced Fee Management](#section/Enhanced-Fee-Management) for full documentation.
        - `type` 'processing_fee' | 'platform_fee', required: The type of fee: - `processing_fee`: Fees related to payment processing costs - `platform_fee`: Fees for your platform's services
        - `amount` integer, required: Fee amount in cents
    - `created_at` string, date-time
    - `updated_at` string, date-time
    - `completions` CheckoutCompletionAttempt[]: list of checkout completion attempts, if any
      - `id` string: unique checkout completion id
      - `payment_mode` 'ecom' | 'bnpl' | 'card_present'
      - `payment_token` string: the payment method token used to process the payment, only for ecom payments
      - `status` 'succeeded' | 'failed' | 'processing': the status of the completion, only succeeded or failed
      - `payment_status` 'succeeded' | 'failed' | 'pending' | 'canceled' | 'skipped': depending upon payment mode, the status of the payment API call, bnpl transaction, or card reader transaction.
      - `payment_error_code` string: when payment fails, related error code
      - `payment_error_description` string: when payment fails, related error description
      - `payment_response` object: payment object if completion attempt was successful, error object if not successful
        - `id` string: unique payment id, same as id in data object
        - `type` string: the object type
        - `data` CardPayment
          - `id` string: unique payment id
          - `account_id` string, uuid
          - `amount` number: payment amount in cents
          - `amount_disputed` number: sum of open or lost disputes for this payment, in cents
          - `amount_refunded` number: sum of refunds for this payment, in cents
          - `amount_refundable` number: amount of this payment currently able to be refunded, in cents
          - `balance` number: sum of debits and credits for this payment, in cents (reflects the amount this account has earned from this payment). Compiled and calculated value, eventually consistent. To see all changes affecting the payment's balance call [Get Balance Transactions](#operation/GetPaymentBalanceTransactions)
          - `fee_amount` number: sum of fees for this payment
          - `financial_transaction_id` string: associated financial transaction id
          - `captured` boolean: whether or not this payment is captured
          - `capture_strategy` 'automatic' | 'manual'
          - `currency` 'usd' | 'cad'
          - `description` string: your meaningful description of the payment (e.g. an order number or other value from your system)
          - `disputed` boolean: whether or not this payment has any open or lost disputes
          - `disputes` unknown[]: list of associated disputes
            - unknown
          - `error_code` string: error code if the payment fails
          - `error_description` string: text description of the error code
          - `is_test` boolean: whether or not this payment was made using the test account
          - `metadata` object: any useful information you'd like to store alongside this payment
          - `payment_intent_id` string: unique id of associated payment intent
          - `checkout_id` string: unique id of associated checkout
          - `payment_method` CardPaymentMethod
            - `card` Card
              - …
            - `customer_id` string, nullable: customer_id is a deprecated field. Please use our payment method groups instead.
            - `signature` string, nullable: signature that uniquely identifies a credit card or bank account across payment methods
            - `account_id` string, nullable: account id associated with payment method
          - `application_fee` ApplicationFee
            - `id` string, uuid: unique application fee id
            - `amount` number: application fee amount, in cents
            - `currency` 'usd' | 'cad'
            - `created_at` string, date-time
            - `updated_at` string, date-time
          - `application_fee_rate_id` string: unique id of application fee rate applied to this payment, if any
          - `fees` FeeResponse[]: Array of fee objects showing the fees charged on this payment with their remaining refundable amounts. Populated whether the fees were provided via the `fees` array in the payment request or calculated automatically (for example, from a Standard Fee Configuration, or the `processing_fee` on a CAD payment). **Note:** This array is empty in the Create Payment response. Fees are processed asynchronously — subscribe to payment webhook events (recommended) to receive the full fee objects (with `id`, `remaining_amount`, and `currency`), or poll with a subsequent Get Payment request. See [Enhanced Fee Management](https://docs.justifi.tech/api-spec#section/Enhanced-Fee-Management) for full documentation.
            - `id` string: Unique identifier for this fee. Present when fetching a payment.
            - `type` 'processing_fee' | 'platform_fee' | 'refund_processing_fee', required: The type of fee: - `processing_fee`: Fees related to payment processing costs - `platform_fee`: Fees for your platform's services - `refund_processing_fee`: A processing fee charged when a refund is processed. Currently applies to CAD payments only.
            - `amount` integer, required: Fee amount in cents
            - `currency` 'usd' | 'cad': Currency of the fee amount. Present when fetching a payment.
            - `remaining_amount` integer: Amount still available for refund in cents. Updates after each partial refund. Present when fetching a payment.
            - `source_configuration_id` string, nullable: The public ID of the Standard Fee Configuration used to calculate this fee. Null when the fee was explicitly provided in the payment request rather than auto-calculated.
            - `source_fee_type` string, nullable: The fee type from the Standard Fee Configuration that generated this fee (e.g., `processing_ecomm`, `amex_brand_ecomm`, `platform`). Null when the fee was explicitly provided in the payment request.
            - `refund_id` string, nullable: The public ID of the refund this fee is associated with. Populated for `refund_processing_fee` fees (currently CAD payments only); null for all other fees. Present when fetching a payment.
          - `refunded` boolean: whether or not this payment has any refunds
          - `status` 'pending' | 'authorized' | 'canceled' | 'succeeded' | 'failed' | 'partially_refunded' | 'fully_refunded' | 'disputed': status of the payment
          - `payment_mode` 'ecom' | 'ach' | 'card_present'
          - `terminal_id` string: id of terminal used to process the card payment, if any
          - `transaction_hold` object: present when the payment has been flagged for review and held from payouts
            - `id` string: unique transaction hold id
            - `financial_transaction_id` string, uuid: financial transaction id the transaction hold is associated to
          - `expedited` boolean, nullable: settlement priority of the payment, only applies to ACH payments
          - `created_at` string, date-time
          - `updated_at` string, date-time
        - `page_info` unknown
      - `checkout_id` string, uuid: id of the checkout for this completion
      - `additional_transactions` unknown
      - `payment_id` string, uuid: id of the payment associated with this checkout, when successful
      - `payment_method_id` string, uuid: id of the payment method associated with this checkout, when successful
      - `terminal_id` string, uuid: id of the terminal used for this checkout, when mode is card present
      - `created_at` string, date-time
      - `updated_at` string, date-time
  - `page_info` unknown

---

[API](https://skmtc.dev/justifi/apis/justifi-api-documentation.md) - [All operations](https://skmtc.dev/justifi/apis/justifi-api-documentation/llms.txt) - [OpenAPI document](https://skmtc.dev/justifi/apis/justifi-api-documentation/revisions/dd9f3fed7e46?raw)