Create an invoice with the API

To create an invoice by using the Wingspan API, you must use the POST operation for the payments/invoice endpoint.

Before you begin

Before you begin the Invoice creation process, ensure that you have the following:

memberClientId: The memberClientId is the identifier that indicates the invoice recipient. This is usually the client. If you do not have the memberClientId you can find it by calling the GET /payments/memberClient endpoint and filter your results by using URL query parameters.
General invoice details such as:
- Payment structure: whether you are billing the payer by an hourly rate, by the number of units produced, or as a flat rate.
- The currency that the payer is to be charged in.
- If you need to include attachments to the line items of the Invoice.
- Gather any necessary attachments in PDF format for the Invoice.
- Your Wingspan API authorization token. The authorization token can be found on the Developer page in the Wingspan application. For more information see, Get started with the Wingspan API.
- You policy on late fees for late payments and how frequently they occur.
- Your policy on credit card processing fees.
Review the Invoice components.

To create a Wingspan invoice in with the API

If you don’t already have it, acquire the memberClientId by calling:

GET https://api.wingspan.app/payments/memberClient

URL query parameters
- ?emailTo=<The payer's email address>
For more information about the URL query parameters, see Use URL Query Parameters with Wingspan APIs.

Headers:
- accept: application/json: Specifies the format of the response data.
- content-type: application/json: Indicates the media type of the resource/data.
- Authorization: Bearer \<Your_Access_Token>: This header is required for authentication. Replace <Your_Access_Token> with your actual access token.
Example call request
```
curl --request GET \
     --url https://api.wingspan.app/payments/memberClient?emailTo=<The payer's email address>  \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'Authorization: Bearer YOUR_FULL_ACCESS_TOKEN' \
```
Response:
A successful request returns an appropriate success status code (e.g. 200 OK) along with a JSON response containing details related to all clients associated with your project, unless otherwise specified by a URL query parameter.
If you need to include an attachment to the line items of an Invoice, call:

POST https://api.wingspan.app /files/member/private/upload

Headers:
- Authorization: Bearer {token}: The bearer token for authentication and authorization.
- Content-Type: multipart/form: Indicates the media type of the resource/data.
- Form Data: =@"{file_path}": Represents the file that needs to be uploaded. The file path should point to the location of the file on the system.
Note: {file_path} should be replaced with the actual path of the file. For example, =@"/Users/jsmith/Documents/Project_1_Receipt.pdf".

Request Body Parameters:
There are no body parameters for this call.

Example call request
```
curl --request POST \
     --url https://api.wingspan.app/files/files/member/private/upload \
     --header 'Authorization: Bearer eyJhbG9AyQ' \
     --header 'Content-Type: multipart/form-data' \
     --form '=@"/Users/jsmith/Documents/Project_1_Receipt.pdf"'
```
Response:
A successful request will return an appropriate success status code (e.g., 201 Created or 200 OK) along with a JSON response containing details of the uploaded file, such as file ID, URL, and other metadata. In case of errors, appropriate HTTP status codes and error messages will be returned.
In the response copy and save the fileId. The fileId is needed to attach media to the Invoice.
Create the Invoice by calling:

POST https://api.wingspan.app/payments/invoice

The example below outlines the parameters needed to create an Invoice that is charging the payer by an hourly rate. There are many other parameter options to suit a variety of needs. For more information about Invoice request body parameters, see Invoice components.

Headers:
- accept: application/json: Specifies the format of the response data.
- content-type: application/json: Indicates the media type of the resource/data.
- Authorization: Bearer <Your_Access_Token>: This header is required for authentication. Replace <Your_Access_Token> with your actual access token.
Request Body Parameters:
- memberClientId (string, required): Unique identifier for the payer, also known as a client.
- currency (string, required): Currency type (e.g., USD, CAD).
- dueDate (string, required): Due date for the invoice in ISO format (e.g., "2023-12-01").
- lineItems (array of objects, required): List of items for which payment is to be made.
  - costPerUnit (number): Cost per unit can refer to hourly rates, cost of an item, or a flat rate.
  - description (string): Description or reason for the payment.
  - quantity (number): Quantity of the items or number of hours.
  - reimbursableExpense (boolean): Indicates if the expense is reimbursable.
  - totalCost (number): Total cost for the line item (costPerUnit * quantity).
- acceptedPaymentMethods (array of strings): List of payment methods that are accepted. This can be Credit, ACH, or Manual.
- attachments (object): Any attachments associated with the payable.
  - customAttachmentIds (array of strings): List of custom attachment identifiers. If you need to attach a document to the line time, you include the fileId here.
- invoiceNotes (string): Any notes or comments related to the payable.
- lateFeeHandling (object): Configuration for handling late fees.
  - frequency (object): Specifies how often late fees should be applied.
  - daily (boolean): If set to true, late fees are applied daily.
  - lateFeePercentage (number): Percentage of the payable amount to be charged as a late fee.
- notificationPreferences (object): Preferences for notifications related to the payable.
- sendReminders (boolean): If set to true, reminders will be sent.
- sendInvoice (boolean): If set to true, an invoice will be sent.
- sendReceipt (boolean): If set to true, a receipt will be sent upon successful payment.
- status (string): Current status of the Invoice. Set this to Draft if the Invoice needs to be approved before being sent to the payer. Set this to Open to send immediately.
  Example call and Request body
```
curl --request POST \\
     --url <https://api.wingspan.app/payments/invoice> \\
     --header 'accept: application/json' \\
     --header 'content-type: application/json' \\
     --header 'Authorization: Bearer YOUR_FULL_ACCESS_TOKEN' \\
     --data '
{
  "memberClientId": "abc123",
  "currency": "USD",
  "dueDate": "2023-012-01",
  "lineItems": [
    {
      "costPerUnit": 50,
      "description": "Payment for project 1.",
      "quantity": 40,
      "reimbursableExpense": false,
      "totalCost": 2000
    },
    {
      "costPerUnit": 50,
      "description": "Payment for project 2.",
      "quantity": 25,
      "reimbursableExpense": false,
      "totalCost": 1250
    }
  ],
  "acceptedPaymentMethods": [
    "Credit",
    "ACH"
  ],
  "attachments": {
    "customAttachmentIds": [
      "789hjk"
    ]
  },
  "invoiceNotes": "This is payments for both projects 1 and 2.",
  "lateFeeHandling": {
    "frequency": {
      "daily": true
    },
    "lateFeePercentage": 5
  },
  "notificationPreferences": {
    "sendReminders": true,
    "sendInvoice": true,
    "sendReceipt": true
  },
  "status": "Draft"
}
'
```
  Response:
  A successful request returns a 201 Created status code along with a JSON response containing details of the created Invoice. In case of errors, appropriate HTTP status codes and error messages are returned.
If the call is successful, make note of the invoiceId and invoiceNumber for your personal records. It’s a good idea to keep these in an accessible location should you need to modify the Invoice later on.
Now that your invoice is created, you can send the Invoice to the payer with the invoiceId by calling:

POST payments/invoice/{invoice_id}/send

Path Parameters
- invoiceId: This is the identifier of the invoice that you want to send. This was included in the response of the Invoice creation API call. If you do not know the Invoice ID of the Invoice that you want to send, you can find a list of all available Invoices by calling the GET /payments/invoice endpoint.
You must provide the invoice unique identifier in the URL of the call. For example: https://api.wingspan.app/payments/invoice/123-abc-456/send

Request Body Parameters:

There are no body parameters for this call.

Example call request
```
curl --request POST \
     --url https://api.wingspan.app/payments/invoice/123-abc-456/send \
     --header 'accept: application/json' \\
     --header 'content-type: application/json' \\
     --header 'Authorization: Bearer YOUR_FULL_ACCESS_TOKEN' \\
```
Response:

The call returns standard HTTP 1.1 response codes and, if successful, the invoice is sent to the client.