Marketplaces / Colizey Technical Scope / Colizey - Order Management / Colizey - Download Orders

Colizey - Download Orders

Summary of Changes: (The purpose of this table is to keep traceability and Product team to highlight the things that were changed into the scope, based on comments or discussions)

Date	Version	Editor	Comment
31/08/2022	1.1		details regarding the initial run of cron added; Note for prices added;
01/08/2022	1.2		`status` field correted with the right field ;
The note for prices applied to the other fields that consist price amount
05/09/2022	1.3		New fields for Billing/Shipping street 3; Some mapping fields were edited;
07/09/2022	1.4		Added some more clarifications based on a comments; Order status table statuses changed
08/09/2022	1.5		Status changes applied based on discussion on the estimation; Added info for refund status.
15/09/2022	1.6	Bogomil Pavlov	Vat mapping changed as per

             [HEMISPHERE-15801](https://hemi.atlassian.net/browse/HEMISPHERE-15801)
                -
        Getting issue details...
                                STATUS |

| 19/10/2022 | 1.7 | Bogomil Pavlov | Latest update from Colizey states we wont be receiving MP VAT so the mapping is updated. | | 07/11/2022 | 1.8 | Bogomil Pavlov | Change mapping for quantity to be original_quantity | | 23/01/2023 | 1.9 | Danail Deltchev | Change in mapping for order total in Hemi from payload (instead of price to use originalPrice) |

The purpose of this page is to describe in details how we will download order on Colizey MP.

The flow is straight forward - first we need to obtain all orders, using “List Order“ API call, and then to get all related information for order, like shipping info, payment method info, products in order information, and all the other information, related to order, using “Get Order“ API call.

Seems that Colizey supports partial refunds, as they have provided in their documentation Order line statuses as per the abstraction Order management general requirements .

Also, we need to make sure we download order and store them in Hemi with the respective order status.

If the order not exist in Hemi we will download the order on the respectively status in Hemi. Once we have downloaded the order and the order exist in Hemi, we need to check the status of the order and to check if the order status can be changed, according to order status on the marketplace.

If we download order on status “New“ (Incomplete in Hemi), we should store this order and to call it periodically in order to catch when the status will be modified, i.e. the order to become on status “Paid“, respectively in Hemi - “Pending“. This is important because we need to make sure we will store the orders in Hemi on statuses as on the marketplace. Once the status of the order is “Paid“ (Pending status in Hemi) and to proceed with the fulfillment of the order we must first Accept the order, using the Accept Order API. Once accepted, the order status should be “Accepted“ (Ready for Shipping in Hemi);

If we download the orders on status different from “New“ & “Paid“, we need to make sure we will store the order with the respective MP status as per the table below.

Please find below the Colizey order statuses & order line statuses mapped to our internal Hemi statuses and also, a picture of the flow

Order statuses:

	Colizey Order Status	Colizey Notes	Hemi Order Statuses	Hemi Notes
1	New - 0	An order has been made, but is not already paid	Pending	We need to set Order > Is Acknowledged to “Pending”
2	PAID - 1	The order has been paid	Pending	We need to set Order > Is Acknowledged to “Pending”
3	Accepted - 2	The merchant has accepted the order	Ready For Shipping	We need to set Order > Is Acknowledged to “Completed”
4	Proceed - 3	All order lines have been shipped	Shipped	We need to set Order > Is Acknowledged to “Completed”
5	Refused - 4	The merchant did not accept the order	Cancelled	We need to set Order > Is Acknowledged to “Completed”
6	Cancelled - 5	The order has been canceled : all items have been refund before shipping	Cancelled	We need to set Order > Is Acknowledged to “Completed”

Colizey Order Status Flow:

Legend:

A blue arrow means that Colizey makes the transition.

A green arrow means that the Merchant makes the transition.

A plain arrow ―― means the transition should be applied on the corresponding object.

A dashed arrow - - - - means the transition is applied automatically after you have made the corresponding transition on the parent/child object.

Order Line statuses:

	Colizey Order Status	Colizey Notes	Hemi Order Line Statuses	Hemi Notes
1	New - 0	An order has been made, but is not already paid	Incomplete
2	PAID - 1	The order has been paid	Pending	The status will be RFS again, but bear in mind, we are not allowed to ship order which was not accepted!!!
3	ACCEPTED - 2	The order item is accepted, should be shipped afterwards	Ready For Shipping
4	REFUSED - 3	The order item is not accepted	Cancelled
5	REFUNDED BEFORE SHIPPING - 4	The order item is refunded before shipping (stock mistake, client changes his mind...)	Cancelled
6	SHIPPED - 5	The order is shipped	Shipped
7	REFUNDED AFTER SHIPPING -6	The order is refunded after shipping (problem with shipping, legal 14 day period...)	Cancelled
8	CANCELED - 7	Order has been canceled before merchant approval or denial	Cancelled
9	PAYMENT REFUSED - 8	Payment for all items has been refused	Cancelled

Colizey Order Line Status Flow:

List order

Returns a list of orders. Orders are sorted by creation date, the last orders first.

Basically, to download orders, first we need to make “List Order“ API call.

Seems that into the payload for each order node we receive UpdatedAt parameter, which indicate we can have only 1 cron for downloading orders (i.e. without separating crons to get new & get modified orders). To do this we need to specify the parameted dateType=update

*Note: During tests we have noticed we receive all related order information within the response of List order call. But our assumption here is this is valid only for paid orders (into the sandbox account test orders were with status=paid). In order to be on the safe side, we will implement both calls List orders & Get orders at this stage. As a standard, we would want to download all orders on respective status! Based on the information we have at current stage, we need to bear in mind if we perform List order and we receive unpaid order, maybe we will have empty fields and in such case we do not want those missing fields (the fields we are using for some calculations for example) to block the order script BUT in such case we need to store the available info from the order and the cron to continue downloading the others orders.

The very first cron run will check for new orders in the last 90 days and afterwards (once we have stored the orders) we will get the date from last_date_run table and filter orders using parameter:

from - {last_date_run - 1 hours}

API Call: GET **https://api.colizey.fr/merchant/orders

(For sandbox testing please use https://api.sandbox.colizey.fr/merchant/orders)

API Docs: https://apidoc.colizey.fr/?php#list-orders

Parameters:

Paramter	Type	Required	Description	Hemi Notes
from	DateTime	no	Only select orders since this from date included.
dateType	string	no	Enum create or update to filter on creation or update date. Default is create.	In order to have only 1 cron (without implementing cron for modified order, we will set the dateType=update and will look at DateUpdatedAt

Example response:

[
    {
        "id": "a50b9957-ac24-435d-ad1c-145390ae1e46",
        "date": "2022-07-28T08:35:25+00:00",
        "clientFirstName": "",
        "clientLastName": "",
        "clientCreatedAt": "2018-11-07T14:40:58+00:00",
        "clientId": "44829359-6c77-480e-b793-f85df9199308",
        "orderNumber": "CLZ2207962152",
        "price": 5000,
        "originalPrice": 5000,
        "billingAddress": {
            "id": "7743b6c9-bb59-4f61-8ee0-be63eec0b01f",
            "firstName": "Hubert",
            "lastName": "Bonisseur de La Bath",
            "company": "DGSE",
            "street": "141, boulevard Mortier",
            "street2": "",
            "street3": "",
            "postcode": "75020",
            "city": "Paris",
            "countryCode": "FR",
            "phoneNumber": "0123456789",
            "splitStreet": [
                "141, boulevard Mortier"
            ],
            "state": "Île-de-France",
            "email": "client-clz2207962152dd@colizey.com"
        },
        "status": 1,
        "dateShipped": null,
        "orderLines": [
            {
                "id": "3a5a8d9a-0e50-11ed-8471-42010a840002",
                "sku": "sku_1",
                "original_quantity": 1,
                "refunded_quantity": 0,
                "quantity": 1,
                "itemPrice": 5000,
                "productDescription": "Test Order2",
                "status": 1,
                "merchant_product_id": 5733,
                "vatRate": 0,
                "vatAmount": 0,
                "customMerchantId": ""
            }
        ],
        "shippingMethod": "Mondial Relay",
        "shippingPrice": 0,
        "shippingTrackingNumber": null,
        "shippingTrackingUrl": null,
        "shippingAddress": {
            "firstName": "Hubert",
            "lastName": "Bonisseur de La Bath",
            "phoneNumber": "0123456789",
            "id": "eba0c23b-a74f-40ba-85b5-bdab62d2da6f",
            "company": "La Post",
            "street": "rue du Louvre",
            "street2": "",
            "street3": "",
            "postcode": "75001",
            "city": "Paris",
            "countryCode": "FR",
            "splitStreet": [
                "rue du Louvre"
            ],
            "state": "Île-de-France",
            "email": "client-clz2207962152dd@colizey.com"
        },
        "shippingType": "relay",
        "shippingIsRelay": true,
        "shippingIsAtHome": false,
        "shippingRelayId": "1234",
        "shippingRelayProvider": "Mondial Relay",
        "shippingRelayProviderId": "e5246b74-04ee-4b6a-9bb2-362a4da9d255",
        "returns": [],
        "partialRefunds": [],
        "updatedAt": "2022-07-28T08:35:27+00:00",
        "downloadDeliveryNoteLink": "https://api.sandbox.colizey.fr/merchant/orders/a50b9957-ac24-435d-ad1c-145390ae1e46/delivery-note/download"
    }

Mapping:

Integration Field		Type	Integration Notes	Hemi Mapping	Hemi Notes
`id`		uuid	Order id	Orders > Marketplace Order ID
`date`		DateTime	Creation date	Orders > Order Created Time
`orderNumber`		string	Colizey order number for display	Order > Selling Manager SalesRecordNumber
`price`		integer	Total current order price	N/A
`originalPrice`		integer	Total original price, before refunds if any	Orders > Оrder Тotal Аmount	As we will receive only integers, but we could not store integers in our field and as per Colizey confirmation “Prices are in cents, and will always be integers. No floats. No digit point. Just numbers. 123,45€ will be sent as 12345.“ We need to divide by 100 the price we will receive into the response before we save it into Hemi
New 23.01.2023 - remapping this field - instead of `price` we are using `originalPrice`
`billingAddress`			Billing address
	`id`			N/A
	`firstName`	string	First name	Orders > Billing Name	Concatenate with Last Name
	`lastName`	string	Last name	Orders > Billing Name	Concatenate with First Name
	`company`	string	Company	Orders >Billing Details > Company name
	`street`	string	Street - 1st line	Orders > Billing Street 1	If we have info here, we will store & send it. If we have info filled in Billing Street 2 but not in Billing Street 1, we will store the info from Billing Street 2 into Billing Street 1.
	`street2`	string	Street - 2nd line	Orders > Billing Street 2
	`street3`	string	Street - 3rd line	Orders > Billing Street 3	Concatenate with Billing Street 2 field
	`postcode`	string	Postal code	Orders > Billing Postal Code
	`state`	string	State	Orders > Billing State Province
	`city`	string	City	Orders > Billing City Name
	`countryCode`	string	2-chars Country ISO 3166 Code	Orders > Billing Country Code
	`phoneNumber`	string	Phone number, with international prefix	Orders > Billing Phone
	`email`			Orders > Buyer mail	We can take it from shipping node too.
The value filled into `billingAddress` is with priority
`status`		integer	Order status	Orders>Marketplace Status

AND Orders > Order Status | We will receive the integers, but better to save and display the strings as follow: New; Paid; Accepted; Refused; Proceed; Cancelled In Orders > Order Status we need to map Colizey’s statuses to our internal statuses. Please see the mapping table above (“Order statuses“) | | dateShipped | | | DateTime or null | Shipping date | Orders > Shipping Shipped Date | To decide how we will store the data into the field | | orderLines | | | OrderLine[] | Items in order (see OrderLine) | | | | | id | | uuid | Order line id | Product in Order > Item Order Line ID | We should use the sku to determine which lines are for which order item. Also we will receive the exact count lines as quantities.

Note: Because of the way we are receiving qty we will store this value into Item Order Line ID | | | sku | | string | Item unique identifier for the merchant | Product in Order > SKU | | | | quantity | | integer | The quantity of items that should be shipped, and that do not have been returned. | N/A | | | | original_quantity | | integer | The quantity the client has ordered before any return. | Product in Order > Quantity | | | | refunded_quantity | | integer | The quantity the client has returned. | TBD see Hemi Notes column | Based on a quantity, we need to calculate the quantity of returned item the price of the item and to store the result in Order Refund Row > Amount | | | itemPrice | | integer | Price of a single item | Product in Order >Item Price | As we will receive only integers, but we could not store integers in our field and as per Colizey confirmation “Prices are in cents, and will always be integers. No floats. No digit point. Just numbers. 123,45€ will be sent as 12345.“* We need to divide by 100 the price we will receive into the response before we save it into Hem | | | productDescription | | string | Description of what the product is (usually merchant title for product) | Product in Order >Item Title | | | | status | | integer | Order line status | Product in Order > Status AND Order Item Line > Marketplace Status | We would to visualize and save the string values. And also, we can visualized as follow: New; Paid; Accepted; Refused; Refunded Before Shipping; Shipped; Refunded After Shipping; Cancelled; Payment Refused;

Once we download an order, we should always create a payment record (we should always threat an order as paid, unless the status of order is ”New”). As per abstraction: Order management general requirements

Into the response, we will receive if there is refunded item(s) (As you can see from the payload and the mapping).

If there is no refunded item, we will simply receive returns[].

If there is a refunded item(s) we will receive all related information regarding the returned item (the SKU & Quantity). In case we receive a refund information, we need to update the status of the order, to fill out refunded so far sum.

If there is a partial refund we need to update the statuses of the order items, to fill out refunded so far sum, payment statuses to be updated

Basically, when we download refunds from the MP, we would need to implement the logic and requirements described into the abstraction: Refund Row Lines. The Refunds which we are downloading from the MP and store in Hemi should be on status “Completed“. Based on the status mapping (Please see he table with order line statuses at the beginning of the scope) we update our tool status.

NOT APPLICABLE!!! DO NOT READ IT PLEASE!

Get Order - N/A at this stage

Please note that this call might not be part of the scope if we are going to receive all order information within the Get Order List response. As we do not have any confirmation from Colizey, Get Order call will remain into the scope!!

Using the order ID, which we have stored in Marketplace Order ID, we are able to get related order information.

API Call: GET https://api.colizey.fr/merchant/orders/{orderId}

API Docs: https://apidoc.colizey.fr/?shell#get-an-order

Example response:

{
    "id": "df899a54-a7b7-4b88-bcd6-e8b5f904b13d",
    "date": "2018-10-30T14:53:33+00:00",
    "orderNumber": "CLZ1811839998",
    "price": 1090,
    "originalPrice": 1090,
    "billingAddress": {
        "id": "4f7661f4-9613-4fba-89ad-421dcf2916c6",
        "firstName": "Hubert",
        "lastName": "Bonisseur de La Bath",
        "company": "DGSE",
        "street": "141, boulevard Mortier",
        "street2": "",
        "street3": "",
        "postcode": "75020",
        "state": "Ile de france",
        "city": "Paris",
        "countryCode": "FR",
        "phoneNumber": "",
        "email":,
    },
    "status": 0,
    "dateShipped": null,
    "orderLines": [
        {
            "id": "9260bf42-dc53-11e8-bab5-6ee62b314dc6",
            "sku": "sku2",
            "quantity": 2,
            "original_quantity": 2,
            "refunded_quantity": 0,
            "itemPrice": 200,
            "productDescription": "2\u20ac short",
            "status": 0,
            "merchant_product_id": 5733,
            "vatRate": 0,
            "vatAmount": 0,
            "customMerchantId": ""
        }
    ],
    "shippingMethod": null,
    "shippingRelayId": null,
    "shippingPrice": 590,
    "shippingTrackingNumber": null,
    "shippingTrackingUrl": null,
    "shippingLocationId": null,
    "shippingAddress": {
        "id": "4f7661f4-9613-4fba-89ad-421dcf2916c6",
        "firstName": "Hubert",
        "lastName": "Bonisseur de La Bath",
        "company": "DGSE",
        "street": "141, boulevard Mortier",
        "street2": "",
        "street3": "",
        "postcode": "75020",
        "state": "Ile de france",
        "city": "Paris",
        "countryCode": "FR",
        "phoneNumber": "",
        "email":,
    },
    "returns": [
      {
        "id": "cd309b03-f277-cf9f-5a62-d9d327d1d227",
        "date": "1972-08-02T00:52:36.158Z",
        "lineReturns": [
          {
            "id": "urn:uuid:8a248f97-e341-8ee6-213d-d851eb6a3e2f",
            "sku": "tempor",
            "quantity": 26209744
          },
          {
            "id": "urn:uuid:8f7529b9-f786-59ee-c69d-33cad57b5bbc",
            "sku": "eiusmod sunt amet ea",
            "quantity": -45968868
          }
        ]
      },
      {
        "id": "urn:uuid:65b63a93-8d79-7129-ff4b-05f7709afd20",
        "date": "1982-06-21T11:44:25.228Z",
        "lineReturns": [
          {
            "id": "aa4f6f18-c46a-c776-3401-b219e120d71e",
            "sku": "non",
            "quantity": 16167969
          },
          {
            "id": "95420302-f506-cd3f-e318-0dac53e0e759",
            "sku": "ut deserunt nostrud labore",
            "quantity": 5066306
          }
        ]
      }
    ],
    "partialRefunds": [
     {
        "id": "urn:uuid:b52611d4-89ae-b437-32fe-6112536ec1a5",
        "description": "voluptate",
        "amount": -60921988,
        "commission": -73063269,
        "date": "1992-02-02T06:13:38.128Z"
      }
      ],
    "updatedAt": null
}

Mapping is the same as the mapping given in Get Order List call above

Is this article helpful?

0 0 0