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

# Dates and timestamps

> Business definitions, date formats, timezone rules, and REST/webhook field names.

Dates describe different events. A shipment becoming ready, freight being picked up, an invoice being issued, and money arriving are separate events; do not substitute one date for another.

Each definition lists the entities that own the field and links to an API operation that includes it. An entity may appear inside another response; for example, appointmentEnd belongs to a shipment stop. Some fields are exposed only in create/update inputs, search filters, or webhook payloads. Expand the request or response fields on the linked page to see that context.

## Formats and timezones

| Schema | JSON representation | Meaning |
| - | - | - |
| `date` / `NullableDate` | `"2026-10-16"` | Calendar date (YYYY-MM-DD), without a time or timezone. Do not convert a date-only value through UTC and shift its day. |
| `timestamptz` / `NullableTimestamptz` / `DateTime` | `"2026-10-16T14:30:00Z"` or `"2026-10-16T10:30:00-04:00"` | Timestamp identifying an instant. Include an explicit UTC marker or offset. The returned offset may differ while representing the same instant. |
| `timestamp` | `"2026-10-16T14:30:00"` | Timestamp stored without timezone. An input offset does not survive storage. Keep the originating timezone separately when it matters; do not assume UTC. |

The field's endpoint schema determines its representation. Fields with the same business meaning can have different REST and webhook representations. Stop appointmentTimezone and actualTimezone carry the local scheduling/event context separately.

## Missing values and updates

Omit an optional field on update to leave its value unchanged. Null is a value, not an instruction to use today's date: only send it where the endpoint accepts clearing that field. Do not send an empty string as a date. Requiredness, write access, and defaults are endpoint-specific; an absent date is not evidence that the event occurred.

## REST and webhook names

REST generally uses camelCase; invoice webhook payloads use snake\_case. For example, issue\_date corresponds to issueDate, due\_date to dueDate, ship\_date to shipDate, and sent\_at to sentAt. They link to the same business definitions below. The invoice create/update field is issueDate, not invoiceDate. Vendor invoices and remittance lines have their own invoiceDate field.

## Business and lifecycle definitions

## Issue date

**Field:** `issueDate`

**Entities:** [Bills](/api-reference/bills/get-one-bill); [Carrier invoice webhook payload](/api-reference/webhooks/handle-carrier-invoice-events); [Carrier invoices](/api-reference/carrier-invoices/get-one-carrier-invoice); [Customer invoice webhook payload](/api-reference/webhooks/handles-invoice-events); [Customer invoices](/api-reference/invoices/get-one-invoice).

Date the invoice was issued, as printed on the invoice. This is the invoice date for customer and carrier invoices; creating the Upwell record is a separate event recorded by createdAt.

## Invoice date

**Field:** `invoiceDate`

**Entities:** [Remittance webhook line items](/api-reference/webhooks/handles-remittance-events); [Vendor invoices](/api-reference/vendor-invoices/get-one-vendor-invoice).

Date printed on the vendor invoice, or the invoice date reported on a remittance line. Customer and carrier invoice endpoints call this field issueDate; invoiceDate is not an alias accepted by those endpoints.

## Due date

**Field:** `dueDate`

**Entities:** [Bills](/api-reference/bills/get-one-bill); [Carrier invoice webhook payload](/api-reference/webhooks/handle-carrier-invoice-events); [Carrier invoices](/api-reference/carrier-invoices/get-one-carrier-invoice); [Customer invoice webhook payload](/api-reference/webhooks/handles-invoice-events); [Customer invoices](/api-reference/invoices/get-one-invoice); [Vendor invoices](/api-reference/vendor-invoices/get-one-vendor-invoice).

Date payment is due under the invoice payment terms. Used for accounts-receivable aging and reminders; it is not the shipment delivery date.

## Ready date

**Field:** `readyDate`

**Entities:** [Shipments](/api-reference/shipments/create-one-shipment).

Date the shipment is scheduled to be ready for pickup. This is a readiness/planning date, not confirmation that pickup occurred. Source integrations may populate it from the earliest scheduled pickup date.

## Ship date

**Field:** `shipDate`

**Entities:** [Customer invoice webhook payload](/api-reference/webhooks/handles-invoice-events); [Customer invoices](/api-reference/invoices/create-one-invoice).

Shipping date recorded on the invoice or reported by its source system. It describes the freight movement, not invoice issuance. Source systems may report a planned or actual shipping date; this field alone does not certify actual pickup. Use shipment/stop event timestamps for recorded movement events.

## Delivery date

**Field:** `deliveryDate`

**Entities:** [Customer invoice webhook payload](/api-reference/webhooks/handles-invoice-events); [Customer invoices](/api-reference/invoices/create-one-invoice); [Purchase-order line schedules (schedules\[\])](/api-reference/purchase-orders/get-one-purchase-order).

Freight delivery date recorded on the invoice. On a purchase-order line schedule, the scheduled delivery date of that release. It does not mean the invoice email was delivered; invoice sending is recorded separately by sentAt.

## Pickup at

**Field:** `pickupAt`

**Entities:** [Shipments](/api-reference/shipments/get-one-shipment).

Pickup timestamp recorded for the shipment. A source integration may supply an actual event or a scheduling fallback; inspect stop actualArrival/actualDeparture for explicitly recorded actual events. Distinct from the date-only readyDate.

## Delivered at

**Field:** `deliveredAt`

**Entities:** [Shipments](/api-reference/shipments/get-one-shipment).

Delivery timestamp recorded for the shipment and used by post-delivery invoice workflows. Some creation/import workflows supply a fallback value, so it is not by itself proof of delivery. Distinct from invoice delivery/sending.

## Release date

**Field:** `releaseDate`

**Entities:** [Shipments](/api-reference/shipments/get-one-shipment).

Shipment release/planned-start date supplied by the source system. Some integrations copy readyDate or use the planned load start; it is not a guarantee of actual departure.

## Covered date

**Field:** `coveredDate`

**Entities:** [Shipments](/api-reference/shipments/get-one-shipment).

Date the shipment was recorded as covered by a carrier in the source system. Distinct from dispatch, pickup, and delivery.

## Dispatched date

**Field:** `dispatchedDate`

**Entities:** [Shipments](/api-reference/shipments/get-one-shipment).

Date the shipment was recorded as dispatched in the source system. Dispatch does not confirm physical pickup.

## Loaded date

**Field:** `loadedDate`

**Entities:** [Shipments](/api-reference/shipments/get-one-shipment).

Date the shipment was recorded as loaded in the source system. Distinct from the planned readiness date.

## Billed date

**Field:** `billedDate`

**Entities:** [Shipments](/api-reference/shipments/get-one-shipment).

Date the shipment was recorded as billed in the source system. This shipment lifecycle date need not equal an associated invoice's issueDate.

## Appointment start

**Field:** `appointmentStart`

**Entities:** [Shipment stops](/api-reference/stops/get-one-stop).

Start of the scheduled appointment window at a stop. Use appointmentTimezone to interpret the stop's local scheduling context; this is not an actual arrival event.

## Appointment end

**Field:** `appointmentEnd`

**Entities:** [Shipment stops](/api-reference/stops/get-one-stop).

End of the scheduled appointment window at a stop. Use appointmentTimezone for the local scheduling context; this is not an actual departure event.

## Actual arrival

**Field:** `actualArrival`

**Entities:** [Shipment stops](/api-reference/stops/create-one-stop).

Recorded actual arrival time at a stop. Distinct from appointmentStart, which describes the scheduled window. actualTimezone identifies the local event context.

## Actual departure

**Field:** `actualDeparture`

**Entities:** [Shipment stops](/api-reference/stops/create-one-stop).

Recorded actual departure time from a stop. Distinct from appointmentEnd, which describes the scheduled window. actualTimezone identifies the local event context.

## Paid date

**Field:** `paidDate`

**Entities:** [Customer invoices](/api-reference/invoices/create-one-invoice).

Timestamp recorded for invoice payment. It is separate from individual payment transaction dates and from a scheduled or promised payment date. Determine the outstanding amount from balance and payment records.

## Scheduled payment date

**Field:** `scheduledPaymentDate`

**Entities:** [Customer invoice webhook payload](/api-reference/webhooks/handles-invoice-events); [Customer invoices](/api-reference/invoices/create-one-invoice).

Expected or scheduled date of payment reported for the invoice. It is a forecast, not proof that funds were received.

## Transaction date

**Field:** `transactionDate`

**Entities:** [Bill payments](/api-reference/bill-payments/get-bill-payment); [Carrier payment line items](/api-reference/carrier-payment-line-items/get-one-carrier-payment-line-item); [Customer payment line items](/api-reference/customer-payment-line-items/get-one-customer-payment-line-item); [Customer payments](/api-reference/customer-payments/get-one-customer-payment).

Accounting transaction date recorded on a payment or payment allocation. It can differ from the date printed on a check and the date funds become available at the bank.

## Check date

**Field:** `checkDate`

**Entities:** [Customer payment line items](/api-reference/customer-payment-line-items/get-one-customer-payment-line-item); [Customer payments](/api-reference/customer-payments/get-one-customer-payment).

Date printed on the check or reported by the payment source for the check/ACH remittance. It does not establish when the bank settled the payment.

## Payment date

**Field:** `paymentDate`

**Entities:** [Remittance webhook payload](/api-reference/webhooks/handles-remittance-events).

Payment date reported in the remittance webhook. This reflects the source remittance's payment date, not the webhook delivery time.

## Value date

**Field:** `valueDate`

**Entities:** [Document annotations (purchase orders and vendor invoices)](/api-reference/purchase-orders/get-one-purchase-order).

Date value extracted for a document annotation on a purchase order or vendor invoice, such as a date written beside a signature or stamp. Interpret it with the annotation's fieldLabel, text, and type. It is not inherently a bank settlement date or an invoice issue date.

## Po date

**Field:** `poDate`

**Entities:** [Purchase orders](/api-reference/purchase-orders/get-one-purchase-order).

Date the purchase order was issued, as recorded on the document. Distinct from requested shipment and delivery dates.

## Order date

**Field:** `orderDate`

**Entities:** [Vendor invoices](/api-reference/vendor-invoices/get-one-vendor-invoice).

Order date stated on the purchase order or vendor invoice. This describes the underlying order, not invoice creation in Upwell.

## Revision date

**Field:** `revisionDate`

**Entities:** [Purchase orders](/api-reference/purchase-orders/get-one-purchase-order).

Date of the document revision, as printed on the purchase order. It does not represent the original order date.

## Requested ship date

**Field:** `requestedShipDate`

**Entities:** [Purchase orders](/api-reference/purchase-orders/get-one-purchase-order).

Date the buyer requests goods to be shipped. A requested date is not confirmation that shipment occurred.

## Requested delivery date

**Field:** `requestedDeliveryDate`

**Entities:** [Purchase orders](/api-reference/purchase-orders/get-one-purchase-order); [Purchase-order line items](/api-reference/purchase-orders/get-one-purchase-order).

Date the buyer requests goods or a particular order line to be delivered. A requested date is not confirmation of delivery.

## Promised delivery date

**Field:** `promisedDeliveryDate`

**Entities:** [Purchase-order line items](/api-reference/purchase-orders/get-one-purchase-order).

Delivery date promised or scheduled by the supplier for an order line. Distinct from the buyer's requestedDeliveryDate and actual delivery.

## Cancel after date

**Field:** `cancelAfterDate`

**Entities:** [Purchase orders](/api-reference/purchase-orders/get-one-purchase-order).

Purchase-order cancellation cutoff printed on the document. Recording this date does not itself cancel an order in Upwell.

## Pickup date

**Field:** `pickupDate`

**Entities:** [Purchase orders](/api-reference/purchase-orders/get-one-purchase-order).

Pickup date stated on the source purchase order or vendor document. This document field is distinct from the shipment pickupAt timestamp.

## Shipped date

**Field:** `shippedDate`

**Entities:** [Vendor invoice shipment details (shipmentInfo)](/api-reference/vendor-invoices/update-one-vendor-invoice).

Shipping date printed in a vendor invoice's shipmentInfo block. It reflects the source document rather than an independently observed shipment event.

## Cargo insurance expire date

**Field:** `cargoInsuranceExpireDate`

**Entities:** [Carriers](/api-reference/carriers/get-one-carrier).

Expiration date recorded for the carrier's cargo insurance policy. A populated date is not a verification that coverage is currently valid.

## General liability insurance expire date

**Field:** `generalLiabilityInsuranceExpireDate`

**Entities:** [Carriers](/api-reference/carriers/get-one-carrier).

Expiration date recorded for the carrier's general liability insurance policy. Distinct from cargo and other liability coverage.

## Liability insurance expire date

**Field:** `liabilityInsuranceExpireDate`

**Entities:** [Carriers](/api-reference/carriers/get-one-carrier).

Expiration date recorded for the carrier's liability insurance policy. Consult the policy for coverage details; this field is not a coverage guarantee.

## Automation go live date

**Field:** `automationGoLiveDate`

**Entities:** [Customer automation settings (customerRule)](/api-reference/customers/create-many-customers).

Configured go-live date for customer automation. It is an automation setting, not an invoice issue date or shipment event.

## Created at

**Field:** `createdAt`

**Entities:** [Addresses](/api-reference/addresses/get-one-address); [Bill line items](/api-reference/bill-line-items/create-one-bill-line-item); [Bill payments](/api-reference/bill-payments/get-bill-payment); [Bills](/api-reference/bills/get-one-bill); [Carrier invoice approval requests](/api-reference/carrier-invoice-approval-requests/get-carrier-invoice-approval-request); [Carrier invoice documents](/api-reference/carrier-invoice-documents/get-many-carrier-invoice-documents); [Carrier invoice exceptions](/api-reference/carrier-invoices/approve-one-carrier-invoice); [Carrier invoice webhook event envelope](/api-reference/webhooks/handle-carrier-invoice-events); [Carrier invoice webhook payload](/api-reference/webhooks/handle-carrier-invoice-events); [Carrier invoices](/api-reference/carrier-invoices/get-one-carrier-invoice); [Carrier payment line items](/api-reference/carrier-payment-line-items/get-one-carrier-payment-line-item); [Carriers](/api-reference/carriers/get-one-carrier); [Companies](/api-reference/companies/get-company); [Customer invoice documents](/api-reference/invoice-documents/get-many-invoice-documents); [Customer invoice exceptions](/api-reference/invoice-approval/approve-customer-invoice); [Customer invoice line items](/api-reference/invoice-line-items/create-one-invoice-line-item); [Customer invoice webhook event envelope](/api-reference/webhooks/handles-invoice-events); [Customer invoice webhook payload](/api-reference/webhooks/handles-invoice-events); [Customer invoices](/api-reference/invoices/get-one-invoice); [Customer payment line items](/api-reference/customer-payment-line-items/get-one-customer-payment-line-item); [Customer payments](/api-reference/customer-payments/get-one-customer-payment); [Customers](/api-reference/customers/get-one-customer); [Document reference specifications](/api-reference/document-reference-specifications/get-one-document-reference-specification); [Documents](/api-reference/documents/get-one-document); [Field-update webhook event envelope](/api-reference/webhooks/handle-carrier-invoice-status-approved-events); [Invoice–shipment links](/api-reference/invoice-shipments/link-invoice-to-shipment); [Notes (shipments and carrier invoices)](/api-reference/shipments/create-shipment-note); [Purchase orders](/api-reference/purchase-orders/get-one-purchase-order); [Remittance webhook event envelope](/api-reference/webhooks/handles-remittance-events); [Remittance webhook line items](/api-reference/webhooks/handles-remittance-events); [Remittance webhook payload](/api-reference/webhooks/handles-remittance-events); [Rules](/api-reference/rules/get-one-rule); [Shipment documents](/api-reference/shipment-documents/get-many-shipment-documents); [Shipment line items](/api-reference/shipment-line-items/search-shipment-line-items); [Shipment stops](/api-reference/stops/get-one-stop); [Shipments](/api-reference/shipments/get-one-shipment); [Vendor invoices](/api-reference/vendor-invoices/get-one-vendor-invoice); [Vendors](/api-reference/vendors/get-one-vendor); [Webhook event envelope](/api-reference/webhooks/handle-carrier-invoice-shipment-creation-events).

Timestamp when this record was created in Upwell. It is not the business document date and may be much later when historical data is imported.

## Updated at

**Field:** `updatedAt`

**Entities:** [Addresses](/api-reference/addresses/get-one-address); [Bill line items](/api-reference/bill-line-items/create-one-bill-line-item); [Bill payments](/api-reference/bill-payments/get-bill-payment); [Bills](/api-reference/bills/get-one-bill); [Carrier invoice approval requests](/api-reference/carrier-invoice-approval-requests/get-carrier-invoice-approval-request); [Carrier invoice documents](/api-reference/carrier-invoice-documents/get-many-carrier-invoice-documents); [Carrier invoice exceptions](/api-reference/carrier-invoices/approve-one-carrier-invoice); [Carrier invoice webhook event envelope](/api-reference/webhooks/handle-carrier-invoice-events); [Carrier invoice webhook payload](/api-reference/webhooks/handle-carrier-invoice-events); [Carrier invoices](/api-reference/carrier-invoices/get-one-carrier-invoice); [Carrier payment line items](/api-reference/carrier-payment-line-items/get-one-carrier-payment-line-item); [Carriers](/api-reference/carriers/get-one-carrier); [Companies](/api-reference/companies/get-company); [Customer invoice documents](/api-reference/invoice-documents/get-many-invoice-documents); [Customer invoice exceptions](/api-reference/invoice-approval/approve-customer-invoice); [Customer invoice line items](/api-reference/invoice-line-items/create-one-invoice-line-item); [Customer invoice webhook event envelope](/api-reference/webhooks/handles-invoice-events); [Customer invoice webhook payload](/api-reference/webhooks/handles-invoice-events); [Customer invoices](/api-reference/invoices/get-one-invoice); [Customer payment line items](/api-reference/customer-payment-line-items/get-one-customer-payment-line-item); [Customer payments](/api-reference/customer-payments/get-one-customer-payment); [Customers](/api-reference/customers/get-one-customer); [Document reference specifications](/api-reference/document-reference-specifications/get-one-document-reference-specification); [Field-update webhook event envelope](/api-reference/webhooks/handle-carrier-invoice-status-approved-events); [Remittance webhook event envelope](/api-reference/webhooks/handles-remittance-events); [Remittance webhook line items](/api-reference/webhooks/handles-remittance-events); [Remittance webhook payload](/api-reference/webhooks/handles-remittance-events); [Rules](/api-reference/rules/get-one-rule); [Shipment documents](/api-reference/shipment-documents/get-many-shipment-documents); [Shipment line items](/api-reference/shipment-line-items/search-shipment-line-items); [Shipment stops](/api-reference/stops/get-one-stop); [Shipments](/api-reference/shipments/get-one-shipment); [Vendors](/api-reference/vendors/get-one-vendor); [Webhook event envelope](/api-reference/webhooks/handle-carrier-invoice-shipment-creation-events).

Timestamp of the record's latest recorded update in Upwell. It is not a shipment event, payment date, or document revision date.

## Deleted at

**Field:** `deletedAt`

**Entities:** [Carrier invoice webhook payload](/api-reference/webhooks/handle-carrier-invoice-events); [Carrier invoices](/api-reference/carrier-invoices/update-one-carrier-invoice); [Companies](/api-reference/companies/get-company); [Customers](/api-reference/customers/update-one-customer-by-source-system-id).

Timestamp recorded when the object was marked deleted. A deletion marker is separate from invoice cancellation status.

## Sent at

**Field:** `sentAt`

**Entities:** [Customer invoice webhook payload](/api-reference/webhooks/handles-invoice-events); [Customer invoices](/api-reference/invoices/update-one-invoice-by-source-system-id).

Timestamp recorded for sending the invoice. It does not establish freight delivery or guarantee that the recipient opened or accepted the invoice.

## Received at

**Field:** `receivedAt`

**Entities:** [Carrier invoice webhook payload](/api-reference/webhooks/handle-carrier-invoice-events); [Carrier invoices](/api-reference/carrier-invoices/get-one-carrier-invoice); [Customer invoice webhook payload](/api-reference/webhooks/handles-invoice-events); [Customer invoices](/api-reference/invoices/search-invoices).

Timestamp when the relevant inbound record or document was received. It is not the date printed on that document.

## Pinned at

**Field:** `pinnedAt`

**Entities:** [Notes (shipments and carrier invoices)](/api-reference/shipments/create-one-shipment).

Timestamp when the note was pinned. It is a note-management event rather than a financial or shipment date.

## Scheduled at

**Field:** `scheduledAt`

**Entities:** [Carrier invoice webhook event envelope](/api-reference/webhooks/handle-carrier-invoice-events); [Customer invoice webhook event envelope](/api-reference/webhooks/handles-invoice-events); [Field-update webhook event envelope](/api-reference/webhooks/handle-carrier-invoice-status-approved-events); [Remittance webhook event envelope](/api-reference/webhooks/handles-remittance-events); [Webhook event envelope](/api-reference/webhooks/handle-carrier-invoice-shipment-creation-events).

Timestamp when the asynchronous job is scheduled to run. It is not a promise of completion at that time.

## Processed at

**Field:** `processedAt`

**Entities:** [Carrier invoice webhook event envelope](/api-reference/webhooks/handle-carrier-invoice-events); [Customer invoice webhook event envelope](/api-reference/webhooks/handles-invoice-events); [Field-update webhook event envelope](/api-reference/webhooks/handle-carrier-invoice-status-approved-events); [Remittance webhook event envelope](/api-reference/webhooks/handles-remittance-events); [Webhook event envelope](/api-reference/webhooks/handle-carrier-invoice-shipment-creation-events).

Timestamp recorded for processing the event or job. It is separate from the event's underlying business date.

## Synced at

**Field:** `syncedAt`

**Entities:** [Remittance webhook payload](/api-reference/webhooks/handles-remittance-events).

Timestamp recorded when the synchronization ran. It describes data synchronization, not invoice issuance or shipment movement.

## Exceptions last evaluated at

**Field:** `exceptionsLastEvaluatedAt`

**Entities:** [Carrier invoices](/api-reference/carrier-invoices/get-one-carrier-invoice); [Customer invoices](/api-reference/invoices/get-one-invoice).

Timestamp when the record's exception checks were last evaluated. It is a processing marker, not the date an exception first occurred or was resolved.

## Portal documents uploaded at

**Field:** `portalDocumentsUploadedAt`

**Entities:** [Shipments](/api-reference/shipments/search-shipments).

Timestamp recorded for shipment document upload to the portal. It is not the freight delivery time or invoice issue date.

## Enabled at

**Field:** `enabledAt`

**Entities:** [Customers](/api-reference/customers/search-customers).

Timestamp when the associated feature or workflow was enabled. This lifecycle timestamp does not describe the invoice or shipment itself.

## Final check passed at

**Field:** `finalCheckPassedAt`

**Entities:** [Customer invoices](/api-reference/invoices/search-invoices).

Timestamp when the invoice's final processing check was recorded as passed. It is separate from approval, sending, and payment dates.

## Lifecycle event at

**Field:** `lifecycleEventAt`

**Entities:** [Customer payments](/api-reference/customer-payments/search-customer-payments).

Timestamp recorded for the associated lifecycle event. Interpret it with that event's type rather than treating it as an invoice issue date.

## Debits updated at

**Field:** `debits_updated_at`

**Entities:** [Customer invoice webhook payload](/api-reference/webhooks/handles-invoice-events).

Timestamp when the invoice's debit-related data was updated. This is a change-tracking marker in the webhook payload.

## Documents modified at

**Field:** `documents_modified_at`

**Entities:** [Carrier invoice webhook payload](/api-reference/webhooks/handle-carrier-invoice-events).

Timestamp when the invoice's document data was modified. This is a change-tracking marker, not a document issue date.

## Documents type or customer visibility updated at

**Field:** `documents_type_or_customer_visibility_updated_at`

**Entities:** [Carrier invoice webhook payload](/api-reference/webhooks/handle-carrier-invoice-events).

Timestamp when document classification or customer visibility changed. This is distinct from the document's own issue date.

## File associations updated at

**Field:** `file_associations_updated_at`

**Entities:** [Customer invoice webhook payload](/api-reference/webhooks/handles-invoice-events).

Timestamp when the invoice's file associations changed. It tracks attachment links rather than invoice issuance.

## Line items last updated at

**Field:** `line_items_last_updated_at`

**Entities:** [Customer invoice webhook payload](/api-reference/webhooks/handles-invoice-events).

Timestamp when invoice line-item data was last updated. It is a change-tracking marker rather than a financial transaction date.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.