#Create New Invoice API

The following endpoint allows merchant to create new invoice in their Fatora Platform account.

https://api.fatora.io/v1/invoices
curl -X POST "https://api.fatora.io/v1/invoices" \
     -H "api_key: E4B73FEE-F492-4607-A38D-852B0EBC91C9" \
     -H "Content-Type: application/json" \
     -d '{
         "number": "INV123",
         "amount": 100.0,
         "currency": "QAR",
         "terms_conditions": "Sample terms and conditions",
         "note": "Sample note",
         "due_date": "2023-10-10T00:00:00Z",
         "date": "2023-09-30T00:00:00Z",
         "status": "paid",
         "type": "detailed",
         "title": "Sample Invoice",         
         "description": "Sample invoice description",
         "client": {
             "name": "Client name",
             "email": "[email protected]",
             "phone": "Phone number",
             "address": "Client address"
         },
         "items": [
             {
                 "product_id": "123",
                 "description": "Item 1",
                 "qty": 2,
                 "amount": 50.0
             },
             {
                "product_id": "456",
                 "description": "Item 2",
                 "qty": 5,
                 "amount": 50.0
             }
         ],
         "payments": [
             {                
                 "payment_date": "2023-10-10T00:00:00Z",
                 "transaction_id": "TXN123",
                 "amount": 50.0, 
                 "note": "Payment received",
                 "payment_type": "credit",
                 "status": "paid
                
             },
             {
                 "payment_date": "2023-10-10T00:00:00Z",
                 "transaction_id": "TXN456",
                 "amount": 50.0,  
                 "note": "Another payment received",
                 "payment_type": "PayPal",
                 "status": "active"                
             }
         ],
         "setting": {             
             "tax": true,
             "discount": 10.0,
             "discount_type": "Percentage",
             "language": "ar",
             "accepted_payment_methods": {
                 "card": true,
                 "bank_account": true,
                 "cash": true,
                 "paypal": true,
                 "e_signature": true
             }
         }
     }'
// Define the API endpoint URL.
$apiUrl = "https://api.fatora.io/v1/invoices";

// Define the API key.
$apiKey = "E4B73FEE-F492-4607-A38D-852B0EBC91C9";

$invoice = [
    "number" => "INV567",
    "amount" => 100.0,
    "currency" => "QAR",
    "terms_conditions" => "Sample terms and conditions",
    "note" => "Sample note",
    "due_date" => date('Y-m-d\TH:i:s\Z', strtotime('+30 days')), // Format the date as required
    "date" => date('Y-m-d\TH:i:s\Z'), // Format the date as required
    "status" => "paid",
    "type" => "detailed",
    "title" => "Sample Invoice",   
    "description" => "Sample invoice description",
    "client" => [
        "name" => "Client name",
        "email" => "[email protected]",
        "phone" => "Phone number",
        "address" => "Client address"
    ],
    "items" => [
        [
            "product_id" => "123",
            "description" => "Item 1",
            "qty" => 2,
            "amount" => 50.0
        ],
        [
            "product_id" => "456",
            "description" => "Item 2",
            "qty" => 5,
            "amount" => 50.0
        ]
    ],
    "payments" => [
        [
            
            "payment_date" => "2023-10-10T00:00:00Z",
            "transaction_id" => "TXN123",
            "amount" => 50.0, 
            "note" => "Payment received",
            "payment_type" => "credit",
            "status" => "paid"
            
        ],
        [
            "payment_date" => "2023-10-10T00:00:00Z",
            "transaction_id" => "TXN456",
            "amount" => 50.0, 
            "note" => "Another payment received",
            "payment_type" => "PayPal",
            "status" => "active
        ]
    ],
    "setting" => [        
        "tax" => true,
        "discount" => 10.0,
        "discount_type" => "Percentage",
        "language" => "ar",
        "accepted_payment_methods" => [
            "card" => true,
            "bank_account" => true,
            "cash" => true,
            "paypal" => true,
            "e_signature" => true
        ]
    ]
];

// Convert the data array to a JSON string.
$jsonPayload = json_encode($invoice);

// Initialize cURL session.
$ch = curl_init();

// Set cURL options.
curl_setopt($ch, CURLOPT_URL, $apiUrl);
curl_setopt($ch, CURLOPT_HTTPHEADER, ["api_key: $apiKey", "Content-Type: application/json"]);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonPayload);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

// Execute the cURL session and capture the response.
$response = curl_exec($ch);

// Check for cURL errors.
if (curl_errno($ch)) {
    echo "cURL Error: " . curl_error($ch);
}

// Close the cURL session.
curl_close($ch);

// Display the response.
echo "API Response: " . $response;
// Define the API endpoint URL.
    string apiUrl = "https://api.fatora.io/v1/invoices";
    // Define the API key.
    string apiKey = "E4B73FEE-F492-4607-A38D-852B0EBC91C9";

    var invoice = new Invoice
    {
        number = "INV567",
        amount = 100.0m,
        currency = "QAR",
        terms_conditions = "Sample terms and conditions",
        note = "Sample note",
        due_date = DateTime.Now.AddDays(30),
        date = DateTime.Now,
        status = "paid",
        type = "detailed",
        title = "Sample Invoice",       
        description = "Sample invoice description",
        
    };

    invoice.client = new Client
    {
        name = "Client name",
        email = "[email protected]",
        phone = "Phone number",
        address = "Client address"
    };
    // Populate items
    invoice.items = new List
    {
        new InvocieItem
        {   
            "product_id" => "123",                 
            description = "Item 1",
            qty = 2,
            amount = 50.0m
        },
        new InvocieItem
        {   
            "product_id" => "456",                
            description = "Item 2",
            qty = 5,
            amount = 50.0m
        }
    };

    // Populate payments
    invoice.payments = new List
    {
        new InvoicePayment
        {
           
            payment_date = "2023-10-10",
            transaction_id = "TXN123",
            amount = 50.0m, 
            note = "Payment received",
            payment_type = "credit",
            status = "paid"
        },
        new InvoicePayment
        {
            
            payment_date = "2023-10-10",
            transaction_id = "TXN456",
            amount = 50.0m,
            note = "Another payment received",
            payment_type = "PayPal",
            status = "active"            
        }
    };

    // Populate setting
    invoice.setting = new InvoiceSetting
    {       
        tax = true,
        discount = 10.0m,
        discount_type = "Percentage",
        language = "ar",
        accepted_payment_methods = new PaymentMethod
        {
            card = true,
            bank_account = true,
            cash = true,
            paypal = true,
            e_signature = true
        }
    };

    // Serialize the Product object to JSON.
    string jsonPayload = JsonConvert.SerializeObject(invoice);

    // Create a WebRequest.
    HttpWebRequest request = (HttpWebRequest)WebRequest.Create(apiUrl);

    // Set the request method to POST.
    request.Method = "POST";

    // Set the API key header.
    request.Headers.Add("api_key", apiKey);

    // Set the request content type.
    request.ContentType = "application/json";

    // Convert the JSON payload to bytes.
    byte[] data = Encoding.UTF8.GetBytes(jsonPayload);

    // Set the content length.
    request.ContentLength = data.Length;

    // Get the request stream and write the JSON data to it.
    using (var stream = request.GetRequestStream())
    {
        stream.Write(data, 0, data.Length);
    }

    try
    {
        // Get the response.
        using (HttpWebResponse response = (HttpWebResponse)request.GetResponse())
        {
            if (response.StatusCode == HttpStatusCode.Created)
            {
                // Read the response data.
                using (var responseStream = response.GetResponseStream())
                using (var reader = new StreamReader(responseStream))
                {
                    string responseContent = reader.ReadToEnd();
                    Console.WriteLine("API Response: " + responseContent);
                }
            }
            else
            {
                Console.WriteLine("API Request failed with status code: " + response.StatusCode);
            }
        }
    }
    catch (WebException ex)
    {
        Console.WriteLine("API Request failed with an exception: " + ex.Message);
    }
{
"status": "SUCCESS",
"invoice": {
"id": 2075,
"number": "INV567",
"currency": "QAR",
"terms_conditions": "Sample terms and conditions",
"note": null,
"due_date": "2023-11-23T10:21:04",
"date": "2023-10-24T10:21:00.9047758+02:00",
"status": "paid",
"type": "Detailed invoice",
"client": {
    "id": 1307,
    "name": "Client name",
    "address": "Client address",
    "phone": "Phone number",
    "email": "[email protected]",
    "notes": null
},
"title": "Sample Invoice",
"items": [
    {
        "id": 2376,
        "product_id" : 123,
        "description": "Sample invoice description",
        "type": "Service Item",       
        "qty": 1.0,
        "amount": 50.0
    },
    {
        "id": 8796,
        "product_id" : 456,
        "description": "Sample invoice description",
        "type": "Service Item",       
        "qty": 1.0,
        "amount": 50.0
    }
],
"payments": [
    {
        "id": 942,
        "payment_date": "2023-10-10T00:00:00",
        "transaction_id": "TXN123",
        "amount": 50.0,
        "note": "external",
        "payment_type": "Credit",
        "status": "Paid"
    },
    {
        "id": 943,
        "payment_date": "2023-10-10T00:00:00", 
        "transaction_id": "TXN456",
        "amount": 50.0,
        "note": "external",
        "payment_type": "PayPal",
        "status": "Paid"
    }
],
"setting": {   
    "tax": true,
    "discount": 0.0,
    "discount_type": "",
    "language": "ar",
    "accepted_payment_methods": {
        "card": true,
        "bank_account": true,
        "cash": true,
        "paypal": true,
        "e_signature": true
    }
}
}
}

Try it now: Add Invoice API

Header Parameters

Header Value
api_key REQUIRED Use the valid API key of your Fatora account. Read more information about Authentication.
Content-Type REQUIRED application/json

Request Parameters

Parameter Description
title OPTIONAL string The title or name of the invoice.
description REQUIREDIF: items are not set string A description of the invoice.
amount REQUIREDIF: items are not set decimal The total amount of the invoice.
date OPTIONAL string The date of the invoice.
status OPTIONAL string The status of the invoice, The possible values are:" ["sent", "paid", "void", or "refund."]. by default it is sent.
- If the status of the invoice is set to "paid," a list of payments (payments) must be provided.
- The amount in the payment details must be equal to the sum of amounts for all items in the invoice.
number OPTIONAL string A unique identifier for the invoice.
currency OPTIONAL string The currency used for the invoice. Verify that the 'currency' value is a valid ISO currency code, and ensure that the specified 'currency' is supported by your account. If the provided currency is not in the list of currencies associated with your account, the API request will return a Bad Request error.
client OPTIONAL object An object representing the client's details. It should have the following properties:
  • name (string): The client's name.
  • email (required, string): The client's email address.
  • phone (string): The client's phone number.
  • address (string): The client's address.
When providing client details within the 'invoice' object, ensure that the client information is properly updated, if needed, during the API request.
note OPTIONAL string Additional notes related to the invoice.
type OPTIONAL string The accepted value for the type of the invoice is "detailed". Use this value to create a detailed invoice. If the 'type' is not set to 'detailed,' the API request will return a Bad Request error.
terms_conditions OPTIONAL string Terms and conditions associated with the invoice.
items REQUIREDIF: description and invoice amount are not set array A list of invoice items. each representing a item for the invoice. Each item object should have the following properties:
  • product_id (string): The id of product in the store.
  • description (string): The description or name of the item.
  • qty (decimal): The quantity of the item. Must be a non-negative decimal value.
  • amount (required, decimal): The amount or price of the item. Must be a non-negative decimal value.
payments REQUIREDIF: status of invoice is set to paid or refund array A list of payment objects, each representing a payment for the invoice. Each payment object should have the following properties:
  • payment_date (required, DateTime): The date of the payment.
  • transaction_id (string): The transaction ID associated with the payment.
  • amount (required, decimal): The payment amount.
  • note (string): Additional notes or description of the payment.
  • payment_type (string): The type of payment, e.g., "credit," "cash," "PayPal," etc. by default it is cash
  • status (string): The status of the payment, which can be "paid," "active," or "refund." by default it is paid
setting OPTIONAL object an object representing the settings for an invoice. It should have the following properties:
  • tax (boolean): Indicates if taxes are applied to the invoice. by defualt it is false
  • discount (decimal): The discount applied to the invoice. Must be a decimal value between 1 and 99 (representing a percentage). by defualt it is 0.0
  • discount_type (string): The type of discount. It should be one of the following: "percentage or fixed. by default it is "fixed".
  • language (string): The language of the invoice. Should be either "ar" for Arabic or "en" for English. by defualt it is "ar"
  • accepted_payment_methods (object): An object representing the accepted payment methods for the invoice. It should have the following properties:
    • card (boolean): Indicates if credit card payments are accepted. If 'card' is set to 'true' and card payments are not supported by your account the API call will return a Bad Request error.
    • bank_account (boolean): Indicates if bank account payments are accepted.
    • cash (boolean): Indicates if cash payments are accepted.
    • paypal (boolean): Indicates if PayPal payments are accepted. If 'paypal' is set to 'true' and card payments are not supported by your account the API call will return a Bad Request error.
    • e_signature (boolean): Indicates if electronic signatures for payments are accepted. by defualt it is false

Response

Response Schema: application/json
status string the status of response.
SUCCESS
invoice object:
  • id: int The id of the invoice
  • number: string The invoice number
  • amount: decimal The total amount of the invoice
  • currency: string The currency used for the invoice
  • terms_conditions: string The terms and conditions associated with the invoice
  • note: string Additional notes for the invoice
  • due_date: datetime The due date of the invoice
  • date: datetime The date of the invoice
  • status: string The status of the invoice
  • type: string The type of the invoice
  • client: object
    • id: int The client's unique identifier
    • name: string The client's name
    • address: string The client's address
    • phone: string The client's phone number
    • email: string The client's email address
    • notes: string (null) Additional notes for the client
  • title: string The title of the invoice
  • link: string The URL link to the invoice
  • description: string (null) The description of the invoice
  • items: array of objects
    • id: int The unique identifier for each item
    • product_id: int The unique identifier for product
    • description: string The description of the item
    • type: string The type of item (e.g., 'Service Item')
    • qty: decimal The quantity of the item
    • amount: decimal The amount for the item
  • payments: array of objects
    • id: int The unique identifier for each payment
    • payment_date: datetime The date of the payment
    • transaction_id: string The transaction ID associated with the payment
    • amount: decimal The amount of the payment
    • note: string Additional notes for the payment
    • payment_type: string The payment type (e.g., 'Credit','Cash')
    • status: string The status of the payment
  • setting: object
    • tax: bool Indicates whether tax is applicable
    • discount: decimal The discount amount
    • discount_type: string The type of discount (e.g., 'Percentage', 'fixed')
    • language: string The language for the invoice (e.g., 'ar', 'en')
    • accepted_payment_methods: object
      • card: bool Indicates if credit card payments are accepted
      • bank_account: bool Indicates if bank account payments are accepted
      • cash: bool Indicates if cash payments are accepted
      • paypal: bool Indicates if PayPal payments are accepted
      • e_signature: bool Indicates if electronic signatures for payments are accepted

Otherwise if there was a problem with your request, you'll receive an error response such as 400 status code, and the response will include an error object describing why this request failed.

Response Schema: application/json
status string The status of response.
error object:
  • error_code string, the naumber of error: e.g: 400, For more information
    see Response Code
  • description string, the description of error: e.g: bad request
technical-support

🛠️ Technical Support