Guides
RoadmapAPI StatusChangelog

Product Item

Learn how to use the Product Item resource with Metaprise Invoicing.

Overview

Product Items are the 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.

Items appear as lines on sales forms. Each unique item gets a line with its name, description, quantity, and cost per item. That’s why items are sometimes called 'line items'.



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.


Item operation

The item type determines if and how an item is tracked in Metaprise. There are four basic item types: inventory, non-inventory, services, and bundles.


Item typeDescription
ItemItem are products a business sells and wants to track the quantity of. Typically, a business creates or buys these items, holds them “in stock,” and then sells them to customers. Metaprise tracks inventory so users can quickly check the quantity on hand, the cost of goods sold, and the inventory’s total value.
BundleBundles (also known as “groups”), represent a unique group of items bundled together.

For example, you can set up a bundle with 5 apples, 5 oranges, and 5 pineapples and call it a “fruit basket” bundle. The bundle becomes a single item that contains other items.

Bundles can’t contain other bundles.
Bundles can’t contain categories.
An item can be listed more than once with same or different quantities.
Bundles can be added to transactions.

Create a new Product Item

  1. Use dashboard to create a new product item.

    1. Sign up and log in the Metaprise dashboard

    2. Click 'Product Items' button.

    3. Click 'Add New' button and fill the item name, currency, price.

    4. You can also edit/delete an existing item. For bundle, the price is not editable as the price is calculated automatically with underlining items' price.

  2. Use API to create a new product item.

    By default, the subtotal and total fields of line items are automatically calculated based on the unit_price, quantity, and tax fields, therefore, are read-only and appear only in the response schema.

    Add line items to a payable

    To add line items to an invoice, send a POST request to the /payables/{payable_id}/line_items endpoint: 

    curl -X POST 'https://api.sandbox.metaprise.com/v1/payables/{payable_id}/line_items' \
     -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 '{
        "name": "Ice cream",
        "description": "A delicious vanilla ice cream",
        "quantity": 1,
        "unit": "unit",
        "unit_price": 1200,
        "tax": 1250,
        "ledger_account_id": "7df884fd-8be8-4eba-b6ff-417b66efe033",
        "accounting_tax_rate_id": "dd13735f-ef3a-4312-8c37-835d70341375"
      }'

    The successful response contains information about the created line item: 

{
    "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": "", 
    }
}

List all line items of a payable

To list all line items of a specific invoice, send a GET request to the /payables/{payable_id}/line_items endpoint:

curl GET 'https://api.sandbox.metaprise.com/v1/payables/{payable_id}/line_items' \
     -H 'X-Metaprise-Version: 2024-01-31' \
     -H 'X-Metaprise-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN'

You will get a list of all line items present in the informed invoice: 

{
    "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": "", 
    }
}

Retrieve a line item

To retrieve information from a specific line item in an invoice, send a GET request to the /payables/{payable_id}/line_items/{line_item_id} endpoint: 

curl -X GET 'https://api.sandbox.metaprise.com/v1/payables/{payable_id}/line_items/{line_item_id}' \
     -H 'X-Metaprise-Version: 2024-01-31' \
     -H 'X-Metaprise-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN'

Update a specific line item

To update some information about a specific line item in an invoice, send a PATCH request to the /payables/{payable_id}/line_items/{line_item_id} endpoint: 

curl -X PATCH 'https://api.sandbox.metaprise.com/v1/payables/{payable_id}/line_items/{line_item_id}' \
     -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 '{"name": "Double ice cream"}'

Remove a line item

To remove the line item from the invoice, send a DELETE request to the /payables/{payable_id}/line_items/{line_item_id} endpoint:

curl -X DELETE 'https://api.sandbox.metaprise.com/v1/payables/{payable_id}/line_items/{line_item_id}`' \
     -H 'X-Metaprise-Version: 2024-01-31' \
     -H 'X-Metaprise-Entity-Id: ENTITY_ID' \
     -H 'Authorization: Bearer YOUR_PARTNER_TOKEN'

Updated 2 months ago