Figma Payments API

openapi: 3.2.0
info:
  title: Figma Activity Logs Payments API
  version: 0.21.0
  description: 'Figma allows designers to create and prototype their digital experiences -

    together in real-time and in one place - helping them turn their ideas and

    visions into products, faster. Figma''s mission is to make design

    accessible to everyone. The Figma API is one of the ways we aim to do that.'
  termsOfService: https://www.figma.com/developer-terms/
  contact:
    email: support@figma.com
servers:
- url: https://api.figma.com
  description: Figma Production API Server
tags:
- name: Payments
  description: Operations for querying user payment information on plugins, widgets, and Community files
paths:
  /v1/payments:
    get:
      tags:
      - Payments
      summary: Figma Get Payments
      security:
      - PersonalAccessToken: []
      description: 'There are two methods to query for a user''s payment information on a plugin, widget, or Community file. The first method, using plugin payment tokens, is typically used when making queries from a plugin''s or widget''s code. The second method, providing a user ID and resource ID, is typically used when making queries from anywhere else.

        Note that you can only query for resources that you own. In most cases, this means that you can only query resources that you originally created.'
      operationId: getPayments
      x-microcks-operation:
        dispatcher: FALLBACK
        dispatcherRules: ''
        defaultResponse: GetPaymentsSuccessExample
      parameters:
      - $ref: '#/components/parameters/PluginPaymentTokenQuery'
      - $ref: '#/components/parameters/UserIdQuery'
      - $ref: '#/components/parameters/CommunityFileIdQuery'
      - $ref: '#/components/parameters/PluginIdQuery'
      - $ref: '#/components/parameters/WidgetIdQuery'
      responses:
        '200':
          $ref: '#/components/responses/GetPaymentsResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedErrorResponse'
        '429':
          $ref: '#/components/responses/TooManyRequestsErrorResponse'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponse'
components:
  schemas:
    PaymentStatus:
      type: string
      description: The payment status of the user for the resource.
      enum:
      - UNPAID
      - PAID
      - NOT_SUPPORTED
      example: PAID
    PaymentInformation:
      type: object
      description: An object describing a user's payment information for a plugin, widget, or Community file.
      properties:
        user_id:
          type: string
          description: The ID of the user whose payment information was queried. Can be used to verify the validity of a response.
          example: '500123'
        resource_id:
          type: string
          description: The ID of the plugin, widget, or Community file that was queried. Can be used to verify the validity of a response.
          example: '500123'
        resource_type:
          type: string
          description: The type of the resource.
          enum:
          - PLUGIN
          - WIDGET
          - COMMUNITY_FILE
          example: PLUGIN
        payment_status:
          $ref: '#/components/schemas/PaymentStatus'
        date_of_purchase:
          type: string
          format: date-time
          description: The UTC ISO 8601 timestamp indicating when the user purchased the resource. No value is given if the user has never purchased the resource.
          example: '2026-01-15T10:30:00Z'
      required:
      - user_id
      - resource_id
      - resource_type
      - payment_status
      example:
        user_id: '1234567890'
        resource_id: '1122334455'
        resource_type: PLUGIN
        payment_status: PAID
        date_of_purchase: '2024-06-15T14:30:00Z'
    ErrorResponsePayload:
      type: object
      description: A response indicating an error occurred.
      properties:
        error:
          type: boolean
          description: For erroneous requests, this value is always `true`.
          enum:
          - true
          example: true
        status:
          type: number
          description: Status code
          example: 42.5
        message:
          type: string
          description: A string describing the error
          example: example_value
      required:
      - error
      - status
      - message
    TooManyRequestsError:
      allOf:
      - $ref: '#/components/schemas/ErrorResponsePayload'
      - type: object
        properties:
          status:
            type: number
            description: Status code
            enum:
            - 429
        required:
        - status
      example:
        error: true
        status: 429
        message: Rate limit exceeded. Please wait before retrying.
    GetPaymentsResponseBody:
      type: object
      description: Successful response containing payment information.
      properties:
        status:
          type: number
          enum:
          - 200
          description: The response status code.
          example: 200
        error:
          type: boolean
          enum:
          - false
          description: For successful requests, this value is always `false`.
          example: false
        meta:
          $ref: '#/components/schemas/PaymentInformation'
      required:
      - status
      - error
      - meta
      example:
        status: 200
        error: false
        meta:
          user_id: '1234567890'
          resource_id: '1122334455'
          resource_type: PLUGIN
          payment_status: PAID
          date_of_purchase: '2024-06-15T14:30:00Z'
    UnauthorizedError:
      allOf:
      - $ref: '#/components/schemas/ErrorResponsePayload'
      - type: object
        properties:
          status:
            type: number
            description: Status code
            enum:
            - 401
        required:
        - status
      example:
        error: true
        status: 401
        message: Token is missing or incorrect
    InternalServerError:
      allOf:
      - $ref: '#/components/schemas/ErrorResponsePayload'
      - type: object
        properties:
          status:
            type: number
            description: Status code
            enum:
            - 500
        required:
        - status
      example:
        error: true
        status: 500
        message: Internal server error
  parameters:
    PluginIdQuery:
      name: plugin_id
      in: query
      description: The ID of the plugin to query a user's payment information on. You can get the plugin ID from the plugin's manifest, or from the plugin's Community page (look for the number after "plugin/" in the URL). Provide exactly one of "community_file_id", "plugin_id", or "widget_id".
      schema:
        type: number
      example: 1122334455
    PluginPaymentTokenQuery:
      name: plugin_payment_token
      in: query
      description: Short-lived token returned from "getPluginPaymentTokenAsync" in the plugin payments API and used to authenticate to this endpoint. Read more about generating this token through "Calling the Payments REST API from a plugin or widget" below.
      schema:
        type: string
      example: ppt_abc123xyz789
    CommunityFileIdQuery:
      name: community_file_id
      in: query
      description: The ID of the Community file to query a user's payment information on. You can get the Community file ID from the file's Community page (look for the number after "file/" in the URL). Provide exactly one of "community_file_id", "plugin_id", or "widget_id".
      schema:
        type: number
      example: 9876543210
    UserIdQuery:
      name: user_id
      in: query
      description: The ID of the user to query payment information about. You can get the user ID by having the user OAuth2 to the Figma REST API.
      schema:
        type: number
      example: 1234567890
    WidgetIdQuery:
      name: widget_id
      in: query
      description: The ID of the widget to query a user's payment information on. You can get the widget ID from the widget's manifest, or from the widget's Community page (look for the number after "widget/" in the URL). Provide exactly one of "community_file_id", "plugin_id", or "widget_id".
      schema:
        type: number
      example: 5544332211
  responses:
    InternalServerErrorResponse:
      description: An internal server error occurred.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/InternalServerError'
          examples:
            InternalServerErrorExample:
              summary: Internal server error
              value:
                error: true
                status: 500
                message: Internal server error
    TooManyRequestsErrorResponse:
      description: In some cases API requests may be throttled or rate limited. Please wait a while before attempting the request again (typically a minute).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TooManyRequestsError'
          examples:
            TooManyRequestsExample:
              summary: Rate limit exceeded error
              value:
                error: true
                status: 429
                message: Rate limit exceeded. Please wait before retrying.
    GetPaymentsResponse:
      description: Response from the GET /v1/payments endpoint.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GetPaymentsResponseBody'
          examples:
            GetPaymentsSuccessExample:
              summary: Successful payment information response
              value:
                status: 200
                error: false
                meta:
                  user_id: '1234567890'
                  resource_id: '1122334455'
                  resource_type: PLUGIN
                  payment_status: PAID
                  date_of_purchase: '2024-06-15T14:30:00Z'
    UnauthorizedErrorResponse:
      description: Token is missing or incorrect.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UnauthorizedError'
          examples:
            UnauthorizedExample:
              summary: Unauthorized error
              value:
                error: true
                status: 401
                message: Token is missing or incorrect
  securitySchemes:
    OrgOAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://www.figma.com/oauth
          tokenUrl: https://api.figma.com/v1/oauth/token
          scopes:
            org:activity_log_read: Read organization activity logs