Introducing the Orders API, a versatile integration solution built to revolutionize your order management process. Seamlessly connect your online store to our app and effortlessly synchronize your orders.

With the Orders API, merchants gain the ability to push orders directly into our system, enabling quick access to a wide range of shipping label options for their products.

Authentication

The API uses API keys to authenticate requests. You can view and manage your API keys in the Vesyl Dashboard.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail with a 401 Unauthorized status code.

Making a request

All URLs start with https://orders.api.vesyl.com. SSL only. The path is prefixed with /v1.0. If we change the API in backward-incompatible ways, we'll bump the version marker and maintain stable support for the old URLs.

To make a request for all orders, you'd append the orders index path to the base url to form something like https://orders.api.vesyl.com/v1.0/orders. In curl, that looks like:

curl --request GET 
  --url https://orders.api.vesyl.com/v1.0/orders 
  --header 'Authorization: Bearer <YOUR_API_KEY>'

Errors

The API uses standard HTTP status codes to indicate the success or failure of the API call. The body of the response will be JSON in the following format:

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid request params"
}

Metadata

Attach custom metadata to an order — a flat set of string key/value pairs that is returned whenever you read the order.

• Keys must be enabled for your account; any key that isn't enabled is silently ignored (the request still succeeds). Contact support to enable keys. Key names are lowercase letters and underscores (e.g. warehouse_zone), and all values are strings.
• On update, metadata is merged over the order's existing values; set a key to null to remove it. Omitting metadata entirely leaves it unchanged.

Create an order with metadata:

curl --request POST 
  --url https://orders.api.vesyl.com/v1.0/orders 
  --header 'Authorization: Bearer <YOUR_API_KEY>' 
  --header 'Content-Type: application/json' 
  --data '{ "reference": "order-1234", "metadata": { "warehouse_zone": "east" } }'

Update metadata (merge), and remove a key by setting it to null:

curl --request PUT 
  --url https://orders.api.vesyl.com/v1.0/orders/order-1234 
  --header 'Authorization: Bearer <YOUR_API_KEY>' 
  --header 'Content-Type: application/json' 
  --data '{ "metadata": { "warehouse_zone": "west", "old_key": null } }'