---
title: "tipConfiguration"
method: GET
path: "/v2/merchant/tipConfiguration"
tags: ["Merchant Management"]
---

# tipConfiguration

`GET /v2/merchant/tipConfiguration`

## Request

- Base URL: `https://api.sandbox-pay.aero.inc`
- URL: `https://api.sandbox-pay.aero.inc/v2/merchant/tipConfiguration`
- Auth: none declared. Required headers: `authorization`
- TypeScript: <https://skmtc.dev/aero/apis/aeropay-v2-api/docs/v2/merchant/tipConfiguration/get.ts> (a function with typed inputs; its response is checked against the schema)

Retrieve the Aeropay tipping configuration for the authenticated merchant.

Use this endpoint to render tip options in your own checkout flow instead of maintaining a duplicate copy of the merchant's tip settings. Tip settings are managed in the Aeropay Merchant Portal, and this response always reflects their current state.

The merchant is derived from the merchant-scoped token, so this endpoint takes no request parameters. Tipping is configured at the merchant level and cannot be configured per merchant location.

### Check `enabled` first

The response has two shapes. When tipping is off, `tipConfiguration` contains `enabled` and nothing else:

```json
{"tipConfiguration": {"enabled": false}}
```

`options`, `defaultValue`, and `customTipEnabled` are omitted entirely rather than returned empty, because they describe how to render a tip prompt that will never be shown. A merchant that configured tip options and later turned tipping off returns this same response - leftover options are not surfaced. Read `enabled` before reading any other field.

A merchant with no tipping configuration at all returns this same shape with `200`. It is not an error condition.

### Reading `options`

When `enabled` is `true`, each entry in `options` is discriminated by `type`, and the shape of `value` changes accordingly:

- `type: "percentage"` — `value` is the tip percentage as a number, for example `15` or `12.5`. It is a percentage of the transaction amount, not a decimal multiplier.
- `type: "flat"` — `value` is a money object, `{"amount": <integer cents>, "currency": "USD"}`, matching the amount convention used elsewhere in the v2 API. An `amount` of `500` is $5.00.

A custom (user-entered) tip is reported by the `customTipEnabled` boolean and is never returned as an entry in `options`. A merchant whose only configured tip is a custom one returns `enabled: true` with an empty `options` array and `customTipEnabled: true`.

This endpoint is read-only and does not apply a tip. Once a tip is selected, send it as a tip attribute on `POST /v2/transaction` or `PATCH /v2/preauthTransaction/{preauthTransactionId}`.

<details>
<summary><strong>Error Glossary</strong> (click to expand)</summary>

| Code | HTTP Status | Message |
|------|-------------|---------|
| `AP101` | 401 | A merchant-scoped token is required |

</details>

## Headers

- `authorization` string, required

## Response `200`

Success - Tip configuration retrieved

- union
  - TipConfigurationResponse
    - `tipConfiguration` union: The merchant's current tipping configuration. Returned in one of two shapes depending on `enabled`.
      - object: Returned when the merchant has tipping switched on.
        - `enabled` true, required: Always `true` in this variant. The remaining fields are present only in this shape.
        - `options` object[], required: The tip options configured by the merchant, in configured order. A custom tip is never included here - see `customTipEnabled`. May be empty when the merchant's only configured tip is a custom one.
          - `type` 'percentage' | 'flat': Determines how `value` is interpreted. `percentage` is a percentage of the transaction amount; `flat` is a fixed currency amount.
          - `value` union: The tip value. A number when `type` is `percentage`, a money object when `type` is `flat`.
            - number: Returned when `type` is `percentage`. The tip percentage of the transaction amount, for example `15` or `12.5` - not a decimal multiplier.
            - object: Returned when `type` is `flat`.
              - …
        - `defaultValue` unknown, required
        - `customTipEnabled` boolean, required: Whether the merchant has configured a custom, user-entered tip. When `true`, present a custom tip input alongside `options`. A custom tip is reported here rather than as an entry in `options`.
      - object: Returned when the merchant has tipping switched off, or has no tipping configuration at all. `enabled` is the only key present - `options`, `defaultValue`, and `customTipEnabled` are omitted rather than returned empty.
        - `enabled` false, required: Always `false` in this variant. Do not present tipping at checkout.
  - 200failure
    - `error` object
      - `code` string
      - `message` string
      - `help` string: Support contact information
    - `reasonCodes` string[]: Optional array of granular reason codes returned for certain error types (e.g. AP307).

## Other responses

- `401`: Unauthorized

## Changes

- **2026-11-03** `e7a372a209e8`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/aero/apis/aeropay-v2-api/changes/v2/merchant/tipConfiguration/get.md)

---

[API](https://skmtc.dev/aero/apis/aeropay-v2-api.md) - [All operations](https://skmtc.dev/aero/apis/aeropay-v2-api/llms.txt) - [OpenAPI document](https://skmtc.dev/aero/apis/aeropay-v2-api/revisions/e7a372a209e8?raw)