Orders API v2

Use this page for the Merchant API v2 order flows, including order retrieval, accept or reject actions, and merchant invoice file operations.

Variables

merchantAPIEndpoint: https://merchant.api.shopflix.gr/v2
orderReference: GR--3001--MER78
invoiceId: 42

API Overview

This page documents the Merchant API v2 order flows.

Area	Details
Order identifier	`orderReference` is the merchant order reference
Order actions	List, retrieve, accept, and reject orders
Invoice file actions	Upload and soft-delete merchant invoice files
Invoice visibility	Uploaded invoice files are returned in the single-order response under `invoices`

Orders

1. Get Orders

GET {{merchantAPIEndpoint}}/orders

Parameters

Name	Type	Description	Required	Default
`page`	number	Page number for pagination.	No	None
`itemsPerPage`	number	Items per page.	No	10
`state`	string	Filter by order state, e.g. `delivered-to-customer`.	No	null
`dateFrom`	date	Filter orders from this date (`YYYY-MM-DD`).	No	null
`dateTo`	date	Filter orders to this date (`YYYY-MM-DD`).	No	null

Example

GET {{merchantAPIEndpoint}}/orders?page=1&itemsPerPage=10

Response

Status: 200 OK

Content-Type: application/json

response

{
  "params": {
    "page": 1,                     // Current page number
    "itemsPerPage": 10,            // Number of items returned per page
    "totalItems": 265,             // Total number of available orders
    "status": null,                // Order status filter (null = no filter applied)
    "dateFrom": "2020-01-01 00:00:00", // Start date for filtering orders
    "dateTo": "2025-10-14 10:24:00"    // End date for filtering orders
  },
  "orders": [
    {
      "id": "GR--3292--MER78",      // Merchant order reference
      "state": "return-canceled",  // Current order state
      "countryCode": "GR",         // Order country code
      "hasInvoice": false,         // Indicates whether checkout invoice details exist
      "totalItemsAmount": 1000,    // Total amount of the order
      "createdAt": "2025-09-30 17:31:31", // Order creation timestamp
      "updatedAt": null,           // Last update timestamp (null if never updated)
      "customer": {
        "userId": 17,              // Internal customer identifier
        "email": "sarah@example.com", // Customer email address
        "phone": "425-222-45-76",  // Customer phone number
        "firstName": "Sarah",      // Customer first name
        "lastName": "Muller"       // Customer last name
      }
    },
    {
      "id": "GR--3291--MER78",      // Merchant order reference
      "state": "delivered-to-customer", // Current order state
      "countryCode": "GR",         // Order country code
      "hasInvoice": false,         // Indicates whether checkout invoice details exist
      "totalItemsAmount": 1000,    // Total amount of the order
      "createdAt": "2025-09-30 17:23:14", // Order creation timestamp
      "updatedAt": null,           // Last update timestamp
      "customer": {
        "userId": 17,              // Internal customer identifier
        "email": "sarah@example.com", // Customer email address
        "phone": "425-222-45-76",  // Customer phone number
        "firstName": "Sarah",      // Customer first name
        "lastName": "Muller"       // Customer last name
      }
    }
    // More orders can be listed here...
  ]
}

2. Retrieve a single order

GET {{merchantAPIEndpoint}}/orders/{orderReference}

Response Structure

Order Details
Customer Information
Address Details
Invoice Details
Carrier Information
Payment Details
Line Items

Response

Status: 200 OK

Content-Type: application/json

response

{
  "order": {
    "id": "GR--3001--MER78",               // Merchant order reference
    "state": "picked-by-courier",          // Current order state
    "countryCode": "GR",                   // Country code where the order was placed
    "hasInvoice": false,                   // Indicates whether checkout invoice details exist
    "subTotalItemsAmount": 2346,           // Sum of line item prices (before additional charges)
    "totalItemsAmount": 2746,              // Final order amount
    "createdAt": "2024-11-05 15:27:04",    // Order creation timestamp
    "updatedAt": null,                     // Last update timestamp (null if never updated)
    "expiresAt": null,                     // Order expiration timestamp (if applicable)
    "dispatchUntil": null,                 // Latest allowed dispatch time
 
    "customer": {
      "userId": 0,                         // Internal customer identifier (0 = guest)
      "email": "maria.williams@example.com", // Customer email address
      "phone": null,                       // Customer phone number (if provided)
      "firstName": "Maria",                // Customer first name
      "lastName": "Williams"               // Customer last name
    },
 
    "addressDetails": {
      "street": "Aiolou",                 // Street name
      "streetNumber": "24",               // Street number
      "postCode": "10552",                // Postal code
      "city": "Athens",                   // City
      "region": "ATTICA",                 // Region name
      "regionCode": "ATT",                // Region code
      "country": "Greece",                // Country name
      "countryCode": "GR"                 // Country ISO code
    },
 
    "invoiceDetails": null,                // Checkout invoice details (null when hasInvoice is false)
 
    "invoices": [
      {
        "id": 42,
        "url": "https://s3.{region}.amazonaws.com/{bucket}/invoices/GR--3001--MER78/invoice-1.pdf", // Example public invoice URL
        "created_at": "2026-04-10T12:30:00Z" // Invoice upload timestamp
      },
      {
        "id": 43,
        "url": "https://s3.{region}.amazonaws.com/{bucket}/invoices/GR--3001--MER78/invoice-2.pdf",
        "created_at": "2026-04-11T09:15:00Z"
      }
    ],
 
    "carrier": {
      "shipmentId": 88,                   // Shipment identifier
      "name": "Courier Center",           // Courier company name
      "deliveryName": "Box Now",          // Delivery service name
      "deliveryKey": "courier_center_box_now", // Internal delivery method key
      "trackingCodes": "013742332791",    // Shipment tracking code(s)
      "comments": null,                   // Optional delivery comments
      "deliveryToCourierEstimationDate": null, // Estimated pickup date by courier
      "deliveryToCustomerEstimationDate": null // Estimated delivery date to customer
    },
 
    "payment": {
      "name": "cod"                       // Payment method key
    },
 
    "lineItems": [
      {
        "id": 310,                        // Line item identifier
        "sku": "SF-5",                    // Product SKU
        "merchantEan": "sf-foo-bar-9",    // Merchant EAN
        "merchantSku": "MERSKU9",         // Merchant SKU
        "productName": "Fashion Product Second", // Product name
        "unitPrice": 2346,                // Unit price
        "originalUnitPrice": 2346,        // Original unit price before discounts
        "totalPrice": 2346,               // Total price for this line item
        "quantity": 1,                    // Quantity ordered
        "sfArticle39Valid": false,        // Business rule flag
        "giftWrap": false,                // Gift wrap indicator
        "extendedAttributes": []          // Additional attributes (can be empty)
      }
 
      // Additional line items may follow...
    ]
  }
}

Response Notes

invoiceDetails contains checkout invoice-request details, if present.
carrier.deliveryKey contains the shipment method key. See Carrier Delivery Method Values.
invoices contains merchant-uploaded invoice files.
Invoice file URLs use the configured S3 region and bucket: https://s3.{region}.amazonaws.com/{bucket}/invoices/{orderReference}/{filename}.

When no merchant-uploaded invoices are available, the invoices field returns an empty array: [].

Invoice Details Structure

When hasInvoice is true, invoiceDetails contains the invoice data submitted by the customer during checkout.

invoiceDetails example

{
  "doy": "1201",
  "doyName": "Athens A DOY",
  "vatNumber": "EL123456789",
  "company": "Example Company SA",
  "occupation": "Retail",
  "address": "Aiolou 12",
  "postCode": "10552",
  "city": "Athens",
  "article39": null,
  "article39Eligible": "1",
  "article39IdentityType": "ΔΙ ΔΙΑΒΑΤΗΡΙΟ",
  "article39IdentityNo": "AB1234567",
  "article39MobilePhone": "+306971234567",
  "article39Otp": "842315",
  "article39Valid": null
}

Field	Type	Required	Description
`doy`	string \| null	No	Tax office code.
`doyName`	string \| null	No	Tax office name.
`vatNumber`	string	Yes	Customer VAT number.
`company`	string \| null	No	Company name.
`occupation`	string \| null	No	Business occupation/activity.
`address`	string \| null	No	Invoice address.
`postCode`	string \| null	No	Invoice postal code.
`city`	string \| null	No	Invoice city.
`article39`	string \| null	No	Article 39 flag/value when present.
`article39Eligible`	string \| boolean \| null	No	Whether Article 39 is eligible.
`article39IdentityType`	string \| null	No	Article 39 identity document type label. See Article 39 Identity Type Values.
`article39IdentityNo`	string \| null	No	Article 39 identity document number.
`article39MobilePhone`	string \| null	No	Mobile phone used for Article 39 verification.
`article39Otp`	string \| null	No	Article 39 OTP value.
`article39Valid`	string \| boolean \| null	No	Article 39 validation status when available.

Error Response

Status: 404 NOT FOUND

Returned when the order is not found.

response

{
	"error": {
		"code": "10301",
		"message": "The order with id {orderReference} was not found"
	}
}

3. Accept Order

PATCH {{merchantAPIEndpoint}}/orders/{orderReference}/accept

Response

Status: 200 OK

Content-Type: application/json

response

{
	"success": true
}

Status: 400 BAD REQUEST

response

{
	"error": {
		"code": "10304",
		"message": "Cannot Accept Order"
	}
}

Possible Reasons

The order has already been rejected or canceled.
The order is in a final state (e.g., already shipped or completed).
The order has already been accepted or is currently being processed.

4. Reject Order

PATCH {{merchantAPIEndpoint}}/orders/{orderReference}/reject

Request Body

Content-Type: application/json

{
    "status":"D",
    "reason": "damaged" // optional
}

Available Reasons
out-of-stock
damaged
wrong-price
disabled-product
wrong-product

Response

Status: 200 OK

Content-Type: application/json

response

{
	"success": true
}

Status: 400 BAD REQUEST

response

{
	"error": {
		"code": "10304",
		"message": "Cannot Reject Order"
	}
}

Possible Reasons

The order has already been accepted, processed, or shipped.
The order is in a terminal state (e.g., completed, canceled).

Invalid Reason

response

{
    "error": {
        "code": "10301",
        "message": "The reason is not valid"
    }
}

Invoice Files

These endpoints manage merchant-uploaded invoice files for a specific order.

In v2, {orderReference} is the merchant order reference.

5. Upload Order Invoice

POST {{merchantAPIEndpoint}}/orders/{orderReference}/invoices

Use this endpoint to upload a new invoice file for an order that belongs to the authenticated merchant.

Validation Rules

The request body must be valid JSON.
filename is required and is used to determine the file extension.
The invoice file content must be sent in contentBase64.
Supported filename extensions are pdf, png, jpeg, and jpg.
The maximum decoded file size is 4,000,000 bytes.
A hard limit of 3 invoice files per order is enforced.
The uploaded invoice becomes available in the order response immediately after a successful upload.

Request Body

Content-Type: application/json

body

{
  "filename": "invoice-GR--5009--MER78.pdf",
  "contentBase64": "JVBERi0xLjcKJcfs..."
}

Name	Type	Required	Description
`filename`	string	Yes	Original filename. The extension controls file type validation.
`contentBase64`	string	Yes	Base64-encoded file content

Response

Status: 200 OK

Content-Type: application/json

response

{
  "message": "success",
  "invoice": {
    "id": 42,
    "url": "https://s3.{region}.amazonaws.com/{bucket}/invoices/GR--5009--MER78/invoice_GR--5009--MER78_27_04_2026_10_00_00.pdf",
    "created_at": "2026-04-21T10:15:00Z"
  }
}

Response Notes

The returned invoice object is the newly created invoice file entry.
The same invoice will be included in GET /orders/{orderReference} immediately after upload.
Invoice file URLs use the configured S3 region and bucket: https://s3.{region}.amazonaws.com/{bucket}/invoices/{orderReference}/{filename}.

Status: 400 BAD REQUEST

Examples:

response

{
  "message": "Invalid payload."
}

response

{
  "message": "The file type is not supported."
}

response

{
  "message": "The file size is too big."
}

response

{
  "message": "You cannot upload more than 3 files."
}

Status: 404 NOT FOUND

Returned when the order does not exist or does not belong to the authenticated merchant.

response

{
  "message": "The order with id {orderReference} was not found"
}

Status: 500 INTERNAL SERVER ERROR

Returned when the temporary file cannot be created or written before upload.

response

{
  "message": "There were errors during the upload."
}

6. Delete Order Invoice

DELETE {{merchantAPIEndpoint}}/orders/{orderReference}/invoices/{invoiceId}

Use this endpoint to soft-delete an invoice that belongs to the given order and the authenticated merchant.

Response

Status: 200 OK

Content-Type: application/json

response

{
  "message": "success",
  "invoices": [
    {
      "id": 43,
      "url": "https://s3.{region}.amazonaws.com/{bucket}/invoices/GR--5009--MER78/invoice-2.pdf",
      "created_at": "2026-04-11T09:15:00Z"
    }
  ]
}

Response Notes

Deletion is soft-delete for parity with current platform behavior.
The returned invoices array reflects the remaining active invoice files for the order.

Status: 400 BAD REQUEST

Returned when the request parameters are invalid.

response

{
  "message": "Invalid request params."
}

Status: 404 NOT FOUND

Returned when the order or invoice is not found, does not belong to the authenticated merchant, or the invoice does not belong to the given order.

response

{
  "message": "The invoice was not found."
}

Error Codes

Code	Message	Explanation
10301	The order with id %s was not found	Invalid or missing order ID
10303	Cannot Accept Order	Order cannot be accepted in current state
10304	Cannot Reject Order	Order cannot be rejected in current state
10305	Invalid Action	Action is not allowed
10306	The reason is not valid	Invalid or unsupported reason

Quick Reference

Endpoint	Description	Method	Response
`/orders`	List all orders (with filters & pagination)	`GET`	Paginated orders list
`/orders/{orderReference}`	Retrieve a specific order	`GET`	Order details
`/orders/{orderReference}/accept`	Accept an order	`PATCH`	`success: true`
`/orders/{orderReference}/reject`	Reject an order	`PATCH`	`success: true`
`/orders/{orderReference}/invoices`	Upload a new order invoice	`POST`	Uploaded invoice object
`/orders/{orderReference}/invoices/{invoiceId}`	Soft-delete an order invoice	`DELETE`	`message: "success"` and refreshed invoices

Returns Shipments

Orders API v2

Table of Contents

Variables

API Overview

Orders

1. Get Orders

Parameters

Response

2. Retrieve a single order

Response Structure

Response

Response Notes

Invoice Details Structure

Error Response

3. Accept Order

Response

4. Reject Order

Request Body

Response

Invoice Files

5. Upload Order Invoice

Validation Rules

Request Body

Response

Response Notes

6. Delete Order Invoice

Response

Response Notes

Error Codes

Quick Reference