Etsy Payment API

openapi: 3.0.2
info:
  title: Etsy Open API v3 BuyerTaxonomy Payment API
  description: <div class="wt-text-body-01"><p class="wt-pt-xs-2 wt-pb-xs-2">Etsy's Open API provides a simple RESTful interface for various Etsy.com features.</p><p class="wt-pb-xs-2">If you'd like to report an issue or provide feedback on the API design, <a target="_blank" class="wt-text-link wt-p-xs-0" href="https://github.com/etsy/open-api/discussions">please add an issue in Github</a>.</p></div>&copy; 2021-2026 Etsy, Inc. All Rights Reserved. Use of this code is subject to Etsy's <a class='wt-text-link wt-p-xs-0' target='_blank' href='https://www.etsy.com/legal/api'>API Developer Terms of Use</a>.
  termsOfService: https://www.etsy.com/legal/api
  contact:
    email: developers@etsy.com
  version: 3.0.0
  x-generated-from: https://www.etsy.com/openapi/generated/oas/3.0.0.json
  x-last-validated: '2026-05-30'
servers:
- url: https://openapi.etsy.com
  description: Etsy Open API v3 base URL (per Etsy developer documentation; live calls also resolve at https://api.etsy.com/v3/application).
security:
- api_key: []
tags:
- name: Payment
paths:
  /v3/application/shops/{shop_id}/payment-account/ledger-entries/payments:
    get:
      operationId: getPaymentAccountLedgerEntryPayments
      description: '<div class="wt-display-flex-xs wt-align-items-center wt-mt-xs-2 wt-mb-xs-3"><span class="wt-badge wt-badge--notificationPrimary wt-bg-slime-tint wt-mr-xs-2">General Release</span><a class="wt-text-link" href="https://github.com/etsy/open-api/discussions" target="_blank" rel="noopener noreferrer">Report bug</a></div><div class="wt-display-flex-xs wt-align-items-center wt-mt-xs-2 wt-mb-xs-3"><p class="wt-text-body-01 banner-text">This endpoint is ready for production use.</p></div>


        Get a Payment from a PaymentAccount Ledger Entry ID, if applicable'
      tags:
      - Payment
      parameters:
      - name: shop_id
        in: path
        description: The unique positive non-zero numeric ID for an Etsy Shop.
        required: true
        schema:
          type: integer
          description: The unique positive non-zero numeric ID for an Etsy Shop.
          format: int64
          minimum: 1
        example: 123456
      - name: ledger_entry_ids
        in: query
        description: ''
        required: true
        schema:
          type: array
          items:
            type: integer
            format: int64
            minimum: 1
        example:
        - 1
      responses:
        '200':
          description: A list of Payments
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payments'
              examples:
                GetPaymentAccountLedgerEntryPayments200Example:
                  summary: Default getPaymentAccountLedgerEntryPayments 200 response
                  x-microcks-default: true
                  value:
                    count: 1
                    results:
                    - null
        '400':
          description: There was a problem with the request data. See the error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
              examples:
                GetPaymentAccountLedgerEntryPayments400Example:
                  summary: Default getPaymentAccountLedgerEntryPayments 400 response
                  x-microcks-default: true
                  value:
                    error: example string
        '403':
          description: The request attempted to perform an operation it is not allowed to. See the error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
              examples:
                GetPaymentAccountLedgerEntryPayments403Example:
                  summary: Default getPaymentAccountLedgerEntryPayments 403 response
                  x-microcks-default: true
                  value:
                    error: example string
        '401':
          description: The request lacks valid authentication credentials. See the error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
              examples:
                GetPaymentAccountLedgerEntryPayments401Example:
                  summary: Default getPaymentAccountLedgerEntryPayments 401 response
                  x-microcks-default: true
                  value:
                    error: example string
        '500':
          description: The server encountered an internal error. See the error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
              examples:
                GetPaymentAccountLedgerEntryPayments500Example:
                  summary: Default getPaymentAccountLedgerEntryPayments 500 response
                  x-microcks-default: true
                  value:
                    error: example string
      security:
      - api_key: []
        oauth2:
        - transactions_r
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      summary: Etsy Get Payment Account Ledger Entry Payments
  /v3/application/shops/{shop_id}/receipts/{receipt_id}/payments:
    get:
      operationId: getShopPaymentByReceiptId
      description: '<div class="wt-display-flex-xs wt-align-items-center wt-mt-xs-2 wt-mb-xs-3"><span class="wt-badge wt-badge--notificationPrimary wt-bg-slime-tint wt-mr-xs-2">General Release</span><a class="wt-text-link" href="https://github.com/etsy/open-api/discussions" target="_blank" rel="noopener noreferrer">Report bug</a></div><div class="wt-display-flex-xs wt-align-items-center wt-mt-xs-2 wt-mb-xs-3"><p class="wt-text-body-01 banner-text">This endpoint is ready for production use.</p></div>


        Retrieves a payment from a specific receipt, identified by `receipt_id`, from a specific shop, identified by `shop_id`'
      tags:
      - Payment
      parameters:
      - name: shop_id
        in: path
        description: The unique positive non-zero numeric ID for an Etsy Shop.
        required: true
        schema:
          type: integer
          description: The unique positive non-zero numeric ID for an Etsy Shop.
          format: int64
          minimum: 1
        example: 123456
      - name: receipt_id
        in: path
        description: The numeric ID for the [receipt](/documentation/reference#tag/Shop-Receipt) associated to this transaction.
        required: true
        schema:
          type: integer
          description: The numeric ID for the [receipt](/documentation/reference#tag/Shop-Receipt) associated to this transaction.
          format: int64
          minimum: 1
        example: 234567890
      responses:
        '200':
          description: A single payment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payments'
              examples:
                GetShopPaymentByReceiptId200Example:
                  summary: Default getShopPaymentByReceiptId 200 response
                  x-microcks-default: true
                  value:
                    count: 1
                    results:
                    - null
        '404':
          description: A resource could not be found. See the error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
              examples:
                GetShopPaymentByReceiptId404Example:
                  summary: Default getShopPaymentByReceiptId 404 response
                  x-microcks-default: true
                  value:
                    error: example string
        '403':
          description: The request attempted to perform an operation it is not allowed to. See the error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
              examples:
                GetShopPaymentByReceiptId403Example:
                  summary: Default getShopPaymentByReceiptId 403 response
                  x-microcks-default: true
                  value:
                    error: example string
        '400':
          description: There was a problem with the request data. See the error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
              examples:
                GetShopPaymentByReceiptId400Example:
                  summary: Default getShopPaymentByReceiptId 400 response
                  x-microcks-default: true
                  value:
                    error: example string
        '401':
          description: The request lacks valid authentication credentials. See the error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
              examples:
                GetShopPaymentByReceiptId401Example:
                  summary: Default getShopPaymentByReceiptId 401 response
                  x-microcks-default: true
                  value:
                    error: example string
        '500':
          description: The server encountered an internal error. See the error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
              examples:
                GetShopPaymentByReceiptId500Example:
                  summary: Default getShopPaymentByReceiptId 500 response
                  x-microcks-default: true
                  value:
                    error: example string
      security:
      - api_key: []
        oauth2:
        - transactions_r
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      summary: Etsy Get Shop Payment by Receipt Id
  /v3/application/shops/{shop_id}/payments:
    get:
      operationId: getPayments
      description: '<div class="wt-display-flex-xs wt-align-items-center wt-mt-xs-2 wt-mb-xs-3"><span class="wt-badge wt-badge--notificationPrimary wt-bg-slime-tint wt-mr-xs-2">General Release</span><a class="wt-text-link" href="https://github.com/etsy/open-api/discussions" target="_blank" rel="noopener noreferrer">Report bug</a></div><div class="wt-display-flex-xs wt-align-items-center wt-mt-xs-2 wt-mb-xs-3"><p class="wt-text-body-01 banner-text">This endpoint is ready for production use.</p></div>


        Retrieves a list of payments from a shop identified by `shop_id`. You can also filter results using a list of payment IDs.'
      tags:
      - Payment
      parameters:
      - name: shop_id
        in: path
        description: The unique positive non-zero numeric ID for an Etsy Shop.
        required: true
        schema:
          type: integer
          description: The unique positive non-zero numeric ID for an Etsy Shop.
          format: int64
          minimum: 1
        example: 123456
      - name: payment_ids
        in: query
        description: A comma-separated array of Payment IDs numbers.
        required: true
        schema:
          type: array
          description: A comma-separated array of Payment IDs numbers.
          items:
            type: integer
            format: int64
            minimum: 1
        example:
        - 1
      responses:
        '200':
          description: A list of payments from a specific shop.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payments'
              examples:
                GetPayments200Example:
                  summary: Default getPayments 200 response
                  x-microcks-default: true
                  value:
                    count: 1
                    results:
                    - null
        '404':
          description: A resource could not be found. See the error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
              examples:
                GetPayments404Example:
                  summary: Default getPayments 404 response
                  x-microcks-default: true
                  value:
                    error: example string
        '403':
          description: The request attempted to perform an operation it is not allowed to. See the error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
              examples:
                GetPayments403Example:
                  summary: Default getPayments 403 response
                  x-microcks-default: true
                  value:
                    error: example string
        '400':
          description: There was a problem with the request data. See the error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
              examples:
                GetPayments400Example:
                  summary: Default getPayments 400 response
                  x-microcks-default: true
                  value:
                    error: example string
        '401':
          description: The request lacks valid authentication credentials. See the error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
              examples:
                GetPayments401Example:
                  summary: Default getPayments 401 response
                  x-microcks-default: true
                  value:
                    error: example string
        '500':
          description: The server encountered an internal error. See the error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
              examples:
                GetPayments500Example:
                  summary: Default getPayments 500 response
                  x-microcks-default: true
                  value:
                    error: example string
      security:
      - api_key: []
        oauth2:
        - transactions_r
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      summary: Etsy Get Payments
components:
  schemas:
    PaymentAdjustmentItem:
      type: object
      x-resource-id: PaymentAdjustmentItem
      description: A payment adjustment line item for a payment adjustment.
      properties:
        payment_adjustment_id:
          type: integer
          description: The numeric ID for a payment adjustment.
          format: int64
          minimum: 1
          example: 1
        payment_adjustment_item_id:
          type: integer
          description: Unique ID for the adjustment line item.
          format: int64
          minimum: 1
          example: 1
        adjustment_type:
          type: string
          description: String indicating the type of adjustment for this line item.
          nullable: true
          example: example string
        amount:
          type: integer
          description: Integer value for the amount of the adjustment in original currency.
          default: 0
          example: 2500
        shop_amount:
          type: integer
          description: Integer value for the amount of the adjustment in currency for the shop.
          default: 0
          example: 2500
        transaction_id:
          type: integer
          description: The unique numeric ID for a transaction.
          format: int64
          nullable: true
          minimum: 1
          example: 345678901
        bill_payment_id:
          type: integer
          description: Unique ID for the bill payment adjustment.
          format: int64
          nullable: true
          minimum: 1
          example: 1
        created_timestamp:
          type: integer
          description: The transaction's creation date and time, in epoch seconds.
          minimum: 946684800
          example: 1758153645
        updated_timestamp:
          type: integer
          description: The update date and time the payment adjustment in epoch seconds.
          minimum: 946684800
          example: 1758153645
    Payments:
      type: object
      x-resource-id: Payments
      description: Represents several payments made with Etsy Payments. All monetary amounts are in USD pennies unless otherwise specified.
      properties:
        count:
          type: integer
          description: The number of payments in the response.
          minimum: 0
          example: 1
        results:
          type: array
          description: A list of payments.
          items:
            description: A list of payments.
            oneOf:
            - $ref: '#/components/schemas/Payment'
    ErrorSchema:
      type: object
      x-resource-id: ErrorSchema
      required:
      - error
      properties:
        error:
          type: string
          example: example string
    PaymentAdjustment:
      type: object
      x-resource-id: PaymentAdjustment
      description: Represents a refund, which applies to a prior Etsy payment. All monetary amounts are in USD pennies unless otherwise specified.
      properties:
        payment_adjustment_id:
          type: integer
          description: The numeric ID for a payment adjustment.
          format: int64
          minimum: 1
          example: 1
        payment_id:
          type: integer
          description: A unique numeric ID for a payment to a specific Etsy [shop](/documentation/reference#tag/Shop).
          format: int64
          minimum: 1
          example: 1
        status:
          type: string
          description: The status string of the payment adjustment.
          example: example string
        is_success:
          type: boolean
          description: When true, the payment adjustment was or is likely to complete successfully.
          example: true
        user_id:
          type: integer
          description: The numeric ID for the [user](/documentation/reference#tag/User) (seller) fulfilling the purchase.
          format: int64
          minimum: 1
          example: 456789
        reason_code:
          type: string
          description: A human-readable string describing the reason for the refund.
          example: example string
        total_adjustment_amount:
          type: integer
          description: The total numeric amount of the refund in the payment currency.
          nullable: true
          minimum: 0
          example: 2500
        shop_total_adjustment_amount:
          type: integer
          description: The numeric amount of the refund in the shop currency.
          nullable: true
          minimum: 0
          example: 2500
        buyer_total_adjustment_amount:
          type: integer
          description: The numeric amount of the refund in the buyer currency.
          nullable: true
          minimum: 0
          example: 2500
        total_fee_adjustment_amount:
          type: integer
          description: The numeric amount of card processing fees associated with a payment adjustment.
          nullable: true
          minimum: 0
          example: 2500
        create_timestamp:
          type: integer
          description: The transaction's creation date and time, in epoch seconds.
          minimum: 946684800
          example: 1758153645
        created_timestamp:
          type: integer
          description: The transaction's creation date and time, in epoch seconds.
          minimum: 946684800
          example: 1758153645
        update_timestamp:
          type: integer
          description: The date and time of the last change to the payment adjustment in epoch seconds.
          minimum: 946684800
          example: 1758153645
        updated_timestamp:
          type: integer
          description: The date and time of the last change to the payment adjustment in epoch seconds.
          minimum: 946684800
          example: 1758153645
        payment_adjustment_items:
          type: array
          description: List of payment adjustment line items.
          items:
            description: List of payment adjustment line items.
            oneOf:
            - $ref: '#/components/schemas/PaymentAdjustmentItem'
    Payment:
      type: object
      x-resource-id: Payment
      description: Represents a payment made with Etsy Payments. All monetary amounts are in USD pennies unless otherwise specified.
      properties:
        payment_id:
          type: integer
          description: A unique numeric ID for a payment to a specific Etsy [shop](/documentation/reference#tag/Shop).
          format: int64
          minimum: 1
          example: 1
        buyer_user_id:
          type: integer
          description: The numeric ID for the [user](/documentation/reference#tag/User) who paid the purchase.
          format: int64
          minimum: 1
          example: 456789
        shop_id:
          type: integer
          description: The unique positive non-zero numeric ID for an Etsy Shop.
          format: int64
          minimum: 1
          example: 123456
        receipt_id:
          type: integer
          description: The numeric ID for the [receipt](/documentation/reference#tag/Shop-Receipt) associated to this transaction.
          format: int64
          minimum: 1
          example: 234567890
        amount_gross:
          description: An integer equal to gross amount of the order, in pennies, including shipping and taxes.
          oneOf:
          - $ref: '#/components/schemas/Money'
          example: example
        amount_fees:
          description: An integer equal to the original card processing fee of the order in pennies.
          oneOf:
          - $ref: '#/components/schemas/Money'
          example: example
        amount_net:
          description: An integer equal to the payment value, in pennies, less fees (`amount_gross` - `amount_fees`).
          oneOf:
          - $ref: '#/components/schemas/Money'
          example: example
        posted_gross:
          description: The total gross value of the payment posted once the purchase ships. This is equal to the `amount_gross` UNLESS the seller issues a refund prior to shipping. We consider "shipping" to be the event which "posts" to the ledger. Therefore, if the seller refunds first, we reduce the `amount_gross` first and post then that amount. The seller never sees the refunded amount in their ledger. This is equal to the "Credit" amount in the ledger entry.
          oneOf:
          - $ref: '#/components/schemas/Money'
          nullable: true
          example: example
        posted_fees:
          description: The total value of the fees posted once the purchase ships. Etsy refunds a proportional amount of the fees when a seller refunds a buyer. When the seller issues a refund prior to shipping, the posted amount is less than the original.
          oneOf:
          - $ref: '#/components/schemas/Money'
          nullable: true
          example: example
        posted_net:
          description: The total value of the payment at the time of posting, less fees. (`posted_gross` - `posted_fees`)
          oneOf:
          - $ref: '#/components/schemas/Money'
          nullable: true
          example: example
        adjusted_gross:
          description: The gross payment amount after the seller refunds a payment, partially or fully.
          oneOf:
          - $ref: '#/components/schemas/Money'
          nullable: true
          example: example
        adjusted_fees:
          description: The new fee amount after a seller refunds a payment, partially or fully.
          oneOf:
          - $ref: '#/components/schemas/Money'
          nullable: true
          example: example
        adjusted_net:
          description: The total value of the payment after refunds, less fees (`adjusted_gross` - `adjusted_fees`).
          oneOf:
          - $ref: '#/components/schemas/Money'
          nullable: true
          example: example
        currency:
          type: string
          description: The ISO (alphabetic) code string for the payment's currency.
          example: example string
        shop_currency:
          type: string
          description: The ISO (alphabetic) code for the shop's currency. The shop displays all prices in this currency by default.
          nullable: true
          example: example string
        buyer_currency:
          type: string
          description: The currency string of the buyer.
          nullable: true
          example: example string
        shipping_user_id:
          type: integer
          description: The numeric ID of the user to which the seller ships the order.
          format: int64
          nullable: true
          minimum: 1
          example: 456789
        shipping_address_id:
          type: integer
          description: The numeric id identifying the shipping address.
          format: int64
          minimum: 1
          example: 1
        billing_address_id:
          type: integer
          description: The numeric ID identifying the billing address of the buyer.
          minimum: 0
          maximum: 9223372036854775807
          example: 1
        status:
          type: string
          description: A string indicating the current status of the payment, most commonly "settled" or "authed".
          example: example string
        shipped_timestamp:
          type: integer
          description: The transaction's shipping date and time, in epoch seconds.
          nullable: true
          minimum: 946684800
          example: 1758153645
        create_timestamp:
          type: integer
          description: The transaction's creation date and time, in epoch seconds.
          minimum: 946684800
          example: 1758153645
        created_timestamp:
          type: integer
          description: The transaction's creation date and time, in epoch seconds.
          minimum: 946684800
          example: 1758153645
        update_timestamp:
          type: integer
          description: The date and time of the last change to the payment adjustment in epoch seconds.
          minimum: 946684800
          example: 1758153645
        updated_timestamp:
          type: integer
          description: The date and time of the last change to the payment adjustment in epoch seconds.
          minimum: 946684800
          example: 1758153645
        payment_adjustments:
          type: array
          description: List of refund objects on an Etsy Payments transaction. All monetary amounts are in USD pennies unless otherwise specified.
          items:
            description: List of refund objects on an Etsy Payments transaction. All monetary amounts are in USD pennies unless otherwise specified.
            oneOf:
            - $ref: '#/components/schemas/PaymentAdjustment'
    Money:
      type: object
      x-resource-id: Money
      description: A representation of an amount of money.
      properties:
        amount:
          type: integer
          description: The amount of represented by this data.
          example: 2500
        divisor:
          type: integer
          description: The divisor to render the amount.
          minimum: 0
          example: 1
        currency_code:
          type: string
          description: The ISO currency code for this data.
          example: USD
  securitySchemes:
    api_key:
      type: apiKey
      name: x-api-key
      in: header
      description: Every request to a v3 API endpoint must include this data in the format `keystring:shared_secret`. Your keystring and shared secret are available on the [Your Apps](https://www.etsy.com/developers/your-apps) page.
    oauth2:
      type: oauth2
      description: Open API v3 supports authenticating via OAuth 2.0. More information about Etsy's specific implementation of OAuth2 can be found [here](/documentation/essentials/oauth2).
      flows:
        authorizationCode:
          authorizationUrl: https://www.etsy.com/oauth/connect
          tokenUrl: https://openapi.etsy.com/v3/public/oauth/token
          scopes:
            address_r: see billing and shipping addresses
            address_w: update billing and shipping addresses
            billing_r: see all billing statement data
            cart_r: read shopping carts
            cart_w: add/remove from shopping carts
            email_r: read a user profile
            favorites_r: see private favorites
            favorites_w: add/remove favorites
            feedback_r: see purchase info in feedback
            listings_d: delete listings
            listings_r: see all listings (including expired etc)
            listings_w: create/edit listings
            profile_r: see all profile data
            profile_w: update user profile, avatar, etc
            recommend_r: see recommended listings
            recommend_w: accept/reject recommended listings
            shops_r: see private shop info
            shops_w: update shop
            transactions_r: see all checkout/payment data
            transactions_w: update receipts
x-tagGroups:
- name: Listing Management
  tags:
  - BuyerTaxonomy
  - SellerTaxonomy
  - ShopListing
  - ShopListing File
  - ShopListing Image
  - ShopListing Inventory
  - ShopListing Offering
  - ShopListing Personalization
  - ShopListing Product
  - ShopListing Translation
  - ShopListing VariationImage
  - ShopListing Video
- name: Other
  tags:
  - Other
- name: Payment Management
  tags:
  - Ledger Entry
  - Payment
- name: Receipt Management
  tags:
  - Shop Receipt
  - Shop Receipt Transactions
- name: Review Management
  tags:
  - Review
- name: Shipping Management
  tags:
  - Shop HolidayPreferences
  - Shop ProcessingProfiles
  - Shop ShippingProfile
- name: Shop Management
  tags:
  - Shop
  - Shop ProductionPartner
  - Shop Section
- name: Shop Policy Management
  tags:
  - Shop Return Policy
- name: User Management
  tags:
  - User
  - UserAddress