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 a Contact _id to create an Order, use the Contact API to create or retrieve a Contact.

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": "656b9ef1a3258074a705433b",
      "source": "manual",
      "suppliers": ["656b9ef1a3258074a705433b"]
    }),
  });

  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);
}

Suppliers

An order may be associated with multiple "Suppliers". You can use the Partnerships API to retrieve the partnership _id and use as it in the suppliers array.

You should attach the supplier to the Order creation if any of the Order Items also has a supplier.

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": "456b9ff1b3258074l705433b",
      "supplier": "656b9ef1a3258074a705433b"
    }),
  });

  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 may be associated with one "Supplier". You can use the Partnerships API to retrieve the partnership _id and use as it in the supplier property.

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 is created you can use its _id when creating an Order.

You need to have a Service _id to create an Order Item, use the Services API to create or retrieve a Service.