Skip to content

Order Taking

Operation

sequenceDiagram participant Client participant Covage API participant Covage Backend Client ->> Covage API: Create an order session Covage API -->> Client: Retrieve the order session ID Client ->> Covage API: Create an order line Covage API -->> Client: Retrieve the order line ID Client ->> Covage API: Update the order line information Covage API -->> Client: Confirm the order line update Client ->> Covage API: Confirm the order session Covage API -->> Client: Confirm the order receipt Covage API ->> Covage Backend: Create the order Covage Backend -->> Covage API: Confirm the order

Lifecycle of an order session

flowchart LR A[<a href='/en/api-prise-commande/#creating-an-order-session'>Creation of an order session</a>] -->B(created) B -->C[<a href='/en/api-prise-commande/#confirming-the-order-session'>Confirmation of the order session</a>] C -->D(in_progress) D -->E{Were all order lines created ?} E -->|yes| F[completed] E -->G{Is at least one line created ?} G -->|yes| H[partial] G -->|no| I[rejected]

Lifecycle of an order line

flowchart LR A[<a href='/en/api-prise-commande/#creating-an-order-line'>Creating an order line</a>] -->B(created) B -->C[<a href='/en/api-prise-commande/#confirming-the-order-session'>Confirmation of the order line</a>] C -->D(in_progress) D -->E{Was the order created ?} E -->|yes| F[acknowledged\nheld_adv_validation\nin_progress] style F text-align:left E -->|no| G[rejected_creation]

Creating an Order Session

Once the order sesion has been created, one or many order lines can be added.

POST /api/v1/product_order

Request Field Parameters

Name Type Description Required
external_id string External identifier for the request No
project_id string Associated project identifier No
Example
{
  "external_id": "12345",
  "project_id": ""
}

Response

Name Type Description Required
external_id string External identifier for the request No
project_id string Associated project identifier No
id string Order identifier Yes
creation_date string Order creation date Yes
cancellation_date string Order cancellation date No
completion_date string Order completion date No
order_date string Order date Yes
state string Current state of the order Yes
Example
{
    "external_id": "12345",
    "project_id": "",
    "id": "0b10ba8a-3c31-44ba-a758-d178ec0bb166",
    "creation_date": "2025-04-10T12:11:57.548+02:00",
    "cancellation_date": null,
    "completion_date": null,
    "order_date": null,
    "state": "created"
}

Creating an Order Line

During an order line creation, some non-required fields become required during the order session confirmation. It becomes necessary to fill them beforehand by updating the order line.

POST /api/v1/product_order/{id}/product_order_item

Request Field Parameters

Name Type Description Required
end_customer_name string End customer name No
external_id string External identifier for the request No
option_ids array List of option identifiers No
note string Note associated with the order No
technical_note string Technical note associated with the order No
product_offering_id string Product offering identifier Yes
product_offering_qualification_item_id string Product offering qualification item identifier Yes
project_id string Associated project identifier No
quote_item_id string Quote item identifier No
delivery_mode string Delivery mode No
enni string ENNI identifier Yes (during confirmation only*)
enni_2 string Secondary ENNI identifier No
vlan_reference number VLAN reference No
customer_order_name string Customer order name No
business_code string Business code No
billing_site_ref string Billing site reference No
related_contact_information array Related contact information Yes (during confirmation only)
siret_known boolean Should the SIRET be filled ? No
additional_vlan_reference string Additional VLAN reference No
offer_family string Offer's family No
offer_technology string Offer's technology No
specific_request string Specific request No
access_instructions string Access instructions given by the customer No
scheduled_delivery_date date Scheduled delivery date No
Special case of the enni field for the DIA offer

The enni field should not be filled in for the DIA offer: if it is filled in, it will be replaced by the value calculated by our system.

Example
{
  "end_customer_name": "Covage",
  "external_id": "6789",
  "option_ids": [...],
  "note": "",
  "technical_note": "",
  "product_offering_id": "2173",
  "product_offering_qualification_item_id":"{eligibility_id}",
  "project_id": "",
  "quote_item_id": "{quote_id}",
  "delivery_mode": "",
  "enni": "AZ001234",
  "enni2": "",
  "vlan_reference": "1257",
  "customer_order_name": "john Doe",
  "business_code": "AB123",
  "billing_site_ref": "AUX99",
  "related_contact_information": [...],
  "siret_known": true,
  "additional_vlan_reference": "1258",
  "offer_family": "BPE",
  "offer_technology": "FIBDE",
  "specific_request": "Demande de raccordement spécifique",
  "access_instructions": "Prendre la grande porte",
  "scheduled_delivery_date": "2025-09-21"
}
Name Type Description Required
end_customer_name string End customer name Yes (during confirmation only)
siret string SIRET number No
contact1_email_address string On-site contact email address Yes (during confirmation only)
contact1_firstname string On-site contact firstname Yes (during confirmation only)
contact1_lastname string On-site contact name Yes (during confirmation only)
contact1_phone_number string On-site contact phone number Yes (during confirmation only)
contact2_email_address string Secondary contact email address No
contact2_firstname string Secondary contact firstname No
contact2_lastname string Secondary contact name No
contact2_phone_number string Secondary contact phone number No
city string City Yes (during confirmation only)
postcode string Postal code Yes (during confirmation only)
street_name string Street name Yes (during confirmation only)
street_number string Street number Yes (during confirmation only)
street_number_extension string Street number extension No
insee_code string INSEE code Yes (during confirmation only)
building_name string Building name No
level_number string Level number No
latitude number Address latitude No
longitude number Address longitude No
Example
"related_contact_information": [
    {
      "end_customer_name": "Covage corp",
      "siret": "00000000000000",
      "contact1_email_address": "John.Doe@unknown.com",
      "contact1_firstname": "John",
      "contact1_lastname": "Doe",
      "contact1_phone_number": "0123456789",
      "contact2_email_address": "Jane.Doe@unknown.com",
      "contact2_firstname": "Jane",
      "contact2_lastname": "Doe",
      "contact2_phone_number": "0987654321",
      "city": "Mont-Saint-Aignan",
      "postcode": "76130",
      "street_name": "Rue Andrei Sakharov",
      "street_number": "4",
      "street_number_extension": "B",
      "insee_code": "76451",
      "building_name": "",
      "level_number": "0",
      "latitude": 49.4744077,
      "longitude": 1.091455
    }]

Response

Name Type Description Required
end_customer_name string End customer name No
external_id string External identifier for the request No
option_ids array List of option identifiers No
note string Note associated with the order No
technical_note string Technical note associated with the order No
product_offering_id string Product offering identifier Yes
product_offering_qualification_item_id string Product offering qualification item identifier Yes
project_id string Associated project identifier No
quote_item_id string Quote item identifier No
delivery_mode string Delivery mode No
enni string ENNI identifier No
enni_2 string Secondary ENNI identifier No
vlan_reference number VLAN reference No
business_code string Business code No
customer_order_name string Customer order name No
related_contact_information array Related contact information No
id string Order identifier Yes
cancellation_date string Order cancellation date No
cancellation_reason string Cancellation reason No
completion_date string Order completion date No
order_date string Order date No
state string Current state of the order Yes
state_change array State change history No
termination_error array Associated termination errors No
order_reference string Order reference No
temporary_reference string Order temporary reference No
building_ref string Building reference No
offer_family string Offer family No
offer_technology string Offer technology No
Exemple
{
    "end_customer_name": "Covage",
    "external_id": "",
    "option_ids": [],
    "note": "",
    "technical_note": "",
    "product_offering_id": "2173",
    "product_offering_qualification_item_id": "d5a4a9aa-ba2c-4f53-95c7-0c1ce6f6e7fa",
    "project_id": "",
    "quote_item_id": "",
    "delivery_mode": "",
    "enni": "",
    "enni2": "",
    "vlan_reference": 1257,
    "customer_order_name": "john Doe",
    "business_code": "",
    "billing_site_ref": "AUX00",
    "related_contact_information": [
        {
            "end_customer_name": "Covage corp",
            "siret": "00000000000000",
            "contact1_email_address": "John.Doe@unknown.com",
            "contact1_firstname": "John",
            "contact1_lastname": "Doe",
            "contact1_phone_number": "0123456789",
            "contact2_email_address": "Jane.Doe@unknown.com",
            "contact2_firstname": "Jane",
            "contact2_lastname": "Doe",
            "contact2_phone_number": "0987654321",
            "city": "Mont-Saint-Aignan",
            "postcode": "76130",
            "street_name": "Rue Andrei Sakharov",
            "street_number": "4",
            "street_number_extension": "B",
            "insee_code": "76451",
            "building_name": "",
            "level_number": "0",
            "latitude": 49.4744077,
            "longitude": 1.091455
        }
    ],
    "id": "259a1c5b-8462-4c5e-90d0-90d135763378",
    "product_order_id": "908d2cc0-4bdc-4f62-b812-f8c1f48c96cd",
    "cancellation_date": null,
    "cancellation_reason": "",
    "completion_date": null,
    "order_date": null,
    "state": "created",
    "state_change": [
        {
            "change_reason": "",
            "change_date": "2025-04-23T10:13:08.733+02:00",
            "state": "created"
        }
    ],
    "termination_error": [],
    "order_reference": "",
    "temporary_reference": "PO_DC173_20250423_003363",
    "building_ref": "",
    "offer_family": "BPE",
    "offer_technology": "FIBDE"
}
Name Type Description Required
end_customer_name string End customer name Yes
siret string SIRET number Yes
contact1_email_address string On-site contact email address Yes
contact1_firstname string On-site contact firstname Yes
contact1_lastname string On-site contact name Yes
contact1_phone_number string On-site contact phone number Yes
contact2_email_address string Secondary contact email address No
contact2_firstname string Secondary contact firstname No
contact2_lastname string Secondary contact name No
contact2_phone_number string Secondary contact phone number No
city string City Yes
postcode string Postal code Yes
street_name string Street name Yes
street_number string Street number Yes
street_number_extension string Street number extension No
insee_code string INSEE code Yes
building_name string Building name No
level_number string Level number No
latitude number Address latitude Yes
longitude number Address longitude Yes

State Change Details

Name Type Description Required
change_reason string State change reason Yes
change_date string State change date Yes
state string New state Yes

Termination Error Details

Name Type Description Required
code string Error code Yes
property_path string Concerned property path Yes
value string Associated value Yes
Exemple
"termination_error": [
    {
    "code":"string",
    "property_path":"string",
    "value":"string"
    }
]

Updating Order Line Information

PATCH /api/v1/product_order/{id}/product_order_item/{item_id}

Request Field Parameters

Name Type Description Required
end_customer_name string End customer name No
external_id string External identifier for the request No
option_ids array List of option identifiers No
note string Note associated with the order No
technical_note string Technical note associated with the order No
product_offering_id string Product offering identifier No
product_offering_qualification_item_id string Product offering qualification item identifier No
project_id string Associated project identifier No
quote_item_id string Quote item identifier No
delivery_mode string Delivery mode No
enni string ENNI identifier Yes (during confirmation only*)
enni_2 string Secondary ENNI identifier No
vlan_reference number VLAN reference No
customer_order_name string Customer order name No
business_code string Business code No
billing_site_ref string Billing site reference No
related_contact_information array Related contact information Yes (during confirmation only)
siret_known boolean Should the SIRET be filled ? No
additional_vlan_reference string Additional VLAN reference No
specific_request string Specific request No
access_instructions string Access instructions given by the customer No
scheduled_delivery_date date Scheduled delivery date No
Exemple
{
  "product_offering_id": "b99fce70-d195-41ed-b029-9b75c62ecd7c",
  "product_offering_qualification_item_id": "1b83a456-89a2-456e-9b78-a578c39b0474",
  "end_customer_name": "Covage corp edited",
  "external_id": "99999",
  "option_ids": [],
  "note": "you can add any information here",
  "technical_note": "you can add any technical information here",
  "project_id": "56789",
  "quote_item_id": "c0b5c9ab-c206-4858-8957-3befa6cbe58a",
  "delivery_mode": "string",
  "enni": "string",
  "enni2": "string",
  "vlan_reference": "1234",
  "customer_order_name": "John Doe",
  "business_code": "FLASH",
  "related_contact_information": [...],
  "siret_known": true,
  "specific_request": "Demande de raccordement spécifique"
}
Name Type Description Required
end_customer_name string End customer name Yes (during confirmation only)
siret string SIRET number No
contact1_email_address string On-site contact email address Yes (during confirmation only)
contact1_firstname string On-site contact firstname Yes (during confirmation only)
contact1_lastname string On-site contact name Yes (during confirmation only)
contact1_phone_number string On-site contact phone number Yes (during confirmation only)
contact2_email_address string Secondary contact email address No
contact2_firstname string Secondary contact firstname No
contact2_lastname string Secondary contact name No
contact2_phone_number string Secondary contact phone number No
city string City Yes (during confirmation only)
postcode string Postal code Yes (during confirmation only)
street_name string Street name Yes (during confirmation only)
street_number string Street number Yes (during confirmation only)
street_number_extension string Street number extension No
insee_code string INSEE code Yes (during confirmation only)
building_name string Building name No
level_number string Level number No
latitude number Address latitude No
longitude number Address longitude No

Response

Name Type Description Required
end_customer_name string End customer name No
external_id string External identifier for the request No
option_ids array List of option identifiers No
note string Note associated with the order No
technical_note string Technical note associated with the order No
product_offering_id string Product offering identifier Yes
product_offering_qualification_item_id string Product offering qualification item identifier Yes
project_id string Associated project identifier No
quote_item_id string Quote item identifier No
delivery_mode string Delivery mode No
enni string ENNI identifier No
enni_2 string Seconday ENNI identifier No
vlan_reference number VLAN reference No
customer_order_name string Customer order name No
business_code string Business code No
related_contact_information array Related contact information No
id string Order identifier Yes
cancellation_date string Order cancellation date No
cancellation_reason string Cancellation reason No
completion_date string Order completion date No
order_date string Order date No
state string Current state of the order Yes
state_change array State change history No
termination_error array Associated termination errors No
order_reference string Order reference No
temporary_reference string Order line temporary reference No
building_ref string Building reference No
Exemple
{
    "end_customer_name": "Covage",
    "external_id": "",
    "option_ids": [],
    "note": "",
    "technical_note": "",
    "product_offering_id": "2173",
    "product_offering_qualification_item_id": "1b83a456-89a2-456e-9b78-a578c39b0474",
    "project_id": "",
    "quote_item_id": "",
    "delivery_mode": "",
    "enni": "",
    "enni2": "",
    "vlan_reference": 1257,
    "customer_order_name": "john Doe",
    "business_code": "",
    "billing_site_ref": "",
    "related_contact_information": [...],
    "id": "764a778c-4b16-4502-8377-e817b93d5b08",
    "product_order_id": "2144c9f2-6ac1-49fd-8a7d-905def231857",
    "cancellation_date": null,
    "cancellation_reason": "",
    "completion_date": null,
    "order_date": null,
    "state": "created",
    "state_change": [...],
    "termination_error": [],
    "order_reference": "",
    "temporary_reference": "PO_DG541_20250404_000001",
    "building_ref": "",
}
Name Type Description Required
end_customer_name string End customer name Yes
siret string SIRET number Yes
contact1_email_address string On-site contact email address Yes
contact1_firstname string On-site contact firstname Yes
contact1_lastname string On-site contact name Yes
contact1_phone_number string On-site contact phone number Yes
contact2_email_address string Secondary contact email address No
contact2_firstname string Secondary contact firstname No
contact2_lastname string Secondary contact name No
contact2_phone_number string Secondary contact phone number No
city string City Yes
postcode string Postal code Yes
street_name string Street name Yes
street_number string Street number Yes
street_number_extension string Street number extension No
insee_code string INSEE code Yes
building_name string Building name No
level_number string Level number No
latitude number Address latitude Yes
longitude number Address longitude Yes
Exemple
    {
        "end_customer_name": "Covage corp",
        "siret": "00000000000000",
        "contact1_email_address": "John.Doe@unknown.com",
        "contact1_firstname": "John",
        "contact1_lastname": "Doe",
        "contact1_phone_number": "0123456789",
        "contact2_email_address": "Jane.Doe@unknown.com",
        "contact2_firstname": "Jane",
        "contact2_lastname": "Doe",
        "contact2_phone_number": "0987654321",
        "city": "Mont-Saint-Aignan",
        "postcode": "76130",
        "street_name": "Rue Andrei Sakharov",
        "street_number": "4",
        "street_number_extension": "B",
        "insee_code": "76451",
        "building_name": "",
        "level_number": "0",
        "latitude": 49.4744077,
        "longitude": 1.091455
    }

State Change Details

Name Type Description Required
change_reason string State change reason Yes
change_date string State change date Yes
state string New state Yes
Exemple
    {
        "change_reason": "",
        "change_date": "2025-04-04T11:30:47.475+02:00",
        "state": "created"
    }

Termination Error Details

Name Type Description Required
code string Error code Yes
property_path string Concerned property path Yes
value string Associated value Yes

Deleting order line

This endpoint allows you to delete an order line from an order session.

DELETE /api/product_order/{product_order_id}/product_order_item/{item_id}/

Request Field Parameters

Name Type Description Required
product_order_id string Order Session Identifier Yes
item_id string Offer Qualification Item Identifier Yes

Response

Name Type Description Required
external_id string Request's external identifier No
project_id string Related project's identifier No
id string Order identifier Yes
product_order_item array List of order items Yes
Example
{
    "external_id": "444555666777",
    "project_id": "",
    "id": "f12c54b3-881b-48e0-9c96-fea9b2597967",
    "product_order_item": []
}

Confirming the Order Session

Confirming the order session starts the creation of the orders from the order lines stored within the order session.

It's then possible to follow the state of those newly created order (except the ones with status rejected_creation) with the Order Tracking API.

PATCH /api/v1/product_order/{id}/confirm/

Response

Name Type Description Required
external_id string External identifier for the request No
project_id string Associated project identifier No
id string Order identifier Yes
product_order_item array List of order items Yes
Exemple
{
    "external_id": "777888999",
    "project_id": "",
    "id": "908d2cc0-4bdc-4f62-b812-f8c1f48c96cd",
    "product_order_item": [
        {
            "end_customer_name": "Covage",
            "external_id": "",
            "option_ids": [
                "2210",
                "2220",
                "1615"
            ],
            "note": "",
            "technical_note": "",
            "product_offering_id": "2173",
            "product_offering_qualification_item_id": "d5a4a9aa-ba2c-4f53-95c7-0c1ce6f6e7fa",
            "project_id": "",
            "quote_item_id": "",
            "delivery_mode": "",
            "enni": "",
            "enni2": "",
            "vlan_reference": 1257,
            "customer_order_name": "john Doe",
            "business_code": "",
            "billing_site_ref": "AUX00",
            "related_contact_information": [
                {
                    "end_customer_name": "Covage corp",
                    "siret": "00000000000000",
                    "contact1_email_address": "John.Doe@unknown.com",
                    "contact1_firstname": "John",
                    "contact1_lastname": "Doe",
                    "contact1_phone_number": "0123456789",
                    "contact2_email_address": "Jane.Doe@unknown.com",
                    "contact2_firstname": "Jane",
                    "contact2_lastname": "Doe",
                    "contact2_phone_number": "0987654321",
                    "city": "Mont-Saint-Aignan",
                    "postcode": "76130",
                    "street_name": "Rue Andrei Sakharov",
                    "street_number": "4",
                    "street_number_extension": "B",
                    "insee_code": "76451",
                    "building_name": "",
                    "level_number": "0",
                    "latitude": 49.4744077,
                    "longitude": 1.091455
                }
            ],
            "id": "259a1c5b-8462-4c5e-90d0-90d135763378",
            "product_order_id": "908d2cc0-4bdc-4f62-b812-f8c1f48c96cd",
            "cancellation_date": null,
            "cancellation_reason": "",
            "completion_date": null,
            "order_date": null,
            "state": "in_progress",
            "state_change": [
                {
                    "change_reason": "",
                    "change_date": "2025-04-23T10:13:08.733+02:00",
                    "state": "created"
                },
                {
                    "change_reason": "",
                    "change_date": "2025-04-23T10:24:57.225+02:00",
                    "state": "in_progress"
                }
            ],
            "termination_error": [],
            "order_reference": "",
            "temporary_reference": "PO_DC173_20250423_003363",
            "building_ref": ""
        }
    ]
}

Order Item Details

Name Type Description Required
end_customer_name string End customer name No
external_id string External identifier for the request No
option_ids array List of option identifiers No
note string Note associated with the order No
technical_note string Technical note associated with the order No
product_offering_id string Product offering identifier Yes
product_offering_qualification_item_id string Product offering qualification item identifier Yes
project_id string Associated project identifier No
quote_item_id string Quote item identifier No
delivery_mode string Delivery mode No
enni string ENNI identifier No
enni_2 string Seconday ENNI identifier No
vlan_reference number VLAN reference No
customer_order_name string Customer order name No
business_code string Business code No
related_contact_information array Related contact information No
id string Order identifier Yes
cancellation_date string Order cancellation date No
cancellation_reason string Cancellation reason No
completion_date string Order completion date No
order_date string Order date No
state string Current state of the order Yes
state_change array State change history No
termination_error array Associated termination errors No
order_reference string Order reference No
temporary_reference string Order's temporary reference No
building_ref string Building reference No
Name Type Description Required
end_customer_name string End customer name Yes
siret string SIRET number Yes
contact1_email_address string On-site contact email address Yes
contact1_firstname string On-site contact firstname Yes
contact1_lastname string On-site contact name Yes
contact1_phone_number string On-site contact phone number Yes
contact2_email_address string Secondary contact email address No
contact2_firstname string Secondary contact firstname No
contact2_lastname string Secondary contact name No
contact2_phone_number string Secondary contact phone number No
city string City Yes
postcode string Postal code Yes
street_name string Street name Yes
street_number string Street number Yes
street_number_extension string Street number extension No
insee_code string INSEE code Yes
building_name string Building name No
level_number string Level number No
latitude number Address latitude Yes
longitude number Address longitude Yes

State Change Details

Name Type Description Required
change_reason string State change reason Yes
change_date string State change date Yes
state string New state Yes

Termination Error Details

Name Type Description Required
code string Error code Yes
property_path string Concerned property path Yes
value string Associated value Yes

Exporting order sessions

The process for exporting order sessions consists of three steps:

1. Starting the CSV export

POST /api/v1/product_order/export/csv/

Starts the export of order sessions to the CSV format. This operation is limited to one request every 5 minutes per user.

Response

Field Type Description
task_id string Export task's identifier

Response

{ 
    "task_id": "550e8400-e29b-41d4-a716-446655440000" 
}

2. Checking statuses

GET /api/v1/product_order/export/{task_id}/status/

Allows you to check on the status of export tasks

Request Field Parameters

Parameter Type Description
task_id string Export task's identifier

Response

Field Type Description
task_id string Export task's identifier
success boolean Task's status (null if it's still on-going)
started datetime Start date
stopped datetime End date

The success field in the response can have three distinct values:

Value Description
null The task is still on-going or hasn't started yet
true Task complete. The CSV file is available for download
false Task failed.

Response

{
    "task_id": "550e8400-e29b-41d4-a716-446655440000",
    "success": true,
    "started": "2025-07-08T10:30:00Z",
    "stopped": "2025-07-08T10:31:00Z"
}

3. Downloading the file

GET /api/v1/product_order/export/{task_id}/download/

Downloads the generated CSV file after exporting is complete

Request Field Parameters

Parameter Type Description
task_id string Export task's identifier

Response

CSV file containing the exported data.

Response Headers

Header Value
Content-Type text/csv

Error details

HTTP Code Description
401 User lacks authentication
403 Permission denied
404 Task or file not found
429 Too many requests (rate limit reached)