Guides

Create an Invoice

Draft an invoice with our API.

Suggest Edits

This guide provides instructions for drafting and saving an invoice. Doing so generates an invoice_id, which you can use to send the invoice. See Create an Invoice in API Reference for field definitions.


Prerequisites

  1. See Create a Sandbox Account to sign up and log in to the Maast Manager portal.
  2. Follow the steps in Get Your API Credentials to save a sandbox ID and API key.
  3. See Authentication to format the credentials and generate your API token. (Alternatively, use the credentials as-is to test this endpoint with our 'Try It!' feature.)

Implement

Write a POST request to send to the /platform/invoice endpoint. Assign the invoice a number and include it in the request body. See the sample code below:

curl --request POST \
     --url https://api-test.maast.com/platform/invoice \
     --header 'accept: application/json' \
     --header 'authorization: Basic OjllZGVjMjFhMzFjMHh5ejc4OWUzMGEzNDE2YWJjMTIz' \
     --header 'content-type: application/json' \
     --data '
{
     "invoice_number": "XYZ1234"
}
'

Customer Information

Add a customer ID to the body of the request. This is required. Please note:

  • You may use the customer_id value of a profile you have added to Customer Vault. See the Add a Customer guide for more details.
  • If you are using an unsaved customer, you must assign them a customer_id value here and set save_customer to true, which saves their profile in Customer Vault.

See the sample code below:

{
     "customer_id": "JOHNDOE",
     "save_customer": true
}

Contact Information

Add contact information to the request body using the from_contact and billing_contact object fields. See the following sample code:

{
     "from_contact": {
          "first_name": "John",
          "last_name": "Doe",
          "firm_name": "CompanyXYZ",
          "address1": "4W 4th Avenue",
          "address2": "#401",
          "city": "San Mateo",
          "state": "CA",
          "zip": "94404",
          "zip4": "1234",
          "phone": "9999999999",
          "email_address": "[email protected]",
          "country_code": "840",
          "country": "United States"
     },
     "billing_contact": {
          "first_name": "John",
          "last_name": "Doe",
          "firm_name": "CompanyXYZ",
          "address1": "4W 4th Avenue",
          "address2": "#401",
          "city": "San Mateo",
          "state": "CA",
          "zip": "94404",
          "zip4": "1234",
          "phone": "9999999999",
          "email_address": "[email protected]",
          "country_code": "840",
          "country": "United States"
     }
}

Invoice and Payment Information

In the request body, add information for the invoice and the payment stage, such as the currency, line items, payment terms, and modified settings for your Hosted Checkout page. See the sample code below:

{
     "profile_id": "21200000000100000840",
     "tran_currency": "840",
     "sales_tax": {
          "type": "RATE",
          "value": 2.345
     },
     "date_invoice": "2025-01-01T00:00:00.000Z",
     "payment_terms": {
          "type": "DAYS",
          "value": "10"
     },
     "payment_terms_note": "Late fees calculated after 10 days.",
     "checkout_settings": {
          "allow_partial_payments": false,
          "email_receipt": false,
          "allow_ach_payment": true
     },
     "line_items": [
          {
               "quantity": 10,
               "description": "Pencils",
               "unit_cost": 1.49
          }
     ],
     "footer_note": "Thanks for your business!"
}

Example Request

Once configured, your request will resemble the following sample code:

curl --request POST \
     --url https://api-test.maast.com/platform/invoice \
     --header 'accept: application/json' \
     --header 'authorization: Basic OjllZGVjMjFhMzFjMHh5ejc4OWUzMGEzNDE2YWJjMTIz' \
     --header 'content-type: application/json' \
     --data '
{
     "customer_id": "JOHNDOE",
     "from_contact": {
          "first_name": "John",
          "last_name": "Doe",
          "firm_name": "CompanyXYZ",
          "address1": "4W 4th Avenue",
          "address2": "#401",
          "city": "San Mateo",
          "state": "CA",
          "zip": "94404",
          "zip4": "1234",
          "phone": "9999999999",
          "email_address": "[email protected]",
          "country_code": "840",
          "country": "United States"
     },
     "billing_contact": {
          "first_name": "John",
          "last_name": "Doe",
          "firm_name": "CompanyXYZ",
          "address1": "4W 4th Avenue",
          "address2": "#401",
          "city": "San Mateo",
          "state": "CA",
          "zip": "94404",
          "zip4": "1234",
          "phone": "9999999999",
          "email_address": "[email protected]",
          "country_code": "840",
          "country": "United States"
     },
     "invoice_number": "XYZ1234",
     "profile_id": "21200000000100000840",
     "tran_currency": "840",
     "footer_note": "Thanks for your business!",
     "payment_terms_note": "Late fees calculated.",
     "checkout_settings": {
          "allow_partial_payments": false,
          "email_receipt": false,
          "allow_ach_payment": true
     },
     "sales_tax": {
          "type": "RATE",
          "value": 2.345
     },
     "payment_terms": {
          "type": "DAYS",
          "value": "10"
     },
     "date_invoice": "2025-01-01T00:00:00.000Z",
     "line_items": [
          {
               "quantity": 10,
               "description": "Pencils",
               "unit_cost": 1.49
          }
     ],
     "save_customer": true
}
'

Integrate

Send the request to the /platform/invoice endpoint with your configurations in the body.

Maast will return a response like the code below:

{
  "code": 0,
  "message": "Success",
  "data": {
    "invoice_id": 1234,
    "merchant_id": 212000000001,
    "customer_id": "JOHNDOE",
    "from_contact": {
      "first_name": "John",
      "last_name": "Doe",
      "firm_name": "CompanyXYZ",
      "address1": "4W 4th Avenue",
      "address2": "#401",
      "city": "San Mateo",
      "state": "CA",
      "zip": "94404",
      "zip4": "1234",
      "phone": "9999999999",
      "email_address": "[email protected]",
      "country_code": "840",
      "country": "United States"
    },
    "billing_contact": {
      "first_name": "John",
      "last_name": "Doe",
      "firm_name": "CompanyXYZ",
      "address1": "4W 4th Avenue",
      "address2": "#401",
      "city": "San Mateo",
      "state": "CA",
      "zip": "94404",
      "zip4": "1234",
      "phone": "9999999999",
      "email_address": "[email protected]",
      "country_code": "840",
      "country": "United States"
    },
    "invoice_number": "XYZ1234",
    "status": "SAVED",
    "amt_tran": 100.45,
    "amt_tax": 1.45,
    "amt_sub_total": 1.45,
    "amt_paid": 50,
    "amt_balance": 50.45,
    "profile_id": "21200000000100000840",
    "tran_currency": "840",
    "footer_note": "Thanks for your business!",
    "payment_terms_note": "Late fees calculated.",
    "checkout_settings": {
      "allow_partial_payments": false,
      "email_receipt": false,
      "allow_ach_payment": true
    },
    "invoice_link": "https://app.maast.com/checkout/invoice/7d8e96ac261711e8b413acde4800bbbb",
    "sales_tax": {
      "type": "RATE",
      "value": 2.345
    },
    "payment_terms": {
      "type": "DAYS",
      "value": "10"
    },
    "date_invoice": "2025-01-01T00:00:00.000Z",
    "line_items": [
      {
        "quantity": 10,
        "description": "Pencils",
        "unit_cost": 1.49
      }
    ],
    "date_due": "2025-01-01T00:00:00.000Z",
    "date_last_view": "2025-10-01T00:00:00.000Z",
    "date_notice": "2025-08-01T00:00:00.000Z",
    "db_timestamp": "2025-01-01T12:57:47.000-0700"
  }
}

Check the code field in the request response: 0 confirms that you have successfully created and saved the invoice. If the value is something other than 0, check Platform API Response Codes in Reference.

Check the invoice_id field and save its value to your records. You can now use this invoice ID to send the invoice to your customer or to find, update, or cancel it.

See Create an Invoice in API Reference for response field definitions.

🚧

Save the Invoice ID

Be sure to save the invoice_id value that appears in your request response. You will need it to interact with this invoice using the Invoice API.


Test and Go Live

See our Test and Go Live guide to test your API integration and to start transacting with an active production account.


Updated 9 months ago