Sign in

v1

latestOpenAPI 3.0.02026-07-24161215397.4 KB
Payments

Create a new allocation for credit note/overpayment

Create a new allocation for a credit note/overpayment. The paymentId used here is the _id of the credit note/overpayment, while the request body contains the _id of the target invoice.

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

post/api/v2/organizations/{orgSlug}/payments/{paymentId}/allocations

Path parameters

paymentIdstring required

overpayment/credit note id

orgSlugstring required

organization slug

Request body

targetstring required

If payment is an invoice, a reference to the credit note, sourcing the credit. If payment is a credit note, a reference to the invoice the credit is allocated to.

amountnumber required

The allocated amount.

Example request

{
  "target": "6780f1ba3a4b5c6d7e8f9a0b",
  "amount": 60,
  "accounting": {
    "provider": "xero",
    "providerId": "123456789",
    "externalOrgId": "987654321",
    "deepLink": "https://quickbooks.com/123456789",
    "lastSync": "2025-01-01T00:00:00.000Z",
    "error": "An error occurred while syncing with Xero"
  }
}

Response

propertiesobject

An object that contains all custom properties that can be applied to the item.

_idstring

The id of the payment.

numberstring

The document number for the payment.

documentType'creditNote' | 'invoice' | 'overpayment' | 'paymentCharge'

The type of the document. It could be either invoice, creditNote, or overpayment. If omitted, invoice is assumed.

datestring

The issue date of the payment.

dueDatestring

The due date of the payment.

companystring

A reference to the company the payment is issued for.

memberstring

A reference to the member or individual the payment is issued for.

locationstring

A reference to the location the payment is issued by.

referencestring

Additional data describing the payment. It could be any string value.

taxType'included' | 'excluded' | 'noTax'

The type of the tax calculation for the payment. It could be excluded, included or noTax.

subTotalnumber

The total of the payment before tax.

amountnumber

The total of the payment after tax and discount.

payableAmountnumber

Total amount due for this payment. Voided and paid payments have payableAmount of 0.

baseTotalnumber

The base total amount of the payment.

totalnumber

The total amount of the payment.

paidAmountnumber

The total amount paid for the payment.

pendingAmountnumber

The total amount pending for the payment.

allocatedAmountnumber

The total amount allocated for the payment.

currencystring

The currency of the payment.

currencyConversionRatenumber

The conversion rate for the currency of the payment.

isFailedboolean

Determines whether the payment is considered as failed.

isPaidboolean

Determines whether the payment is considered as paid.

isSentboolean

Shows if the payment has been sent.

status'voided' | 'failed' | 'draft' | 'pending' | 'refunded' | 'paid' | 'awaiting_payment' | 'partially_paid'

The status of the payment.

chargeMethodstring

The charge method of the payment.

createdAtstring

The date when the payment has been created at.

createdBystring

The user that created the payment.

modifiedAtstring

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.

modifiedBystring

The user that did the last modification to the payment. Before the first modification, this field equals to the createdBy field.

Example response

{
  "properties": {
    "customProperty1": "value1",
    "customProperty2": "value2"
  },
  "_id": "6780f1ba1a2b3c4d5e6f7a8b",
  "number": "INV-123",
  "date": "2025-01-01T00:00:00.000Z",
  "dueDate": "2025-01-01T00:00:00.000Z",
  "company": "6780f1ba3c4d5e6f7a8b9c0d",
  "member": "6780f1ba2b3c4d5e6f7a8b9c",
  "location": "6780f1ba4d5e6f7a8b9c0d1e",
  "reference": "Payment for the membership fee.",
  "allocations": [],
  "lines": [
    {
      "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"
      ]
    }
  ],
  "processingFeeLine": {
    "taxPercent": 12,
    "taxAmount": 15,
    "price": 60,
    "discountAmount": 10,
    "unitPrice": 30,
    "baseUnitPrice": 70,
    "subTotal": 60,
    "baseTotal": 60,
    "total": 60,
    "convertedAmounts": {
      "taxPercent": 12,
      "taxAmount": 15,
      "price": 60,
      "discountAmount": 10,
      "unitPrice": 30,
      "baseUnitPrice": 70,
      "subTotal": 60,
      "baseTotal": 60,
      "total": 60
    },
    "description": "Membership fee",
    "account": "6780f1ba5e6f7a8b9c0d1e2f",
    "plan": "6780f1ba6f7a8b9c0d1e2f3a",
    "fee": "6780f1ba7a8b9c0d1e2f3a4b",
    "location": "6780f1ba4d5e6f7a8b9c0d1e",
    "membership": "6780f1ba9c0d1e2f3a4b5c6d",
    "taxRate": "6780f1ba1e2f3a4b5c6d7e8f",
    "discount": 10,
    "unitDiscount": 5,
    "quantity": 2,
    "startDate": "2023-01-01T00:00:00.000Z",
    "endDate": "2023-01-01T00:00:00.000Z",
    "addOns": {
      "name": "Basic addon",
      "unitPrice": 10,
      "description": "Addon description"
    },
    "fees": [
      "6780f1ba7a8b9c0d1e2f3a4b",
      "6780f1ba8b9c0d1e2f3a4b5c"
    ],
    "memberships": [
      "6780f1ba9c0d1e2f3a4b5c6d",
      "6780f1ba0d1e2f3a4b5c6d7e"
    ]
  },
  "taxAmounts": [
    {
      "percent": 25,
      "total": 25.7,
      "taxRate": "6780f1ba1e2f3a4b5c6d7e8f"
    }
  ],
  "subTotal": 60,
  "amount": 60,
  "payableAmount": 60,
  "accounting": {
    "provider": "xero",
    "providerId": "123456789",
    "externalOrgId": "987654321",
    "deepLink": "https://quickbooks.com/123456789",
    "lastSync": "2025-01-01T00:00:00.000Z",
    "error": "An error occurred while syncing with Xero"
  },
  "baseTotal": 60,
  "total": 80,
  "paidAmount": 40,
  "pendingAmount": 40,
  "allocatedAmount": 40,
  "currency": "USD",
  "currencyConversionRate": 0.98567,
  "isPaid": true,
  "chargeMethod": "Credit Card",
  "createdAt": "2025-01-01T00:00:00.000Z",
  "createdBy": "6780f1ba4b5c6d7e8f9a0b1c",
  "modifiedAt": "2025-01-01T00:00:00.000Z",
  "modifiedBy": "6780f1ba4b5c6d7e8f9a0b1c"
}