> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alvys.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create carrier invoice

> Create a carrier invoice in Alvys for a completed load, including line items, accessorials, deductions, and the total amount owed to the carrier.

This endpoint allows factoring or payment platforms to push carrier invoices directly into Alvys and associate them with the relevant trip.

The request uses `multipart/form-data` and must contain exactly one file.

### Path Parameters

| Parameter | Type   | Required | Description               |
| --------- | ------ | -------- | ------------------------- |
| version   | string | Yes      | API version (e.g., `1.0`) |

### Request Body

Content-Type: `multipart/form-data`

| Parameter            | Type   | Required | Description                                                              |
| -------------------- | ------ | -------- | ------------------------------------------------------------------------ |
| File                 | binary | Yes      | Carrier invoice document file                                            |
| TripId               | string | Yes      | Identifier of the trip the invoice belongs to                            |
| CarrierInvoiceNumber | string | No       | Carrier-provided invoice number                                          |
| PaymentType          | string | No       | Payment type for the carrier invoice (e.g., `Standard Pay`, `Quick Pay`) |

***

### Example Request (cURL)

```bash theme={null}
curl -X POST "{{host}}/api/p/v1/invoices/carrier-invoice" \
  -H "Authorization: Bearer $TOKEN" \
  -F "File=@carrier_invoice.pdf" \
  -F "TripId=trip_12345" \
  -F "CarrierInvoiceNumber=INV-93842" \
  -F "PaymentType=Standard Pay"
```

***

### Responses

#### 200 OK

Returns metadata for the uploaded carrier invoice attachment.

#### 400 Bad Request

Returned when required fields are missing or the multipart request is invalid.

#### 401 Unauthorized

Returned when authentication is missing or invalid.

#### 403 Forbidden

Returned when access to this endpoint is not allowed.

#### 404 Not Found

Returned when the specified `TripId` does not exist.

#### 413 Content Too Large

Returned when the uploaded file exceeds the allowed size limit.

#### 415 Unsupported Media Type

Returned when the uploaded file type is not supported.

### Response Body

| Field          | Type    | Description                                             |
| -------------- | ------- | ------------------------------------------------------- |
| id             | string  | Unique identifier of the uploaded document              |
| AttachmentPath | string  | File path or filename assigned during upload            |
| AttachmentType | string  | Type of the uploaded document                           |
| AttachmentSize | integer | File size in bytes                                      |
| UploadedAt     | string  | UTC timestamp when the file was uploaded                |
| ParentId       | string  | Identifier of the parent entity (TripId)                |
| ParentType     | string  | Entity type the document is attached to                 |
| UploadedBy     | string  | Identifier of the user or system that uploaded the file |
| DownloadUrl    | string  | Temporary URL to download the uploaded file             |
| ExpiresAt      | string  | Expiration timestamp for the download URL               |

***

### Example Response

```json theme={null}
{
  "id": "string",
  "AttachmentPath": "string",
  "AttachmentType": "string",
  "AttachmentSize": 0,
  "UploadedAt": "2026-03-16T13:45:12.539Z",
  "ParentId": "string",
  "ParentType": "string",
  "UploadedBy": "string",
  "DownloadUrl": "string",
  "ExpiresAt": "2026-03-16T13:45:12.539Z"
}
```

***

### Notes

* The request must include exactly **one file**.
* The uploaded document will be associated with the specified **TripId**.
* This endpoint is typically used by **factoring or payment platforms** to submit carrier invoices programmatically.
* Response schema uses the standard `AttachmentResponse` model.
* Supports `multipart/form-data` upload only.

Example integration use case:

Carriers upload invoices to a factoring/payment platform (e.g., **EPay**), which then pushes the invoice to Alvys via this endpoint so the invoice is attached to the relevant trip.

***

### Validation Notes

`PaymentType` currently accepts any string value. If the provided value does not match a configured payment type, the system defaults to **30-day payment terms**.

Recommended improvement:

The API should validate `PaymentType` against configured carrier payment terms and return **400 Bad Request** when an invalid value is provided.


## OpenAPI

````yaml POST /api/p/v{version}/invoices/carrier-invoice
openapi: 3.0.1
info:
  title: Alvys
  description: >-
    Alvys provides a robust set of REST APIs to allow you to integrate Alvys
    into virtually any platform. These APIs cover most of Alvys' major product
    areas with additional endpoints being added regularly based on customer
    requests.
  contact:
    name: Alvys Support
    url: https://www.alvys.com/resources/contact/
  version: v1
servers:
  - url: https://integrations.alvys.com
    description: Public API Server
  - url: https://api.alvys.com/
    description: Public API Server
security:
  - Public: []
tags:
  - name: Authentication
    description: Obtain an OAuth 2.0 access token for the Alvys Public API.
  - name: Carrier Settlement Statements
    description: >-
      Search carrier settlement statements and retrieve a single statement by
      number.
  - name: Carriers
    description: Read carrier records, search carriers, and manage carrier documents.
  - name: Customers
    description: Create, read, update, delete, and search customer records.
  - name: Deductions
    description: >-
      Create one-time deductions and search or delete existing deduction
      records.
  - name: DispatchPreferences
    description: Dispatch preferences endpoints for reading dispatch rules and preferences.
  - name: Driver Settlement Statements
    description: >-
      Search driver settlement statements and retrieve a single statement by
      number.
  - name: Drivers
    description: >-
      Read driver records, search drivers and driver events, and manage driver
      documents.
  - name: Fuel
    description: Read and search fuel transactions.
  - name: Invoices
    description: >-
      Read invoices, create carrier invoices, and record carrier and customer
      payments.
  - name: Loads
    description: Read, update, search loads, and manage load documents and notes.
  - name: Locations
    description: Read and search company location details.
  - name: Maintenance
    description: Read and search maintenance records.
  - name: Tenders
    description: Create, accept, reject, cancel, update, and search inbound EDI tenders.
  - name: Tolls
    description: Read and search toll transactions.
  - name: Trailers
    description: Read trailers, search trailer events, and manage trailer documents.
  - name: Trips
    description: >-
      Read, search trips, manage trip documents, and record stop appointments,
      arrivals, and departures.
  - name: Trucks
    description: Read trucks, search truck events, and manage truck documents.
  - name: Users
    description: List and search users.
  - name: Visibility
    description: >-
      Read inbound and outbound visibility history and search outbound
      visibility errors.
  - name: Webhooks
    description: >-
      Create, read, update, delete, enable, disable, verify, test, and rotate
      secrets for webhook subscriptions; read event types, delivery logs, and
      health metrics.
paths:
  /api/p/v{version}/invoices/carrier-invoice:
    post:
      tags:
        - Invoices
      summary: Create carrier invoice
      parameters:
        - name: version
          in: path
          description: API version (e.g., 1.0)
          required: true
          schema:
            type: string
            default: '1.0'
            example: '1.0'
      requestBody:
        content:
          multipart/form-data:
            schema:
              required:
                - File
                - TripId
              type: object
              properties:
                File:
                  type: string
                  format: binary
                TripId:
                  type: string
                CarrierInvoiceNumber:
                  type: string
                PaymentType:
                  type: string
            encoding:
              File:
                allowReserved: true
              TripId:
                allowReserved: true
              CarrierInvoiceNumber:
                allowReserved: true
              PaymentType:
                allowReserved: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Alvys.Models.PublicAPI.AttachmentResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/Microsoft.AspNetCore.Mvc.ValidationProblemDetails
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
        '413':
          description: Content Too Large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
        '415':
          description: Unsupported Media Type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
        '429':
          description: Too Many Requests
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Microsoft.AspNetCore.Mvc.ProblemDetails'
      security:
        - Public: []
components:
  schemas:
    Alvys.Models.PublicAPI.AttachmentResponse:
      required:
        - AttachmentPath
        - AttachmentType
        - id
        - ParentId
        - ParentType
      type: object
      properties:
        id:
          type: string
        AttachmentPath:
          type: string
        AttachmentType:
          type: string
        AttachmentSize:
          type: integer
          format: int64
          nullable: true
        UploadedAt:
          type: string
          format: date-time
          nullable: true
        ParentId:
          type: string
        ParentType:
          type: string
        UploadedBy:
          type: string
          nullable: true
        DownloadUrl:
          type: string
          nullable: true
        ExpiresAt:
          type: string
          format: date-time
          nullable: true
      additionalProperties: false
    Microsoft.AspNetCore.Mvc.ValidationProblemDetails:
      required:
        - Errors
      type: object
      properties:
        Errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
        Type:
          type: string
          nullable: true
        Title:
          type: string
          nullable: true
        Status:
          type: integer
          format: int32
          nullable: true
        Detail:
          type: string
          nullable: true
        Instance:
          type: string
          nullable: true
      additionalProperties: {}
    Microsoft.AspNetCore.Mvc.ProblemDetails:
      type: object
      properties:
        Type:
          type: string
          nullable: true
        Title:
          type: string
          nullable: true
        Status:
          type: integer
          format: int32
          nullable: true
        Detail:
          type: string
          nullable: true
        Instance:
          type: string
          nullable: true
      additionalProperties: {}
  securitySchemes:
    Public:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        OAuth 2.0 client-credentials access token. Obtain one from
        https://auth.alvys.com/oauth/token (grant_type=client_credentials,
        audience=https://api.alvys.com/public/), then paste it here. The
        playground sends it as `Authorization: Bearer <token>`.

````