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 type | Description |
---|---|
Item | Item 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. |
Bundle | Bundles (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
-
Use dashboard to create a new product item.
-
Sign up and log in the Metaprise dashboard
-
Click 'Product Items' button.
-
Click 'Add New' button and fill the item name, currency, price.
-
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.
-
-
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 17 days ago