Zoho Inventory customer-payments API
Customer-Payments Module
OpenAPI Specification
openapi: 3.0.0
info:
title: batches customer-payments API
description: Batches help you track inventory items by batch numbers, manufacturing dates, and expiration dates.
contact: {}
version: 1.0.0
servers:
- url: https://www.zohoapis.com/inventory/v1
description: API Endpoint
tags:
- name: customer-payments
description: Customer-Payments Module
paths:
/customerpayments:
x-mcp-group:
- Customer Payments
parameters:
- $ref: '#/components/parameters/organization_id'
post:
tags:
- customer-payments
operationId: create_customer_payment
summary: Create a payment
description: Create a new payment.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/create-a-payment-request'
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/create-a-payment-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.customerpayments.CREATE
get:
tags:
- customer-payments
operationId: list_customer_payments
summary: List Customer Payments
description: List all the payments made by your customer.
parameters:
- name: customer_name
in: query
description: 'Search payments by customer name. Variants: <code>customer_name_startswith</code> and <code>customer_name_contains</code>. Maximum length [100]'
required: false
schema:
type: string
example: Bowman Furniture
- name: reference_number
in: query
description: 'Search payments by reference number. Variants: <code>reference_number_startswith</code> and <code>reference_number_contains</code>. Maximum length [100]'
required: false
schema:
type: string
example: INV-384
- name: date
in: query
description: Date on which payment is made. Date Format [yyyy-mm-dd]
required: false
schema:
type: string
example: '2016-06-05'
- name: amount
in: query
description: 'Search payments by payment amount. Variants: <code>amount_less_than</code>, <code>amount_less_equals</code>, <code>amount_greater_than</code> and <code>amount_greater_equals</code>'
required: false
schema:
type: number
format: double
example: 450
- name: notes
in: query
description: 'Search payments by customer notes. Variants: <code>notes_startswith</code> and <code>notes_contains</code>'
required: false
schema:
type: string
example: ''
- name: payment_mode
in: query
description: 'Search payments by payment mode. Variants: <code>payment_mode_startswith</code> and <code>payment_mode_contains</code>'
required: false
schema:
type: string
example: cash
- name: filter_by
in: query
description: 'Filter payments by mode.Allowed Values: <code>PaymentMode.All</code>, <code>PaymentMode.Check</code>, <code>PaymentMode.Cash</code>, <code>PaymentMode.BankTransfer</code>, <code>PaymentMode.Paypal</code>, <code>PaymentMode.CreditCard</code>, <code>PaymentMode.GoogleCheckout</code>, <code>PaymentMode.Credit</code>, <code>PaymentMode.Authorizenet</code>, <code>PaymentMode.BankRemittance</code>, <code>PaymentMode.Payflowpro</code>, <code>PaymentMode.Stripe</code>, <code>PaymentMode.TwoCheckout</code>, <code>PaymentMode.Braintree</code> and <code>PaymentMode.Others</code>'
required: false
schema:
type: string
example: ''
- name: sort_column
in: query
description: Sort based on selected column
required: false
schema:
type: string
example: created_time
- name: search_text
in: query
description: Search payments by reference number or customer name or payment description. Maximum length [100]
required: false
schema:
type: string
example: ''
- name: page
in: query
description: Page number to be fetched. Default value is 1.
required: false
schema:
type: integer
default: 1
example: 1
- name: per_page
in: query
description: Number of records to be fetched per page. Default value is 200.
required: false
schema:
type: integer
default: 200
example: 200
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/list-customer-payments-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.customerpayments.READ
/customerpayment/{customer_payment_id}/customfields:
x-mcp-group:
- Customer Payments
put:
tags:
- customer-payments
operationId: update_custom_field_in_customer_payment
summary: Update custom field in existing customerpayments
description: Update the value of the custom field in existing customerpayments.
parameters:
- name: customer_payment_id
in: path
required: true
description: Unique identifier of the customer payment.
schema:
type: string
example: '9030000079467'
- $ref: '#/components/parameters/organization_id'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/custom_fields_update'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/update-an-customerpayment-customfield-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.customerpayments.UPDATE
/customerpayments/{payment_id}:
x-mcp-group:
- Customer Payments
parameters:
- name: payment_id
in: path
required: true
description: Unique identifier of the payment.
schema:
type: string
example: '9030000079467'
- $ref: '#/components/parameters/organization_id'
put:
tags:
- customer-payments
operationId: update_customer_payment
summary: Update a payment
description: 'Update an existing payment information. '
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/update-a-payment-request'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/update-a-payment-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.customerpayments.UPDATE
get:
tags:
- customer-payments
operationId: retrieve_customer_payment
summary: Retrieve a payment
description: 'Details of an existing payment. '
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/retrieve-a-payment-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.customerpayments.READ
delete:
tags:
- customer-payments
operationId: delete_customer_payment
summary: Delete a payment
description: Delete an existing payment.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/delete-a-payment-response'
deprecated: false
security:
- Zoho_Auth:
- ZohoInventory.customerpayments.DELETE
components:
schemas:
tax_amount_withheld:
description: Amount withheld for tax.
type: number
format: double
example: 0
last_four_digits:
description: Last four digits of the card.
type: integer
example: 1111
currency_code:
description: Currency code in which the payment is made.
type: string
example: USD
status:
description: Status of the payment. It can either be <code>success</code> or <code>failure</code>.
type: string
example: success
list-customer-payments-response:
type: object
properties:
code:
type: integer
example: 0
readOnly: true
message:
type: string
example: success
readOnly: true
customerpayments:
type: array
items:
type: object
properties:
payment_id:
$ref: '#/components/schemas/payment_id'
payment_number:
$ref: '#/components/schemas/payment_number'
invoice_number:
$ref: '#/components/schemas/invoice_number'
date:
$ref: '#/components/schemas/date'
payment_mode:
$ref: '#/components/schemas/payment_mode'
amount:
$ref: '#/components/schemas/amount'
bcy_amount:
$ref: '#/components/schemas/bcy_amount'
unused_amount:
$ref: '#/components/schemas/unused_amount'
account_id:
$ref: '#/components/schemas/account_id'
account_name:
$ref: '#/components/schemas/account_name'
description:
$ref: '#/components/schemas/description'
reference_number:
$ref: '#/components/schemas/reference_number'
customer_id:
$ref: '#/components/schemas/customer_id'
customer_name:
$ref: '#/components/schemas/customer_name'
location_id:
$ref: '#/components/schemas/location_id'
location_name:
$ref: '#/components/schemas/location_name'
amount_refunded:
description: Amount that is refunded. Refunds are applicable only for payments whose payment_mode is <code>autotransaction</code>. Refunds would be made to the respective card provided by the customer.
type: number
format: double
example: 50
label:
description: Label of the custom field.
type: string
example: label
update-an-customerpayment-customfield-response:
type: object
properties:
code:
type: integer
example: 0
readOnly: true
message:
type: string
example: Custom Fields Updated Successfully
readOnly: true
create-a-payment-request:
required:
- customer_id
- payment_mode
- amount
- invoices
type: object
properties:
customer_id:
$ref: '#/components/schemas/customer_id'
payment_mode:
$ref: '#/components/schemas/payment_mode'
amount:
$ref: '#/components/schemas/amount'
date:
$ref: '#/components/schemas/date'
reference_number:
$ref: '#/components/schemas/reference_number'
description:
$ref: '#/components/schemas/description'
invoices:
description: List of invoices associated with the payment. Each invoice object contains <code>invoice_id</code>, <code>invoice_number</code>, <code>date</code>, <code>invoice_amount</code>, <code>amount_applied</code> and <code>balance_amount</code>.
type: array
items:
type: object
required:
- invoice_id
- amount_applied
properties:
invoice_id:
$ref: '#/components/schemas/invoice_id'
amount_applied:
$ref: '#/components/schemas/amount_applied'
tax_amount_withheld:
$ref: '#/components/schemas/tax_amount_withheld'
exchange_rate:
$ref: '#/components/schemas/exchange_rate'
payment_form:
$ref: '#/components/schemas/payment_form'
bank_charges:
$ref: '#/components/schemas/bank_charges'
account_id:
$ref: '#/components/schemas/account_id'
tax_account_id:
$ref: '#/components/schemas/tax_account_id'
location_id:
$ref: '#/components/schemas/location_id'
custom_fields:
description: Additional fields for the payments.
type: array
items:
type: object
properties:
label:
$ref: '#/components/schemas/label'
value:
$ref: '#/components/schemas/value'
invoice_number:
description: Unique ID (starts with INV) of an invoice.
type: string
example: INV-384
location_name:
description: Name of the location.
type: string
payment_id:
description: Unique ID of the payment generated by the server. Maximum length allowed [2000]
type: string
example: '9030000079467'
custom_fields_update:
description: Custom fields for an payments.
type: array
items:
type: object
properties:
customfield_id:
type: string
description: Unique ID of the custom field.
example: '46000000012845'
value:
$ref: '#/components/schemas/value'
data_type:
description: Data type of the custom field.
type: string
example: text
balance_amount:
description: Unpaid amount of the invoice.
type: number
format: double
example: 0
customer_id:
description: Customer ID of the customer involved in the payment.
type: string
example: '903000000000099'
bank_charges:
description: Denotes any additional bank charges.
type: number
format: double
example: 10
account_id:
description: ID of the cash/ bank account the payment has to be deposited.
type: string
example: '450000000000353'
delete-a-payment-response:
type: object
properties:
code:
type: integer
example: 0
readOnly: true
message:
type: string
example: The payment has been deleted.
readOnly: true
create-a-payment-response:
type: object
properties:
code:
type: integer
example: 0
readOnly: true
message:
type: string
example: The payment has been created.
readOnly: true
payment:
$ref: '#/components/schemas/payment-response'
email:
description: Email address of the customer involved in the payment.
type: string
example: benjamin.george@bowmanfurniture.com
date:
description: Date on which payment is made. Date Format [yyyy-mm-dd]
type: string
example: '2016-06-05'
customer_name:
description: Name of the customer to whom the invoice is raised. Maximum length [100]
type: string
example: Bowman Furniture
invoice_id:
description: Invoice ID of the required invoice.
type: string
example: '90300000079426'
update-a-payment-response:
type: object
properties:
code:
type: integer
example: 0
readOnly: true
message:
type: string
example: The payment details have been updated.
readOnly: true
payment:
description: Payment details of the customer
type: object
properties:
payment_id:
$ref: '#/components/schemas/payment_id'
payment_mode:
$ref: '#/components/schemas/payment_mode'
amount:
$ref: '#/components/schemas/amount'
amount_refunded:
$ref: '#/components/schemas/amount_refunded'
bank_charges:
$ref: '#/components/schemas/bank_charges'
date:
$ref: '#/components/schemas/date'
status:
$ref: '#/components/schemas/status'
reference_number:
$ref: '#/components/schemas/reference_number'
description:
$ref: '#/components/schemas/description'
customer_id:
$ref: '#/components/schemas/customer_id'
customer_name:
$ref: '#/components/schemas/customer_name'
email:
$ref: '#/components/schemas/email'
tax_amount_withheld:
$ref: '#/components/schemas/tax_amount_withheld'
invoices:
description: Invoices linked to the payment
type: array
items:
type: object
properties:
invoice_id:
$ref: '#/components/schemas/invoice_id'
invoice_number:
$ref: '#/components/schemas/invoice_number'
date:
description: Date on which the invoice was raised.
example: '2016-06-05'
invoice_amount:
$ref: '#/components/schemas/invoice_amount'
amount_applied:
$ref: '#/components/schemas/amount_applied'
balance_amount:
$ref: '#/components/schemas/balance_amount'
exchange_rate:
$ref: '#/components/schemas/exchange_rate'
currency_id:
$ref: '#/components/schemas/currency_id'
currency_code:
$ref: '#/components/schemas/currency_code'
currency_symbol:
$ref: '#/components/schemas/currency_symbol'
account_id:
$ref: '#/components/schemas/account_id'
account_name:
$ref: '#/components/schemas/account_name'
tax_account_id:
$ref: '#/components/schemas/tax_account_id'
tax_account_name:
$ref: '#/components/schemas/tax_account_name'
unused_amount:
$ref: '#/components/schemas/unused_amount'
last_four_digits:
$ref: '#/components/schemas/last_four_digits'
location_id:
$ref: '#/components/schemas/location_id'
location_name:
$ref: '#/components/schemas/location_name'
custom_fields:
description: Additinal fields of the invoice
type: array
items:
type: object
properties:
index:
$ref: '#/components/schemas/index'
value:
$ref: '#/components/schemas/value'
label:
$ref: '#/components/schemas/label'
data_type:
$ref: '#/components/schemas/data_type'
index:
description: Index of the custom field. It can hold any value from 1 to 10.
type: integer
example: 1
amount_applied:
description: Amount paid for the invoice.
type: number
format: double
example: 450
retrieve-a-payment-response:
type: object
properties:
code:
type: integer
example: 0
readOnly: true
message:
type: string
example: success
readOnly: true
payment:
description: Payment details of the invoice
type: object
properties:
payment_id:
$ref: '#/components/schemas/payment_id'
payment_mode:
$ref: '#/components/schemas/payment_mode'
amount:
$ref: '#/components/schemas/amount'
amount_refunded:
$ref: '#/components/schemas/amount_refunded'
bank_charges:
$ref: '#/components/schemas/bank_charges'
date:
$ref: '#/components/schemas/date'
status:
$ref: '#/components/schemas/status'
reference_number:
$ref: '#/components/schemas/reference_number'
description:
$ref: '#/components/schemas/description'
customer_id:
$ref: '#/components/schemas/customer_id'
customer_name:
$ref: '#/components/schemas/customer_name'
email:
$ref: '#/components/schemas/email'
tax_amount_withheld:
$ref: '#/components/schemas/tax_amount_withheld'
invoices:
description: Invoices linked to a payment
type: array
items:
type: object
properties:
invoice_id:
$ref: '#/components/schemas/invoice_id'
invoice_number:
$ref: '#/components/schemas/invoice_number'
date:
description: Date on which the invoice was raised.
example: '2016-06-05'
invoice_amount:
$ref: '#/components/schemas/invoice_amount'
amount_applied:
$ref: '#/components/schemas/amount_applied'
balance_amount:
$ref: '#/components/schemas/balance_amount'
exchange_rate:
$ref: '#/components/schemas/exchange_rate'
currency_id:
$ref: '#/components/schemas/currency_id'
currency_code:
$ref: '#/components/schemas/currency_code'
currency_symbol:
$ref: '#/components/schemas/currency_symbol'
account_id:
$ref: '#/components/schemas/account_id'
account_name:
$ref: '#/components/schemas/account_name'
tax_account_id:
$ref: '#/components/schemas/tax_account_id'
tax_account_name:
$ref: '#/components/schemas/tax_account_name'
unused_amount:
$ref: '#/components/schemas/unused_amount'
last_four_digits:
$ref: '#/components/schemas/last_four_digits'
location_id:
$ref: '#/components/schemas/location_id'
location_name:
$ref: '#/components/schemas/location_name'
custom_fields:
description: Additional fields for invoice
type: array
items:
type: object
properties:
index:
$ref: '#/components/schemas/index'
value:
$ref: '#/components/schemas/value'
label:
$ref: '#/components/schemas/label'
data_type:
$ref: '#/components/schemas/data_type'
value:
description: Value of the custom field.
type: string
example: 129890
exchange_rate:
description: Exchange rate for the currency used in the invoices and customer's currency. The payment amount would be the multiplicative product of the original amount and the exchange rate.
type: number
format: double
example: 1
default: 1
currency_symbol:
description: Customer's currency symbol.
type: string
example: $
currency_id:
description: ID of the currency used in the payment
type: string
example: '3000000002321'
invoice_amount:
description: Total amount raised for the invoice.
type: number
format: double
example: 450
reference_number:
description: Reference number generated for the payment. A string of your choice can also be used as the reference number. Maximum length of the reference number [100]
type: string
example: INV-384
location_id:
description: Location ID
type: string
example: '460000000038080'
payment_mode:
description: Mode through which payment is made. This can be <code>check</code>, <code>cash</code>, <code>creditcard</code>, <code>banktransfer</code>, <code>bankremittance</code>, <code>autotransaction</code> or <code>others</code>. Maximum length [100]
type: string
example: cash
account_name:
description: Name of the cash/ bank account the payment has to be deposited.
type: string
example: Petty Cash
tax_account_id:
description: ID of the tax account, in case of withholding tax.
type: string
example: ''
unused_amount:
description: Amount which is not used for invoice payment yet.
type: number
format: double
example: 0
payment_form:
description: Mode of Vendor Payment
type: string
example: cash
x-node_available_in:
- mx
x-node_unavailable_in: []
description:
description: Description about the payment.
type: string
example: Payment has been added to INV-384
update-a-payment-request:
required:
- customer_id
- payment_mode
- amount
- invoices
type: object
properties:
customer_id:
$ref: '#/components/schemas/customer_id'
payment_mode:
$ref: '#/components/schemas/payment_mode'
amount:
$ref: '#/components/schemas/amount'
date:
$ref: '#/components/schemas/date'
reference_number:
$ref: '#/components/schemas/reference_number'
description:
$ref: '#/components/schemas/description'
invoices:
description: List of invoices associated with the payment. Each invoice object contains <code>invoice_id</code>, <code>invoice_number</code>, <code>date</code>, <code>invoice_amount</code>, <code>amount_applied</code> and <code>balance_amount</code>.
type: array
items:
type: object
required:
- invoice_id
- amount_applied
properties:
invoice_id:
$ref: '#/components/schemas/invoice_id'
amount_applied:
$ref: '#/components/schemas/amount_applied'
tax_amount_withheld:
$ref: '#/components/schemas/tax_amount_withheld'
exchange_rate:
$ref: '#/components/schemas/exchange_rate'
payment_form:
$ref: '#/components/schemas/payment_form'
bank_charges:
$ref: '#/components/schemas/bank_charges'
account_id:
$ref: '#/components/schemas/account_id'
tax_account_id:
$ref: '#/components/schemas/tax_account_id'
location_id:
$ref: '#/components/schemas/location_id'
custom_fields:
description: Additional fields for the payments.
type: array
items:
type: object
properties:
label:
$ref: '#/components/schemas/label'
value:
$ref: '#/components/schemas/value'
payment_number:
description: Number for the payment.
type: string
example: '2'
tax_account_name:
description: Name of the tax account, in case of withholding tax.
type: string
example: ''
bcy_amount:
type: string
example: 450
amount:
description: Amount paid in the respective payment.
type: number
format: double
example: 450
payment-response:
description: Payment details of the transaction
type: object
properties:
payment_id:
$ref: '#/components/schemas/payment_id'
payment_mode:
$ref: '#/components/schemas/payment_mode'
amount:
$ref: '#/components/schemas/amount'
amount_refunded:
$ref: '#/components/schemas/amount_refunded'
bank_charges:
$ref: '#/components/schemas/bank_charges'
date:
$ref: '#/components/schemas/date'
status:
$ref: '#/components/schemas/status'
reference_number:
$ref: '#/components/schemas/reference_number'
description:
$ref: '#/components/schemas/description'
customer_id:
$ref: '#/components/schemas/customer_id'
customer_name:
$ref: '#/components/schemas/customer_name'
email:
$ref: '#/components/schemas/email'
tax_amount_withheld:
$ref: '#/components/schemas/tax_amount_withheld'
invoices:
description: Invoice related to a payment
type: array
items:
type: object
properties:
invoice_id:
$ref: '#/components/schemas/invoice_id'
invoice_number:
$ref: '#/components/schemas/invoice_number'
date:
description: Date on which the invoice was raised.
example: '2016-06-05'
invoice_amount:
$ref: '#/components/schemas/invoice_amount'
amount_applied:
$ref: '#/components/schemas/amount_applied'
balance_amount:
$ref: '#/components/schemas/balance_amount'
exchange_rate:
$ref: '#/components/schemas/exchange_rate'
currency_id:
$ref: '#/components/schemas/currency_id'
currency_code:
$ref: '#/components/schemas/currency_code'
currency_symbol:
$ref: '#/components/schemas/currency_symbol'
account_id:
$ref: '#/components/schemas/account_id'
account_name:
$ref: '#/components/schemas/account_name'
tax_account_id:
$ref: '#/components/schemas/tax_account_id'
tax_account_name:
$ref: '#/components/schemas/tax_account_name'
unused_amount:
$ref: '#/components/schemas/unused_amount'
last_four_digits:
$ref: '#/components/schemas/last_four_digits'
location_id:
$ref: '#/components/schemas/location_id'
location_name:
$ref: '#/components/schemas/location_name'
custom_fields:
description: Additional field for a payment
type: array
items:
type: object
properties:
index:
$ref: '#/components/schemas/index'
value:
$ref: '#/components/schemas/value'
label:
$ref: '#/components/schemas/label'
data_type:
$ref: '#/components/schemas/data_type'
parameters:
organization_id:
name: organization_id
description: ID of the organization
in: query
required: true
schema:
type: string
example: '10234695'
securitySchemes:
Zoho_Auth:
type: oauth2
flows:
implicit:
authorizationUrl: https://accounts.zoho.com/oauth/v2/auth
scopes:
ZohoInventory.items.CREATE: Create Items
ZohoInventory.items.READ: Read Items
ZohoInventory.items.UPDATE: Update Items
ZohoInventory.items.DELETE: Delete Items