Draft invoice workflow

Create a draft invoice

You can create an invoice in draft state by setting status to Draft. Draft invoices are not visible to the client and no notifications are sent.

curl --request POST \
     --url https://api.maroo.us/v1/invoices \
     --header "accept: application/json" \
     --header "authorization: Bearer $API_TOKEN" \
     --header "content-type: application/json" \
     --data '
{
  "contact": {
    "type": "Client",
    "name": "Sarah Collins",
    "email": "[email protected]"
  },
  "eventDate": "2024-06-15",
  "totalAmount": 120000,
  "paymentSchedule": [
    {
      "dueDate": "2024-03-15",
      "amount": 60000
    },
    {
      "dueDate": "2024-06-01",
      "amount": 60000
    }
  ],
  "paymentMethods": ["DebitCard", "CreditCard"],
  "note": "Engagement Photography",
  "deliveryMethod": "Email",
  "status": "Draft"
}'

The response will include status: "Draft" and paymentLink: null since the invoice is not yet active:

{
  "timestamp": "2024-02-10T14:00:00.000Z",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "contactId": "f0e1d2c3-b4a5-6789-0abc-def123456789",
    "totalAmount": 120000,
    "paymentSchedule": [
      {
        "id": "11111111-aaaa-bbbb-cccc-dddddddddddd",
        "dueDate": "2024-03-15",
        "name": null,
        "amount": 60000,
        "status": "Draft",
        "paymentDate": null,
        "fee": null
      },
      {
        "id": "22222222-aaaa-bbbb-cccc-dddddddddddd",
        "dueDate": "2024-06-01",
        "name": null,
        "amount": 60000,
        "status": "Draft",
        "paymentDate": null,
        "fee": null
      }
    ],
    "paymentMethods": ["DebitCard", "CreditCard"],
    "ccEmails": [],
    "enableAutoreminders": true,
    "note": "Engagement Photography",
    "deliveryMethod": "Email",
    "paymentLink": null,
    "status": "Draft"
  },
  "error": null
}

Activate the draft invoice

When you are ready to send the invoice to the client, activate it by setting status to Active. You can also update other fields in the same request:

curl --request PATCH \
     --url https://api.maroo.us/v1/invoices/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
     --header "accept: application/json" \
     --header "authorization: Bearer $API_TOKEN" \
     --header "content-type: application/json" \
     --data '
{
  "note": "Engagement Photography - Updated Package",
  "status": "Active"
}'

Once activated, the invoice becomes visible to the client. Notifications are sent based on the delivery method, and a payment link is generated:

{
  "timestamp": "2024-02-12T09:15:00.000Z",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "contactId": "f0e1d2c3-b4a5-6789-0abc-def123456789",
    "totalAmount": 120000,
    "paymentSchedule": [
      {
        "id": "11111111-aaaa-bbbb-cccc-dddddddddddd",
        "dueDate": "2024-03-15",
        "name": null,
        "amount": 60000,
        "status": "Due",
        "paymentDate": null,
        "fee": null
      },
      {
        "id": "22222222-aaaa-bbbb-cccc-dddddddddddd",
        "dueDate": "2024-06-01",
        "name": null,
        "amount": 60000,
        "status": "Scheduled",
        "paymentDate": null,
        "fee": null
      }
    ],
    "paymentMethods": ["DebitCard", "CreditCard"],
    "ccEmails": [],
    "enableAutoreminders": true,
    "note": "Engagement Photography - Updated Package",
    "deliveryMethod": "Email",
    "paymentLink": "https://pay.maroo.us/photographer/r/AbCdEfGh",
    "status": "Active"
  },
  "error": null
}

Note: Once an invoice is active, it cannot be reverted to draft status. Attempting to set status: "Draft" on an active invoice will return a 422 error.