Light APIv1.0.0

API / Reference / Purchase Orders

Create purchase order

POST https://api.light.inc/v1/purchase-orders

Creates a new purchase order

Nothing is required at creation — vendor, entity, owner and even lines may be empty; everything is checked at lock. At most 500 lines (PURCHASE_ORDER_LINES_COUNT_EXCEEDED). unitPrice is net; per-line taxAmount is computed from taxCodeId only once the order has a companyEntityId, and cannot be overridden. Most response fields marked required below are null on a fresh draft. States: IN_DRAFT → lock → APPROVED_ACCOUNTING_ENTRY_PENDING → OPEN (in the background, when the ERP confirms; erpNumber and documentKey appear then) → close → CLOSE_PENDING → CLOSED, or cancel → CANCEL_PENDING → CANCELLED, or reset → RESET_PENDING → IN_DRAFT. A wrong-state call fails with PURCHASE_ORDER_INVALID_STATE_TRANSITION.

Authorization

Send one of these on every request. See Authentication for how to get credentials.

  • API key

    Basic authentication header of the form Basic <api_key>, where <api_key> is your api key.

  • Bearer token

Request body

application/json;charset=UTF-8

  • vendorId string · uuid

  • companyEntityId string · uuid

  • ownerId string · uuid

  • currency string

  • purchaseOrderDate string · date

  • deliveryAddress string

  • deliveryDate string · date

  • description string

  • lines array of object

    • description string

    • costCenterId string · uuid

    • accountId string · uuid

    • taxCodeId string · uuid

    • quantity number

    • unitPrice integer · int64

    • customProperties array of object

      • groupId string · uuid

        ID of the custom property group.

      • valueIds array of string · uuid

        IDs of the selected custom property values. It behaves as a PUT operation, so if empty the existing ones will be effectively deleted.

        Catalogue value ids for this group. Required; send [] (with an empty inlineValues) to clear the group. SINGLE_SELECT and MULTI_SELECT groups accept nothing else. See Custom properties on writes.

      • inlineValues array of string

        Inline custom property values (used for TEXT/NUMERIC/DATE/etc. groups). It behaves as a PUT operation, so if empty or null the existing ones will be effectively deleted.

        Literal values for TEXT, NUMERIC, BOOLEAN and DATE groups, as strings (yyyy-MM-dd for dates). Rejected on select groups with CUSTOM_PROPERTY_VALUE_TYPE_MISMATCH. See Custom properties on writes.

  • customProperties array of object

    • groupId string · uuid

      ID of the custom property group.

    • valueIds array of string · uuid

      IDs of the selected custom property values. It behaves as a PUT operation, so if empty the existing ones will be effectively deleted.

      Catalogue value ids for this group. Required; send [] (with an empty inlineValues) to clear the group. SINGLE_SELECT and MULTI_SELECT groups accept nothing else. See Custom properties on writes.

    • inlineValues array of string

      Inline custom property values (used for TEXT/NUMERIC/DATE/etc. groups). It behaves as a PUT operation, so if empty or null the existing ones will be effectively deleted.

      Literal values for TEXT, NUMERIC, BOOLEAN and DATE groups, as strings (yyyy-MM-dd for dates). Rejected on select groups with CUSTOM_PROPERTY_VALUE_TYPE_MISMATCH. See Custom properties on writes.

Response

  • id string · uuid

  • companyId string · uuid

  • createdBy string · uuid

  • companyEntityId string · uuid

  • purchaseRequestId string · uuid

  • state string

    ⚠️ This enum is not exhaustive; new values may be added in the future.

    One of IN_DRAFT RESET_PENDING APPROVED_ACCOUNTING_ENTRY_PENDING OPEN CLOSE_PENDING CLOSED CANCEL_PENDING CANCELLED

  • totalAmount integer · int64

  • totalNetAmount integer · int64

  • totalTaxAmount integer · int64

  • erpNumber string

    Assigned when the order reaches OPEN, after the ERP confirms the lock in the background; null before that.

  • description string

  • currency string

  • ownerId string · uuid

  • vendorId string · uuid

  • vendorEmail string

  • deliveryAddress string

  • deliveryDate string · date

  • documentKey string

  • failureContext object

    Failure context when vendor onboarding fails.

    • name string

      The error name

    • type string

      The error type

      ⚠️ This enum is not exhaustive; new values may be added in the future.

      One of BAD_REQUEST UNAUTHORIZED FORBIDDEN NOT_FOUND CONFLICT UNPROCESSABLE_CONTENT

    • errors array of object

      List of errors providing details about what went wrong

      • type string

        A string code identifying the error type

      • message string

        A human-readable message providing more details about the error

      • path array of string

        Optional path of the error when the error is for a specific field. Used mostly on BAD_REQUEST errors, that path will match the field name on the request object

      • context object

        Optional context providing additional information about the error. This can include any relevant data that might help in understanding or resolving the error

  • editStatus string

    ⚠️ This enum is not exhaustive; new values may be added in the future.

    ALL_EDITS_LOCKED from lock onwards; CORE_EDITS_LOCKED on drafts created from a purchase request (vendor, entity, currency, line quantities and prices, and adding or removing lines are frozen). Not returned by the list endpoint.

    One of ALL_EDITS_ALLOWED ALL_EDITS_LOCKED CORE_EDITS_LOCKED

  • purchaseOrderDate string · date

  • erpSyncedAt string · date-time

  • lockedAt string · date-time

  • closedAt string · date-time

  • cancelledAt string · date-time

  • createdAt string · date-time

  • updatedAt string · date-time

  • lines array of object

    • id string · uuid

    • companyId string · uuid

    • purchaseOrderId string · uuid

    • description string

    • costCenterId string · uuid

    • accountId string · uuid

    • taxCodeId string · uuid

    • quantity number

    • unitPrice integer · int64

    • amount integer · int64

    • netAmount integer · int64

    • createdAt string · date-time

    • updatedAt string · date-time

    • customProperties array of object

      • groupId string · uuid

        ID of the custom property group

      • groupInternalName string

        Internal name of the custom property group

      • values array of object

        List of values. Note that this will be a single value unless the group input type supports multiple values

        • id string · uuid

          Unique identifier for the object

        • groupId string · uuid

          ID of the custom property group

        • groupInternalName string

          Internal name of the custom property group

        • companyId string · uuid

          ID of the company

        • internalName string

          Internal name of the custom property value

        • label string

          Label of the custom property value

        • context string

          Context/description of the custom property value

        • createdAt string · date-time

          Timestamp when the custom property value was created

        • updatedAt string · date-time

          Timestamp when the custom property value was last updated

  • customProperties array of object

    • groupId string · uuid

      ID of the custom property group

    • groupInternalName string

      Internal name of the custom property group

    • values array of object

      List of values. Note that this will be a single value unless the group input type supports multiple values

      • id string · uuid

        Unique identifier for the object

      • groupId string · uuid

        ID of the custom property group

      • groupInternalName string

        Internal name of the custom property group

      • companyId string · uuid

        ID of the company

      • internalName string

        Internal name of the custom property value

      • label string

        Label of the custom property value

      • context string

        Context/description of the custom property value

      • createdAt string · date-time

        Timestamp when the custom property value was created

      • updatedAt string · date-time

        Timestamp when the custom property value was last updated