Figma Payments API

openapi: 3.2.0
info:
  title: Figma Payments API
  version: 0.45.0
  description: 'This is the OpenAPI specification for the Figma REST API.


    Note: we are releasing the OpenAPI specification as a beta given the large surface area and complexity of the REST API. If you notice any inaccuracies with the specification, please file an issue.'
  termsOfService: https://www.figma.com/developer-terms/
  contact:
    email: support@figma.com
servers:
- url: https://api.figma.com
tags:
- name: Payments
  description: Get purchase information for your Community resources.
  externalDocs:
    description: Payment endpoints documentation
    url: https://developers.figma.com/docs/rest-api/payments-endpoints/
paths:
  /v1/payments:
    get:
      tags:
      - Payments
      summary: 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
      parameters:
      - 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
      - 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: string
      - 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: string
      - 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: string
      - 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: string
      responses:
        '200':
          $ref: '#/components/responses/GetPaymentsResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedErrorResponseWithErrorBoolean'
        '429':
          $ref: '#/components/responses/TooManyRequestsErrorResponseWithErrorBoolean'
        '500':
          $ref: '#/components/responses/InternalServerErrorResponseWithErrorBoolean'
components:
  responses:
    TooManyRequestsErrorResponseWithErrorBoolean:
      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:
            allOf:
            - $ref: '#/components/schemas/ErrorResponsePayloadWithErrorBoolean'
            - type: object
              properties:
                status:
                  type: number
                  description: Status code
                  enum:
                  - 429
              required:
              - status
    UnauthorizedErrorResponseWithErrorBoolean:
      description: Token is missing or incorrect.
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/ErrorResponsePayloadWithErrorBoolean'
            - type: object
              properties:
                status:
                  type: number
                  description: Status code
                  enum:
                  - 401
              required:
              - status
    InternalServerErrorResponseWithErrorBoolean:
      description: An internal server error occurred.
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/ErrorResponsePayloadWithErrorBoolean'
            - type: object
              properties:
                status:
                  type: number
                  description: Status code
                  enum:
                  - 500
              required:
              - status
    GetPaymentsResponse:
      description: Response from the GET /v1/payments endpoint.
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: number
                enum:
                - 200
                description: The response status code.
              error:
                type: boolean
                enum:
                - false
                description: For successful requests, this value is always `false`.
              meta:
                $ref: '#/components/schemas/PaymentInformation'
            required:
            - status
            - error
            - meta
  schemas:
    PaymentStatus:
      type: object
      description: An object describing the user's payment status.
      properties:
        type:
          type: string
          description: "The current payment status of the user on the resource, as a string enum:\n  \n- `UNPAID`: user has not paid for the resource\n- `PAID`: user has an active purchase on the resource\n- `TRIAL`: user is in the trial period for a subscription resource"
          enum:
          - UNPAID
          - PAID
          - TRIAL
    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.
        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.
        resource_type:
          type: string
          description: The type of the resource.
          enum:
          - PLUGIN
          - WIDGET
          - COMMUNITY_FILE
        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.\n  \nNote that a value will still be returned if the user had purchased the resource, but no longer has active access to it (e.g. purchase refunded, subscription ended)."
      required:
      - user_id
      - resource_id
      - resource_type
      - payment_status
    ErrorResponsePayloadWithErrorBoolean:
      type: object
      description: A response indicating an error occurred.
      properties:
        error:
          type: boolean
          description: For erroneous requests, this value is always `true`.
          enum:
          - true
        status:
          type: number
          description: Status code
        message:
          type: string
          description: A string describing the error
      required:
      - error
      - status
      - message
  securitySchemes:
    PersonalAccessToken:
      type: apiKey
      name: X-Figma-Token
      in: header
    PlanAccessToken:
      type: apiKey
      name: X-Figma-Token
      in: header
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://www.figma.com/oauth
          tokenUrl: https://api.figma.com/v1/oauth/token
          refreshUrl: https://api.figma.com/v1/oauth/refresh
          scopes:
            current_user:read: Read your name, email, and profile image.
            file_comments:read: Read the comments for files.
            file_comments:write: Post and delete comments and comment reactions in files.
            file_content:read: Read the contents of files, such as nodes and the editor type.
            file_dev_resources:read: Read dev resources in files.
            file_dev_resources:write: Write to dev resources in files.
            file_metadata:read: Read metadata of files.
            file_variables:read: 'Read variables in Figma file. Note: this is only available to members in Enterprise organizations.'
            file_variables:write: 'Write to variables in Figma file. Note: this is only available to members in Enterprise organizations.'
            file_versions:read: Read the version history for files you can access.
            files:read: Deprecated. Read files, projects, users, versions, comments, components & styles, and webhooks.
            library_analytics:read: Read library analytics data.
            library_assets:read: Read data of individual published components and styles.
            library_content:read: Read published components and styles of files.
            project_metadata:read: Read metadata of projects.
            projects:read: List projects and files in projects.
            folders:read: List folders and files in folders.
            folder_metadata:read: Read metadata of folders.
            team_library_content:read: Read published components and styles of teams.
            webhooks:read: Read metadata of webhooks.
            webhooks:write: Create and manage webhooks.
    OrgOAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://www.figma.com/oauth
          tokenUrl: https://api.figma.com/v1/oauth/token
          refreshUrl: https://api.figma.com/v1/oauth/refresh
          scopes:
            org:activity_log_read: Read activity logs in the organization.
externalDocs:
  description: Figma REST API Documentation
  url: https://developers.figma.com/docs/rest-api/