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
cpe_networking_number string CPE networking number No
cpe_serial_number string CPE serial number 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",
  "cpe_network_number": "NET-123456",
  "cpe_serial_number": "SR-123456"
}
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
cpe_networking_number string CPE networking number No
cpe_serial_number string CPE serial number 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",
    "cpe_network_number": "NET-123456",
    "cpe_serial_number": "SR-123456"
}
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
cpe_networking_number string CPE networking number No
cpe_serial_number string CPE serial number 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",
  "cpe_network_number": "NET-123456",
  "cpe_serial_number": "SR-123456"
}
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
cpe_networking_number string CPE networking number No
cpe_serial_number string CPE serial number 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": "",
    "cpe_network_number": "NET-123456",
    "cpe_serial_number": "SR-123456"
}
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.

The cpe_networking_number and cpe_serial_number fields are required if option 7021 is present in option_ids, otherwise they must be empty.

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"
            ],
            "cpe_network_number": "NET-123456",
            "cpe_serial_number": "SR-123456",
            "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
cpe_networking_number string CPE networking number No
cpe_serial_number string CPE serial number 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)