> ## Documentation Index > Fetch the complete documentation index at: https://polar.sh/docs/llms.txt > Use this file to discover all available pages before exploring further. # List Payments > List payments. **Scopes**: `payments:read` ## OpenAPI ````yaml /openapi/2027-01.openapi.json get /v1/payments/ openapi: 3.1.0 info: title: Polar API summary: Polar HTTP and Webhooks API description: >- Read the docs at https://polar.sh/docs/api-reference. See https://polar.sh/docs/api-reference/versioning for the API versioning and deprecation policy. version: 2027-01 servers: - url: https://api.polar.sh description: Production environment x-speakeasy-server-id: production x-polar-environment: production - url: https://sandbox-api.polar.sh description: Sandbox environment x-speakeasy-server-id: sandbox x-polar-environment: sandbox security: [] tags: - name: public description: >- Endpoints shown and documented in the Polar API documentation and available in our SDKs. - name: private description: >- Endpoints that should appear in the schema only in development to generate our internal JS SDK. - name: mcp description: Endpoints supported by Polar's MCP server. - name: cli description: Endpoints exposed as commands by Polar's CLI. externalDocs: description: API versioning and deprecation policy url: https://polar.sh/docs/api-reference/versioning paths: /v1/payments/: get: tags: - payments - public - mcp - cli summary: List Payments description: |- List payments. **Scopes**: `payments:read` operationId: payments:list parameters: - name: organization_id in: query required: false schema: anyOf: - type: string format: uuid4 description: The organization ID. examples: - 1dbfc517-0bbf-4301-9ba8-555ca42b9737 - type: array items: type: string format: uuid4 description: The organization ID. examples: - 1dbfc517-0bbf-4301-9ba8-555ca42b9737 - type: 'null' title: OrganizationID Filter description: Filter by organization ID. description: Filter by organization ID. - name: checkout_id in: query required: false schema: anyOf: - type: string format: uuid4 - items: type: string format: uuid4 type: array - type: 'null' title: CheckoutID Filter description: Filter by checkout ID. description: Filter by checkout ID. - name: order_id in: query required: false schema: anyOf: - type: string format: uuid4 - items: type: string format: uuid4 type: array - type: 'null' title: OrderID Filter description: Filter by order ID. description: Filter by order ID. - name: customer_id in: query required: false schema: anyOf: - type: string format: uuid4 description: The customer ID. - type: array items: type: string format: uuid4 description: The customer ID. - type: 'null' title: CustomerID Filter description: Filter by customer ID. description: Filter by customer ID. - name: status in: query required: false schema: anyOf: - $ref: '#/components/schemas/PaymentStatus' - type: array items: $ref: '#/components/schemas/PaymentStatus' - type: 'null' title: Status Filter description: Filter by payment status. description: Filter by payment status. - name: method in: query required: false schema: anyOf: - type: string - items: type: string type: array - type: 'null' title: Method Filter description: Filter by payment method. description: Filter by payment method. - name: customer_email in: query required: false schema: anyOf: - type: string - items: type: string type: array - type: 'null' title: CustomerEmail Filter description: Filter by customer email. description: Filter by customer email. - name: page in: query required: false schema: type: integer exclusiveMinimum: 0 description: Page number, defaults to 1. default: 1 title: Page description: Page number, defaults to 1. - name: limit in: query required: false schema: type: integer exclusiveMinimum: 0 description: Size of a page, defaults to 10. Maximum is 100. default: 10 title: Limit description: Size of a page, defaults to 10. Maximum is 100. - name: sorting in: query required: false schema: anyOf: - type: array items: $ref: '#/components/schemas/PaymentSortProperty' - type: 'null' description: >- Sorting criterion. Several criteria can be used simultaneously and will be applied in order. Add a minus sign `-` before the criteria name to sort by descending order. default: - '-created_at' title: Sorting description: >- Sorting criterion. Several criteria can be used simultaneously and will be applied in order. Add a minus sign `-` before the criteria name to sort by descending order. responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ListResource_Payment_' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - oidc: - payments:read - pat: - payments:read - oat: - payments:read x-codeSamples: - lang: python source: | from polar.v2027_01 import Polar polar = Polar("polar_oat_xxx") for item in polar.payments.iter_list( page=1, limit=10, sorting=['-created_at'], ): print(item) - lang: typescript source: | import { createPolar } from "@polar-sh/sdk/2027-01"; const polar = createPolar({ accessToken: "polar_oat_xxx", }); for await (const item of polar.payments.iterList( { "page": 1, "limit": 10, "sorting": [ "-created_at" ] }, )) { console.log(item); } components: schemas: PaymentStatus: type: string enum: - pending - succeeded - failed title: PaymentStatus PaymentSortProperty: type: string enum: - created_at - '-created_at' - status - '-status' - amount - '-amount' - method - '-method' title: PaymentSortProperty ListResource_Payment_: properties: items: items: $ref: '#/components/schemas/Payment' type: array title: Items pagination: $ref: '#/components/schemas/Pagination' type: object required: - items - pagination title: ListResource[Payment] HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError Payment: anyOf: - $ref: '#/components/schemas/CardPayment' - $ref: '#/components/schemas/KrCardPayment' - $ref: '#/components/schemas/GenericPayment' Pagination: properties: total_count: type: integer title: Total Count max_page: type: integer title: Max Page type: object required: - total_count - max_page title: Pagination ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError CardPayment: properties: created_at: type: string format: date-time title: Created At description: Creation timestamp of the object. examples: - '2026-01-01T00:00:00.000000Z' modified_at: anyOf: - type: string format: date-time examples: - '2026-01-01T00:00:00.000000Z' - type: 'null' title: Modified At description: Last modification timestamp of the object. id: type: string format: uuid4 title: Id description: The ID of the object. processor: $ref: '#/components/schemas/PaymentProcessor' description: The payment processor. examples: - stripe status: $ref: '#/components/schemas/PaymentStatus' description: The payment status. examples: - succeeded amount: type: integer title: Amount description: The payment amount in cents. examples: - 1000 currency: type: string title: Currency description: The payment currency examples: - usd method: type: string const: card title: Method description: The payment method used. examples: - card trigger: anyOf: - $ref: '#/components/schemas/PaymentTrigger' - type: 'null' description: >- What initiated this payment attempt, e.g. initial purchase, subscription renewal, or an automated dunning retry. examples: - subscription_cycle decline_reason: anyOf: - type: string - type: 'null' title: Decline Reason description: Error code, if the payment was declined. examples: - insufficient_funds decline_message: anyOf: - type: string - type: 'null' title: Decline Message description: Human-readable error message, if the payment was declined. examples: - Your card has insufficient funds. organization_id: type: string format: uuid4 title: Organization Id description: The ID of the organization that owns the payment. examples: - 1dbfc517-0bbf-4301-9ba8-555ca42b9737 checkout_id: anyOf: - type: string format: uuid4 - type: 'null' title: Checkout Id description: The ID of the checkout session associated with this payment. examples: - e4b478fa-cd25-4253-9f1f-8a41e6370ede order_id: anyOf: - type: string format: uuid4 - type: 'null' title: Order Id description: The ID of the order associated with this payment. examples: - e4b478fa-cd25-4253-9f1f-8a41e6370ede processor_metadata: additionalProperties: true type: object title: Processor Metadata description: Additional metadata from the payment processor for internal use. method_metadata: $ref: '#/components/schemas/CardPaymentMetadata' description: Additional metadata for the card payment method. type: object required: - created_at - modified_at - id - processor - status - amount - currency - method - trigger - decline_reason - decline_message - organization_id - checkout_id - order_id - method_metadata title: CardPayment description: Schema of a payment with a card payment method. KrCardPayment: properties: created_at: type: string format: date-time title: Created At description: Creation timestamp of the object. examples: - '2026-01-01T00:00:00.000000Z' modified_at: anyOf: - type: string format: date-time examples: - '2026-01-01T00:00:00.000000Z' - type: 'null' title: Modified At description: Last modification timestamp of the object. id: type: string format: uuid4 title: Id description: The ID of the object. processor: $ref: '#/components/schemas/PaymentProcessor' description: The payment processor. examples: - stripe status: $ref: '#/components/schemas/PaymentStatus' description: The payment status. examples: - succeeded amount: type: integer title: Amount description: The payment amount in cents. examples: - 1000 currency: type: string title: Currency description: The payment currency examples: - usd method: type: string const: kr_card title: Method description: The payment method used. examples: - kr_card trigger: anyOf: - $ref: '#/components/schemas/PaymentTrigger' - type: 'null' description: >- What initiated this payment attempt, e.g. initial purchase, subscription renewal, or an automated dunning retry. examples: - subscription_cycle decline_reason: anyOf: - type: string - type: 'null' title: Decline Reason description: Error code, if the payment was declined. examples: - insufficient_funds decline_message: anyOf: - type: string - type: 'null' title: Decline Message description: Human-readable error message, if the payment was declined. examples: - Your card has insufficient funds. organization_id: type: string format: uuid4 title: Organization Id description: The ID of the organization that owns the payment. examples: - 1dbfc517-0bbf-4301-9ba8-555ca42b9737 checkout_id: anyOf: - type: string format: uuid4 - type: 'null' title: Checkout Id description: The ID of the checkout session associated with this payment. examples: - e4b478fa-cd25-4253-9f1f-8a41e6370ede order_id: anyOf: - type: string format: uuid4 - type: 'null' title: Order Id description: The ID of the order associated with this payment. examples: - e4b478fa-cd25-4253-9f1f-8a41e6370ede processor_metadata: additionalProperties: true type: object title: Processor Metadata description: Additional metadata from the payment processor for internal use. method_metadata: $ref: '#/components/schemas/KrCardPaymentMetadata' description: Additional metadata for the South Korean card payment method. type: object required: - created_at - modified_at - id - processor - status - amount - currency - method - trigger - decline_reason - decline_message - organization_id - checkout_id - order_id - method_metadata title: KrCardPayment description: Schema of a payment with a South Korean card payment method. GenericPayment: properties: created_at: type: string format: date-time title: Created At description: Creation timestamp of the object. examples: - '2026-01-01T00:00:00.000000Z' modified_at: anyOf: - type: string format: date-time examples: - '2026-01-01T00:00:00.000000Z' - type: 'null' title: Modified At description: Last modification timestamp of the object. id: type: string format: uuid4 title: Id description: The ID of the object. processor: $ref: '#/components/schemas/PaymentProcessor' description: The payment processor. examples: - stripe status: $ref: '#/components/schemas/PaymentStatus' description: The payment status. examples: - succeeded amount: type: integer title: Amount description: The payment amount in cents. examples: - 1000 currency: type: string title: Currency description: The payment currency examples: - usd method: type: string title: Method description: The payment method used. examples: - card trigger: anyOf: - $ref: '#/components/schemas/PaymentTrigger' - type: 'null' description: >- What initiated this payment attempt, e.g. initial purchase, subscription renewal, or an automated dunning retry. examples: - subscription_cycle decline_reason: anyOf: - type: string - type: 'null' title: Decline Reason description: Error code, if the payment was declined. examples: - insufficient_funds decline_message: anyOf: - type: string - type: 'null' title: Decline Message description: Human-readable error message, if the payment was declined. examples: - Your card has insufficient funds. organization_id: type: string format: uuid4 title: Organization Id description: The ID of the organization that owns the payment. examples: - 1dbfc517-0bbf-4301-9ba8-555ca42b9737 checkout_id: anyOf: - type: string format: uuid4 - type: 'null' title: Checkout Id description: The ID of the checkout session associated with this payment. examples: - e4b478fa-cd25-4253-9f1f-8a41e6370ede order_id: anyOf: - type: string format: uuid4 - type: 'null' title: Order Id description: The ID of the order associated with this payment. examples: - e4b478fa-cd25-4253-9f1f-8a41e6370ede processor_metadata: additionalProperties: true type: object title: Processor Metadata description: Additional metadata from the payment processor for internal use. type: object required: - created_at - modified_at - id - processor - status - amount - currency - method - trigger - decline_reason - decline_message - organization_id - checkout_id - order_id title: GenericPayment description: Schema of a payment with a generic payment method. PaymentProcessor: type: string enum: - stripe title: PaymentProcessor PaymentTrigger: type: string enum: - purchase - subscription_cycle - retry_dunning - retry_customer - retry_payment_method_update - retry_admin title: PaymentTrigger CardPaymentMetadata: properties: brand: type: string title: Brand description: The brand of the card used for the payment. examples: - visa - amex last4: type: string title: Last4 description: The last 4 digits of the card number. examples: - '4242' type: object required: - brand - last4 title: CardPaymentMetadata description: Additional metadata for a card payment method. KrCardPaymentMetadata: properties: brand: anyOf: - type: string - type: 'null' title: Brand description: The local South Korean card brand used for the payment. examples: - kookmin - shinhan last4: anyOf: - type: string - type: 'null' title: Last4 description: The last 4 digits of the card number. examples: - '4242' type: object required: - brand - last4 title: KrCardPaymentMetadata description: Additional metadata for a South Korean card payment method. securitySchemes: oidc: type: openIdConnect openIdConnectUrl: /.well-known/openid-configuration pat: type: http description: >- You can generate a **Personal Access Token** from your [settings](https://polar.sh/settings). scheme: bearer oat: type: http description: >- You can generate an **Organization Access Token** from your organization's settings. scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.