Create an Order

Direct Integration Note: If you are building a direct integration, you can ignore this section, since we will create an orderID that will be returned to you when you call Apply.

All of our mutations rely on the concept of an OrderID. Conceptually, an orderID represents a specific customer session in which a customer applies for financing.

Create an Order

Use the createOrder mutation. An example mutation will look like the following:

mutation CreateOrder($input: NewOrder!) {
  createOrder(input: $input),
  {
    order{
      id
    }
    orderErrors{
      __typename
      ... on FatalError{
        message
      }
      ... on BadRequest{
        message
      }
      ... on UnauthorizedError{
        message
      }
    }
  }
}

This mutation returns type CreateOrderResponse by default GraphQL will only return the fields that you specify in the mutation. In the above example, we are telling GraphQL to return the following information

{
    order{
      id  # newly created orderID 
    }
    orderErrors{ #any errors encountered  
      __typename  #the type of each error
      ... on FatalError{
        message # when there's a FatalError, include the message
      }
      ... on BadRequest{
        message # when there's a BadRequest Error, include the message
      }
      ... on UnauthorizedError {
        message # when there's a UnauthorizedError, include the message
      }
    }
  }

For this example, we are asking GraphQL to return order.id and the list of orderErrors encountered. This is the minimum you should include in your mutation as you need both order and orderErrors to determine whether or not the mutation was successful.

If you want to, you can include more fields in the response. You can find the schema for our CreateOrderResponse in our docs on our sandbox playground

Check for Success

A successful response will look like the following:

{
    "data": {
        "createOrder": {
            "order": {
                "id": "42a72cc1-bdf5-436f-b176-cbba8d5f7cac"
            },
            "orderErrors": []
        }
    }
}

You'll know it's successful because
1. orderErrors returns an empty list
2. The field you specified in the mutation were successfully returned

Check for Errors

📘
GraphQL vs. Rest
Unlike in REST, GraphQL returns a 200 even when there is an error in the response, so you will always need to check the body of the message that is returned to see if your mutation was successful or not.

There are two types of errors that you could encounter when using our mutations - an Application error and a GraphQL error. Our below sections will go over how to check for both and what to do when you encounter an error.

Application Errors

Application Errors are returned when an error occurs while trying to complete the mutation and will look like the following:

{
    "data": {
        "createOrder": {
            "order": null,
            "orderErrors": [
                {
                    "__typename": "FatalError",
                    "message": "Internal Service Error"
                }
            ]
        }
    }
}

To easily determine if your response contains an application error, check the length of orderErrors and confirm that order is not null.

In a typical GraphQL error response __typename refers to the type of error encountered and message is a more detailed explanation of what went wrong. By default, graphQL

To see more in depth checkout out our Handling Common Errors page.

GraphQL Validation Errors

Our graphQL schema enforces field validation for fields where formatting is important such as phone number and email. If you do not pass a field in the correct format then you will get a validation error, which could look like the following:

{
    "errors": [
        {
            "message": "Phone numbers should be in the following format: \"5555555555\" and only be 10 digits",
            "path": [
                "createOrder",
                "input",
                "details",
                "customer",
                "cellPhone"
            ]
        }
    ],
    "data": null
}

A GraphQL validation error will be returned as an errors object which is a separate type from the createOrder type returned on a success or when there is an application error. Generally, you should check for the errors object when data is null. Inside the errors object, the message will tell you the problem with the field and the path will let you know which specific field triggered the validation error.

Validation errors occur before any application code is ever run. If you fix the field and retry the mutation, the mutation will run and you should get a response.

Which fields do I include on my input?

The simplest input you can pass and get a successful response looks like the following

{
    "input":{}
}

If you don't have access to any of the other input fields at the time of order creation, you can leave the object empty like above. All fields here are optional however if you have them available at the time you create the order, then you should go ahead and pass them. If you are using our modal experience then we will pre-populate the modal with any information we have which saves the customer time completing their application.

An example of a more complete input looks like the following

{
"input":{
  "details":{
    "customer":{
      "firstName":"Wally", 
      "lastName":"Koala", 
      "emailAddress":"[email protected]", 
      "cellPhone":"1234567890"
    },
    "items":[{
      "displayName":"Ejection Seat 2.0", 
      "sku":"1776484", 
      "quantity": 2, 
      "price":"1000",
      "itemImageUrl": "http://local.magento/pub/static/frontend/Magento/luma/en_US/Magento_Catalog/images/product/placeholder/thumbnail.jpg",
      "itemUrl": "http://local.magento/index.php/coffee.html",
      "isLeaseable": true
    },
    {
      "displayName":"Ejection Seat 1.0", 
      "sku":"1776484", 
      "quantity":2, 
      "price":"300",
      "itemImageUrl": "http://local.magento/pub/static/frontend/Magento/luma/en_US/Magento_Catalog/images/product/placeholder/thumbnail.jpg",
      "itemUrl": "http://local.magento/index.php/coffee.html",
      "isLeaseable": true
    }
    ],
    "shippingAmnt": "100",
    "taxAmnt": "5.99"
  }
}
}

General Advice:

customer: any information passed here is used to pre-fill their application in our modal experience
items: depending on when a customer is applying for financing or how they're applying, you might not have any information on what they'd like to purchase. It's OK to leave this off an application, just note if you are integrating as a traditional Ecomm app, then you later you will need to update the application with the items the customer is purchasing. More details on how to do that can be found in Loan Approval & Checkout or Lease Approval & Checkout (Ecomm)
shippingAmt: should only be included when items are included. The format should be "0.00"
taxAmt should only be included when items are included. The format should be "0.00"

Direct Integration Note: If you are building a direct integration, you can ignore this section, since we will create an orderID that will be returned to you when you call Apply.

Create an Order

Check for Success

Check for Errors

📘GraphQL vs. Rest

Application Errors

GraphQL Validation Errors

Which fields do I include on my input?

📘
GraphQL vs. Rest