Guides
RoadmapAPI StatusChangelog

Invoice

Create and manage invoices for one-time payments with Metaprise Invoicing.

Overview

The Invoice object represents products and/or services purchased by a Customer from your Organization. In addition to creating invoices, you can attach invoice images or related documents.


Before you begin

Sign up the Metaprise developer devhub platform to get your unique Client ID and API key.
Obtain your access token by authenticating to Metaprise using your unique Client ID and API key. You will need the access token to make API calls.
Set up webhooks to receive notifications on Global Account events.


Invoice operations

The invoice operations API provides a wide range of services.


Invoice AttributesDescription
From EmailThe email addresses from which the clients send customer emails. Clients can use these addresses as the 'From' addresses.
CustomerA business or individual that consumes goods or services from your Organization.
Payment TermsOutline the expected timeline and conditions for customers to submit payment for goods or services rendered
Due DateThe specific date by which the customer must submit payment for the goods or services provided. This date is a crucial element of the overall invoice payment terms.
ItemThe products and services a business buys and sells. Users enter and track items in Metaprise so they can quickly add them to invoices and other sales forms.
TaxTax Rate represents rate applied to calculate tax liability. Use the TaxService entity to create a taxrate. See Global tax model for more information about using TaxRate objects and the tax model in general
Invoice TemplateThe basic invoice template used to send to the customers, clients could also customize the template based on their business demand.
Email TemplateThe basic email template used to send to the customers, clients could also customize the template based on their business demand.


Create a new Invoice


  1. Use dashboard to create a new invoice.

    1. Sign up and log in the Metaprise dashboard

    2. Click 'Create Invoice' button.

    3. Fill the required information based on Invoice operation table.

    4. Select Invoice and Email templates, send payment request to clients.

    5. Clients could also customize the invoice and email template with their own logo and format.

  2. Use API to create a new invoice.

    1. Create a customer who need pay this invoice.
    2. Create one or moreproduct itemsto be listed in the invoice.
    3. Get the applicable Tax Rates based on the entity’s country and the counterpart’s country, and choose the rates for the products that will be listed in the invoice.
    4. Create the invoice, call POST /receivables and provide the quote ID in the based_on field in the request body: 
      curl -X POST 'https://api.sandbox.metaprise.com/v1/receivables' \
     -H 'X-Metaprise-Version: 2024-01-31' \
     -H 'X-Metaprise-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "type": "invoice",
       "based_on": "e9a25ceb-003d-4c82-9e90-5d568ccd8c47"
     }'

The request above creates a new draft invoice with a copy of the quote data (that is, with the same line items and counterpart). The ID and document number of the original quote are saved in the based_on and based_on_document_id properties, respectively:

{
    "result": "success",
    "data": {
        "uid": "12217",
        "customer_id": "12217",
        "customer_name": "Fantastic Juicy",
        "invoice_no": "100000006028",
        "recurring_no": "100000006029",
        "invoice_template": "Pay Invoice",
        "sales_rep": "Alex Yang",
        "po_no": "100000006029",
        "tax_id": "1221",
        "tax_rate": "10%",
        "sub_total_1": "78.00",
        "sub_total_2": "78.00",
        "tax": "13.26",
        "total": "91.26",
        "msg_to_customer": "Please pay the invoice within 30 days",
        "send_from": "[email protected]", 
        "send_to": "[email protected]",
        "send_cc": " ",
        "send_subject": "Invoice-Notice",
        "ready_to_send": "true",
        "sent_status": "sent",
        "payment_status": "Not paid",  
        "payment_total": "91.26",  
        "payment_type": " ", 
        "payment_term": "Net 15", 
        "payment_date": "2015-10-06T10:50:42-07:00", 
        "invoice_date": "2015-10-06T10:50:42-07:00", 
        "sent_date": "2015-10-06T10:50:42-07:00", 
        "due_date": "2015-10-06T10:50:42-07:00", 
        "is_equal": "true", 
        "currency": "usd",   
        "attach": "",   
        "send_result": "",   
        "result_msg": "",  
        "quickbook_sync": "true
        "create_at": "2015-10-06T10:50:42-07:00",  
        "update_at": "2015-10-06T10:50:42-07:00",      
        "transaction_id": "Q240822154005791698",    
        "card_type": "",     
        "st_ticket_id_refund_1": "",     
        "st_ticket_id_refund_2": "",   
        "refund_total": "",  
        "refund_date": "2015-10-06T10:50:42-07:00",   
        "reference": "",   
        "send_from_email": "",   
        "template_id": "",   
        "pdf_url": "",   
        "source": "Metaprise",
        "quickbook_id": "", 
    }
}

Update an invoice

All newly created invoices start in the draft status. You can edit draft invoices before issuing them to a counterpart.

To edit a draft invoice, send a PATCH request to the /receivables/{receivable_id} endpoint with the request body containing the updated properties. You can update counterpart data, payment terms, invoice memo, existing line items data, and other details.

curl -X PATCH 'https://api.sandbox.metaprise.com/v1/receivables/411dc6eb...6289b3' \
     -H 'X-Metaprise-Version: 2024-01-31' \
     -H 'X-Metaprise-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "invoice": {
         "currency": "USD",
         "counterpart_id": "782b6f0f-0177-475c-b1e4-98dc160a656f",
         "counterpart_billing_address_id": "796d1f1d-f345-4888-849c-6cbcfbd39982",
         "payment_terms_id": "f7c577590-2680-462a-a2b4-7c564f65449d",
         "entity_vat_id_id": "96d1f1df7b7-462a-4888-98dc160a656f6d",
         "entity_bank_account_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
         "entity": {
            "logo": "https://new-entity-logo.com/icon-192x192.png",
            "email": "[email protected]"
          }
        }
     }'

Updated about 1 month ago