openapi: 3.0.4
info:
  title: Connector Account notes Payment plans API
  description: General-purpose API that enables partners of Mews to access data and services in Mews Operations
  termsOfService: https://www.mews.com/en/terms-conditions/partners
  contact:
    name: Partner success
    email: partnersuccess@mews.com
  version: v1
servers:
- url: https://api.mews.com
tags:
- name: Payment plans
paths:
  /api/connector/v1/paymentPlans/add:
    post:
      tags:
      - Payment plans
      summary: Add payment plan
      description: "Adds a payment plan connected to a `Reservation` and returns the payment request URL associated with the created payment plan. The fulfillment of the payment request will initiate the payment plan.\r\nNote this operation supports [Portfolio Access Tokens](https://mews-systems.gitbook.io/connector-api/concepts/multi-property/)."
      operationId: paymentPlans_add
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentPlanAddParameters'
            example:
              ClientToken: E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D
              AccessToken: C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D
              Client: Sample Client 1.0.0
              ReservationId: 0f515589-99b4-423d-b83a-b237009f0509
              Name: Payment Plan Name
              PaymentRequest:
                PaymentMethods:
                - PaymentCard
                - SepaDirectDebit
                Message: Payment request message
                Note: Internal Note
                PaymentRequestType: Payment
                PaymentRequestExpirationOffsetDays: 30
                SendEmail: false
              StartMonth: 2023-10
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentPlanAddResult'
              example:
                PaymentRequestUrl: https://example.com/payment-request-url
        '400':
          description: Error caused by the client app, e.g. in case of malformed request or invalid identifier of a resource. In most cases, such an error signifies a bug in the client app (consumer of the API).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorApiExceptionResult'
        '401':
          description: Error caused by usage of invalid ClientToken, AccessToken, or you may not have the necessary permission to use the endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorApiExceptionResult'
        '403':
          description: Server error that should be reported to the end user of the client app. Happens for example when the server-side validation fails or when a business-logic check is violated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorApiExceptionResult'
        '408':
          description: Error caused by heavy request that takes too long to process (typically tens of seconds). To get around this, request data in smaller batches. For more information, see [Request timeouts](https://mews-systems.gitbook.io/connector-api/guidelines/requests#request-timeouts)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorApiExceptionResult'
        '204':
          description: Server has successfully fulfilled the request and there is no additional information to send back.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorApiExceptionResult'
        '429':
          description: Error caused by too many requests sent in a given amount of time. Response contains `Retry-After` header indicating how long the user agent should wait before making a follow-up request. For more information, see [Request limits](https://mews-systems.gitbook.io/connector-api/guidelines/requests#request-limits).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorApiExceptionResult'
        '500':
          description: Unexpected error on the Mews side. This may be due to a software fault. If such a situation occurs, the error will be logged and the development team notified, however you can raise an issue through GitHub on our [documentation repository](https://github.com/MewsSystems/gitbook-connector-api).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorApiExceptionResult'
      x-restricted: true
  /api/connector/v1/billingAutomationPaymentPlans/add:
    post:
      tags:
      - Payment plans
      summary: Add billing automation payment plan
      description: "Adds a payment plan connected to a `Billing automation` and returns the payment request URL associated with the created payment plan. The fulfillment of the payment request will activate the payment plan.\r\nNote this operation supports [Portfolio Access Tokens](https://mews-systems.gitbook.io/connector-api/concepts/multi-property/)."
      operationId: billingAutomationPaymentPlans_add
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BillingAutomationPaymentPlanAddParameters'
            example:
              ClientToken: E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D
              AccessToken: C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D
              Client: Sample Client 1.0.0
              BillingAutomationId: ecd64eec-4423-4c65-b844-814b9199856d
              CustomerId: fadd5bb6-b428-45d5-94f8-fd0d89fece6d
              Name: Payment Plan Name
              PaymentRequest:
                PaymentMethods:
                - PaymentCard
                - SepaDirectDebit
                Message: Your scheduled payments will be collected automatically based on your selected plan and timing.
                Note: Bill for previous month included
                ExpirationDateUtc: '2026-10-01T12:00:00Z'
                SendEmail: false
              PaymentOffsetDays: 5
              StartMonth: 2026-10
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentPlanAddResult'
              example:
                PaymentRequestUrl: https://example.com/payment-request-url
        '400':
          description: Error caused by the client app, e.g. in case of malformed request or invalid identifier of a resource. In most cases, such an error signifies a bug in the client app (consumer of the API).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorApiExceptionResult'
        '401':
          description: Error caused by usage of invalid ClientToken, AccessToken, or you may not have the necessary permission to use the endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorApiExceptionResult'
        '403':
          description: Server error that should be reported to the end user of the client app. Happens for example when the server-side validation fails or when a business-logic check is violated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorApiExceptionResult'
        '408':
          description: Error caused by heavy request that takes too long to process (typically tens of seconds). To get around this, request data in smaller batches. For more information, see [Request timeouts](https://mews-systems.gitbook.io/connector-api/guidelines/requests#request-timeouts)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorApiExceptionResult'
        '204':
          description: Server has successfully fulfilled the request and there is no additional information to send back.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorApiExceptionResult'
        '429':
          description: Error caused by too many requests sent in a given amount of time. Response contains `Retry-After` header indicating how long the user agent should wait before making a follow-up request. For more information, see [Request limits](https://mews-systems.gitbook.io/connector-api/guidelines/requests#request-limits).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorApiExceptionResult'
        '500':
          description: Unexpected error on the Mews side. This may be due to a software fault. If such a situation occurs, the error will be logged and the development team notified, however you can raise an issue through GitHub on our [documentation repository](https://github.com/MewsSystems/gitbook-connector-api).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorApiExceptionResult'
      x-restricted: true
components:
  schemas:
    PaymentPlanPaymentRequestTypeEnum:
      title: Payment plan payment request type
      enum:
      - Payment
      - PaymentMethod
      type: string
      description: '


        Payment


        PaymentMethod'
      x-enumNames:
      - Payment
      - PaymentMethod
      x-enumDescriptions:
      - ''
      - ''
    ConnectorApiExceptionResult:
      title: ConnectorApiExceptionResult
      type: object
      properties:
        Message:
          type: string
          nullable: true
        RequestId:
          type: string
          nullable: true
        Details:
          nullable: true
      additionalProperties: false
      x-schema-id: ConnectorApiExceptionResult
    BillingAutomationPaymentPlanAddParameters:
      title: BillingAutomationPaymentPlanAddParameters
      required:
      - AccessToken
      - BillingAutomationId
      - Client
      - ClientToken
      - CustomerId
      - Name
      - PaymentOffsetDays
      - PaymentRequest
      type: object
      properties:
        ClientToken:
          minLength: 1
          type: string
          description: Token identifying the client application.
        AccessToken:
          minLength: 1
          type: string
          description: Access token of the client application.
        Client:
          minLength: 1
          type: string
          description: Name and version of the client application.
        EnterpriseId:
          type: string
          description: Unique identifier of the enterprise. Required when using [Portfolio Access Tokens](https://mews-systems.gitbook.io/connector-api/concepts/multi-property), ignored otherwise.
          format: uuid
          nullable: true
        BillingAutomationId:
          type: string
          description: Unique identifier of the `Billing automation` associated with the payment plan.
          format: uuid
        CustomerId:
          type: string
          description: Unique identifier of the `Customer` associated with the payment plan.
          format: uuid
        Name:
          maxLength: 255
          minLength: 1
          type: string
          description: Name of the payment plan.
        PaymentRequest:
          title: Billing automation payment plan payment request
          allOf:
          - $ref: '#/components/schemas/BillingAutomationPaymentPlanPaymentRequest'
          description: Data related to the payment request associated with the payment plan created.
        PaymentOffsetDays:
          type: integer
          description: Number of days since the bill creation when the payment will be charged.
          format: int32
        StartMonth:
          type: string
          description: Specifies the month when the payment plan begins collecting payments, in the 'YYYY-MM' format. The month must be in the future. If a value is not set, it'll start with the earliest available bill created from billing automation.
          nullable: true
      additionalProperties: false
      x-schema-id: BillingAutomationPaymentPlanAddParameters
    PaymentPlanPaymentRequest:
      title: Payment plan payment request
      required:
      - Message
      - PaymentMethods
      type: object
      properties:
        PaymentMethods:
          minItems: 1
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/PaymentMethodsEnum'
          description: Allowed payment methods to pay for the payment plan.
        Message:
          minLength: 1
          type: string
          description: Message in the payment request.
        Note:
          type: string
          description: Internal note for the payment request.
          nullable: true
        PaymentRequestType:
          allOf:
          - $ref: '#/components/schemas/PaymentPlanPaymentRequestTypeEnum'
          description: 'Type of payment request to create. If not specified, defaults to `Payment`.


            Payment


            PaymentMethod'
          nullable: true
        PaymentRequestExpirationOffsetDays:
          type: integer
          description: Custom expiration date offset in days for the payment request. If not set, it'll expire in one week, unless the first scheduled payment should be executed before. In that case, The expiration date will be set one second before the scheduled payment execution (the last possible moment when we can get the payment method).
          format: int32
          nullable: true
        SendEmail:
          type: boolean
          description: Specifies whether a payment request email is sent to the customer. Defaults to true.
          nullable: true
      additionalProperties: false
      x-schema-id: PaymentPlanPaymentRequest
    BillingAutomationPaymentPlanPaymentRequest:
      title: Billing automation payment plan payment request
      required:
      - ExpirationDateUtc
      - Message
      - PaymentMethods
      - SendEmail
      type: object
      properties:
        PaymentMethods:
          minItems: 1
          uniqueItems: true
          type: array
          items:
            $ref: '#/components/schemas/PaymentMethodsEnum'
          description: Allowed payment methods to use for the payment plan.
        Message:
          maxLength: 1000
          minLength: 1
          type: string
          description: Message for customer in the payment request email.
        Note:
          maxLength: 2000
          type: string
          description: Internal note for the payment request.
          nullable: true
        ExpirationDateUtc:
          minLength: 1
          type: string
          description: Expiration date (UTC time) of the payment request. Must be within 30 days of payment plan creation. ISO-8601 format.
          format: date-time
        SendEmail:
          type: boolean
          description: Specifies whether a payment request email is sent to the customer.
      additionalProperties: false
      x-schema-id: BillingAutomationPaymentPlanPaymentRequest
    PaymentMethodsEnum:
      title: Available payment plan payment methods
      enum:
      - Ideal
      - PaymentCard
      - ApplePay
      - GooglePay
      - SepaDirectDebit
      - All
      type: string
      description: '


        Ideal (iDEAL)


        PaymentCard (Payment card)


        ApplePay (Apple Pay)


        GooglePay (Google Pay)


        SepaDirectDebit (SEPA Direct Debit)


        All'
      x-enumNames:
      - Ideal
      - PaymentCard
      - ApplePay
      - GooglePay
      - SepaDirectDebit
      - All
      x-enumDescriptions:
      - iDEAL
      - Payment card
      - Apple Pay
      - Google Pay
      - SEPA Direct Debit
      - ''
    PaymentPlanAddParameters:
      title: PaymentPlanAddParameters
      required:
      - AccessToken
      - Client
      - ClientToken
      - Name
      - PaymentRequest
      - ReservationId
      type: object
      properties:
        ClientToken:
          minLength: 1
          type: string
          description: Token identifying the client application.
        AccessToken:
          minLength: 1
          type: string
          description: Access token of the client application.
        Client:
          minLength: 1
          type: string
          description: Name and version of the client application.
        EnterpriseId:
          type: string
          description: Unique identifier of the enterprise. Required when using [Portfolio Access Tokens](https://mews-systems.gitbook.io/connector-api/concepts/multi-property), ignored otherwise.
          format: uuid
          nullable: true
        ReservationId:
          type: string
          description: Reservation Id associated with the payment plan.
          format: uuid
        Name:
          minLength: 1
          type: string
          description: Name of the payment plan.
        PaymentRequest:
          title: Payment plan payment request
          allOf:
          - $ref: '#/components/schemas/PaymentPlanPaymentRequest'
          description: Data related to the payment request associated with the payment plan created.
        StartMonth:
          type: string
          description: Specifies the month when the payment plan begins collecting payments, in the 'YYYY-MM' format. The month must be in the future and fall within the reservation period.
          format: date-time
          nullable: true
      additionalProperties: false
      x-schema-id: PaymentPlanAddParameters
    PaymentPlanAddResult:
      title: PaymentPlanAddResult
      required:
      - PaymentRequestUrl
      type: object
      properties:
        PaymentRequestUrl:
          minLength: 1
          type: string
          description: Payment request URL associated with the created payment plan.
      additionalProperties: false
      x-schema-id: PaymentPlanAddResult