Edit Invoices

In this manual, we'll guide you through Editing a previous created invoice. You'll learn about the necessary parameters required for the request and all the optional parameters available. We strongly recommend reviewing theInvoice Payment Page | Payment Workflowmanual first to understand the business logic behind this integration and how you can first craete your invoices.
Finally, and once you have already created your invoice, you can follow the guide mentioned here to be able edit this invoice using our APIs

---

Limitations

• Only Pending Invoices: - Invoices can be edited only if they are in the "pending" status. Once an invoice is marked as paid or canceled, it becomes locked and cannot be edited.


• Dashboard-Created Invoices: Invoices manually generated through the PayTabs dashboard are not editable via API.


• Invoice Edit Disabled: If the invoice was created with the disable_edit parameter set to true, it cannot be edited via API or dashboard.


• Invoice Created via Payment Endpoint: Invoices generated through a payment request using the /payment/request endpoint (as opposed to the standard invoice creation endpoint /payment/invoice/new) are not editable, regardless of the disable_edit parameter.


• Invoice Linked to an Agreement (Repeat Billing): - Invoices linked to agreements (repeat billing or subscriptions) are non-editable.


• ZATCA v2 Cleared Invoices: ZATCA v.2-compliant invoices that have been cleared are automatically locked and cannot be modified.
  Kindly note

  ZATCA (Zakat, Tax and Customs Authority) invoices are applicable only within Saudi Arabia via KSA endpoints, in accordance with local tax regulations.


• Credit Note Invoices: Invoices issued as credit notes are not eligible for editing.

---

The Endpoint and Related Postman Collection

In this section, we will rely on the PayTabs Invoice Payment Page edit API Endpoint, mentioned on PayTabs API endpoints postman collection, which you can access from po_link. The endpoint will need to be accessed with a POST request on the below-mentioned URL

POST	{{domain}}/payment/invoice/<invoiceID>/edit

Be Aware Of

Please note that not using the proper endpoint URL {domain} will lead to authentication issues within your responses. To find the your proper domain you can read ourWhat is my (Region)/(endpoint URL)?tutorial article.

KSA

https://secure.paytabs.sa/payment/invoice/<invoiceID>/edit

UAE

https://secure.paytabs.com/payment/invoice/<invoiceID>/edit

Egypt

https://secure-egypt.paytabs.com/payment/invoice/<invoiceID>/edit

Oman

https://secure-oman.paytabs.com/payment/invoice/<invoiceID>/edit

Jordan

https://secure-jordan.paytabs.com/payment/invoice/<invoiceID>/edit

Kuwait

https://secure-kuwait.paytabs.com/payment/invoice/<invoiceID>/edit

Global

https://secure-global.paytabs.com/payment/invoice/<invoiceID>/edit

---

The Minimum Required Parameters

To edit/update a pending invoice at least you need to provide the following parameter within your request payload along with the parameter/s you want to update if note included:

{
    "profile_id": 180###,
    "tran_type": "sale",
    "tran_class": "ecom",
    "cart_currency": "SAR",
    "cart_amount": "666",
    "cart_id": "CART#1001",
    "cart_description": "Description of the invoice items/services",
    "invoice": {
        "line_items": [
            {
                "quantity": 1,
                "unit_cost": 666
            }
        ]
    }
}

---

Sample Request Payloads

The below sample request payload will show you how you can pass the above-mentioned parameters, which are needed to be passed with valid values to perform a request and update the invoice reference code:

Make sure you are using the valid invoice ID within the endpoint as shown below, along with the authorization details:

{
    "profile_id": 1801##,
    "tran_type": "sale",
    "tran_class": "ecom",
    "cart_description": "Description of the items/services",
    "cart_id": "Unique order reference00",
    "cart_amount": 100,
    "cart_currency": "SAR",
    "invoice": {
        "ref": "The Invoice Reference code",
      "line_items": [
          {
              "unit_cost": 100,
              "quantity":2
          }
      ]
    }
}

---

Sample Response Payloads

{
    "invoiceID": 3126###,
    "status": "invoice updated successfully",
    "trace": "PMNT0401.674DB9E5.000BBE4C"
}

---

Expected Flow Behavior

Reaching this point, you already should have an pending invoice that you want to update:

1. As we mentioned above you will use the required parameters along with desired parameters that needs to be updated if not included [Sample].
2. If the invoice is pending, then the invoice reference will updated and you will get a success response.
3. In case, the invoice is not editable like its status is Cancelled, Overdue, or Paid, you will get 400 Bad Request invalid request:

{
    "code": 1,
    "message": "Invoice is not editable",
    "trace": "PMNT0401.674E9C9B.000D1AC0"
}