Order

Version 1.0

The Order Entity stands as the linchpin in our platform, serving as the focal point for orchestrating seamless transactions within marketplaces. Crafted to be the central nerve center for all order-related operations, this entity empowers merchants with a robust and dynamic framework for managing transactions across diverse channels. From essential details such as order status, customer information, and payment details to more intricate elements like shipping preferences and order history, the Order Entity captures and organizes a comprehensive array of data with precision. Going beyond mere transaction tracking, it forms the backbone of a well-coordinated marketplace ecosystem, ensuring coherence and accuracy across all transaction touchpoints.

The Order Entity plays a pivotal role in streamlining the order fulfillment process, facilitating efficient communication between merchants, customers, and other stakeholders. Its meticulous organization of data enables merchants to confidently navigate the complexities of order management, ultimately enhancing the overall customer experience. As the authoritative source of truth for transactions, the Order Entity fosters trust and reliability in the marketplace, providing a sturdy foundation for successful e-commerce operations.

# Endpoints

GET

/v1/orders/123456789# Retrieve a single order

GET

/v1/orders# Get all orders

Order Entity

Name
id
Type
string
Required
Description
Every order is assigned a unique identifier - an unsigned 64-bit integer known as the Order ID. This specific number is exclusive and distinct across the entire Qooly platform, ensuring an unparalleled level of uniqueness for each order.
Name
channel_id
Type
foreignId
Required
Description
This property indicates the channel through which the order was placed. It serves as a unique identifier, specific to each channel in Qooly's system. The 'channel_id' provides a reliable reference to the channel through which the order was initiated, facilitating seamless order tracking and management.
Name
currency_id
Type
foreignId
Required
Description
This property indicates the currency used for the order. It serves as a unique identifier, specific to each currency in Qooly's system. The 'currency_id' provides a reliable reference to the currency in which the order's total price is expressed, ensuring accurate financial transactions.
Name
customer_id
Type
foreignId
Required
Description
This serves as a unique identifier for each customer placing an order in Qooly's system. As a distinct numerical value, the 'customer_id' provides a reliable reference to every individual customer, facilitating seamless order tracking and management.
Name
order_created_at
Type
datetime
Required
Description
This property indicates the date and time when the order was created. It serves as a timestamp in the 'YYYY-MM-DD HH:MM:SS' format, providing a precise record of the order's creation time.
Name
order_updated_at
Type
datetime
Required
Description
This property indicates the date and time when the order was last updated. It serves as a timestamp in the 'YYYY-MM-DD HH:MM:SS' format, providing a precise record of the order's last update time.

Name: status
Type: varchar(16)
Description: This property indicates the status of the order.

Name: fulfillment_status
Type: varchar(16)
Description: This property indicates the fulfillment status of the order.

Name: payment_status
Type: varchar(16)
Description: This property indicates the payment status of the order.

Name
name
Type
varchar(255)
Required
Description
This property indicates the order number of the order.
Name
external_identifier
Type
varchar(255)
Description
This property indicates the external identifier of the order.
Name
delivery_method
Type
varchar(16)
Default: STANDARD
Description
This property indicates the delivery method of the order.
Standard The order is being shipped using standard delivery.
Express The order is being shipped using express delivery.
Name
total
Type
decimal
Required
Description
This property indicates the total price of the order, considering the quantity and any applicable taxes or discounts.
Name
tax_total
Type
decimal
Required
Description
This property indicates the total tax applied of the order.
Name
shipping_total
Type
decimal
Required
Description
This property indicates the total shipping cost of the order.
Name
discount_total
Type
decimal
Required
Description
This property indicates the total discount applied of the order.
Name
original_order_data
Type
object
Description
This property indicates the original order data.
Name
shipping_address
Type
object
Description
This property indicates the shipping address of the order.
Name
billing_address
Type
object
Description
This property indicates the billing address of the order.
Name
created_at
Type
timestamp
Description
This property indicates the time in ISO_8601 when the order was created.
Name
updated_at
Type
timestamp
Description
This property indicates the time in ISO_8601 when the order was last updated.
Name
created_by
Type
foreignId
Description
This property indicates the user who created the order.
Name
updated_by
Type
foreignId
Description
This property indicates the user who updated the order recently.

The Order resource

JSON

{
  "id": "123456789",
  "connection_id": "987654321",
  "currency_id": "456789012",
  "customer_id": "789012345",
  "total": 150.25,
  "tax_total": 15.00,
  "payment_status": "Paid",
  "order_status": "Shipped",
  "fulfillment_status": "Fulfilled",
  "delivery_method": "Standard",
  "items_count": 3,
  "original_order_data": {
    "order_number": "ORD123456",
    "payment_method": "Credit Card",
    "shipping_address": {
      "street": "123 Main St",
      "city": "Cityville",
      "state": "CA",
      "zip_code": "12345",
      "country": "US"
    },
    "billing_address": {
      "street": "456 Billing St",
      "city": "Billingtown",
      "state": "CA",
      "zip_code": "54321",
      "country": "US"
    },
    "order_items": [
      {
        "product_id": "789",
        "quantity": 2,
        "unit_price": 49.99
      },
      {
        "product_id": "456",
        "quantity": 1,
        "unit_price": 29.99
      }
    ]
  },
  "created_at": "2024-01-15T10:45:00Z",
  "updated_at": "2024-01-16T14:30:00Z",
  "created_by": "789012345",
  "updated_by": "123456789"
}

Retrieve a single order

This endpoint allows you to retrieve a single order.

Parameters

Name
id
Type
string
Required
Description
The unique identifier of the order you want to retrieve.

Retrieve a single order

GET

/v1/orders/987654321

curl --request GET \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer Token' \
  --url https://local.qooly.test/api/v1/orders/987654321

JSON

{
  "id": "987654321",
  "purchaseDate": "2024-01-15T10:45:00Z",
  "lastUpdateDate": "2024-01-16T14:30:00Z",
  "name": "ORD123456",
  "status": "Shipped",
  "paymentStatus": "Paid",
  "fulfillmentStatus": "Fulfilled",
  "deliveryMethod": "Standard",
  "total": 85.99,
  "taxTotal": 10.50,
  "discountTotal": 0.00,
  "shippingTotal": 10.00,
  "itemsTotal": 75.99,
  "itemsCount": 3,
  "channel": {
    "id": 34,
    "name": "Shopify Test",
    "url": "https://admin.shopify.com/store/shopify-test",
  },
  "currency": {
    "id": 1,
    "code": "USD",
  },
  "customer": {
    "id": 123,
    "email": "testuser@email.com",
    "name": "Test User",
    "phone": "123-456-7890",
  },
  "shippingAddress": {
    "city": "Cityville",
    "phone": "123-456-7890",
    "country": "US",
    "last_name": "User",
    "first_name": "Test",
    "postal_code": "12345",
    "country_code": "US",
    "address_line_1": "123 Main St",
    "address_line_2": "",
  },
  "billingAddress": {
    "city": "Cityville",
    "phone": "123-456-7890",
    "country": "US",
    "last_name": "User",
    "first_name": "Test",
    "postal_code": "12345",
    "country_code": "US",
    "address_line_1": "123 Main St",
    "address_line_2": "",
  },
  "shippingAddressSameAsBillingAddress": true,
  "orderItems": [
    {
      "id": 1,
      "quantity": 2,
      "total": 59.98,
      "taxTotal": 5.00,
      "discountTotal": 0.00,
      "status": "Shipped",
      "orderItemId": 1,
      "qoolyProduct": {
        "id": 1,
        "name": "Test Product 1",
        "sku": "TEST-PROD-1",
        "image": "https://cdn.qooly.io/images/test-product-1.jpg",
      },
      "qoolyProductVariant": {
        "id": 1,
        "name": "Test Product 1 - Variant 1",
        "sku": "TEST-PROD-1-VAR-1",
        "barcode": "1234567890123",
      },
      "name": "Test Product 1",
      "sku": "TEST-PROD-1",
      "barcode": "1234567890123",
    },
    {
      "id": 2,
      "quantity": 1,
      "total": 29.99,
      "taxTotal": 2.50,
      "discountTotal": 0.00,
      "status": "Shipped",
      "orderItemId": 2,
      "qoolyProduct": {
        "id": 2,
        "name": "Test Product 2",
        "sku": "TEST-PROD-2",
        "image": "https://cdn.qooly.io/images/test-product-2.jpg",
      },
      "qoolyProductVariant": {
        "id": 2,
        "name": "Test Product 2 - Variant 1",
        "sku": "TEST-PROD-2-VAR-1",
        "barcode": "1234567890987",
      },
      "name": "Test Product 2",
      "sku": "TEST-PROD-2",
      "barcode": "1234567890987",
    }
  ],
  "additionalData": {
     // Some additional order data
  }
}

Get all orders

This endpoint allows you to get all orders.

Query Parameters

Name
minUpdateDate
Type
string
Description
The minimum update date for filtering orders.
Name
sortDirection
Type
string
Description
The direction to sort the orders (e.g., asc, desc).
Name
sortKey
Type
string
Description
The key to sort the orders by (e.g., purchaseDate).
Name
salesChannelCode
Type
string
Description
The sales channel code to filter orders.
Name
connectorType
Type
string
Description
The connector type to filter orders.
Name
connectorCode
Type
string
Description
The connector code to filter orders.
Name
maxUpdateDate
Type
string
Description
The maximum update date for filtering orders.
Name
perPage
Type
integer
Description
The number of orders to return per page.
Name
cursor
Type
string
Description
The cursor for pagination.

Get all orders

GET

/v1/orders

curl --request GET \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer Token' \
  --url 'https://local.qooly.test/api/v1/orders?minUpdateDate=2024-12-10T14%3A30%3A45Z&sortDirection=ASC&sortKey=created_at&salesChannelCode=shopify-test&connectorType=Online%20Store&connectorCode=Shopify&maxUpdateDate=2024-01-31&perPage=100&cursor=abc123'

JSON

{
  "orders": [
    {
      "id": "987654321",
      "purchaseDate": "2024-01-15T10:45:00Z",
      "lastUpdateDate": "2024-01-16T14:30:00Z",
      "name": "ORD123456",
      "status": "Shipped",
      "paymentStatus": "Paid",
      "fulfillmentStatus": "Fulfilled",
      "deliveryMethod": "Standard",
      "total": 85.99,
      "taxTotal": 10.50,
      "discountTotal": 0.00,
      "shippingTotal": 10.00,
      "itemsTotal": 75.99,
      "itemsCount": 3,
      "channel": {
        "id": 34,
        "name": "Shopify Test",
        "url": "https://admin.shopify.com/store/shopify-test",
      },
      "currency": {
        "id": 1,
        "code": "USD",
      },
      "customer": {
        "id": 123,
        "email": "testuser@email.com",
        "name": "Test User",
        "phone": "123-456-7890",
      },
      "shippingAddress": {
        "city": "Cityville",
        "phone": "123-456-7890",
        "country": "US",
        "last_name": "User",
        "first_name": "Test",
        "postal_code": "12345",
        "country_code": "US",
        "address_line_1": "123 Main St",
        "address_line_2": "",
      },
      "billingAddress": {
        "city": "Cityville",
        "phone": "123-456-7890",
        "country": "US",
        "last_name": "User",
        "first_name": "Test",
        "postal_code": "12345",
        "country_code": "US",
        "address_line_1": "123 Main St",
        "address_line_2": "",
      },
      "shippingAddressSameAsBillingAddress": true,
      "orderItems": [
        {
          "id": 1,
          "quantity": 2,
          "total": 59.98,
          "taxTotal": 5.00,
          "discountTotal": 0.00,
          "status": "Shipped",
          "orderItemId": 1,
          "qoolyProduct": {
            "id": 1,
            "name": "Test Product 1",
            "sku": "TEST-PROD-1",
            "image": "https://cdn.qooly.io/images/test-product-1.jpg",
          },
          "qoolyProductVariant": {
            "id": 1,
            "name": "Test Product 1 - Variant 1",
            "sku": "TEST-PROD-1-VAR-1",
            "barcode": "1234567890123",
          },
          "name": "Test Product 1",
          "sku": "TEST-PROD-1",
          "barcode": "1234567890123",
        },
        {
          "id": 2,
          "quantity": 1,
          "total": 29.99,
          "taxTotal": 2.50,
          "discountTotal": 0.00,
          "status": "Shipped",
          "orderItemId": 2,
          "qoolyProduct": {
            "id": 2,
            "name": "Test Product 2",
            "sku": "TEST-PROD-2",
            "image": "https://cdn.qooly.io/images/test-product-2.jpg",
          },
          "qoolyProductVariant": {
            "id": 2,
            "name": "Test Product 2 - Variant 1",
            "sku": "TEST-PROD-2-VAR-1",
            "barcode": "1234567890987",
          },
          "name": "Test Product 2",
          "sku": "TEST-PROD-2",
          "barcode": "1234567890987",
        }
      ],
      "additionalData": {
        // Some additional order data
      }
    },
    {
      "id": "987654322",
      "purchaseDate": "2024-01-15T10:45:00Z",
      "lastUpdateDate": "2024-01-16T14:30:00Z",
      "name": "ORD123457",
      "status": "Shipped",
      "paymentStatus": "Paid",
      "fulfillmentStatus": "Fulfilled",
      "deliveryMethod": "Standard",
      "total": 85.99,
      "taxTotal": 10.50,
      "discountTotal": 0.00,
      "shippingTotal": 10.00,
      "itemsTotal": 75.99,
      "itemsCount": 3,
      "channel": {
        "id": 34,
        "name": "Shopify Test",
        "url": "https://admin.shopify.com/store/shopify-test",
      },
      "currency": {
        "id": 1,
        "code": "USD",
      },
      "customer": {
        "id": 123,
        "email": "testuser2@email.com",
        "name": "Test User 2",
        "phone": "123-456-7890",
      },
      "shippingAddress": {
        "city": "Cityville",
        "phone": "123-456-7890",
        "country": "US",
        "last_name": "User 2",
        "first_name": "Test",
        "postal_code": "12345",
        "country_code": "US",
        "address_line_1": "123 Main St",
        "address_line_2": "",
      },
      "billingAddress": {
        "city": "Cityville",
        "phone": "123-456-7890",
        "country": "US",
        "last_name": "User 2",
        "first_name": "Test",
        "postal_code": "12345",
        "country_code": "US",
        "address_line_1": "123 Main St",
        "address_line_2": "",
      },
      "shippingAddressSameAsBillingAddress": true,
      "orderItems": [
        {
          "id": 1,
          "quantity": 2,
          "total": 59.98,
          "taxTotal": 5.00,
          "discountTotal": 0.00,
          "status": "Shipped",
          "orderItemId": 1,
          "qoolyProduct": {
            "id": 1,
            "name": "Test Product 1",
            "sku": "TEST-PROD-1",
            "image": "https://cdn.qooly.io/images/test-product-1.jpg",
          },
          "qoolyProductVariant": {
            "id": 1,
            "name": "Test Product 1 - Variant 1",
            "sku": "TEST-PROD-1-VAR-1",
            "barcode": "1234567890123",
          },
          "name": "Test Product 1",
          "sku": "TEST-PROD-1",
          "barcode": "1234567890123",
        },
        {
          "id": 2,
          "quantity": 1,
          "total": 29.99,
          "taxTotal": 2.50,
          "discountTotal": 0.00,
          "status": "Shipped",
          "orderItemId": 2,
          "qoolyProduct": {
            "id": 2,
            "name": "Test Product 2",
            "sku": "TEST-PROD-2",
            "image": "https://cdn.qooly.io/images/test-product-2.jpg",
          },
          "qoolyProductVariant": {
            "id": 2,
            "name": "Test Product 2 - Variant 1",
            "sku": "TEST-PROD-2-VAR-1",
            "barcode": "1234567890987",
          },
          "name": "Test Product 2",
          "sku": "TEST-PROD-2",
          "barcode": "1234567890987",
        }
      ],
      "additionalData": {
        // Some additional order data
      }
    }
  ],
  "pagination": {
    "perPage": 10,
    "cursor": "abc123",
    "nextCursor": "def456"
  }
}

`Pending`	The order is waiting for the process.
`Processing`	The order is currently being processed.
`Partially Fulfilled`	The order has been partially fulfilled to the customer.
`Partially Cancelled`	The order han been partially cancelled.
`Fulfilled`	The order has been fulfilled to the customer.
`Delivered`	The order has been successfully delivered.
`Cancelled`	The order has been cancelled.

`Pending`	The order is pending fulfillment.
`Unfulfilled`	The order is unfulfilled.
`Partially Fulfilled`	The order has been partially fulfilled.
`Fulfilled`	The order has been fulfilled.
`In Progress`	The order process is still continue.
`Cancelled`	The order is cancelled.

`Pending`	The payment for the order is pending.
`Authorized`	The payment for the order is authorized.
`Partially Paid`	The payment for the order is partially paid.
`Paid`	The payment for the order has been successfully processed.
`Failed`	The payment for the order has failed.
`Refunded`	The payment for the order is refunded.
`Partially Refunded`	The payment for the order is partially refunded.
`Disputed`	The payment for the order is disputed.
`Expired`	The payment for the order is expired.

Order

Order Entity

Available options

Available options

Available options

Available options

The Order resource

Retrieve a single order

Parameters

Retrieve a single order

Response

Get all orders

Query Parameters

Get all orders

Response

`Standard`	The order is being shipped using standard delivery.
`Express`	The order is being shipped using express delivery.