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
- orderErrors returns an empty list
- 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"
Updated 6 months ago