---
title: "List payment links"
method: GET
path: "/api/v1/payment-links"
tags: ["Payment Links"]
---

# List payment links

`GET /api/v1/payment-links`

## Request

- Base URL: `https://merchant.zahlo.eu`
- URL: `https://merchant.zahlo.eu/api/v1/payment-links`
- Auth: API key in header `x-api-key`

List payment links. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.

## Query parameters

- `limit` integer
- `startingAfter` string
- `endingBefore` string
- `active` boolean

## Response `200`

Successful response

- object
  - `object` 'list', required
  - `data` PaymentLink[], required
    - `id` string, required
    - `object` 'payment_link', required
    - `url` string, uri, required
    - `active` boolean, required
    - `lineItems` object[], required
      - `priceId` string, required
      - `quantity` integer, required
    - `couponId` string, nullable
    - `allowPromotionCodes` boolean
    - `paymentMethodTypes` string[], nullable: Per-link override; null uses the merchant default.
    - `collectCustomerEmail` true, required
    - `shippingAddressCollection` object, nullable: Ask the payer for a shipping address on the link page. Null turns it off.
      - `allowedCountries` string[], required: ISO 3166-1 alpha-2 codes the payer may ship to.
    - `shippingOptions` object[]: Shipping rates the payer picks from on the link page, the first preselected. Needs shippingAddressCollection; one-time links only. An empty list removes them.
      - `shippingRate` string, required: An active shipping rate in the link's currency.
    - `restrictions` object, nullable: Sales limit: the checkout that reaches `limit` turns the link off, and the page shows `inactiveMessage`. Payers checking out at the same moment can go slightly over. Raising the limit does not turn the link back on. Null removes the limit.
      - `completedSessions` object, required
        - `limit` integer, required
        - `count` integer, required: Completed checkouts so far; late payments are not counted.
    - `inactiveMessage` string, nullable: Shown on the link page once the link is off or sold out; null shows the default text.
    - `customFields` CustomField[]: Asked on the link page; `value` is always null here.
      - `key` string, required
      - `label` object, required
        - `type` 'custom', required
        - `custom` string, required
      - `type` 'dropdown' | 'text', required
      - `optional` boolean, required
      - `dropdown` object, nullable, required
        - `options` object[], required
          - `label` string, required
          - `value` string, required
        - `defaultValue` string, nullable, required
        - `value` string, nullable, required
      - `text` object, nullable, required
        - `minimumLength` integer, nullable, required
        - `maximumLength` integer, nullable, required
        - `defaultValue` string, nullable, required
        - `value` string, nullable, required
    - `submitType` 'auto' | 'pay' | 'book' | 'donate': The payment page's button label: `auto` keeps the default, the others say Pay, Book or Donate.
    - `afterCompletion` object
      - `redirectUrl` string, uri, nullable
      - `customMessage` string, nullable: Shown on the confirmation page after payment; null shows the default text. Not shown when `redirectUrl` is set.
    - `phoneNumberCollection` object: The link page asks for a phone number (6 to 20 digits, optional +); the session's `customerDetails.phone`.
      - `enabled` boolean, required
    - `nameCollection` object: The link page asks for a full name and/or a business name (optional next to the full name); the session's `customerDetails`.
      - `individual` object
        - `enabled` boolean, required
      - `business` object
        - `enabled` boolean, required
    - `consentCollection` object
      - `promotions` 'auto' | 'none': `auto`: an optional marketing checkbox; the session's `consent.promotions`.
      - `termsOfService` 'required' | 'none': `required`: a checkbox the payer must tick, linking the terms of service in Checkout → Store policies (400 when none is set).
    - `metadata` object: Up to 50 key-value pairs; keys up to 40 characters, values strings up to 500 characters.
  - `hasMore` boolean, required

## Other responses

- `400`: Invalid request
- `401`: Authentication failed
- `404`: Resource not found
- `409`: Request conflicts with existing state

---

[API](https://skmtc.dev/zahlo/apis/zahlo-merchant-api.md) - [All operations](https://skmtc.dev/zahlo/apis/zahlo-merchant-api/llms.txt) - [OpenAPI document](https://skmtc.dev/zahlo/apis/zahlo-merchant-api/revisions/8fcbef981e0d?raw)