Orders for partners

The headless commerce orders module exposes multiple endpoints to manage a store’s orders, making it easy to manage them through the flow of the app.

Order

type Order {
    id: ID
    customerCode: String
    storeCode: String
    sessionUid: ID
    items: [CartProduct]
    status: OrderStatus
    processedAt: Date
    externalRef: String
    parentOrderUid: ID
    notes: String
    externalErrorMessage: String
    externalMessage: String
    source: String
    customFields: JSON
    total: Float
    sequence: Int!
    checkoutRules: [OrderCheckoutRule]
    postOrderCheck: JSON
    preOrderCheck: JSON
    activePromotions: [ActivePromotions]
    createdAt: Date
    updatedAt: Date
  }

enum OrderStatus {
    CREATED
    PROCESSED
    CANCELLED
    CONFIRMED
    ERROR
  }

  type OrderCheckoutRule {
    type: String
    value: JSON
 }

💡 Fields with the exclamation mark **!** are required**.**

customerCode: code of the customer that owns the order.
storeCode: code of the store.
sessionUid: UID of the session that owns the order.
items: items list.
status: order status.
processedAt: confirmation date.
externalRef: reference in an external system.
parentOrderUid: id of the parent order in case of order splitting.
notes: notes about the order.
externalErrorMessage: error message from an external system.
externalMessage: message from an external system.
source: source of the order, where it came from.
customFields: custom fields saved on the order, these are defined by the client.
total: the total price of the order.
sequence: order sequence number.

Admin Workspace

Order creation

To create an order, you can use the following mutation:

input OrderInput {
    customerCode: String!
    storeCode: String
    sessionUid: ID!
    items: [CartProductInput]!
    status: String
    processedAt: Date
    externalRef: String
    parentOrderUid: ID
    notes: String
    externalErrorMessage: String
    externalMessage: String
    source: String
    customFields: JSON
    total: Float
    sequence: Float!
 }

input CartProductInput {
    sku: String!
    quantity: Int!
    price: Float
    packageType: String
    unitsPerPackage: Int
    unitDivision: String
    divisionsByUnit: Int
    discount: Float
    customFields: JSON
    attributes: [String]
  }

createOrder(
	storefrontName: String!, 
	data: OrderInput!
): Order

💡 Fields with the exclamation mark **!** are required**.**

Example response

The following response fields may vary

{
  "data": {
    "createOrder": {
      "id": "61e89a2eed1ae27660e64e26",
      "customerCode": "YALO",
      "sessionUid": "61e8996ced1ae27660e64de5",
      "items": [
        {
          "sku": "YALO000016",
          "quantity": 2,
          "price": 60,
          "name": "Libreta",
          "imageURL": [
            "https://storage.googleapis.com/storefront-default-products/YALO000014.png"
          ],
          "description": "Libreta hojas linea",
        },
        {
          "sku": "YALO000017",
          "quantity": 5,
          "price": 60,
          "name": "Camisa Polo",
          "imageURL": [
            "https://storage.googleapis.com/storefront-default-products/YALO000015.png"
          ],
          "description": "Camisa tipo polo",
        }
      ],
      "status": "CREATED",
      "total": 420,
      "activePromotions": [],
      "sequence": 0,
      "createdAt": {
        "timestamp": 1642633774333,
        "string": "15:09:34 GMT-0800 (Pacific Standard Time)"
      },
      "updatedAt": {
        "timestamp": 1642633774333,
        "string": "15:09:34 GMT-0800 (Pacific Standard Time)"
      },
    }
  }
}

Get Orders

To retrieve your orders, you can use the following query:

input PaginationInput {
    pageNumber: Int
    pageSize: Int
}

orders(
  storefrontName: String!
  status: OrderStatus
  pagination: PaginationInput
): [Order]

💡 The **status** field can be used to filter the orders by the status. 💡 Fields with the exclamation mark **!** are required**.**

Example response

The following response fields may vary

{
  "data": {
    "orders": [
      {
        "id": "61e89a2eed1ae27660e64e26",
        "customerCode": "YALO",
        "sessionUid": "61e8996ced1ae27660e64de5",
        "items": [
          {
            "sku": "YALO000016",
            "quantity": 2,
            "price": 60,
            "name": "Libreta",
            "imageURL": [
              "https://storage.googleapis.com/storefront-default-products/YALO000014.png"
            ],
            "description": "Libreta hojas linea",
          },
          {
            "sku": "YALO000017",
            "quantity": 5,
            "price": 60,
            "name": "Camisa Polo",
            "imageURL": [
              "https://storage.googleapis.com/storefront-default-products/YALO000015.png"
            ],
            "description": "Camisa tipo polo",
          }
        ],
        "status": "CREATED",
        "total": 420,
        "activePromotions": [],
        "sequence": 0,
        "createdAt": "2022-01-19T23:09:34.333Z",
        "updatedAt": "2022-01-19T23:09:34.333Z",
      }
    ]
  }
}

Get order

To retrieve an order, you can use the following query:

order(
	storefrontName: String!, 
	id: ID!
): Order

💡 Fields with the exclamation mark **!** are required**.**

Example response

The following response fields may vary

{
  "data": {
    "order": {
      "id": "61e89a2eed1ae27660e64e26",
      "customerCode": "YALO",
      "sessionUid": "61e8996ced1ae27660e64de5",
      "items": [
        {
          "sku": "YALO000016",
          "quantity": 2,
          "price": 60,
          "name": "Libreta",
          "imageURL": [
            "https://storage.googleapis.com/storefront-default-products/YALO000014.png"
          ],
          "description": "Libreta hojas linea",
        },
        {
          "sku": "YALO000017",
          "quantity": 5,
          "price": 60,
          "name": "Camisa Polo",
          "imageURL": [
            "https://storage.googleapis.com/storefront-default-products/YALO000015.png"
          ],
          "description": "Camisa tipo polo",
        }
      ],
      "status": "CREATED",
      "total": 420,
      "activePromotions": [],
      "sequence": 0,
      "createdAt": "2022-01-19T23:09:34.333Z",
      "updatedAt": "2022-01-19T23:09:34.333Z",
    }
  }
}

Update Order

The update an order, you can use the following mutation:

updateOrder(
	storefrontName: String!, 
	id: ID!, 
	data: OrderUpdate!
): Order

💡 Fields with the exclamation mark **!** are required**.**

Example response

The following response fields may vary

{
  "data": {
    "updateOrder": {
      "id": "61e89a2eed1ae27660e64e26",
      "status": "PROCESSED",
      "customerCode": "YALO",
      "sessionUid": "61e8996ced1ae27660e64de5",
      "items": [
        {
          "sku": "YALO000016",
          "quantity": 2,
          "price": 60,
          "name": "Libreta",
          "imageURL": [
            "https://storage.googleapis.com/storefront-default-products/YALO000014.png"
          ],
          "description": "Libreta hojas linea",
        }
      ],
      "total": 420,
    }
  }
}

Remove Order

To remove an order, you can use the following mutation:

removeOrder(
	storefrontName: String!, 
	id: ID!
): Order

💡 Fields with the exclamation mark **!** are required**.**

Example response

The following response fields may vary

{
  "data": {
    "removeOrder": {
      "id": "61e89a2eed1ae27660e64e26",
      "status": "PROCESSED",
      "customerCode": "YALO",
      "sessionUid": "61e8996ced1ae27660e64de5",
      "items": [
        {
          "sku": "YALO000016",
          "quantity": 2,
          "price": 60,
          "name": "Libreta",
          "imageURL": [
            "https://storage.googleapis.com/storefront-default-products/YALO000014.png"
          ],
          "description": "Libreta hojas linea",
        }
      ],
      "total": 420,
    }
  }
}

User workspace

Order creation

On the user API, orders are created based on the session and the cart belonging to that session, that's the default behavior. The cart will be updated to the “CHECK_OUT” status in which no new items could be added and the check-out rules will be checked to ensure everything is in order.

To create an order, the following mutation can be used:

input OrderInput {
    customerCode: String
    storeCode: String
    sessionUid: ID
    items: [CartProductInput]
    status: String
    processedAt: Date
    externalRef: String
    parentOrderUid: ID
    notes: String
    externalErrorMessage: String
    externalMessage: String
    source: String
    customFields: JSON
    total: Float
    sequence: Float
 }

input CartProductInput {
    sku: String!
    quantity: Int!
    price: Float
    packageType: String
    unitsPerPackage: Int
    unitDivision: String
    divisionsByUnit: Int
    discount: Float
    customFields: JSON
    attributes: [String]
  }

createOrder(
    storefrontName: String!
    sessionUid: ID!
    data: OrderInput
): Order

💡 Orders fields could be forced using the **data** field, it overrides the result fields from the default behavior with the ones passed. 💡 Fields with the exclamation mark **!** are required**.**

Example response

The following response fields may vary

{
  "data": {
    "createOrder": {
      "id": "61e89a2eed1ae27660e64e26",
      "customerCode": "YALO",
      "sessionUid": "61e8996ced1ae27660e64de5",
      "items": [
        {
          "sku": "YALO000016",
          "quantity": 2,
          "price": 60,
          "name": "Libreta",
          "imageURL": [
            "https://storage.googleapis.com/storefront-default-products/YALO000014.png"
          ],
          "description": "Libreta hojas linea",
        },
        {
          "sku": "YALO000017",
          "quantity": 5,
          "price": 60,
          "name": "Camisa Polo",
          "imageURL": [
            "https://storage.googleapis.com/storefront-default-products/YALO000015.png"
          ],
          "description": "Camisa tipo polo",
        }
      ],
      "status": "CREATED",
      "total": 420,
      "activePromotions": [],
      "sequence": 0,
      "createdAt": {
        "timestamp": 1642633774333,
        "string": "15:09:34 GMT-0800 (Pacific Standard Time)"
      },
      "updatedAt": {
        "timestamp": 1642633774333,
        "string": "15:09:34 GMT-0800 (Pacific Standard Time)"
      },
    }
  }
}

Get order

To retrieve an order, the following mutation can be used:

order(
	storefrontName: String!, 
	id: ID!
): Order

💡 Fields with the exclamation mark **!** are required**.**

Example response

The following response fields may vary

{
  "data": {
    "order": {
      "id": "61e89a2eed1ae27660e64e26",
      "customerCode": "YALO",
      "sessionUid": "61e8996ced1ae27660e64de5",
      "items": [
        {
          "sku": "YALO000016",
          "quantity": 2,
          "price": 60,
          "name": "Libreta",
          "imageURL": [
            "https://storage.googleapis.com/storefront-default-products/YALO000014.png"
          ],
          "description": "Libreta hojas linea",
        },
        {
          "sku": "YALO000017",
          "quantity": 5,
          "price": 60,
          "name": "Camisa Polo",
          "imageURL": [
            "https://storage.googleapis.com/storefront-default-products/YALO000015.png"
          ],
          "description": "Camisa tipo polo",
        }
      ],
      "status": "CREATED",
      "total": 420,
      "activePromotions": [],
      "sequence": 0,
      "createdAt": "2022-01-19T23:09:34.333Z",
      "updatedAt": "2022-01-19T23:09:34.333Z",
    }
  }
}

Status updates

The order status can be managed in different ways based on the needs, there are multiple statuses an order can have, CREATED, PROCESSED, CANCELLED, ERROR, and CONFIRMED. Being the CONFIRMED status is the most important of all, this status confirms the discount of the stock for each product of the order (if applicable).

The followings mutations are part of the user API:

Place order

This mutation changes the status of the order to “PROCESSED”

placeOrder(
	storefrontName: String!, 
	sessionUid: ID!, 
	id: ID!
): Order

💡 Fields with the exclamation mark **!** are required**.**

Example response

The following response fields may vary

{
  "data": {
    "placeOrder": {
      "id": "61e89a2eed1ae27660e64e26",
      "status": "PROCESSED",
      "customerCode": "YALO",
      "sessionUid": "61e8996ced1ae27660e64de5",
      "items": [
        {
          "sku": "YALO000016",
          "quantity": 2,
          "price": 60,
          "name": "Libreta",
          "imageURL": [
            "https://storage.googleapis.com/storefront-default-products/YALO000014.png"
          ],
          "description": "Libreta hojas linea",
        }
      ],
      "processedAt": {
        "timestamp": 1642635230337,
        "string": "15:33:50 GMT-0800 (Pacific Standard Time)"
      },
      "total": 420,
    }
  }
}

Confirm order

This mutation changes the status of the order to “CONFIRMED”, also discounts the stocks of the products if the stock is active in the store configuration.

confirmOrder(
	storefrontName: String!, 
	sessionUid: ID!, 
	id: ID!
): Order

💡 Fields with the exclamation mark **!** are required**.**

Example response

The following response fields may vary

{
  "data": {
    "confirmOrder": {
      "id": "61e89a2eed1ae27660e64e26",
      "status": "CONFIRMED",
      "customerCode": "YALO",
      "sessionUid": "61e8996ced1ae27660e64de5",
      "items": [
        {
          "sku": "YALO000016",
          "quantity": 2,
          "price": 60,
          "name": "Libreta",
          "imageURL": [
            "https://storage.googleapis.com/storefront-default-products/YALO000014.png"
          ],
          "description": "Libreta hojas linea",
        }
      ],
      "processedAt": {
        "timestamp": 1642635230337,
        "string": "15:33:50 GMT-0800 (Pacific Standard Time)"
      },
      "total": 420,
    }
  }
}

Cancel Order

This mutation changes the status of the order to “CANCELLED”

cancelOrder(
	storefrontName: String!, 
	sessionUid: ID!, 
	id: ID!
): Order

💡 Fields with the exclamation mark **!** are required**.**

Example response

The following response fields may vary

{
  "data": {
    "cancelOrder": {
      "id": "61e89a2eed1ae27660e64e26",
      "status": "CANCELLED",
      "customerCode": "YALO",
      "sessionUid": "61e8996ced1ae27660e64de5",
      "items": [
        {
          "sku": "YALO000016",
          "quantity": 2,
          "price": 60,
          "name": "Libreta",
          "imageURL": [
            "https://storage.googleapis.com/storefront-default-products/YALO000014.png"
          ],
          "description": "Libreta hojas linea",
        }
      ],
      "processedAt": {
        "timestamp": 1642635230337,
        "string": "15:33:50 GMT-0800 (Pacific Standard Time)"
      },
      "total": 420,
    }
  }
}

Mark order as error

This mutation changes the status of the order to “ERROR”

markOrderAsError(
	storefrontName: String!, 
	sessionUid: ID!, 
	id: ID!
): Order

💡 Fields with the exclamation mark **!** are required**.**

Example response

The following response fields may vary

{
  "data": {
    "markOrderAsError": {
      "id": "61e89a2eed1ae27660e64e26",
      "status": "ERROR",
      "customerCode": "YALO",
      "sessionUid": "61e8996ced1ae27660e64de5",
      "items": [
        {
          "sku": "YALO000016",
          "quantity": 2,
          "price": 60,
          "name": "Libreta",
          "imageURL": [
            "https://storage.googleapis.com/storefront-default-products/YALO000014.png"
          ],
          "description": "Libreta hojas linea",
        }
      ],
      "processedAt": {
        "timestamp": 1642635230337,
        "string": "15:33:50 GMT-0800 (Pacific Standard Time)"
      },
      "total": 420,
    }
  }
}