POST
/
v1
/
orders
Create Order
curl --request POST \
  --url https://api.roastify.app/v1/orders \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "externalSourceId": "your-order-123",
  "toAddress": {
    "name": "<string>",
    "company": "<string>",
    "street1": "<string>",
    "street2": "<string>",
    "city": "<string>",
    "state": "<string>",
    "country": "<string>",
    "zip": "<string>",
    "phone": "<string>",
    "email": "<string>"
  },
  "returnAddress": {
    "name": "<string>",
    "company": "<string>",
    "street1": "<string>",
    "street2": "<string>",
    "city": "<string>",
    "state": "<string>",
    "country": "<string>",
    "zip": "<string>",
    "phone": "<string>",
    "email": "<string>"
  },
  "shipping": {
    "carrier": "USPS",
    "priority": "GroundAdvantage"
  },
  "items": [
    {
      "externalSourceId": "your-line-item-456",
      "sku": "COF-WHB-12O-COL-BOX",
      "artworkUrl": "https://storage.roastify.app/mockup-images/a045d749-8372-44a0-aga3-098688ab6ad2.jpeg",
      "quantity": 3
    }
  ]
}'
{
  "orderId": "<string>"
}

Authorizations

x-api-key
string
header
required

The API key to authenticate requests provided by Roastify. A Base or Pro plan is required to use the API.

Headers

Idempotency-Key
string

The idempotency key to use for the request (V4 UUID recommended)

Example:

"123e4567-e89b-12d3-a456-426614174000"

Body

application/json
toAddress
object
required

Recipient information

items
object[]
required

List of items in the order

Minimum length: 1
externalSourceId
string | null

Your external source ID. This is an optional field that can be used to map orders from your system to Roastify.

Example:

"your-order-123"

returnAddress
object

Optional return address. If not provided, uses the Roastify default distribution center address.

shipping
object

Optional shipping information. This is only required for API users with custom shipping integrations with Roastify. Carrier and Priority need to be camelCase or PascalCase.

Example:
{
"carrier": "USPS",
"priority": "GroundAdvantage"
}

Response

Succesful order. Returns the orderId of the new order

orderId
string
required