---
updatedAt: 2026-04-21T05:36:14.000Z
agentTools:
  projectIndex: https://developer.officernd.com/llms.txt
---

# Create a new overpayment

Create a new overpayment. 

 Required scopes: `flex.billing.payments.create`

# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "paths": {
    "/api/v2/organizations/{orgSlug}/payments": {
      "post": {
        "description": "Create a new overpayment. \n\n Required scopes: `flex.billing.payments.create`",
        "operationId": "PaymentsController_addOverpayment_api/v2",
        "parameters": [
          {
            "name": "orgSlug",
            "required": true,
            "in": "path",
            "description": "organization slug",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AddOverpaymentDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentResultDto"
                }
              }
            }
          }
        },
        "security": [
          {
            "oauth2": [
              "flex.billing.payments.create"
            ]
          }
        ],
        "summary": "Create a new overpayment",
        "tags": [
          "Payments"
        ]
      }
    }
  },
  "info": {
    "title": "Billing & Product API",
    "description": "",
    "version": "2.0",
    "contact": {}
  },
  "servers": [
    {
      "url": "https://app.officernd.com"
    }
  ],
  "components": {
    "securitySchemes": {
      "oauth2": {
        "type": "oauth2",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://identity.officernd.com/auth/token",
            "scopes": {}
          },
          "authorizationCode": {
            "authorizationUrl": "https://identity.officernd.com/auth/authorize",
            "tokenUrl": "https://identity.officernd.com/auth/token",
            "scopes": {}
          }
        }
      }
    },
    "schemas": {
      "PaymentDocumentType": {
        "type": "string",
        "enum": [
          "creditNote",
          "invoice",
          "overpayment",
          "paymentCharge"
        ],
        "description": "The type of the document. It could be either invoice, creditNote, or overpayment. If omitted, invoice is assumed."
      },
      "TaxType": {
        "type": "string",
        "enum": [
          "included",
          "excluded",
          "noTax"
        ],
        "description": "The type of the tax calculation for the payment. It could be excluded, included or noTax."
      },
      "AccountingResultDto": {
        "type": "object",
        "properties": {
          "provider": {
            "type": "string",
            "description": "The name of the accounting provider.",
            "example": "xero"
          },
          "providerId": {
            "type": "string",
            "description": "The id of the payment in the accounting provider.",
            "example": "123456789"
          },
          "externalOrgId": {
            "type": "string",
            "description": "The organization id in the accounting provider.",
            "example": "987654321"
          },
          "deepLink": {
            "type": "string",
            "description": "A deep link to the payment in the accounting provider.",
            "example": "https://quickbooks.com/123456789"
          },
          "lastSync": {
            "type": "string",
            "description": "The date of the last sync of the payment with the accounting integration.",
            "example": "2025-01-01T00:00:00.000Z"
          },
          "error": {
            "type": "string",
            "description": "An error message with more details about the reason of the failure.",
            "example": "An error occurred while syncing with Xero"
          }
        }
      },
      "CreditAllocationResultDto": {
        "type": "object",
        "properties": {
          "_id": {
            "type": "string",
            "description": "The id of the credit allocation.",
            "example": "6780f1ba2f3a4b5c6d7e8f9a"
          },
          "target": {
            "type": "string",
            "description": "If payment is an invoice, a reference to the credit note, sourcing the credit. \n             If payment is a credit note, a reference to the invoice the credit is allocated to.",
            "example": "6780f1ba3a4b5c6d7e8f9a0b"
          },
          "amount": {
            "type": "number",
            "description": "The allocated amount.",
            "example": 60
          },
          "documentType": {
            "description": "The type of document that was allocated to the payment.",
            "example": "creditNote",
            "allOf": [
              {
                "$ref": "#/components/schemas/PaymentDocumentType"
              }
            ]
          },
          "accounting": {
            "description": "The accounting data for the allocation.",
            "example": {
              "provider": "xero",
              "providerId": "123456789",
              "externalOrgId": "987654321",
              "deepLink": "https://xero.com/123456789",
              "lastSync": "2025-01-01T00:00:00.000Z",
              "error": "An error occurred while syncing with Xero"
            },
            "allOf": [
              {
                "$ref": "#/components/schemas/AccountingResultDto"
              }
            ]
          }
        }
      },
      "CalculatedLineStatsDto": {
        "type": "object",
        "properties": {
          "taxPercent": {
            "type": "number",
            "description": "The tax percent applied to the line item.",
            "example": 12
          },
          "taxAmount": {
            "type": "number",
            "description": "The tax amount applied to the line item.",
            "example": 15
          },
          "price": {
            "type": "number",
            "description": "The total price as described in the system.",
            "example": 60
          },
          "discountAmount": {
            "type": "number",
            "description": "The calculated discount amount based on the discount set in the payment.",
            "example": 10
          },
          "unitPrice": {
            "type": "number",
            "description": "Based on the quantity of the line item, this is the price of a single unit.",
            "example": 30
          },
          "baseUnitPrice": {
            "type": "number",
            "description": "Based on the quantity of the line item, this is the price of a single unit in the base currency.",
            "example": 70
          },
          "subTotal": {
            "type": "number",
            "description": "The subtotal of the line item (including tax).",
            "example": 60
          },
          "baseTotal": {
            "type": "number",
            "description": "The total price of the line item in the base currency (including discount).",
            "example": 60
          },
          "total": {
            "type": "number",
            "description": "The total for the line item (including tax).",
            "example": 60
          }
        }
      },
      "LineItemAddonDto": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "The name of the addon.",
            "example": "Basic addon"
          },
          "unitPrice": {
            "type": "number",
            "description": "The unit price of the addon.",
            "example": 10
          },
          "description": {
            "type": "string",
            "description": "The description of the addon.",
            "example": "Addon description"
          }
        }
      },
      "LineItemDto": {
        "type": "object",
        "properties": {
          "taxPercent": {
            "type": "number",
            "description": "The tax percent applied to the line item.",
            "example": 12
          },
          "taxAmount": {
            "type": "number",
            "description": "The tax amount applied to the line item.",
            "example": 15
          },
          "price": {
            "type": "number",
            "description": "The total price as described in the system.",
            "example": 60
          },
          "discountAmount": {
            "type": "number",
            "description": "The calculated discount amount based on the discount set in the payment.",
            "example": 10
          },
          "unitPrice": {
            "type": "number",
            "description": "Based on the quantity of the line item, this is the price of a single unit.",
            "example": 30
          },
          "baseUnitPrice": {
            "type": "number",
            "description": "Based on the quantity of the line item, this is the price of a single unit in the base currency.",
            "example": 70
          },
          "subTotal": {
            "type": "number",
            "description": "The subtotal of the line item (including tax).",
            "example": 60
          },
          "baseTotal": {
            "type": "number",
            "description": "The total price of the line item in the base currency (including discount).",
            "example": 60
          },
          "total": {
            "type": "number",
            "description": "The total for the line item (including tax).",
            "example": 60
          },
          "convertedAmounts": {
            "description": "If the invoice's currency is different than the base currency of the organization, \n                these are the converted stats for the line item.",
            "example": {
              "price": 60,
              "discountAmount": 10,
              "baseUnitPrice": 70,
              "subTotal": 60,
              "unitPrice": 30,
              "taxAmount": 12,
              "taxPercent": 15,
              "baseTotal": 60,
              "total": 60
            },
            "allOf": [
              {
                "$ref": "#/components/schemas/CalculatedLineStatsDto"
              }
            ]
          },
          "description": {
            "type": "string",
            "description": "Description of the line item.",
            "example": "Membership fee"
          },
          "account": {
            "type": "string",
            "description": "A reference to the account the line item is allocated to.",
            "example": "6780f1ba5e6f7a8b9c0d1e2f"
          },
          "plan": {
            "type": "string",
            "description": "A reference to the plan the line item is for.",
            "example": "6780f1ba6f7a8b9c0d1e2f3a"
          },
          "fee": {
            "type": "string",
            "description": "A reference to the fee the line item is for.",
            "example": "6780f1ba7a8b9c0d1e2f3a4b"
          },
          "location": {
            "type": "string",
            "description": "A reference to the location the line item is for.",
            "example": "6780f1ba4d5e6f7a8b9c0d1e"
          },
          "membership": {
            "type": "string",
            "description": "A reference to the membership the line item is for. @deprecated Use memberships array instead.",
            "example": "6780f1ba9c0d1e2f3a4b5c6d",
            "deprecated": true
          },
          "taxRate": {
            "type": "string",
            "description": "A reference to the taxRate the line item is for.",
            "example": "6780f1ba1e2f3a4b5c6d7e8f"
          },
          "discount": {
            "type": "number",
            "description": "Based on the quantity of the line item, this is the total discount that applied.",
            "example": 10
          },
          "unitDiscount": {
            "type": "number",
            "description": "Based on the quantity of the line item, this is the single discount of a unit.",
            "example": 5
          },
          "quantity": {
            "type": "number",
            "description": "The quantity of items described in the line item.",
            "example": 2
          },
          "startDate": {
            "type": "string",
            "description": "The start date of the billing period.",
            "example": "2023-01-01T00:00:00.000Z"
          },
          "endDate": {
            "type": "string",
            "description": "The end date of the billing period.",
            "example": "2023-01-01T00:00:00.000Z"
          },
          "addOns": {
            "description": "Any addons that are included in the membership will be added here.",
            "example": {
              "name": "Addon 1",
              "unitPrice": 100,
              "description": "Addon description"
            },
            "allOf": [
              {
                "$ref": "#/components/schemas/LineItemAddonDto"
              }
            ]
          },
          "fees": {
            "description": "An array of fee references from the original lines that were merged into this invoice line.",
            "example": [
              "6780f1ba7a8b9c0d1e2f3a4b",
              "6780f1ba8b9c0d1e2f3a4b5c"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "memberships": {
            "description": "An array of membership references from the original lines that were merged into this invoice line.",
            "example": [
              "6780f1ba9c0d1e2f3a4b5c6d",
              "6780f1ba0d1e2f3a4b5c6d7e"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "TaxAmountDto": {
        "type": "object",
        "properties": {
          "percent": {
            "type": "number",
            "description": "The tax percent for the group.",
            "example": 25
          },
          "total": {
            "type": "number",
            "description": "The tax total for the group.",
            "example": 25.7
          },
          "taxRate": {
            "type": "string",
            "description": "A reference to the taxRate the group is for.",
            "example": "6780f1ba1e2f3a4b5c6d7e8f"
          }
        }
      },
      "PaymentStatus": {
        "type": "string",
        "enum": [
          "voided",
          "failed",
          "draft",
          "pending",
          "refunded",
          "paid",
          "awaiting_payment",
          "partially_paid"
        ],
        "description": "The status of the payment."
      },
      "PaymentResultDto": {
        "type": "object",
        "properties": {
          "properties": {
            "type": "object",
            "description": "An object that contains all custom properties that can be applied to the item.",
            "example": {
              "customProperty1": "value1",
              "customProperty2": "value2"
            }
          },
          "_id": {
            "type": "string",
            "description": "The id of the payment.",
            "example": "6780f1ba1a2b3c4d5e6f7a8b"
          },
          "number": {
            "type": "string",
            "description": "The document number for the payment.",
            "example": "INV-123"
          },
          "documentType": {
            "description": "The type of the document. It could be either invoice, creditNote, or overpayment. If omitted, invoice is assumed.",
            "example": "creditNote",
            "allOf": [
              {
                "$ref": "#/components/schemas/PaymentDocumentType"
              }
            ]
          },
          "date": {
            "type": "string",
            "description": "The issue date of the payment.",
            "example": "2025-01-01T00:00:00.000Z"
          },
          "dueDate": {
            "type": "string",
            "description": "The due date of the payment.",
            "example": "2025-01-01T00:00:00.000Z"
          },
          "company": {
            "type": "string",
            "description": "A reference to the company the payment is issued for.",
            "example": "6780f1ba3c4d5e6f7a8b9c0d"
          },
          "member": {
            "type": "string",
            "description": "A reference to the member or individual the payment is issued for.",
            "example": "6780f1ba2b3c4d5e6f7a8b9c"
          },
          "location": {
            "type": "string",
            "description": "A reference to the location the payment is issued by.",
            "example": "6780f1ba4d5e6f7a8b9c0d1e"
          },
          "reference": {
            "type": "string",
            "description": "Additional data describing the payment. It could be any string value.",
            "example": "Payment for the membership fee."
          },
          "taxType": {
            "description": "The type of the tax calculation for the payment. It could be excluded, included or noTax.",
            "example": "included",
            "allOf": [
              {
                "$ref": "#/components/schemas/TaxType"
              }
            ]
          },
          "allocations": {
            "description": "A list of credit allocations. Each allocation has amount and target.",
            "example": [],
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CreditAllocationResultDto"
            }
          },
          "lines": {
            "description": "A list of payment line items.",
            "example": [
              {
                "description": "Membership fee",
                "quantity": 2,
                "account": "6780f1ba5e6f7a8b9c0d1e2f",
                "plan": "6780f1ba6f7a8b9c0d1e2f3a",
                "fee": "6780f1ba7a8b9c0d1e2f3a4b",
                "membership": "6780f1ba9c0d1e2f3a4b5c6d",
                "location": "6780f1ba4d5e6f7a8b9c0d1e",
                "taxRate": "6780f1ba1e2f3a4b5c6d7e8f",
                "taxPercent": 25,
                "taxAmount": 25.7,
                "discountAmount": 10,
                "price": 60,
                "unitPrice": 30,
                "unitDiscount": 5,
                "subTotal": 60,
                "baseUnitPrice": 70,
                "baseTotal": 60,
                "total": 60,
                "startDate": "2025-01-01T00:00:00.000Z",
                "endDate": "2025-01-01T00:00:00.000Z",
                "convertedAmounts": {
                  "price": 60,
                  "discountAmount": 10,
                  "baseUnitPrice": 70,
                  "subTotal": 60,
                  "unitPrice": 30,
                  "taxAmount": 12,
                  "taxPercent": 15,
                  "baseTotal": 60,
                  "total": 60
                },
                "addons": [
                  {
                    "name": "Addon 1",
                    "unitPrice": 10,
                    "description": "Addon description"
                  },
                  {
                    "name": "Addon 2",
                    "unitPrice": 20,
                    "description": "Addon description"
                  }
                ],
                "fees": [
                  "6780f1ba7a8b9c0d1e2f3a4b",
                  "6780f1ba8b9c0d1e2f3a4b5c"
                ],
                "memberships": [
                  "6780f1ba9c0d1e2f3a4b5c6d"
                ]
              }
            ],
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LineItemDto"
            }
          },
          "processingFeeLine": {
            "description": "The processing fee of the payment.",
            "example": {
              "description": "3.11% Processing Fee",
              "account": "6780f1ba5e6f7a8b9c0d1e2f",
              "plan": "6780f1ba6f7a8b9c0d1e2f3a",
              "fee": "6780f1ba7a8b9c0d1e2f3a4b",
              "taxRate": "6780f1ba1e2f3a4b5c6d7e8f",
              "discount": 0,
              "quantity": 1
            },
            "allOf": [
              {
                "$ref": "#/components/schemas/LineItemDto"
              }
            ]
          },
          "taxAmounts": {
            "description": "A list of payment tax amounts.",
            "example": [
              {
                "percent": 25,
                "total": 25.7,
                "taxRate": "6780f1ba1e2f3a4b5c6d7e8f"
              }
            ],
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/TaxAmountDto"
            }
          },
          "subTotal": {
            "type": "number",
            "description": "The total of the payment before tax.",
            "example": 60
          },
          "amount": {
            "type": "number",
            "description": "The total of the payment after tax and discount.",
            "example": 60
          },
          "payableAmount": {
            "type": "number",
            "description": "Total amount due for this payment. Voided and paid payments have payableAmount of 0.",
            "example": 60
          },
          "accounting": {
            "description": "Data on the payment sync with an accounting integration.",
            "example": {
              "provider": "xero",
              "providerId": "123456789",
              "externalOrgId": "987654321",
              "deepLink": "https://xero.com/123456789",
              "lastSync": "2025-01-01T00:00:00.000Z",
              "error": "An error occurred while syncing with Xero"
            },
            "allOf": [
              {
                "$ref": "#/components/schemas/AccountingResultDto"
              }
            ]
          },
          "baseTotal": {
            "type": "number",
            "description": "The base total amount of the payment.",
            "example": 60
          },
          "total": {
            "type": "number",
            "description": "The total amount of the payment.",
            "example": 80
          },
          "paidAmount": {
            "type": "number",
            "description": "The total amount paid for the payment.",
            "example": 40
          },
          "pendingAmount": {
            "type": "number",
            "description": "The total amount pending for the payment.",
            "example": 40
          },
          "allocatedAmount": {
            "type": "number",
            "description": "The total amount allocated for the payment.",
            "example": 40
          },
          "currency": {
            "type": "string",
            "description": "The currency of the payment.",
            "example": "USD"
          },
          "currencyConversionRate": {
            "type": "number",
            "description": "The conversion rate for the currency of the payment.",
            "example": 0.98567
          },
          "isFailed": {
            "type": "boolean",
            "description": "Determines whether the payment is considered as failed.",
            "example": false
          },
          "isPaid": {
            "type": "boolean",
            "description": "Determines whether the payment is considered as paid.",
            "example": true
          },
          "isSent": {
            "type": "boolean",
            "description": "Shows if the payment has been sent.",
            "example": false
          },
          "status": {
            "description": "The status of the payment.",
            "example": "partially_paid",
            "allOf": [
              {
                "$ref": "#/components/schemas/PaymentStatus"
              }
            ]
          },
          "chargeMethod": {
            "type": "string",
            "description": "The charge method of the payment.",
            "example": "Credit Card"
          },
          "createdAt": {
            "type": "string",
            "description": "The date when the payment has been created at.",
            "example": "2025-01-01T00:00:00.000Z"
          },
          "createdBy": {
            "type": "string",
            "description": "The user that created the payment.",
            "example": "6780f1ba4b5c6d7e8f9a0b1c"
          },
          "modifiedAt": {
            "type": "string",
            "description": "The date when the payment has been modified for the last time. Note that adding/removing charges and credit allocations are considered modifications to both the invoice and the credit note/overpayment.",
            "example": "2025-01-01T00:00:00.000Z"
          },
          "modifiedBy": {
            "type": "string",
            "description": "The user that did the last modification to the payment. Before the first modification, this field equals to the createdBy field.",
            "example": "6780f1ba4b5c6d7e8f9a0b1c"
          }
        }
      },
      "AddOverpaymentLineDto": {
        "type": "object",
        "properties": {
          "unitPrice": {
            "type": "number",
            "description": "The unit price of a single item in the line.",
            "example": 100
          },
          "quantity": {
            "type": "number",
            "description": "The quantity of the line item.",
            "example": 2
          },
          "description": {
            "type": "string",
            "description": "The description of the line item.",
            "example": "Membership fee"
          },
          "location": {
            "type": "string",
            "description": "The location of the line item.",
            "example": "6acde3f52d2ed42e8be32af9"
          }
        },
        "required": [
          "unitPrice",
          "quantity",
          "description"
        ]
      },
      "AccountingRequestDto": {
        "type": "object",
        "properties": {
          "provider": {
            "type": "string",
            "description": "The name of the accounting provider.",
            "example": "quickbooks"
          },
          "providerId": {
            "type": "string",
            "description": "The id of the payment in the accounting provider.",
            "example": "123456789"
          },
          "externalOrgId": {
            "type": "string",
            "description": "The organization id in the accounting provider.",
            "example": "987654321"
          },
          "deepLink": {
            "type": "string",
            "description": "A deep link to the payment in the accounting provider.",
            "example": "https://quickbooks.com/123456789"
          },
          "lastSync": {
            "type": "string",
            "description": "The date of the last sync of the payment with the accounting integration.",
            "example": "2025-01-01T00:00:00.000Z"
          },
          "error": {
            "type": "string",
            "description": "An error message with more details about the reason of the failure.",
            "example": "Error message"
          }
        }
      },
      "AddOverpaymentDto": {
        "type": "object",
        "properties": {
          "date": {
            "type": "string",
            "description": "The issue date of the overpayment.",
            "example": "2025-01-01T00:00:00.000Z"
          },
          "location": {
            "type": "string",
            "description": "A reference to the location the overpayment is issued for.",
            "example": "6acde3f52d2ed42e8be32afa"
          },
          "lines": {
            "description": "The line items of the overpayment.",
            "example": [
              {
                "unitPrice": 100,
                "description": "Membership fee",
                "location": "6acde3f52d2ed42e8be32afb"
              }
            ],
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AddOverpaymentLineDto"
            }
          },
          "member": {
            "type": "string",
            "description": "A reference to the member the payment is issued for.",
            "example": "6acde3f52d2ed42e8be32afc"
          },
          "company": {
            "type": "string",
            "description": "A reference to the company the overpayment is issued for.",
            "example": "6acde3f52d2ed42e8be32afd"
          },
          "currency": {
            "type": "string",
            "description": "The currency of the overpayment.",
            "example": "USD"
          },
          "currencyConversionRate": {
            "type": "number",
            "description": "The conversion rate for the currency of the payment. If the payment's currency is different from the default currency, \n            this rate will be used to convert the payment amount to the default currency.",
            "example": 0.98567
          },
          "chargeMethod": {
            "type": "string",
            "description": "The charge method of the overpayment.",
            "example": "Credit Card"
          },
          "number": {
            "type": "string",
            "description": "The payment number of the overpayment.",
            "example": "OP-356"
          },
          "accounting": {
            "description": "The accounting data of the overpayment.",
            "example": {
              "provider": "xero",
              "providerId": "123456789",
              "externalOrgId": "987654321",
              "deepLink": "https://xero.com/123456789",
              "lastSync": "2025-01-01T00:00:00.000Z",
              "error": "An error occurred while syncing with Xero"
            },
            "allOf": [
              {
                "$ref": "#/components/schemas/AccountingRequestDto"
              }
            ]
          }
        },
        "required": [
          "date",
          "location",
          "lines"
        ]
      }
    }
  }
}
```