Feed order, customer & product data

Overview

This guide walks you through how to include additional data to your shipments and trackers. These extra order and customer data will greatly improve your experience inside the platform as well as allow you to send proactive notifications to your customers.

Get our GraphQL Playground running

To follow along the the steps in this guide we'll provide an interactive environment for Ruby, Python and Node. You can also use GraphQL directly with our GraphQL Playground.

Creating a customer

Customers represent your users in Kublau’s API and allow you to send proactive notifications. It also serves as valuable reference information for a tracker or shipment.

In order to connect a customer with a Tracker or Shipment you'll need to create an Order.

Here is an example of how to create a customer:

GraphQL

mutation customerCreate($input: CustomerCreateInput!) {
  customerCreate(input: $input) {
    customer {
      id
      firstName
      lastName
      phone
      email
      taxId {
        value
        type
      }
    }
    userErrors {
      field
      message
    }
  }
}

GraphQL Query Variables

{
  "data": {
    "customerCreate": {
      "customer": {
        "id": "gid://kublau/Customer/0722d839-52b4-4aa1-bb97-0f6c9fdf2cca",
        "firstName": "John",
        "lastName": "Doe",
        "phone": "52155762343",
        "email": "[email protected]",
        "taxId": {
          "value": "1271823961",
          "type": "MX_RFC"
        }
      },
      "userErrors": []
    }
  }
}

Creating an order

An order connects a Tracker or Shipment with the customer they belong to. It also allows you to store additional information such as a unique identifier, tags (coming soon) or custom attributes (coming soon).

Here is an example of how to create an order:

GraphQL

mutation orderCreate($input: OrderCreateInput!) {
  orderCreate(input: $input) {
    order {
      id
      externalId 
      customer {
        id
        firstName
        lastName
        email
        phone
      }
    }
    userErrors {
      field
      message
    }
  }
}

GraphQL Query Variables

{
  "data": {
    "orderCreate": {
      "order": {
        "id": "gid://kublau/Order/09e00093-5cc8-4a7a-bb52-b94179a7a6fd",
        "externalId": "#1003",
        "customer": {
          "id": "gid://kublau/Customer/0722d839-52b4-4aa1-bb97-0f6c9fdf2cca",
          "firstName": "John",
          "lastName": "Doe",
          "email": "[email protected]",
          "phone": "52155762343"
        }
      },
      "userErrors": []
    }
  }
}

Passing custom data to the Order with metafields

Metafields enable you to save specialized information that isn't usually captured by standard Kublau resources. You can use Metafields for internal tracking, custom flows inside Kublau or to display specialized information on your emails and tracking pages in a variety of ways.

Here is an example of how to include a text my_custom_text_field field and an integer my_custom_integer_field integer field when creating an order:

GraphQL

mutation orderCreate($input: OrderCreateInput!) {
  orderCreate(input: $input) {
    order {
      id
      metafields {
        key
        value
        valueType
      }
    }
    userErrors {
      field
      message
    }
  }
}

GraphQL Query Variables

{
  "data": {
    "orderCreate": {
      "order": {
        "id": "gid://kublau/Order/09e00093-5cc8-4a7a-bb52-b94179a7a6fd",
         "metafields": [
          {
            "key": "my_custom_text_field",
            "value": "This is a custom text field",
            "valueType": "STRING"
          },
          {
            "key": "my_custom_integer_field",
            "value": "6",
            "valueType": "INTEGER"
          }
        ]
      },
      "userErrors": []
    }
  }
}

You can read more on how to add your own custom metafields here.

Adding product information to the order

Products define what you are shipping in Kublau’s API and allow you to improve and customize notifications. It also serves as valuable reference information for a tracker or shipment.

Here is an example of how to specify which product you are shipping while creating an order:

GraphQL

mutation orderCreate($input: OrderCreateInput!) {
  orderCreate(input: $input) {
    order {
      id
    }
    userErrors {
      field
      message
    }
  }
}

GraphQL Query Variables

{
  "data": {
    "orderCreate": {
      "order": {
        "id": "gid://kublau/Order/09e00093-5cc8-4a7a-bb52-b94179a7a6fd"
      },
      "userErrors": []
    }
  }
}

Adding address information to the order

An order has ashippingAddress field which represents the address this order is being shipped to. If you generate the label with our API we will automatically use the destination address of your shipment when referencing an order when creating a tracker.

GraphQL

mutation orderCreate($input: OrderCreateInput!) {
  orderCreate(input: $input) {
    order {
      id
      shippingAddress {
        line1
        line1
        city
        state
        postalCode
        country
      }
    }
    userErrors {
      field
      message
    }
  }
}

GraphQL Query Variables

{
  "data": {
    "orderCreate": {
      "order": {
        "id": "gid://kublau/Order/09e00093-5cc8-4a7a-bb52-b94179a7a6fd",
        "externalId": "#1003",
        "shippingAddress": {
          "line1": "417 MONTGOMERY ST",
          "city": "SAN FRANCISCO",
          "state": "CA",
          "postalCode": "94105",
          "country":"US",
          "name": "John Doe",
          "phone": "123 456 789 15"
        }
      },
      "userErrors": []
    }
  }
}

Referencing the order on a Tracker or Shipment

When creating a Tracker (trackerCreate) or Shipment (shipmentCreate) include the orderId argument with the id of the order you created.

Here is an example of GraphQL Query Variables that include an orderId :

trackerCreate

{
  "input": {
    "orderId": "gid://kublau/Order/b177e171-f288-4bb5-bf94-73807d5053f2",
    "trackingCode": "837323020",
    "carrier": "ESTAFETA"
  }
}

shipmentCreate

That’s it! Your are including order and customer data with your shipments and trackers.