Invoices

Learn how to create, manage, and submit invoices to ZIMRA using the VasBox API.

Invoices are the primary document type in VasBox. They represent a request for payment from a customer and can be submitted to ZIMRA for fiscal compliance.

All invoices must be submitted to ZIMRA within 24 hours of creation to comply with fiscal regulations.

The Invoice Object

The invoice object contains all the information about a transaction, including customer details, line items, taxes, and fiscal status.

Invoice Object
{
  "id": "inv_abc123",
  "number": "INV-2024-0001",
  "status": "draft",
  "customer_id": "cust_xyz789",
  "customer": {
    "id": "cust_xyz789",
    "name": "Acme Corporation",
    "tin": "123456789"
  },
  "items": [
    {
      "id": "itm_001",
      "description": "Software License",
      "quantity": 1,
      "unit_price": 5000.00,
      "tax_code": "STD",
      "tax_amount": 750.00,
      "total": 5750.00
    }
  ],
  "subtotal": 5000.00,
  "tax_total": 750.00,
  "total": 5750.00,
  "currency": "USD",
  "fiscal_code": null,
  "zimra_submitted_at": null,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Invoice Statuses

StatusDescription
draftInvoice is created but not yet finalized. Can be edited.
pendingInvoice is queued for ZIMRA submission.
submittedSuccessfully submitted to ZIMRA with fiscal code.
failedZIMRA submission failed. Check error details.
cancelledInvoice has been voided or cancelled.

Create an Invoice

Create a new invoice with customer and line item details. The invoice will be created in draft status.

POST/v1/invoices
Auth required

Creates a new invoice for the specified customer.

Request Body

customer_idstring required

The unique identifier of the customer.

Example: cust_xyz789

currencystring default: USD

Three-letter ISO currency code.

Example: USD

itemsarray required

Array of line items for the invoice.

notesstring

Optional notes or memo for the invoice.

Example Request

JSON
{
  "customer_id": "cust_xyz789",
  "currency": "USD",
  "items": [
    {
      "description": "Software License",
      "quantity": 1,
      "unit_price": 5000.00,
      "tax_code": "STD"
    }
  ],
  "notes": "Annual license renewal"
}

Response

201Invoice created successfully
JSON
{
  "id": "inv_abc123",
  "number": "INV-2024-0001",
  "status": "draft",
  "customer_id": "cust_xyz789",
  "customer": {
    "id": "cust_xyz789",
    "name": "Acme Corporation",
    "tin": "123456789"
  },
  "items": [
    {
      "id": "itm_001",
      "description": "Software License",
      "quantity": 1,
      "unit_price": 5000.00,
      "tax_code": "STD",
      "tax_amount": 750.00,
      "total": 5750.00
    }
  ],
  "subtotal": 5000.00,
  "tax_total": 750.00,
  "total": 5750.00,
  "currency": "USD",
  "fiscal_code": null,
  "zimra_submitted_at": null,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

List Invoices

Retrieve a paginated list of invoices. You can filter by status, customer, and date range.

GET/v1/invoices
Auth required

Returns a paginated list of invoices.

Query Parameters

statusstring

Filter by invoice status.

Example: submitted

customer_idstring

Filter by customer ID.

fromstring

Start date for date range filter (ISO 8601).

Example: 2024-01-01

tostring

End date for date range filter (ISO 8601).

Example: 2024-01-31

pageinteger default: 1

Page number for pagination.

per_pageinteger default: 20

Number of items per page (max 100).

Response

200List of invoices
JSON
{
  "data": [
    {
      "id": "inv_abc123",
      "number": "INV-2024-0001",
      "status": "submitted",
      "total": 5750.00,
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "inv_def456",
      "number": "INV-2024-0002",
      "status": "draft",
      "total": 2500.00,
      "created_at": "2024-01-16T14:20:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total": 42,
    "last_page": 3
  }
}

Retrieve an Invoice

Retrieve the details of a specific invoice by its ID.

GET/v1/invoices/{invoice_id}
Auth required

Retrieves the details of an existing invoice.

Path Parameters

invoice_idstring required

The unique identifier of the invoice.

Example: inv_abc123

Response

200Invoice details
JSON
{
  "id": "inv_abc123",
  "number": "INV-2024-0001",
  "status": "draft",
  "customer_id": "cust_xyz789",
  "customer": {
    "id": "cust_xyz789",
    "name": "Acme Corporation",
    "tin": "123456789"
  },
  "items": [
    {
      "id": "itm_001",
      "description": "Software License",
      "quantity": 1,
      "unit_price": 5000.00,
      "tax_code": "STD",
      "tax_amount": 750.00,
      "total": 5750.00
    }
  ],
  "subtotal": 5000.00,
  "tax_total": 750.00,
  "total": 5750.00,
  "currency": "USD",
  "fiscal_code": null,
  "zimra_submitted_at": null,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}
404Invoice not found
JSON
{
  'error': {
    'code': 'invoice_not_found',
    'message': 'The requested invoice does not exist.'
  }
}

Submit to ZIMRA

Submit an invoice to ZIMRA for fiscal validation and receive a fiscal code. This action is irreversible once successful.

Important

Once an invoice is submitted to ZIMRA, it cannot be edited or deleted. Make sure all details are correct before submission.
POST/v1/invoices/{invoice_id}/submit
Auth required

Submits the invoice to ZIMRA for fiscal validation.

Path Parameters

invoice_idstring required

The unique identifier of the invoice to submit.

Example: inv_abc123

Response

200Invoice submitted successfully
JSON
{
  'id': 'inv_abc123',
  'status': 'submitted',
  'fiscal_code': 'ZW-2024-ABC123-XYZ',
  'zimra_submitted_at': '2024-01-15T10:35:00Z'
}
422Submission failed
JSON
{
  'error': {
    'code': 'submission_failed',
    'message': 'ZIMRA validation failed.',
    'details': [
      'Customer TIN is invalid',
      'Tax calculation mismatch'
    ]
  }
}
Previous Authentication
NextReceipts