Creating an order

Qualy's API provides robust functionality for creating payments that are part of a multi-product/service order. You can use the Orders API to control when a product/service was purchased, and what are the specific Items of a specific Order.

For example, in an ecommerce website, you may have a "Cart" with multiple items, once the customer purchases the items, all of the items purchased together are part of an "Order" and each specific item, is an "Order Item".

An Order/Order Item may have as many Payment Intents as you want.

Before you start

You need to have an existing Contact to create an Order. The contact field accepts either the Contact ObjectId or the contact email. See Smart references.

Creating an order

To create an order on Qualy, you will have to use the Orders API.

This is an example of creating an Order:

try {
  const response = await fetch('https://api.qualyhq.com/v1/orders/create', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'ApiKey your-api-key-here',
      'X-TENANT-ID': 'your-tenant-id-here',
    },
    body: JSON.stringify({
      "contact": "john.doe@example.com",
      "source": "manual",
      "services": ["Diploma of Business"]
    }),
  });

  if (response.ok) {
    const data = await response.json();

    console.log(data);
  } else {
    throw new Error(`Request failed with status: ${response.status}`);
  }
} catch (error) {
  console.error(error);
}

Services

An order may be associated with multiple services. You can use the Services API to create or retrieve services, then pass each service ObjectId or service name in the services array.

When services are provided, Qualy creates the corresponding Order Items.

Source stypes

Orders can have different source types. The source property helps customers in their reporting and analytics activities, and it's currently used internally to trigger actions and analyse the order payload. Make sure to select the correct source when creating an Order.

Creating an Order Item

An Order may have multiple Order Items, each Order Item is a product/service bought by the customer.

This is an example of a request to create an Order Item:

try {
  const response = await fetch('https://api.qualyhq.com/v1/orders/677d24f98bd3d800483852f2/items/create', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'ApiKey your-api-key-here',
      'X-TENANT-ID': 'your-tenant-id-here',
    },
    body: JSON.stringify({
      "service": "Diploma of Business",
      "supplier": "usyd"
    }),
  });

  if (response.ok) {
    const data = await response.json();

    console.log(data);
  } else {
    throw new Error(`Request failed with status: ${response.status}`);
  }
} catch (error) {
  console.error(error);
}

Supplier

An Order Item may be associated with one "Supplier". The supplier field accepts a Partnership ObjectId, partnership code, exact name, or name prefix.

You should attach the supplier to the Order Item creation if the product/service being provided in the Order Item is actually provided by another company.

A common use case is the International Education industry, where an international educationa agency may have sold a program, but the program (course) is provided by a college or university.

It's important the Suppliers are properly associated, including in the Payment Intent, as they affect how Payment Splits are calculated.

The "Service" property

Using the Services API you can create a catalog of services your customer provides. Once the service exists, use its ObjectId or name when creating an Order or Order Item.

You need to have an existing Service to create an Order Item.