# Create an invoice

**POST /api/v1/invoices**

This endpoint creates an invoice that reflects the insurance premium owed by the contractor for the specified pay period.

## Servers
- Production server: https://api.1099policy.com (Production server)

## Parameters

### Body: application/json (object)

- **contractor** (string)  
  ID of the contractor

- **gross_pay** (integer)  
  The gross pay that the contractor earned in the last pay period.

- **job** (string)  
  ID of the job that the contractor was paid to do.

- **paycycle_enddate** (integer)  
  Pay period end date.

- **paycycle_startdate** (integer)  
  Pay period start date.

- **purchase_order_number** (string)  
  The purchase order number for this invoice. Optional.

By default an invoice inherits the `purchase_order_number` set on the job's `custom_metadata`. Send this field to override that default for this invoice — an explicit value always wins over the job default. Send an empty string (`""`) to create the invoice with no purchase order number, or omit the field to inherit the job's default.

If a later gross_pay change re-prices this invoice, the replacement invoice keeps this purchase order number; it is not re-inherited from the job.

## Responses
### 201
Returns the invoice object if the post succeeded.

#### Body: application/json (object)
- **contractor** (string)  
  ID of the contractor.

- **created** (integer(int64))

- **gross_pay** (integer)  
  The gross pay that the contractor earned in the last pay period.
  
  A positive integer representing the gross pay (e.g., 15000 cents to charge $150.00). The minimum amount is 100 cents US. The maximum amount is 100000000 cents US ($1,000,000).

- **id** (string)

- **job** (string)  
  ID of the job that the contractor was paid to do.

- **paycycle_enddate** (integer(int64))  
  Pay period end date. Measured in seconds since the Unix epoch.

- **paycycle_startdate** (integer(int64))  
  Pay period start date. Measured in seconds since the Unix epoch.

- **premium_due** (integer)  
  Premium due for pay cycle. Calculated as a percentage of gross pay for the period.
  
  A positive integer representing the premium due (e.g., 150 cents to charge $1.50). The minimum amount is 100 cents US.

- **purchase_order_number** (string)  
  The purchase order number for this invoice. Used for dashboard display and agency-pay billing.
  
  By default an invoice inherits this from the `purchase_order_number` set on the job's `custom_metadata` when it is created. It can be overridden per invoice on create or update by sending `purchase_order_number` (an explicit value wins over the job default), or cleared by sending an empty string (`""`). Omitting the field on update leaves the current value unchanged.
  
  When a wage change re-prices an invoice, the replacement invoice keeps this value rather than re-inheriting it from the job.

Precedence: explicit value on the invoice, then the value carried forward when an invoice is re-priced, then the job's `custom_metadata` default.