The Trackstar API enables you to write data into your end users’ connected accounts. You can create new entities POST and update existing entities PUT.

Request Body

Every write request requires a JSON body. The request body will differ depending on the type of write request you are making and the integeration you are writing to.

e.g. Creating orders in WMS A will have a different request body than creating orders in WMS B.

To make it easier to dynamically write into WMS, Trackstar provides a meta endpoint that allows you to get the schema of the request body for a write request.

Meta Endpoint

The meta endpoint returns the request body schema for a given integration and method. For example, calling GET /wms/inbound-shipments/meta?method=POST with access_token=abc123 will return the schema for creating an inbound shipment in the WMS integration associated with the access token abc123.

Instead of building customized write logic for every integration, /meta allows you to:

  • Dynamically generate the request body schema for a write request
  • Automatically account for differences between integrations
  • Autogenerate user interfaces for your end users to create and update entities

Meta Response

The top level of the meta response is an object with three keys: schema, definitions, and $ref.

Every definition has properties, a list of elements called required, and a type (equal to object). This schema conforms to the JSON Schema Draft 07 specification. More information can be found there.

Example

The following example demonstrates how to take the response from the meta endpoint and use it to create the request body for a write request.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "definitions": {
    "InboundShipmentLineItem": {
      "properties": {
        "expected_quantity": {
          "title": "expected_quantity",
          "type": "integer",
          "description": ""
        },
        "expected_weight": {
          "title": "expected_weight",
          "type": "number",
          "format": "float",
          "description": "Expected weight in pounds"
        },
        "received_quantity": {
          "title": "received_quantity",
          "type": "integer",
          "description": ""
        },
        "sku": {
          "title": "sku",
          "type": "string",
          "description": ""
        },
        "unit_price": {
          "title": "unit_price",
          "type": "number",
          "format": "float",
          "description": "Price of the product (USD)."
        }
      },
      "type": "object",
      "required": [
        "expected_quantity",
        "expected_weight",
        "sku",
        "unit_price"
      ],
      "additionalProperties": false
    },
    "ShipToAddress": {
      "properties": {
        "address1": {
          "title": "address1",
          "type": "string",
          "description": ""
        },
        "address2": {
          "title": "address2",
          "type": "string",
          "description": ""
        },
        "city": {
          "title": "city",
          "type": "string",
          "description": ""
        },
        "country": {
          "title": "country",
          "type": "string",
          "description": ""
        },
        "first_name": {
          "title": "first_name",
          "type": "string",
          "description": ""
        },
        "last_name": {
          "title": "last_name",
          "type": "string",
          "description": ""
        },
        "postal_code": {
          "title": "postal_code",
          "type": "string",
          "description": ""
        },
        "state": {
          "title": "state",
          "type": "string",
          "description": ""
        }
      },
      "type": "object",
      "required": [
        "address1",
        "city",
        "country",
        "first_name",
        "last_name",
        "postal_code",
        "state"
      ],
      "additionalProperties": false
    },
    "InboundShipmentSchema": {
      "properties": {
        "supplier": {
          "title": "supplier",
          "type": "string",
          "description": "The supplier from which the shipment is being sent."
        },
        "warehouse_id": {
          "title": "warehouse_id",
          "type": "string",
          "description": "ID of the warehouse that will be receiving the shipment."
        },
        "expected_arrival_date": {
          "title": "expected_arrival_date",
          "type": "string",
          "description": "Date the shipment is expected to reach the warehouse. Returned in YYYY-MM-DDTHH:MM:SSZ format.",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$"
        },
        "status": {
          "title": "status",
          "type": "string",
          "description": "The status of the inbound shipment.",
          "enum": [
            "open",
            "received",
            "cancelled"
          ],
          "enumNames": []
        },
        "ship_to_address": {
          "type": "object",
          "$ref": "#/definitions/ShipToAddress"
        },
        "line_items": {
          "title": "line_items",
          "type": "array",
          "description": "List of line items included in the shipment.",
          "items": {
            "type": "object",
            "$ref": "#/definitions/InboundShipmentLineItem"
          }
        }
      },
      "type": "object",
      "required": [
        "warehouse_id",
        "expected_arrival_date",
        "status",
        "ship_to_address",
        "line_items"
      ],
      "additionalProperties": false
    }
  },
  "$ref": "#/definitions/InboundShipmentSchema"
}

Write Request Flow

  1. Call GET wms/<object_type>/meta?method=[POST|PUT] to get the schema of the request body.
  2. Generate a user interface (e.g. a form) based on the schema.
  3. On submit, serialize the form data into a JSON object.
  4. Call POST wms/<object_type> or PUT wms/<object_type> with the JSON object as the request body.

Example UI Creation

The example React code below demonstrates how to use the meta endpoint to generate a form for creating an inbound-shipment.

  // See "Sample Meta Response" for the schema
  const generateFormFields = (sub_schema) => {
    const properties = sub_schema.properties;
    return Object.keys(properties).map((key) => {
      const property = properties[key];
      const { description, type, enum: enumValues, pattern, items } = property;
      const required = sub_schema.required.includes(key);
      const keyStr = required ? key.concat("*") : key;

      if (type === 'object') {
        const ref = property["$ref"].replace("#/definitions/", "");
        const definition = definitions[ref];
        return (
          <div>
            <label> {keyStr}: </label>
            {generateFormFields(definition)}
          </div>
        );
      }

      if (type === 'array') {
        const ref = items["$ref"].replace("#/definitions/", "");
        const definition = definitions[ref];
        const subForm = generateFormFields(definition);
        return (
          <form id="sub">
            <label>{keyStr}: </label>
            <div key={"item1"}>
              <label>{keyStr} 1: </label>
              {subForm}
            </div>
            <div key={"item2"}>
              <label>{keyStr} 2: </label>
              {subForm}
            </div>
          </form>
        );
      }

      if (enumValues) {
        return (
          <div key={key}>
            <label htmlFor={key}>{keyStr}: </label>
            <select
              id={key}
              name={key}
            >
              {enumValues.map((option) => (
                <option key={option} value={option}>
                  {option}
                </option>
              ))}
            </select>
            <label> ({description})</label>
          </div>
        );
      }

      return (
        <div key={key}>
          <label htmlFor={key}>{keyStr}: </label>
          <input
            type={type}
            id={key}
            name={key}
            required={required}
            pattern={pattern ? pattern : ".+"}
          />
          <label> {description ? "(".concat(description).concat(")") : ""}</label>
        </div>
      );
    });
  };