NAV Navbar
shell php

Introduction

Welcome to Colizey, the marketplace dedicated to sports.

This api contains documentation on Product information update and Orders.

API Usage

Authentication

To authorize, use this code:

curl "api_endpoint_here" \
  -H "x-apikey: xxxxxxxxxxxxxx"

Make sure to replace xxxxxxxxxxxxxx with your API key.

Colizey uses a custom header x-apikey that should contain the API key.

x-apikey: xxxxxxxxxxxxxx

⚠️ Prices are integers

Generic formats definitions

This is the description of some common formats that the API uses.

uuid format

Example : 6a7935b7-dbfe-4dd6-a582-ffeb86ffd947

The uuid is a 36-bytes string representing a GUID.

DateTime format

Example : 2018-01-01T14:28:56+02:00

The DateTime format is the date/time format used in all the API. It is ISO 8601 date time format.

Array parameters in query

Array parameters should follow the OpenAPI Simple Style, which is just a comma-separated value.

Examples :

Parameters in body

All operations that support application/json content type also support application/x-www-form-urlencoded content type as well.

OpenAPI support

curl https://api.colizey.fr/merchant/api

An OpenAPI v3 JSON configuration file can be downloaded for production or sandbox.

For more information on OpenAPI, you can go to the following links :

Products

Global feed processing

A merchant has only one feed. A merchant can :

Category and attributes mapping

All products will be linked to a leaf category of Colizey categories tree.

Some attributes are mandatory, whereas some others are optional. If Colizey team must be able determine some mandatory attributes values.

Orders

An order consists on a basket of items, represented by OrderLine and shipping information.

Each OrderLine references a single product and variant, using sku attribute, with a quantity (integer) and a single price.

The shipping information contains shipping method, price and address.

The total order price corresponds to the sum of shippingPrice and, foreach OrderLine, the itemPrice multiplied by the quantity.

Order has both id and order number. If possible, prefer order number, which is unique too and more human-readable.

Order status definitions

Order status workflow

Order workflow

status definition
0 NEW An order has been made, but is not already paid
1 PAID The order has been paid
2 ACCEPTED The merchant has accepted the order
3 PROCESSED All order lines have been shipped
4 REFUSED The merchant did not accept the order
6 CANCELED The order has been canceled : all items have been refund before shipping

Legends

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 status definitions

Order line status workflow

Order line workflow

status definition
0 NEW The order is new, so is the item.
1 PAID The order has been paid, so is the item.
2 ACCEPTED The order item is accepted, should be shipped afterwards
3 REFUSED The order item is not accepted
4 REFUNDED BEFORE SHIPPING The order item is refunded before shipping (stock mistake, client changes his mind...)
5 SHIPPED The order is shipped
6 REFUNDED AFTER SHIPPING The order is refunded after shipping (problem with shipping, legal 14 day period...)
7 CANCELED Order has been canceled before merchant approval or denial
8 PAYMENT REFUSED Payment for all items has been refused

Refund workflow

The merchant can refund the order before or after the shipping. Multiple refunds can be made. Every time, a refund is represented by an OrderReturn object, containing one or more OrderLineReturn objects.

When a return is made, the quantity in the OrderLine is changed so that is is adjusted to what the consumer should still have in his possession at the end.

Order return diagram

Additionnaly, you can interact with your customers using the Messenger API.

Products API

The product API is asynchronous. All calls will respond a 201 Created status, with a report id.

Product input

Multiple formats are allowed for body input when you want to push products.

You can choose between JSON or File input.

See Products to see how product feeds are handled.

When products are submitted, new products will be validated before going online. If a product already exists, then it will be updated.

File Input

You can push a file, as long as it is always the same format. As long as the Content-Type header is not application/json, input will be treated as a file.

curl "https://api.colizey.fr/merchant/products/1?flush=true" \
  -H "x-apikey: xxxxxxxxxxxxxx" \
  -H "content-type: text/uri-list" \
  -d "https://my.shop/feeds/colizey.csv" \
  -X POST

Push an url

You can also push an url : to do so, just set the Content-Type header to text/uri-list.

❌ Partial updates

Batch processing

curl "https://api.colizey.fr/merchant/products/1?flush=true" \
  -H "x-apikey: xxxxxxxxxxxxxx" \
  -H "content-type: text/csv" \
  -d "@catalogue.csv" \
  -X POST

Response example :

HTTP/2.0 201 Created
Content-type: application/json

"import-process-id"

To post an url :

curl "https://api.colizey.fr/merchant/products/1?flush=true" \
  -H "x-apikey: xxxxxxxxxxxxxx" \
  -H "content-type: text/uri-list" \
  -d "https://mydomain.com/myfeed.csv" \

Products creations, updates and deletions are on the same endpoint. You can pass an extra query parameter flush to deal with deletion.

parameter type description
feed string The feed id. Set it to 1.
flush bool If true, then all products with a stock at 0 and those that are not found in the submitted file but present in Colizey database will be removed. Default false.
resetPublication bool If true, it will reset the publication status of all products. Default false.

Response

If successful, the API call will return a 201 status code, with the id of the feed import process.

Publish a product

curl "https://api.colizey.fr/merchant/products/publish" \
  -H "x-apikey: xxxxxxxxxxxxxx" \
  -H 'Content-Type: application/json' \
  -d '["sku1", "sku2", "sku3"]'

Example response

HTTP/2.0 204 No Content

You can publish products that are currently unpublished.

The only parameter is an array of SKUs (string)

⚠️ Note that all SKUs needs to be in the same format as the ones provided on your feed.

Unpublish a product

curl "https://api.colizey.fr/merchant/products/unpublish" \
  -H "x-apikey: xxxxxxxxxxxxxx" \
  -H 'Content-Type: application/json' \
  -d '["sku1", "sku2", "sku3"]'

Example response

HTTP/2.0 204 No Content

You can unpublish products that are currently published.

The only parameter is an array of SKUs (string)

⚠️ Note that all SKUs needs to be in the same format as the ones provided on your feed.

List of online SKUs object

curl "https://api.colizey.fr/merchant/skus" \
  -H "x-apikey: xxxxxxxxxxxxxx"

Example response

{
  "id": "75856bf2-15e3-4016-b429-deb3628fd59b",
  "downloadLink": "https://api.colizey.fr/merchant/skus/latest/download",
  "count": 4242,
  "buyboxWonPct": 4200,
  "date": "2020-01-06T14:21:51+00:00"
}
field type description
id uuid id of the resource
downloadLink string Products online export download link
count integer Product count
buyboxWonPct integer Buybox won percentage per ten thousands
availableExtensions array An array of strings representing the available formats
date DateTime Creation date

Download list of online SKUs

curl "https://api.colizey.fr/merchant/skus/latest/download?format=<format>" \
  -H "x-apikey: xxxxxxxxxxxxxx"

You can choose the format of the export by passing a format query parameter:

Available formats
xlsx (default)
csv

You can retrieve the latest export of your SKUs online in excel format or in csv format.

Response

If successful, the API call will return a 200 status code, with the content of latest export in excel format.

column name description
product_id Item identifier for Colizey (many SKUs can have the same product id)
brand Brand name
sku Item unique identifier for the merchant
name Merchant title for product
price Product price
original_price Product original price
price_with_shipping Product price with shipping
buy-box Merchant product wins the buy box (yes/no)
sku_in_competition Merchant product is in competition with other (yes/no)
best_price_with_shipping Sum of the best price and the best shipping price
link The product link
category The product category
delivery_time Delivery time of the product (-1: delivery time unavailable)
ean EAN
free_return Is free return (yes/no)
stock Product stock

Get last error report

curl "https://api.colizey.fr/merchant/articles/error/report" \
  -H "x-apikey: xxxxxxxxxxxxxx"

Example response

{
    "reportId": "ced54be6-6573-4b7c-863f-a5909da5f9e1",
    "createdAt": "2022-06-29T15:34:30+00:00"
}

You can retrieve the last product error report id and creation date.

Download last error report

curl "https://api.colizey.fr/merchant/articles/error/report/download" \
  -H "x-apikey: xxxxxxxxxxxxxx"

Additionally, you can download the last product error report as a CSV file.

Order API

Order object

Example

{
    "id": "df899a54-a7b7-4b88-bcd6-e8b5f904b13d",
    "date": "2018-10-30T14:53:33+00:00",
    "locale": "fr",
    "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": ""
    },
    "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
        },
        {
            "id": "9260bde4-dc53-11e8-b654-6ee62b314dc6",
            "sku": "sku1",
            "quantity": 1,
            "original_quantity": 1,
            "refunded_quantity": 0,
            "itemPrice": 100,
            "productDescription": "1\u20ac tee-shirt",
            "status": 0
        }
    ],
    "shippingMethod": null,
    "shippingMethodId": 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": ""
    },
    "shippingLabel": {
        "canGenerateShippingLabel": false,
        "item": {
          "createdAt": "2024-03-11T10:34:18+00:00",
          "id": "uuid",
          "trackingNumber": "XSxxxxxxxxxFR",
          "trackingUrl": null
        },
        "shippingLabelLink": "https://api.colizey.fr/merchant/orders/uuid/shipping-labels/uuid/download?key=key",
    },
    "returns": [],
    "updatedAt": null
}
field type description
id uuid Order id
date DateTime Creation date
locale string fr for FR and BE countries, or it for IT country
orderNumber string Colizey order number for display
price integer Total current order price
originalPrice integer Total original price, before refunds if any
billingAddress Address Billing address
status integer Order status
dateShipped DateTime or null Shipping date
orderLines OrderLine[] Items in order (see OrderLine)
shippingMethod string Shipping method
shippingMethodId string Shipping method id
shippingRelayId string or null Shipping relay id, for specified shippingMethod
shippingPrice integer Shipping price
shippingLocationId string or null Pickup location id
shippingTrackingNumber string or null Tracking number
shippingTrackingUrl string or null Tracking url
shippingAddress Address Shipping address
returns OrderReturn[] Order return, if any
shippingLabel ShippingLabel Shipping label object, contact Colizey for further details
updatedAt DateTime or null Last update date. Is updated each time the order is modified : accepted, refused, partially/totally refunded, shipped.

OrderLine object

field type description
id uuid Order line id
sku string Item unique identifier for the merchant
quantity integer The quantity of items that should be shipped, and that do not have been returned.
itemPrice integer Price of a single item
original_quantity integer The quantity the client has ordered before any return.
refunded_quantity integer The quantity the client has returned.
productDescription string Description of what the product is (usually merchant title for product)
status integer Order line status

OrderReturn object

This describes the OrderReturn object :

field type description
id uuid Order return id
date DateTime Creation date
lineReturns OrderLineReturn[] List of OrderLineReturn.
refundedShipping integer Amount of refunded shipping

OrderLineReturn object

This description the OrderLineReturn object :

field type description
id uuid Order line return id
sku string Item unique identifier for the merchant
quantity integer The quantity of items that should be shipped, or that do not have been returned.

Address object

Example

{
    "firstName": "John",
    "lastName": "Doe",
    "company": "Sportmium",
    "street": "35, rue des chantiers",
    "street2": "",
    "street3": "",
    "postcode": "78000",
    "state": "Ile de france",
    "city": "Versailles",
    "countryCode": "FR",
    "email": "email@colizey.fr",
    "phoneNumber": "+3312873465"
}
field type description
firstName string First name
lastName string Last name
company string Company
street string Street - 1st line
street2 string Street - 2nd line
street3 string Street - 3rd line
postcode string Postal code
state string State
city string City
countryCode string 2-chars Country ISO 3166 Code
email string Contact email
phoneNumber string Phone number, with international prefix

Orders refund reasons

Here are the following refund reasons:

Refund code
stock_issue
customer_return
bad_address
unable_to_deliver
lost_package
defective_product
guarantee
colizey_guarantee
bad_description
other

List orders

# Do not forget to set your apikey, your orderId and your action.
curl "https://api.colizey.fr/merchant/orders" \
  -H "x-apikey: xxxxxxxxxxxxxx"

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

parameters type required Description
limit integer no The maximum number of items to send back. Default is 500.
offset integer no The start offset, used for pagination. Default is 0.
status integer[] no Only select specified status. See status enum list.
You can provide multiple statuses by following the simple style of OpenAPI.
from DateTime no Only select orders since this from date included.
to DateTime no Only select orders until this to date included.
dateType string no Enum create or update to filter on creation or update date. Default is create.
locale string no Enum fr or it to filter by geographic region.

Get an order

curl "https://api.colizey.fr/merchant/orders/{orderId}" \
  -H "x-apikey: xxxxxxxxxxxxxx"

You can retrieve an Order given its id.

Accept a paid order

curl "https://api.colizey.fr/merchant/orders/{orderId}/accept" \
  -H "x-apikey: xxxxxxxxxxxxxx" \
  -X POST \
  -d ""

You can accept a paid order.

If the order is not in the PAID state, then the API will send back a 400 error.

You can afterwards refund some of the lines before shipping.

Refuse a paid order

curl "https://api.colizey.fr/merchant/orders/{orderId}/refuse" \
  -H "x-apikey: xxxxxxxxxxxxxx"
  -X POST \
  -d ""

You can refuse a paid order.

If the order is not in the PAID state, then the API will send back a 400 error.

Ship an accepted order

# Do not forget to set your apikey, your orderId and your action.

# Simple call with only a tracking url & number
curl "https://api.colizey.fr/merchant/orders/{orderId}/ship" \
  -H "x-apikey: xxxxxxxxxxxxxx" \
  -d "trackingUrl=REPLACE_TRACKING_URL" \
  -d "trackingNumber=REPLACE_TRACKING_NUMBER" \
  -X POST

# Another example with a raw payload, with a shipper id and a specific item
curl "https://api.colizey.fr/merchant/orders/{orderId}/ship" \
  -H "content-type: application/json" \
  -H "x-apikey: xxxxxxxxxxxxxx" \
  -X POST \
  -d '{
        "trackingUrl": "https://tracking.url",
        "trackingNumber": "123456789",
        "shipperId": "940a543d-a3c9-43b2-a10a-80777e514d44",
        "items": [
          {
              "sku":"123456",
              "quantity": 1
          }
        ]
      }'

You must ship an accepted order (unless you refund everything before shipping).

If the order is not in the ACCEPTED state, then the API will send back a 400 error.

parameters type required Description
trackingUrl string no Carrier-url for tracking information
trackingNumber string no Carrier tracking number
shipperId uuid no Shipper that will handle the package. Check the shipping carriers. Note that if you don't provide one, the one on your default shipping configuration will be automatically used.
items array no An array of objects representing a pair of required sku/quantity fields that will be added to the parcel. Note that you cannot send twice the same product or more than its quantity that exists in the order. If nothing is provided, then every products will be added to the parcel.

Refund an order

# Do not forget to set your apikey, your orderId and your action.
curl "https://api.colizey.fr/merchant/orders/{orderId}/refund?refundedShipping=null" \
  -H "content-type: application/json" \
  -H "x-apikey: xxxxxxxxxxxxxx" \
  -X POST \
  -d '[{"sku":"sku1","quantity":1,"reason":"customer_return"}]'

Returns the id of the return, which can be retrieve through the order.

"25780e5b-035b-4fbe-a29d-e85eea0fd867"
parameters in type required Description
refundShipping query boolean or null no Whether to refund shipping or not. If true, shipping will be refunded. If false, shipping will not be refunded. If null, then shipping is refunded only if all products are refunded or returned. Default is null.
lines body array yes An array of objects representing sku/quantity/reason that should be returned. Default is an empty array []. See refund reasons here.

If no line is provided AND refundShipping is null, then all the order will be refund.

If no quantity is provided for an sku, then all the quantity for this sku will be refund.

A refund call must refund at least one quantity, or refund shipping.

When refundShipping is null, then :

When refundShipping is false, then you should at least provide one line to refund.

When refundShipping is true, then there should be something to refund, either the shipping itself, or you provided one item to refund, or both.

The API will send a 400 response :

List order document files

# Do not forget to set your apikey, your orderId and your action.
curl "https://api.colizey.fr/merchant/orders/{orderId}/documents" \
  -H "content-type: application/json" \
  -H "x-apikey: xxxxxxxxxxxxxx"

# OR

curl "https://api.colizey.fr/merchant/orders/{orderId}/documents?type=invoice" \
  -H "content-type: application/json" \
  -H "x-apikey: xxxxxxxxxxxxxx"

Returns an array of the order document file objects

[
      {
            "id": "uuid",
            "name": "original-filename",
            "type": "invoice",
            "created_at": "2023-09-01T02:00:00+00:00"
      },
      {
            "id": "uuid",
            "name": "original-filename",
            "type": "credit-note",
            "created_at": "2023-09-01T02:20:00+00:00"
      }
]
parameters in type required Description
type query string no Available values: [invoice,credit-note]. Default is null.

The API will send a 400 response :

Add an order document file

# Do not forget to set your apikey, your orderId and your action.
curl "https://api.colizey.fr/merchant/orders/{orderId}/documents" \
  -X 'POST' \
  -H 'accept: application/json' \
  -H "x-apikey: xxxxxxxxxxxxxx" \
  -H 'Content-Type: multipart/form-data' \
  -F 'type=xxxxxxxxxxxxxx' \
  -F 'file=@filepath'

Returns the order document file object

{
  "id": "uuid",
  "name": "original-filename",
  "type": "credit-note",
  "created_at": "2023-09-01T02:20:00+00:00"
}
parameters in type required Description
type query string yes Available values: [invoice,credit-note]

The API will send a 404 response :

Delete an order document file

# Do not forget to set your apikey, your orderId, your documentId and your action.
curl "https://api.colizey.fr/merchant/orders/{orderId}/documents/{documentId}" \
  -X 'DELETE' \
  -H 'accept: application/json' \
  -H "x-apikey: xxxxxxxxxxxxxx"

Returns an OK response

{}

You can retrieve the ID of the document to delete in List order document files.

The API will send a 400 response :

Download an order document file

# Do not forget to set your apikey, your orderId, your documentId and your action.
curl "https://api.colizey.fr/merchant/orders/{orderId}/documents/{documentId}/download" \
  -H 'accept: */*' \
  -H "x-apikey: xxxxxxxxxxxxxx"

Returns the file and x-suggested-filename header

After making this API call, you will receive the file as a response. You can save the file locally using the filename suggested in the 'x-suggested-filename' header.

You can retrieve the ID of the document to download in List order document files.

The API will send a 400 response :

Merchant API

Who am I ?

curl "https://api.colizey.fr/merchant/me" \
  -H "x-apikey: xxxxxxxxxxxxxx"

Example response

{
    "id": 1,
    "name": "Colizey"
}

If you need to know who you are, you can use this endpoint.

Shipping carriers

curl "https://api.colizey.fr/merchant/v2/shippers" \
  -H "x-apikey: xxxxxxxxxxxxxx"

Example response

[
    {
        "id": "940a543d-a3c9-43b2-a10a-80777e514d44",
        "type": "address",
        "name": "Colissimo"
    },
    {
        "id": "e5246b74-04ee-4b6a-9bb2-362a4da9d255",
        "type": "relay",
        "name": "Mondial Relay"
    }
]

You can retrieve available carriers.

Destinations ids

curl "https://api.colizey.fr/merchant/destinations" \
  -H "x-apikey: xxxxxxxxxxxxxx"

Example response

[
    {
        "id": "77e87475-b238-4b5c-a8cf-828e4af8a918",
        "name": "Belgique"
    },
    {
        "id": "f1ef9d8b-3c72-4166-b563-1b72d32839e2",
        "name": "Corse"
    },
    {
        "id": "a36da2de-4a89-455c-92df-dc141c151999",
        "name": "France Métropolitaine"
    },
    {
        "id": "8cd6ab92-94bd-4b10-af6d-45b40859dfd8",
        "name": "France métropolitaine (hors Corse)"
    }
]

You can retrieve available destinations.

Sandbox

Colizey offers you a sandbox in which you can play 😃

The sandbox offers you a totally different environment with different api key, ids, ...

Ask us another api key for sandbox access.

Additional response headers

The API will answer with two additional headers when in sandbox mode :

Create an order (Sandbox only)

curl "https://api.sandbox.colizey.fr/merchant/orders" \
  -H "x-apikey: xxxxxxxxxxxxxx" \
  -H "content-type: application/json" \
  -d '{"lines":[{"sku":"sku_1","quantity":1,"price":14499,"description":"Lorem Ipsum"}]}' \
  -X POST

Formatted body example

{
  "lines": [
    {"sku": "sku_1", "quantity": 1, "price": 14499, "description": "Lorem Ipsum"}
  ]
}

You can create an order to simulate order management on your own sandbox.

The order creation object is quite similar to the refund object.

parameters in type required Description
relayId query string no If you want a relay shipper, fill this with a non-empty value.
shippingPrice query int no Sets the shipping price. Can be 0 for free shipping. Default is 590 (5,90 €)
lines body array yes An array of objects representing a pair of sku/quantity/price/description that will be added to the order. To avoid mistakes, prices under 10€ will return a 409 error code. Note that the line description field is optional and corresponds to the product name in production.

Changelog

2023-12-19 v1.4.1

2023-09-28 v1.4.0

2023-05-25 v1.3.9

2022-03-31 v1.3.8

2022-03-31 v1.3.7

2022-02-18 v1.3.6

2021-12-20 v1.3.5

2021-03-08 v1.3.4

2020-08-26 v1.3.3

2020-01-06 v1.3.2

2019-06-11 v1.3.1

2019-05-29 v1.3.0

2019-04-23 v1.2.2

2019-04-14 v1.2.1

2019-03-14 v1.2.0

2019-02-06 v1.1.0

2019-01-21 v1.0.1

2018-10-24 v1.0.0

Initial release.

shell php