# MakeLeaps API Documentation - Document Section ## Navigation - [Back to index](/api/llms.txt) - [Current section](/api/llms/document.md) ## Topics in this Section - Documents - Line Items - Line Item Catalog - Document Templates - Document Archive - Document Pickup Link ## Documents ### Endpoints - `/api/partner//document/` - Name: Document List - Methods: GET, POST, OPTIONS - `/api/partner//document//` - Name: Document Instance - Methods: GET, PUT, PATCH, DELETE, OPTIONS Documents --------- Documents are the heart of our system. They are created by users and sent to Clients using one or more of MakeLeaps' Sending Methods. Document Types -------------- The following document types are available. Depending on your company's current setup, some might not be available to you: - `order` for orders - `quote` for quotes - `orderslip` for order slips - `orderconfirmation` for order confirmations - `deliveryslip` for delivery slips - `acceptance` for acceptance certificates - `invoice` for invoices - `receipt` for receipts - `timesheet` for timesheets Document Templates ------------------ See "Document Templates" section for more details. Autocalculate Document Subtotal, Tax, etc. ------------------ When creating and updating documents, you can enable autocalculation to calculate the following "autocalculated fields" automatically. Do NOT specify any of these fields when autocalculation is on. - Document fields - `total` - `subtotal` - `tax` - `jp_withholding_tax` - `subtotal_sales_tax` - `subtotal_withholding_tax` - `mixed_tax_rate_totals` OR `tax_group_totals` - Line Item fields - `price` on normal type Line Items To use autocalculate, set the Document's `autocalculate` to `true` and then specify the following for each line item: - for Templates that do NOT support Advanced Tax Types: `tax_rate` - for Templates that do support Advanced Tax Types: `tax_type` and `tax_rate` Not using autocalculate: legacy tax types ------------------------------- Note: the following applies to use of Document Templates that do NOT support Advanced Tax Types. For other Templates, see "Not using autocalculate: advanced tax types" section. To specify Document Subtotal/Tax for different tax rates, set the Document's `autocalculate` to `false` and then specify the following: - for Document - `mixed_tax_rate_totals` - all other relevant "autocalculated fields" - for all Line Items: - `tax_rate` - `price` The `mixed_tax_rate_totals` field contains a nested dictionary, where each tax rate key contains Money fields for the rate's `subtotal` and `tax`. Example JSON for `mixed_tax_rate_totals` with different tax rates: { "mixed_tax_rate_totals": { "8": { "subtotal": {"amount": "10000", "currency": "JPY"}, "tax": {"amount": "800", "currency": "JPY"} }, "10": { "subtotal": {"amount": "10000", "currency": "JPY"}, "tax": {"amount": "1000", "currency": "JPY"} } } } Not using autocalculate: advanced tax types ---------------------- Note: the following applies to use of Document Templates that support Advanced Tax Types. For other Templates, see "Not using autocalculate: legacy tax types" section. To specify Document Subtotal/Tax for different tax types/rates, set the Document's `autocalculate` to `false` and then specify the following: - for all Line Items: - `tax_type` - `tax_rate` - `price` - for Document - `tax_group_totals` - all other relevant "autocalculated fields" The `tax_group_totals` field contains a nested dictionary, where each tax type/tax rate key contains Money fields for the corresponding `subtotal` and `tax`. Example JSON for `tax_group_totals` with different tax types and tax rates: { "tax_group_totals": [ { "tax_type": "standard", "tax_rate": "10", "currency": "JPY", "subtotal": "10000", "tax": "800" }, { "tax_type": "reduced", "tax_rate": "8", "currency": "JPY", "subtotal": "10000", "tax": "800" }, { "tax_type": "non_taxable", "tax_rate": "0", "currency": "JPY", "subtotal": "10000", "tax": "800" } ] } Group Line Items by Tax Rates ---------------------- By setting `group_lineitem_by_tax_rate` field to `true`, the template: - groups all line items of the same tax setting into separate line item tables (see below for details). - outputs taxes and subtotals for the relevant line item table directly under that table. Notes: - This feature only applies to Document Templates that support output of multiple tax rates and User-defined Templates. - When `group_lineitem_by_tax_rate` is `false`, line items are output in one large line item table per their `position` value. How the line item grouping is done depends on the Template: - for Templates that do NOT support Advanced Tax Types: items grouped by tax rates. - for Templates that DO support Advanced Tax Types: items grouped by their tax type/tax rate. Document Tax Rounding ---------------------- Notes: - The `round_tax_down` field is deprecated. Please use `tax_rounding` instead. The `tax_rounding` and `round_tax_down` fields cannot be specified simultaneously in the request body since they control the same setting. Whether you specify `tax_rounding` or `round_tax_down`, the two fields will always remain synchronized as follows: Setting `tax_rounding` to - `round_down`: `round_tax_down` gets set to `true`. - `round_up`: `round_tax_down` gets set to `false`. - `standard_rounding`: `round_tax_down` gets set to `false`. Setting `round_tax_down` to - `true`: `tax_rounding` gets set to `round_down`. - `false`: `tax_rounding` gets set to `standard_rounding`. Document Extended Data ---------------------- Additional data can be stored on a Document by specifying the `extended_data` dictionary. The keys that can be used in the `extended_data` dictionary depend on the selected Document Template. If a particular field is not on the chosen template, an error will be returned by the API. Setup: In order to store data in Extended Data Fields (`extended_data`) on a Document, you must specify an Document Template that references those Extended Data Fields, such as the following: MakeLeaps' Client Balance Templates (codes end with `client_balance`) support the following Document Extended Data Fields. - `ml_amount_to_pay` - `ml_carryover` - `ml_adjustment` - `ml_last_paid_amount` - `ml_last_invoice_amount` User-Defined Templates can be created referencing the above Extended Data Fields or your own custom fields. A User-Defined Template must be _published_ before you can use it to make a Document. You can learn more about User-Defined Templates and creating custom Extended Data Fields in the [MakeLeaps Help Center][makeleaps_help_center]. [makeleaps_help_center]: https://help.makeleaps.jp/ja/collections/3609246-ml-ml4sf-%E3%82%AB%E3%82%B9%E3%82%BF%E3%83%A0%E3%83%86%E3%83%B3%E3%83%97%E3%83%AC%E3%83%BC%E3%83%88 The structure of the `extended_data` dictionary is as follows, where `key1`, `key2`, etc are the "Keys" defined for each Extended Data Field, and the `` etc is the value you wish to store for the Field. (See below about how to set values for different Fields with different Data Types.) "extended_data": { "key1": , "key2": , ... } Other notes: - The combined length of keys and values set to the extended_data dictionary must not exceed 600 characters (double-byte characters also count as 1 character). - Since the number of Document Extended Data Fields that can be used on a template is limited to 10, you cannot have more than 10 keys in the `extended_fields` dictionary. - Extended Data Field input is not mandatory, so failure to provide values for some or all the Extended Data Fields that exist on the Document Template will not result in an error. How to pass values for different Data Types: - Money type field: requires a valid money dictionary containing `amount` and `currency` keys specified with string literal values. Note that the value for `currency` (e.g. "JPY") must match the Document's currency. `{ "amount": "1000", "currency": "JPY" }` - Date type field: the value must be a in a valid date format, and should not include time. Please refer to the [Dates and Times section][dates_and_times_section] on how to pass a date in the correct format. [dates_and_times_section]: https://app.makeleaps.com/api/#dates-and-times - Text type field: the value must be string literal. String must be no more than 40 characters in length. `{ "note": "MX-0001239", }` Example JSON for handling additional data via the `extended_data` field, using a Client Balance template and the MakeLeaps pre-loaded Extended Data Fields. { "document_template": "ja_JP_pro_4_windowed_client_balance", "extended_data": { "ml_last_invoice_amount": {"currency": "JPY", "amount": "10000"}, "ml_last_paid_amount": {"currency": "JPY", "amount": "9000"}, "ml_adjustment": {"currency": "JPY", "amount": "1000"}, "ml_amount_to_pay": {"currency": "JPY", "amount": "1000"} } } Tax Registration Number ---------------------- `partner_tax_registration_number` can be set as follows: New Documents (`POST`): if `partner_tax_registration_number` key is: - included in the request, it must match the Partner's current tax_registration_number (`""` (blank string) if Partner's `tax_registration_number` is empty) - omitted from the request, the Partner's current `tax_registration_number` will automatically be applied. Existing Documents (`PUT`, `PATCH`): if `partner_tax_registration_number` key is - included in the request, it must match either of the following: - the current Partner's `tax_registration_number` (`""` (blank string) if Partner's `tax_registration_number` is empty) - the existing Document's `partner_tax_registration_number` - omitted from the request, the Document's current `partner_tax_registration_number` will be maintained. `client_tax_registration_number` behaves similarly to `partner_tax_registration_number`. Please substitute 'Your Company' with 'Client' and `partner_tax_registration_number` with `client_tax_registration_number`. Marking Dates on a Document ------------------ When updating a document, it is possible to mark it through the API by specifying the following dates. If these dates are specified at Document creation, the values are ignored and not saved to the Document. - `date_paid`: to mark as paid - `date_cancelled`: to mark as cancelled - `date_sent`: to mark as sent - `date_confirmed`: to mark as confirmed - `date_accepted`: to mark as accepted Please refer to the [Dates and Times section][dates_and_times_section] on how to pass a date in the correct format. [dates_and_times_section]: https://app.makeleaps.com/api/#dates-and-times Example JSON to mark a document as paid: { "date_paid": "2018-03-30T12:00:00+09:00" } Passing a null date will unmark a document if it has been marked previously. For example, to unmark as paid: { "date_paid": null } Depending on the document type, the date might not be supported, in that case the API will produce an error. Here's a list of the current supported dates by document types: - Order: `date_sent`, `date_cancelled`, `date_valid` - Quote: `date_sent`, `date_cancelled`, `date_paid`, `date_accepted`, `date_valid` - Order Slip: `date_sent`, `date_cancelled`, `date_paid`, `date_accepted`, `date_paid` - Order Confirmation: `date_sent`, `date_cancelled` - Timesheet: `date_sent`, `date_cancelled` - Delivery Slips: `date_sent`, `date_cancelled`, `date_shipped` - Acceptance Certificate: `date_sent`, `date_cancelled`, `date_confirmed` - Payment Notice: `date_sent`, `date_cancelled`, `payment_date` - Invoice: `date_sent`, `date_cancelled`, `date_paid`, `date_due` - Receipts: `date_sent`, `date_cancelled` ### Fields - **`document_number`** - **Type**: `String` - **Description**: Document Number - **`document_type`** `Required` - **Type**: `Document Type` - **Description**: Document Type - **`title`** - **Type**: `String` - **Description**: Title - **`project_name`** - **Type**: `String` - **Description**: Project - **`bank_details_header`** - **Type**: `String` - **Description**: Bank Details Header - **`bank_details`** - **Type**: `String` - **Description**: Bank Details - **`message`** - **Type**: `String` - **Description**: Message - **`proviso`** - **Type**: `String` - **Description**: Proviso - **`group_lineitem_by_tax_rate`** - **Type**: `Boolean` - **Description**: Group line items by tax rate - **`has_hanko`** - **Type**: `Boolean` - **Description**: Display Hanko on this document - **`has_prices`** - **Type**: `Boolean` - **Description**: Display prices on this document - **`has_totals`** - **Type**: `Boolean` - **Description**: Display totals on this document - **`has_currency_code`** - **Type**: `Boolean` - **Description**: Display the currency code on this document - **`has_lineitem_tax_state`** - **Type**: `Boolean` - **Description**: Show the tax state for each line item on this document - **`show_lineitem_tax_rate`** - **Type**: `Boolean` - **Description**: Display tax type on each line item - **`show_lineitem_tax_state`** - **Type**: `Boolean` - **Description**: Display tax rate on each line item - **`show_lineitem_tax_type`** - **Type**: `Boolean` - **Description**: Display tax exclusive/inclusive on each line item - **`signature`** - **Type**: `Boolean` - **Description**: Show signature field - **`display_tax_rate`** - **Type**: `Boolean` - **Description**: Display document tax rate - **`hide_tax_description`** - **Type**: `Boolean` - **Description**: Hide alternate tax description - **`has_tax_stamp`** - **Type**: `Boolean` - **Description**: Show tax stamp - **`currency`** `Required` - **Type**: `Currency` - **Description**: Currency - **`subtotal`** - **Type**: `Money` - **Description**: Subtotal - **`tax`** - **Type**: `Money` - **Description**: Tax - **`jp_withholding_tax`** - **Type**: `Money` - **Description**: Withholding Tax - **`tax_rate`** - **Type**: `Number` - **Description**: Tax Rate - **`tax_type`** - **Type**: `One of ['standard', 'reduced', 'non_taxable', 'untaxable', 'duty_free', 'legacy_tax', 'legacy_no_tax']` - **Description**: Tax Type - **`subtotal_sales_tax`** - **Type**: `Money` - **Description**: Subtotal of the items Sales Tax is Applied - **`subtotal_withholding_tax`** - **Type**: `Money` - **Description**: Subtotal of the items Witholding Tax is Applied - **`total`** - **Type**: `Money` - **Description**: Total - **`mixed_tax_rate_totals`** - **Type**: `JSON Object` - **Description**: Totals by Tax Rate - **`tax_group_totals`** - **Type**: `Array of Totals by Tax Type and Rate` - **Description**: Totals by Tax Type and Rate - **`extended_data`** - **Type**: `JSON Object` - **Description**: Extended Data - **`mid`** `Read-Only` - **Type**: `MakeLeaps ID` - **Description**: MakeLeaps ID - **`document_template`** `Required` - **Type**: `Document Template` - **Description**: Template - **`display_name`** `Read-Only` - **Type**: `String` - **Description**: Display Name - **`note`** - **Type**: `String` - **Description**: Notes - **`external_id`** - **Type**: `String` - **Description**: External ID - **`round_tax_down`** - **Type**: `Boolean` - **Description**: Round tax down (Deprecated) - **`tax_rounding`** - **Type**: `One of ['round_up', 'round_down', 'standard_rounding']` - **Description**: Document tax rounding. Defaults to `round_down`. - **`lineitem_price_rounding`** - **Type**: `One of ['round_up', 'round_down', 'standard_rounding']` - **Description**: Line item price rounding. Defaults to `standard_rounding`. - **`tags`** - **Type**: `Array of Tag` - **Description**: Tags - **`url`** `Read-Only` - **Type**: `URL` - **`pickup_links`** `Read-Only` - **Type**: `URL` - **Description**: Pickup Links - **`pdf_content_url`** `Read-Only` - **Type**: `URL` - **`pdf_upload_url`** `Read-Only` - **Type**: `URL` - **`client`** `Required` `Expandable` - **Type**: `Client URL (Expandable)` - **Description**: Client - **`client_contact`** `Required` `Expandable` - **Type**: `URL` - **Description**: Contact - **`modified`** `Read-Only` - **Type**: `Timestamp` - **Description**: Date Modified - **`date_paid`** - **Type**: `Timestamp` - **Description**: Date Paid - **`date_sent`** - **Type**: `Timestamp` - **Description**: Date Sent - **`date_cancelled`** - **Type**: `Timestamp` - **Description**: Date Cancelled - **`date_removed`** `Read-Only` - **Type**: `Timestamp` - **Description**: Date deleted - **`date_accepted`** - **Type**: `Timestamp` - **Description**: Date Accepted - **`date_confirmed`** - **Type**: `Timestamp` - **Description**: Date Confirmed - **`date_converted`** `Read-Only` - **Type**: `Timestamp` - **Description**: Date Converted - **`payment_date`** - **Type**: `Date` - **Description**: Payment Date - **`invoicing_period_start_date`** - **Type**: `Date` - **Description**: Invoice Period Start - **`invoicing_period_end_date`** - **Type**: `Date` - **Description**: Invoice Period End - **`is_accepted`** `Read-Only` - **Type**: `Boolean` - **Description**: Accepted - **`is_confirmed`** `Read-Only` - **Type**: `Boolean` - **Description**: Confirmed - **`is_converted`** `Read-Only` - **Type**: `Boolean` - **Description**: Converted - **`approval_status`** `Read-Only` - **Type**: `One of ['approved', 'rejected']` - **Description**: Approval - **`integrations`** `Read-Only` - **Type**: `JSON Object` - **Description**: Relationship with external systems - **`autocalculate`** - **Type**: `Boolean` - **Description**: Automatically calculate prices, taxes and totals - **`use_virtual_account`** - **Type**: `Boolean` - **Description**: Use Virtual Account - **`date`** `Required` - **Type**: `Date` - **Description**: Issue Date - **`date_due`** - **Type**: `Date` - **Description**: Date Due - **`date_valid`** - **Type**: `Date` - **Description**: Valid Until - **`date_shipped`** - **Type**: `Date` - **Description**: Shipment Date - **`sender_name`** - **Type**: `String` - **Description**: Sender Name - **`sender_contact_department`** - **Type**: `String` - **Description**: Company Contact Department - **`sender_contact_title`** - **Type**: `String` - **Description**: Company Contact Title - **`sender_contact_name`** - **Type**: `String` - **Description**: Company Contact Name - **`sender_address_format`** - **Type**: `String` - **Description**: Company Address Format - **`sender_country`** - **Type**: `String` - **Description**: Company Country Name - **`sender_postal_code`** - **Type**: `String` - **Description**: Company Postal Code - **`sender_region`** - **Type**: `String` - **Description**: Company State - **`sender_locality`** - **Type**: `String` - **Description**: Company City - **`sender_street_address`** - **Type**: `String` - **Description**: Company Street Address - **`sender_extended_address`** - **Type**: `String` - **Description**: Company Extended Address - **`sender_phone_number`** - **Type**: `String` - **Description**: Company Phone Number - **`sender_fax_number`** - **Type**: `String` - **Description**: Company Fax Number - **`partner_tax_registration_number`** - **Type**: `String` - **Description**: Company Tax Registration Number - **`display_partner_tax_registration_number`** - **Type**: `Boolean` - **Description**: Display Partner Tax Registration Number - **`recipient_name`** - **Type**: `String` - **Description**: Client Name - **`recipient_contact_department`** - **Type**: `String` - **Description**: Client Contact Department - **`recipient_contact_title`** - **Type**: `String` - **Description**: Client Contact Title - **`recipient_contact_name`** - **Type**: `String` - **Description**: Client Contact - **`recipient_honorific`** - **Type**: `String` - **Description**: Recipient Honorific - **`recipient_address_format`** - **Type**: `String` - **Description**: Client Address Format - **`recipient_country`** - **Type**: `String` - **Description**: Client City - **`recipient_postal_code`** - **Type**: `String` - **Description**: Client Postal Code - **`recipient_region`** - **Type**: `String` - **Description**: Client State - **`recipient_locality`** - **Type**: `String` - **Description**: Client City - **`recipient_street_address`** - **Type**: `String` - **Description**: Client Street Address - **`recipient_extended_address`** - **Type**: `String` - **Description**: Client Extended Address - **`recipient_phone_number`** - **Type**: `String` - **Description**: Client Phone Number - **`recipient_fax_number`** - **Type**: `String` - **Description**: Client Fax Number - **`client_tax_registration_number`** - **Type**: `String` - **Description**: Client Tax Registration Number - **`display_client_tax_registration_number`** - **Type**: `Boolean` - **Description**: Display Client Tax Registration Number - **`override_client_tax_registration_number`** - **Type**: `Boolean` - **`lineitems`** `Required` - **Type**: `Array of Line Item` - **Description**: Line Items - **`purchase_order_ids`** - **Type**: `Array of String` - **Description**: PO Numbers - **`peppol_details`** - **Type**: `Peppol Send` - **Description**: peppol details - **`source_received_document`** `Expandable` - **Type**: `URL` - **Description**: Received Document URL - **`use_external_pdf`** - **Type**: `Boolean` - **Description**: Use external PDF ### Extra Filters - **`document_number`** - **Type**: `String` - **Description**: Multi-value OR filter (repeat parameter) - **`client`** - **Type**: `MakeLeaps ID` - **`client_contact`** - **Type**: `MakeLeaps ID` - **`currency`** - **Type**: `String` - **`tags`** - **Type**: `String` - **Description**: Multi-value OR filter (comma-separated) Multi-value OR filter (repeat parameter) - **`accepted`** - **Type**: `Boolean` - **`confirmed`** - **Type**: `Boolean` - **`sent`** - **Type**: `Boolean` - **`viewed`** - **Type**: `Boolean` - **`paid`** - **Type**: `Boolean` - **`cancelled`** - **Type**: `Boolean` ## Line Items Line Items ---------- Line Items are mainly used when creating or reading documents. To order the line items on the document, please make sure to assign the `position` field to determine the ordering of a set of items. Line Item Type -------------- The following line item types are available (and assigned to `kind`): - `normal` for a normal line item, that shows all the fields - `simple` for a line item that only has a description and an amount field - `text` for a line item with only a description, and no money amount - `subtotal` When `autocalculate` is on, the subtotal is calculated as the total of preceding line items, either from the top of the table, or from the previous subtotal line if one exists. Source catalog Item ------------------- The `source_catalog_item` field can be used to set default values for the different fields when creating a line item of type `simple` or `normal`. The line item fields other than `kind` and `source_catalog_item` must be omitted in order for the catalog item values to be used. Tax Type -------- A Tax Type can be set for each line item. Different Document Templates support the use of different tax types. Document Templates that support Advanced Tax Types MUST have one of the following advanced Tax Types set: - `standard` - `reduced` - `non_taxable` - `untaxable` - `duty_free` With `standard` and `reduced` Tax Types: - `is_taxable` must be `true` - `tax_rate` must NOT be `0` With `non_taxable`, `untaxable`, and `duty_free` Tax Types: - `is_taxable` must be `false` - `tax_rate` must be `0`. - `is_tax_inclusive` must be `false`. Document Templates that do NOT support Advanced Tax Types accept the following Tax Types: - `legacy_tax` - `legacy_no_tax` Specifying the Tax Type for line items is recommended. With `legacy_tax` Tax Type: - `is_taxable` must be `true` With `legacy_no_tax` Tax Type: - `is_taxable` must be `false` When `tax_type` is not provided, `tax_type` value will be inferred based on the `is_taxable` field. If `is_taxable` is: - `true`, `tax_type` is set to `legacy_tax` - `false`, `tax_type` is set to `legacy_no_tax` Tax Rate -------- A tax rate can be set on the line item as a numeric value. The line item `tax_rate` can be used in combination with the document `autocalculate` field when assigning the line item to the document: If `autocalculate` is `true`, then the document `mixed_tax_rate_totals` field will automatically be built from the different line items tax rate and values. By omitting the `tax_rate` field and specifying the `source_catalog_item` field, the tax rate will be set from the catalog item `tax_category` value. Refer to the [Tax Category][catalog_item_tax_category] section on the different behavior of the catalog `tax_category` field. [catalog_item_tax_category]: https://app.makeleaps.com/api/docs/#line-item-catalog If both fields are omitted, the line item will use the value of the document `tax_rate` field when assigned to a document, otherwise the company default tax rate will be used. Line Item Extended Data ----------------------- Additional data can be stored on each line item by specifying the `extended_data` dictionary. Please refer to the [Document Extended Data section][document_extended_data] about how to handle each data type of additional data. [document_extended_data]: https://app.makeleaps.com/api/docs/#documents Example JSON for handling additional data via the `extended_data` field on a line item: { "document_template": "TPL12345678910", "lineitems: [ { "description": "MX", "has_jp_withholding_tax": false, "is_tax_inclusive": false, "is_taxable": true, "kind": "simple", "position": 0, "price": "1000", "quantity": "1", "quantity_unit": "", "unit_cost": "1000" "extended_data": { "note": "MX-0001239", "purchase_date": "2023-04-01", "additional_charge": {"currency": "JPY", "amount": "1000"} } } ] } ### Fields - **`kind`** `Required` - **Type**: `Line Item Type` - **Description**: Kind - **`description`** - **Type**: `String` - **Description**: Description - **`unit_cost`** - **Type**: `Money` - **Description**: Cost - **`quantity`** - **Type**: `Number` - **Description**: Qty. - **`quantity_unit`** - **Type**: `String` - **Description**: Units - **`price`** - **Type**: `Money` - **Description**: Price - **`is_taxable`** - **Type**: `Boolean` - **Description**: Taxable - **`is_tax_inclusive`** - **Type**: `Boolean` - **Description**: Tax Inclusive - **`has_jp_withholding_tax`** - **Type**: `Boolean` - **Description**: Wthld. - **`currency`** - **Type**: `Currency` - **Description**: Currency - **`tax_rate`** - **Type**: `Number` - **Description**: Tax Rate - **`tax_type`** - **Type**: `One of ['standard', 'reduced', 'non_taxable', 'untaxable', 'duty_free', 'legacy_tax', 'legacy_no_tax']` - **Description**: Tax Type - **`extended_data`** - **Type**: `JSON Object` - **Description**: Extended Data - **`vendor_cost`** - **Type**: `Money` - **Description**: Vendor Cost - **`source_catalog_item`** `Expandable` - **Type**: `URL` - **Description**: Catalog Item URL ## Line Item Catalog ### Endpoints - `/api/partner//item/` - Name: Catalog Item List - Methods: GET, POST, OPTIONS - `/api/partner//item//` - Name: Catalog Item View - Methods: GET, PUT, PATCH, OPTIONS The Line Item Catalog is used to save line items for future use on documents. This is useful for reporting and for keeping track of "standard" products that your company might sell. The resources in the Line Item Catalog resemble Line Items, except with a couple extra fields. Product Code ----------- Product codes are unique identifiers for entries in the Line Item Catalog. It is not required, but recommended, and used when generating reports. You can filter results by product code. - `?product_code=ABC` will filter for an exact match. - `?product_code__contains=ABC` will filter for product codes that include the text `ABC` somewhere inside. Tax Category ----------- Notes: - The `tax_category` field is deprecated. Please use `tax_type` instead. - When `tax_category` is either `default` or `alternate`, `tax_type` cannot be set. See more details in the paragraphs below. If `tax_category` field is used, its value must be one of the following. Tax Rate will be automatically populated based on the rules described below. - `default`: `tax_rate` copied from “Default Tax Rate” in Your Company settings - `alternate`: `tax_rate` copied from “Alternate Tax Rate” in Your Company settings. If "Alternate Tax Rate" is not set, "Default Tax Rate" is used. - `custom`: `tax_rate` field in the request body must be set If `tax_category` is not provided, it defaults to `custom`. When `tax_category` is either `default` or `alternate`, `tax_type` cannot be specified in the request and will be generated automatically based on `is_taxable` field. If `is_taxable` is - `true`, then `tax_type` is set to `legacy_tax` - `false`, then `tax_type` is set to `legacy_no_tax` - not specified in the request, it will be populated based on the `tax_rate`. If `tax_rate` is: - `0`, `is_taxable` will be `false` - non-zero, `is_taxable` will be `true` Note: For POST and PUT requests, `tax_rate` is required if `tax_category` is not provided. When referencing a line item catalog as a `source_catalog_item` on a Document's Line Item, the Line Item's `tax_rate` will be set according to the `tax_category` of the Line Item Catalog. When `tax_category` is: - `custom`, Line Item Catalog's `tax_rate` is applied. - `default`, the Company's Default Tax Rate is applied. - `alternate`, the Company's Alternate Tax Rate is applied. If that is not set, the Default Tax Rate is applied. - null or not set, the Document `tax_rate` value is applied. ### Fields - **`kind`** `Required` - **Type**: `Line Item Type` - **Description**: Kind - **`description`** - **Type**: `String` - **Description**: Description - **`unit_cost`** - **Type**: `Money` - **Description**: Cost - **`quantity`** - **Type**: `Number` - **Description**: Qty. - **`quantity_unit`** - **Type**: `String` - **Description**: Units - **`price`** - **Type**: `Money` - **Description**: Price - **`is_taxable`** - **Type**: `Boolean` - **Description**: Taxable - **`is_tax_inclusive`** - **Type**: `Boolean` - **Description**: Tax Inclusive or not. Defaults to False. - **`has_jp_withholding_tax`** - **Type**: `Boolean` - **Description**: Wthld. - **`currency`** `Required` - **Type**: `Currency` - **Description**: Currency - **`tax_rate`** - **Type**: `Number` - **Description**: Tax Rate - **`tax_type`** - **Type**: `One of ['standard', 'reduced', 'non_taxable', 'untaxable', 'duty_free', 'legacy_tax', 'legacy_no_tax']` - **Description**: Tax Type - **`extended_data`** - **Type**: `JSON Object` - **Description**: Extended Data - **`vendor_cost`** - **Type**: `Money` - **Description**: Vendor Cost - **`mid`** `Read-Only` - **Type**: `MakeLeaps ID` - **Description**: MakeLeaps ID - **`url`** `Read-Only` - **Type**: `URL` - **`product_code`** - **Type**: `String` - **Description**: Product Code - **`tax_category`** - **Type**: `One of ['default', 'alternate', 'custom']` - **Description**: Tax Category (Deprecated) ## Document Templates ### Endpoints - `/api/partner//template//` - Name: Document Templates - Methods: OPTIONS Document Templates ------------------ Document templates define the style of the PDFs that get generated for documents. The list of available document templates for a specific Document Type can be retrieved with the following command: $ curl -v https://api.makeleaps.com/api/partner/{ mid }/template/{ document_type }/?hide_archived=y&is_archived=false \ -X GET \ -H 'Authorization: Bearer < ACCESS TOKEN >' \ { "meta": { "status": 200 }, "response": [ { "template_code": "ja_JP_pro_4", "document_type": "invoice", "display_name": "[JA] Professional", "language_code": "ja" } ] } The following Templates support multiple tax rates. - "Professional" series - "Tax Type Pro" series A Template's `use_advanced_tax_settings` field indicates whether or not it supports Advanced Tax Types. Examples - The "Tax Type Pro" series templates support Advanced Tax Types and show `true`. - "Professional" series templates do NOT support Advanced Tax Types and show `false`. - Support for Advanced Tax Types on User-Defined Templates is set in the Template definition, and can be either `true` or `false`. The `use_advanced_tax_settings` field also affects which field is used to store the Document's Tax/Subtotal/Total. If `use_advanced_tax_settings` is: - `true`, `tax_group_totals` field is used. - `false`, `mixed_tax_rate_totals` field is used. ### Fields - **`template_code`** `Required` - **Type**: `String` - **Description**: Template code - **`document_type`** `Required` - **Type**: `Document Type` - **Description**: Document Type - **`display_name`** `Required` - **Type**: `String` - **Description**: Display name - **`language_code`** `Required` - **Type**: `String` - **Description**: Language code - **`base_template_code`** `Required` - **Type**: `String` - **Description**: Base Template code - **`extended_fields`** `Read-Only` - **Type**: `JSON Object` - **Description**: Document Extended Data Fields - **`lineitem_extended_fields`** `Read-Only` - **Type**: `JSON Object` - **Description**: Line Item Extended Data Fields - **`use_advanced_tax_settings`** `Read-Only` - **Type**: `Boolean` - **Description**: Uses Advanced Tax Types - **`settings`** `Read-Only` - **Type**: `JSON Object` - **Description**: PDF output-related settings - **`is_favourite_template`** `Read-Only` - **Type**: `Boolean` - **Description**: Set as Favorite Template or not ## Document Archive ### Endpoints - `/api/partner//archive/` - Name: Document Archive List - Methods: GET, OPTIONS - `/api/partner//archive//` - Name: Document Archive Instance - Methods: GET, OPTIONS - `/api/partner//archive/create/` - Name: (No Name) - Methods: options, post Document Archive ------------------ Document Archive preserves copies of MakeLeaps Documents as they appeared once sent to their respective recipients, in order to assist with compliance with 電子帳簿保存法 (note: a law in Japan to define the regulations of electronic record retention). A Document Archive can be created as follows: - when a MakeLeaps Document is sent using MakeLeaps sending list, a record is automatically created using the Document data that was sent. - when a user uses "Mark as Sent" in the MakeLeaps UI and chooses to create an Archive. The Archive stores the Document data as it was when it was marked as sent. - by making a request via this API (see below). Sample data (GET): { "meta": { "status": 200, "status_code": 200 }, "response": { "mid": "1234567890", "url": "http://api.makeleaps.com/api/partner//archive/1234567890/", "pdf_content_url": "http://api.makeleaps.com/api/partner//archive/1234567890/pdf/", "uses_external_pdf": false, "document_type": "receipt", "document_number": "REC202302/08-OC585", "sending_methods": ["manually_sent_electronically"], "legal_categories": ["electronically_outside_makeleaps"], "date_sent": "2023-03-23T04:20:56.181801Z", "date": "2023-02-11", "sender": "Employee Name", "client": "Client Name", "currency": "JPY", "total": "1000", "external_id": "" } } `sending_methods` of a Document Archive indicates the method by which the Document was sent. - `secure_send`: sent by Secure Send via MakeLeaps - `send_to_clientinbox`: sent by Send via Client Inbox via MakeLeaps - `japan_post`: sent by Japan Post via MakeLeaps - `manually_sent_electronically`: sent electronically outside MakeLeaps - `manually_sent_physically`: printed and sent paper copy outside MakeLeaps `legal_categories` of a Document Archive reflects the delivery category defined in 電子帳簿保存法. - `electronically_from_makeleaps`: sent using any electronic method via MakeLeaps - `physically_from_makeleaps`: sent using any printed paper copy via MakeLeaps - `electronically_outside_makeleaps`: sent using any electronic method outside MakeLeaps - `physically_outside_makeleaps`: sent using any printed paper copy outside MakeLeaps Create Document Archive ------------------ You can create a Document Archive record for a Document that will save its current state by sending a POST request. In your request, the following must be specified: - `document_mid`: the MID of the target Document. The Document must already have a value for `date_sent`. - `sending_method`: the sending method used when the Document was sent. Only `manually_sent_electronically` and `manually_sent_physically` can be specified when you create a Document Archive via the API. Sample request: $ curl https://api.makeleaps.com/api/partner//archive/create/ \ -X POST \ -H 'Authorization: Bearer < ACCESS TOKEN >' \ -H 'Content-Type: application/json' \ -d '{"document_mid": "1234567890", "sending_method": "manually_sent_electronically"}' If the creation is successful, the endpoint will return the newly created Document Archive as a response. Note: - Document Archive creation is not supported for Acceptance Certificates and Order Slips. - You cannot specify the `date_sent` datetime of the Archive record. It will be timestamped with the datetime the request was received. ### Fields - **`mid`** `Read-Only` - **Type**: `MakeLeaps ID` - **Description**: mid - **`url`** `Read-Only` - **Type**: `URL` - **`pdf_content_url`** `Read-Only` - **Type**: `String` - **`uses_external_pdf`** `Read-Only` - **Type**: `String` - **`document_type`** `Required` - **Type**: `Document Type` - **Description**: Document Type - **`document_number`** `Required` - **Type**: `String` - **Description**: Document Number - **`sending_methods`** `Required` - **Type**: `Can have ['secure_send', 'send_to_clientinbox', 'japan_post', 'manually_sent_electronically', 'manually_sent_physically'] values. Choose one of ['manually_sent_electronically', 'manually_sent_physically'] when you create a Document Archive via the API.` - **Description**: Sending Methods - **`legal_categories`** `Read-Only` - **Type**: `Array of ['electronically_from_makeleaps', 'physically_from_makeleaps', 'electronically_outside_makeleaps', 'physically_outside_makeleaps']` - **Description**: Legal Delivery Categories - **`date_sent`** - **Type**: `Timestamp` - **Description**: Datetime that the Document Archive was created - **`date`** `Required` - **Type**: `Date` - **Description**: Issue Date of the Document archived - **`sender`** `Required` - **Type**: `String` - **`client`** `Required` - **Type**: `String` - **Description**: client - **`currency`** `Required` - **Type**: `Currency` - **`total`** `Required` - **Type**: `Money` - **Description**: Total - **`external_id`** - **Type**: `String` - **Description**: External ID ## Document Pickup Link ### Endpoints - `/api/partner//document//pickup-link/` - Name: Document Pickup Link List - Methods: GET, POST, OPTIONS - `/api/partner//secureinbox/pickup-link//` - Name: Document Pickup Link - Methods: get, OPTIONS - `/api/partner//secureinbox/pickup-link//cancel/` - Name: Cancel Document Pickup Link - Methods: post, OPTIONS - `/api/partner//secureinbox/pickup-link//uncancel/` - Name: Re-enable cancelled Document Pickup Link - Methods: post, OPTIONS A pickup link is a URL that can be sent to the client to share a document online. You can check whether the client visited the link, as well as cancel/uncancel it. Creating a Pickup Link --------------------------------- You can create the pickup link for a document by sending a POST request without a body as follows. POST https:///api/partner//document//pickup-link/ Since MakeLeaps uses a background task to create pickup links, the response will contain the task details, not the link itself. The task details are an instance of `Task`. For more details about `Task`, see the [Task](#task) section. When the task has finished, the pickup link is ready. The pickup link created by this task can be obtained via a GET request to `result_url` in the `Task` instance. The response will look like the following. `link` contains the actual pickup link that may be sent to a client. { "meta": { "status": 200 }, "response": [ { "mid": "", "url": "https://api.makeleaps.com/api/partner//secureinbox/pickup-link//", "cancel_url": "https://api.makeleaps.com/api/partner//secureinbox/pickup-link//cancel/", "uncancel_url": "https://api.makeleaps.com/api/partner//secureinbox/pickup-link//uncancel/", "created": "2021-02-03T05:28:43.271956Z", "link": "https://example.com/secureinbox/p//", "email": "", "date_clicked": null, "source": "Shareable Link Panel", "expiration_date": "2021-04-04T14:30:38", "is_cancelled": false, "created_by": "Somebody", "supersend": null } ] } Getting Pickup Links ------------------------------------ Sending a GET request to `/api/partner//document//pickup-link/` returns pickup links for document specified by `` . Note that the response might be paginated. Cancel or Re-enable a Pickup Link ------------------------------------ You can cancel a pickup link at any time by sending a POST as follows without a body. POST /api/partner//secureinbox/pickup-link//cancel/ If you want to re-enable an expired or cancelled pickup link, send a POST as follows without a body. POST /api/partner//secureinbox/pickup-link//uncancel/ ### Fields - **`mid`** `Read-Only` - **Type**: `MakeLeaps ID` - **Description**: MakeLeaps ID - **`url`** `Read-Only` - **Type**: `URL` - **`cancel_url`** `Read-Only` - **Type**: `URL` - **`uncancel_url`** `Read-Only` - **Type**: `URL` - **`created`** `Read-Only` - **Type**: `Timestamp` - **Description**: Created - **`link`** `Read-Only` - **Type**: `URL` - **Description**: Document Pickup Link - **`email`** - **Type**: `String` - **Description**: Email - **`date_clicked`** - **Type**: `Timestamp` - **Description**: Viewed - **`source`** `Read-Only` - **Type**: `String` - **`expiration_date`** - **Type**: `Timestamp` - **Description**: Expiration date - **`is_cancelled`** `Read-Only` - **Type**: `Boolean` - **Description**: Cancelled - **`created_by`** `Read-Only` - **Type**: `String` - **Description**: Created by - **`supersend`** `Read-Only` - **Type**: `String` - **Description**: Send Order - **`date_cancelled`** `Read-Only` - **Type**: `String`