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

# Create an approved order

> Learn how to create an approved Order in Lucca Invoices

## Steps

Creating an approved Order is done through three distinct calls:

<Steps>
  <Step title="Create a new Purchase" />

  <Step title="Create a Commitment" />

  <Step title="Trigger the approval workflow" />
</Steps>

The order will eventually be created once the approval workflow succeeds, which corresponds to approving the purchase request.

***

## 1. Create a new Purchase

<CodeGroup>
  ```http Create a Purchase theme={null}
  POST /cleemy-procurement/api/purchases HTTPS/2
  Host: example.ilucca.net
  Authorization: lucca application={API_KEY}
  Content-Type: application/json

  {
      "ownerId": 35, // Identifier of the user this purchase belongs to.
      "natureId": 1, // Identifier of the nature of this purchase.
      "costCenterId": 3,// Cost center identifier
      "establishmentId": 1, // Identifier of the business-establishment. Usually the one the owner of this purchase works in.
      "departmentId": 14, // Identifier of the department. Usually the one the owner of this purchase works in.
      "supplier": {
          "id": 6,
          "name": "Amazon",
          "territoryId": "FR"
      },
      "title": "Purchase entry test",
      "axisSectionIds": [361] // Optional, depends on client configuration.
  }
  ```
</CodeGroup>

<Note>Success is indicated by a `201` response status code. If so, the response contains a `purchaseId` which is the identifier of the created Purchase object.</Note>

<Tip>
  File upload is done via the upload API of our file management system (lucca-files). Please [refer to the dedicated documentation](../../files/post-upload).
</Tip>

***

## 2. Create a Commitment

Pleas note a Commitment can be of type "one-time" (i.e. `OneTimeCommitment`) or "recurring" (i.e. `SubscriptionCommitment`). In which case the payload changes slightly.

<CodeGroup>
  ```http Create a OneTimeCommitment theme={null}
  POST /cleemy-procurement/api/commitments HTTPS/2
  Host: example.ilucca.net
  Authorization: lucca application={API_KEY}
  Content-Type: application/json

  {
      "purchaseId": {{purchaseId}}
      "costDate": "2025-04-14", // delivery date
      "invoiceDate": "2025-04-14", // invoice date
      "amountIncludingTaxes": { // amount, with an excluding taxes part and taxes (array by rate)
          "excludingTaxes": {
              "value": 120,
              "currency": "EUR"
          },
          "taxes": [] 
      },
      "type": "OneTimeCommitment", // purchase type, detailed below.
      "attachmentIds": [], // file attached to the purchase request detailed in the annex
      "state": "Created",
      "comment": "Comment",
      "paymentMethod": null // payment method: can be left empty.
  }
  ```

  ```http Create a SubscriptionCommitment (recurring) theme={null}
  POST /cleemy-procurement/api/purchases/{purchaseId}/commitment HTTPS/2
  Host: example.ilucca.net
  Authorization: lucca application={API_KEY}
  Content-Type: application/json

  {
      "startDate": "2025-04-14", // subscription start date 
      "firstInvoiceDate": "2025-04-14", // first invoice date
      "invoicingFrequency": { // invoicing frequency
          "value": 1,
          "unit": "Month" // possible values: Day, Week, Month, Year
      },
      "subscriptionDuration": {
          "value": 12,
          "unit": "Month" // possible values: Day, Week, Month, Year
      },
      "contractualObligation": null, // can be left empty
      "terminationNotice": null, // can be left empty
      "amountIncludingTaxesPerPeriod": {
          "excludingTaxes": {
              "value": 1000,
              "currency": "EUR"
          },
          "taxes": []
      },
      "type": "SubscriptionCommitment",
      "attachmentIds": [],
      "state": "Created",
      "comment": "Comment",
      "paymentMethod": null
  }
  ```
</CodeGroup>

<Accordion title="Retrieve VAT Rates IDs">
  You may retrieve a list of all VAT rates applicable to a given territory at a given date via the tax management service. You will need it to set up the correct VAT rate when creating a Commitment.

  <CodeGroup>
    ```http List taxe rates theme={null}
    GET  /cleemy-procurement/taxes/api/rates?date={date}&territoryId=FR HTTPS/2
    Host: example.ilucca.net
    Authorization: lucca application={API_KEY}
    Accept: application/json
    ```
  </CodeGroup>
</Accordion>

<Note>Success is indicated by a `201` response status code. If so, the response contains a `commitmentId` which is the identifier of the created Commitment object.</Note>

***

## 3. Trigger the approval workflow

<CodeGroup>
  ```http Trigger workflow theme={null}
  POST /cleemy-procurement/api/commitments/{commitmentId}/requests HTTPS/2
  Host: example.ilucca.net
  Authorization: lucca application={API_KEY}
  Content-Length: 0
  ```
</CodeGroup>

<Note>The request body is expected to be empty.</Note>

The system will configure auto-approval of requests so that the order is automatically created at the end of the workflow.

***

## Addendum

<Accordion title="Cancel or Delete a Purchase">
  You may need to cancel or delete a Purchase that was previously created.

  Please note that strictly speaking, a Purchase cannot be deleted (HTTP DELETE requests are not supported), but it can be "closed". A Purchase may only be closed once all invoices related to it have been approved and paid (or just cancelled).

  <CodeGroup>
    ```http Cancel a purchase request theme={null}
    POST /cleemy-procurement/api/requests/{requestId}/cancellations HTTPS/2
    Host: example.ilucca.net
    Authorization: lucca application={API_KEY}
    Content-Type: application/json

    {
        "comment": "Comment"
    }
    ```

    ```http Close a purchase (eq. "delete") theme={null}
    POST /cleemy-procurement/api/purchases/{purchaseId}/closing HTTPS/2
    Host: example.ilucca.net
    Authorization: lucca application={API_KEY}
    Content-Type: application/json

    {
        "comment": "Comment",
        "date": "2025-04-20"
    }
    ```
  </CodeGroup>
</Accordion>