{"id":4127,"date":"2024-04-04T16:13:08","date_gmt":"2024-04-04T14:13:08","guid":{"rendered":"https:\/\/modulus.help\/kb\/?post_type=docs&p=4127"},"modified":"2025-02-25T13:37:50","modified_gmt":"2025-02-25T11:37:50","slug":"api-create-return-receipt","status":"publish","type":"docs","link":"https:\/\/modulus.help\/kb\/docs\/documentation\/invoicing-v1\/api-create-return-receipt\/","title":{"rendered":"API: Create Return Receipt"},"content":{"rendered":"

The purpose of this API is to create new return receipt.<\/p>\n

Request<\/h4>\n\n\n\n\n\n\n\n\n
URL<\/th>\nhttps:\/\/your_account.modulus.biz\/api\/inv\/v1\/Return Receipt?token=YOUR_TOKEN<\/td>\n<\/tr>\n
API Name<\/th>\nReturn Receipt<\/td>\n<\/tr>\n
Method<\/th>\nPOST<\/td>\n<\/tr>\n
Source<\/th>\nThird Party Server<\/td>\n<\/tr>\n
Recipient<\/th>\nmodulus\u00ae Server<\/td>\n<\/tr>\n
Content Type<\/th>\napplication\/json<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

Query String Parameters<\/h4>\n\n\n\n\n\n
Parameter<\/th>\nRequired<\/th>\nType<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
token<\/th>\nYes<\/td>\nText<\/td>\nYour authentication token.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

Payload Parameters<\/h4>\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Parameter<\/th>\nRequired<\/th>\nType<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
customer_details<\/th>\nYes<\/td>\nText<\/td>\nRefers to customer info the return receipt issued to. The structure explained here <\/a>.<\/td>\n<\/tr>\n
branch_code<\/th>\nYes<\/td>\nText<\/td>\nThe code of an active branch.<\/td>\n<\/tr>\n
account_code<\/th>\nYes<\/td>\nText<\/td>\nThe code of the cash account receives the cash amount.<\/td>\n<\/tr>\n
date<\/th>\nYes<\/td>\nDate<\/td>\nDate format must be ISO 8601 (Example: \u201c2020-01-10\u201d).<\/td>\n<\/tr>\n
book_id<\/th>\nYes<\/td>\nNumber<\/td>\nRefers to cash book used for the return receipt.<\/td>\n<\/tr>\n
exchange_rate<\/th>\nNo<\/td>\nDecimal Number<\/td>\nThe exchange rate when the receipt is issued. Mandatory if the customer has foreign currency.<\/td>\n<\/tr>\n
salesperson_id<\/th>\nNo<\/td>\nNumber<\/td>\nRefers to salesperson linked to the branch of this Return Receipt.<\/td>\n<\/tr>\n
reference<\/th>\nNo<\/td>\nText<\/td>\nReturn Receipt reference.<\/td>\n<\/tr>\n
description<\/th>\nNo<\/td>\nText<\/td>\nReturn Receipt description.<\/td>\n<\/tr>\n
items<\/th>\nYes<\/td>\nArray<\/td>\nAn array that contains at least one item. The structure explained here<\/a>.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

Item Parameter Details<\/h4>\n\n\n\n\n\n\n\n\n
Parameter<\/th>\nRequired<\/th>\nType<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
item_code<\/th>\nYes<\/td>\nText<\/td>\nItem code.<\/td>\n<\/tr>\n
unit_id<\/th>\nYes<\/td>\nNumber<\/td>\nRefer to the unit of the sent quantity.<\/td>\n<\/tr>\n
quantity<\/th>\nYes<\/td>\nDecimal<\/td>\nNumber The quantity of the item can not be less than or equal to 0.<\/td>\n<\/tr>\n
unit_price<\/th>\nNo<\/td>\nDecimal<\/td>\nNumber The price of the item. If not sent will defined price in the customer or branch default price list.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

Customer Parameter Details<\/h4>\n\n\n\n\n\n\n\n\n\n\n\n\n
Parameter<\/th>\nRequired<\/th>\nType<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
code<\/td>\nYes<\/td>\nText<\/td>\nThe code of the customer the return receipt issued to.<\/td>\n<\/tr>\n
name<\/td>\nYes<\/td>\nText<\/td>\nThe name of the customer the return receipt issued to.<\/td>\n<\/tr>\n
type<\/td>\nYes<\/td>\nText<\/td>\nThe type of the customer the return receipt issued to. Possible values are: (individual\/organization).<\/td>\n<\/tr>\n
tax_registration_number<\/td>\nNo<\/td>\nNumber<\/td>\nCustomer’s Tax Registration Number.<\/td>\n<\/tr>\n
account_code<\/td>\nNo<\/td>\nText<\/td>\nThe code of the cash account of the customer.<\/td>\n<\/tr>\n
price_list_code<\/td>\nNo<\/td>\nNumber<\/td>\nThe code of the price list of the customer. It must have the same currency as the customer and account.<\/td>\n<\/tr>\n
address<\/td>\nNo<\/td>\nObject<\/td>\nThe address of the customer. The structure explained here<\/a>.<\/td>\n<\/tr>\n
contact<\/td>\nNo<\/td>\nObject<\/td>\nThe contact of the customer. The structure explained here<\/a>.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

Address Parameter Details<\/h4>\n\n\n\n\n\n\n\n\n
Parameter<\/th>\nRequired<\/th>\nType<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
label<\/td>\nYes<\/td>\nText<\/td>\nThe label of the address.<\/td>\n<\/tr>\n
country_code<\/td>\nYes<\/td>\nText<\/td>\nThe country code of the address (Example: “EG”).<\/td>\n<\/tr>\n
city<\/td>\nYes<\/td>\nText<\/td>\nThe name of the city in the specified country.<\/td>\n<\/tr>\n
address<\/td>\nNo<\/td>\nText<\/td>\nAdditional info of the address.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

Contact Parameter Details<\/h4>\n\n\n\n\n\n\n\n
Parameter<\/th>\nRequired<\/th>\nType<\/th>\nDescription<\/th>\n<\/tr>\n<\/thead>\n
type<\/td>\nYes<\/td>\nText<\/td>\nThe type of the contact provided. Possible values are: (mobile\/phone\/email\/fax\/website\/other).<\/td>\n<\/tr>\n
label<\/td>\nYes<\/td>\nText<\/td>\nThe label of the contact.<\/td>\n<\/tr>\n
value<\/td>\nYes<\/td>\nText<\/td>\nThe value of the contact.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n

Responses<\/h4>\n\n\n\n\n\n\n\n\n\n
HTTP Status<\/th>\nresult<\/th>\ntitle<\/th>\nmessage<\/th>\nobject<\/th>\n<\/tr>\n<\/thead>\n
Success Responses<\/th>\n<\/tr>\n
200 OK<\/td>\ntrue<\/td>\nSuccess<\/td>\nReturn Receipt added successfully.<\/td>\n\n
{\n    \"return_receipt_id\": xxx,\n    \"return_receipt_serial\": \"YYYY_ZZZ\",\n    \"document_type\": \"Return Receipt\",\n    \"creation_date_time\": \"yyy-mm-dd hh:MM:ss\"\n}<\/code><\/pre>\n<\/td>\n<\/tr>\n
Failure Responses<\/th>\n<\/tr>\n
400 Bad Request<\/td>\nfalse<\/td>\nError<\/td>\nError message as elaborated here.<\/td>\n\n
{\n    \"error_code\": xxx\n}<\/code><\/pre>\n<\/td>\n<\/tr>\n
500 Internal Server Error<\/td>\nfalse<\/td>\nError<\/td>\nError message as elaborated here.<\/td>\n\n
{\n    \"error_code\": xxx\n}<\/code><\/pre>\n<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
Example 1<\/h4>\n\n\n\n\n
Request<\/th>\n\n
curl --request POST 'https:\/\/your_account.modulus.biz\/api\/inv\/v1\/ReturnReceipt=YOUR_TOKEN' \\\n--header 'Content-Type: application\/json' \\\n--data-raw '{ \n    \"customer_details\": {\n        \"code\": \"1\",\n        \"name\": \"Test name\",\n        \"type\": \"individual\",\n        \"account_code\": \"1.6.10.2\",\n        \"price_list_code\": \"1\",\n        \"tax_registration_number\": \"1\",\n        \"contact\": {\n            \"type\": \"mobile\",\n            \"label\": \"\u0627\u0644\u0642\u0627\u0647\u0631\u0629 \u0627\u0644\u062c\u062f\u064a\u062f\u0629\",\n            \"value\": \"0102224791\"\n        },\n        \"address\": {\n            \"label\": \"HEADOFFICE\",\n            \"country_code\": \"EG\",\n            \"city\": \"Alexandria\",\n            \"address\": \"Test Address\"\n        }\n    },\n    \"account_code\": \"3.6\",\n    \"exchange_rate\": 20,\n    \"branch_code\": \"2\",\n    \"date\": \"2024-01-01\",\n    \"book_id\": 4,\n    \"payment_term_id\": 2,\n    \"items\": [\n        {\n            \"item_code\": \"451\",\n            \"unit_id\": 3,\n            \"quantity\": 50,\n            \"unit_price\": 100\n        }\n    ]\n}'<\/code><\/pre>\n<\/td>\n<\/tr>\n
200 OK<\/th>\n\n
{\n    \"result\": true,\n    \"title\": \"Success\",\n    \"message\": \"Return Receipt added successfully.\",\n    \"object\": {\n        \"return_receipt_id\": 34,\n        \"return_receipt_serial\": \"RCT_2024_01_01_005\",\n        \"document_type\": \"Return Receipt\",\n        \"creation_date_time\": \"2024-01-14 00:09:00\"\n    }\n}<\/code><\/pre>\n<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
Example 2<\/h4>\n\n\n\n\n
Request<\/th>\n\n
curl --request POST 'https:\/\/your_account.modulus.biz\/api\/inv\/v1\/ReturnReceipt=YOUR_TOKEN' \\\n--header 'Content-Type: application\/json' \\\n--data-raw '{ \n    \"customer_details\": {\n        \"code\": \"1\",\n        \"name\": \"Test name\",\n        \"type\": \"individual\",\n        \"account_code\": \"1.6.10.2\",\n        \"price_list_code\": \"1\",\n        \"tax_registration_number\": \"1\",\n        \"contact\": {\n            \"type\": \"mobile\",\n            \"label\": \"\u0627\u0644\u0642\u0627\u0647\u0631\u0629 \u0627\u0644\u062c\u062f\u064a\u062f\u0629\",\n            \"value\": \"0102224791\"\n        },\n        \"address\": {\n            \"label\": \"HEADOFFICE\",\n            \"country_code\": \"EG\",\n            \"city\": \"Alexandria\",\n            \"address\": \"Test Address\"\n        }\n    },\n    \"account_code\": \"3.3.5\",\n    \"exchange_rate\": 20,\n    \"branch_code\": \"2\",\n    \"date\": \"2024-01-01\",\n    \"book_id\": 4,\n    \"payment_term_id\": 2,\n    \"reference\": \"CSH-084\",\n    \"items\": [\n        {\n            \"item_code\": \"6\",\n            \"unit_id\": 2,\n            \"quantity\": 15,\n            \"unit_price\": 40\n        }\n    ]\n}'<\/code><\/pre>\n<\/td>\n<\/tr>\n
400 Bad Request<\/th>\n\n
{\n    \"result\": false,\n    \"title\": \"Error\",\n    \"message\": \"Account currency is different than customer currency.\",\n    \"object\": {\n        \"error_code\": xxx\n    }\n}<\/code><\/pre>\n<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n","protected":false},"featured_media":0,"parent":4104,"menu_order":4,"comment_status":"closed","ping_status":"closed","template":"","doc_tag":[],"comment_count":0,"_links":{"self":[{"href":"https:\/\/modulus.help\/kb\/wp-json\/wp\/v2\/docs\/4127"}],"collection":[{"href":"https:\/\/modulus.help\/kb\/wp-json\/wp\/v2\/docs"}],"about":[{"href":"https:\/\/modulus.help\/kb\/wp-json\/wp\/v2\/types\/docs"}],"replies":[{"embeddable":true,"href":"https:\/\/modulus.help\/kb\/wp-json\/wp\/v2\/comments?post=4127"}],"version-history":[{"count":13,"href":"https:\/\/modulus.help\/kb\/wp-json\/wp\/v2\/docs\/4127\/revisions"}],"predecessor-version":[{"id":4398,"href":"https:\/\/modulus.help\/kb\/wp-json\/wp\/v2\/docs\/4127\/revisions\/4398"}],"up":[{"embeddable":true,"href":"https:\/\/modulus.help\/kb\/wp-json\/wp\/v2\/docs\/4104"}],"next":[{"title":"API: Update Invoice","link":"https:\/\/modulus.help\/kb\/docs\/documentation\/invoicing-v1\/api-update-invoice\/","href":"https:\/\/modulus.help\/kb\/wp-json\/wp\/v2\/docs\/4375"}],"prev":[{"title":"API: Create Collection Receipt","link":"https:\/\/modulus.help\/kb\/docs\/documentation\/invoicing-v1\/api-create-collection-receipt\/","href":"https:\/\/modulus.help\/kb\/wp-json\/wp\/v2\/docs\/4113"}],"wp:attachment":[{"href":"https:\/\/modulus.help\/kb\/wp-json\/wp\/v2\/media?parent=4127"}],"wp:term":[{"taxonomy":"doc_tag","embeddable":true,"href":"https:\/\/modulus.help\/kb\/wp-json\/wp\/v2\/doc_tag?post=4127"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}