Skip to main content
More in Learn

Order Management with the Core API

There are many order-related operations within the Core API. In order to perform these operations, ensure that you have the proper authentication and user permissions.

Registering an Order

To register an order via the Core API, you would use the registerOrder mutation that takes in all the order details including the cart, customer, payment, etc.

mutation RegisterOrder {
  registerOrder(
    input: {
      customer: {
        firstName: "Legolas"
        lastName: "Greenleaf"
        identifier: "legolasgreenleaf@fellowship.com"
        addresses: [
          {
            type: billing
            streetNumber: "16"
            street: "Greenwood"
            city: "Woodland Realm"
            country: "Ithilien"
            postalCode: "9999"
            email: "legolasgreenleaf@fellowship.com"
          }
        ]
      }
      cart: {
        name: "Bow of the Galadhrim"
        sku: "bow-galadhrim"
        imageUrl: "https://media.crystallize.com/lotr/23/1/27/6/@200/bow-galadhrim.avif"
        quantity: 1
        price: {
          gross: 1000
          net: 800
          tax: { name: "Tax", percent: 25 }
          currency: "EUR"
        }
      }
      payment: {
        provider: stripe
      }
      total: {
        gross: 1000
        net: 800
        currency: "EUR"
        tax: { name: "Tax", percent: 25 }
      }
    }
  ) {
    ... on OrderConfirmation {
      id
    }
    ... on OrderCartEmptyError {
      errorName
      message
    }
    ... on BasicError {
      errorName
      message
    }
  }
}

Fetching an Order by ID

Fetching an order by ID requires you to pass an order ID to fetch the data for.

query FetchOrder {
  order(id: "ORDER_ID"){
    ...on Order {
      id
      cart {
        name
        quantity
      }
      payment {
        provider
      }
      total {
        net
        gross
        tax {
          name
          percent
        }
      }
    }
    ...on BasicError {
      errorName
      message
    }
  }
}

Fetching Multiple Orders

To fetch more than just one order, you can use the following query and apply filters to target only the orders you need instead of everything. The example below filters based on the payment provider.

query FetchOrders {
  orders(filter: { paymentProvider: stripe }) {
    ... on OrderConnection {
      totalCount
      edges {
        node {
          id
          cart {
            name
            quantity
          }
          payment {
            provider
          }
          total {
            net
            gross
            tax {
              percent
            }
          }
        }
      }
    }
    ... on BasicError {
      errorName
      message
    }
  }
}

You can further add pagination. The query below gets the first 10 items after the cursor value provided to the after input field.

query FetchOrders {
  orders(
    first: 10
    after: "CURSOR_VALUE"
  ) {
    ... on OrderConnection {
      totalCount
      pageInfo {
        startCursor
        hasNextPage
      }
      edges {
        node {
          id
          cart {
            name
            quantity
          }
          payment {
            provider
          }
          total {
            net
            gross
            tax {
              percent
            }
          }
        }
      }
    }
    ... on BasicError {
      errorName
      message
    }
  }
}

Updating an Order

Maybe you want to update an order after it has been creating. The example below updates the payment related information for an order. You can change any other information provided in the order.

mutation UpdateOrder {
  updateOrder(
    id: "ORDER_ID"
    input: {
      payment: {
        provider: custom
        custom: { properties: [{ property: "Provider", value: "Adyen" }] }
      }
    }
  ) {
    ... on Order {
      id
      payment {
        provider
      }
    }
    ... on OrderNotFoundError {
      errorName
      message
    }
  }
}

Updating Order Metadata

Updating order metadata takes in three input arguments: order ID and both of the meta fields (i.e. key and value).

mutation UpdateOrderMeta {
  updateOrderMetadata(
    id: "ORDER_ID"
    key: "Warehouse"
    value: "Bergen"
  ) {
    ... on Order {
      id
      meta {
        key
        value
      }
    }
  }
}

Deleting Order Metadata

You can target the exact key you would like to remove via this mutation.

mutation DeleteOrderMeta {
  deleteOrderMetadata(id: "ORDER_ID", key: "Warehouse") {
    ... on Order {
      id
      meta {
        key
        value
      }
    }
  }
}

Deleting an Order from a Pipeline

Deleting an order from a pipeline requires the order ID and pipeline ID.

mutation DeleteOrderPipeline {
  deleteOrderPipeline(
    orderId: "ORDER_ID"
    pipelineId: "PIPELINE_ID"
  ) {
    ... on Order {
      id
      pipelines {
        pipeline {
          name
          id
        }
        stage {
          name
          id
        }
      }
    }
    ... on BasicError {
      errorName
      message
    }
  }
}

Updating Order Pipeline Stage

Move an order to a pipeline stage. Required arguments include order ID, pipeline ID, and stage ID.

mutation UpdateOrderPipeline {
  updateOrderPipelineStage(
    orderId: "ORDER_ID"
    stageId: "STAGE_ID"
    pipelineId: "PIPELINE_ID"
  ) {
    ... on Order {
      id
      pipelines {
        stage {
          id
          name
        }
      }
    }
    ...on BasicError {
      errorName
      message
    }
  }
}

Deleting an Order

The mutation to delete an order take the order ID as an argument.

mutation DeleteOrder {
  deleteOrder(id: "ORDER_ID") {
    ... on DeleteCount {
      removed
    }
    ...on BasicError {
      errorName
      message
    }
  }
}
People showing thumbs up

Need further assistance?

Ask the Crystallize team or other enthusiasts in our slack community.

Join our slack community