Place orders

POST

/orders/batch

Production and sandbox. The token decides the environment.https://api.beautyrouter.com/v1/orders/batch

using System.Net.Http.Headers;
var client = new HttpClient();
var request = new HttpRequestMessage
{
    Method = HttpMethod.Post,
    RequestUri = new Uri("https://api.beautyrouter.com/v1/orders/batch"),
    Headers =
    {
        { "Idempotency-Key", "4f0c2b7e-9a1d-4c36-b8e5-2d7a6f1e3c90" },
        { "Authorization", "Bearer <token>" },
    },
    Content = new StringContent("{ \"orders\": [ { \"supplierId\": \"sup-1Ry6tUi3Op\", \"lines\": [ { \"productId\": \"prod-4Fz9QbX2kL\", \"quantity\": 6 }, { \"productId\": \"prod-6Gh2jKl8Zx\", \"quantity\": 4 } ], \"expectedTotal\": 275.01 } ], \"paymentCardId\": \"card-6Mn3bVc8Xz\" }")
    {
        Headers =
        {
            ContentType = new MediaTypeHeaderValue("application/json")
        }
    }
};
using (var response = await client.SendAsync(request))
{
    response.EnsureSuccessStatusCode();
    var body = await response.Content.ReadAsStringAsync();
    Console.WriteLine(body);
}

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io"
)

func main() {

  url := "https://api.beautyrouter.com/v1/orders/batch"

  payload := strings.NewReader("{ \"orders\": [ { \"supplierId\": \"sup-1Ry6tUi3Op\", \"lines\": [ { \"productId\": \"prod-4Fz9QbX2kL\", \"quantity\": 6 }, { \"productId\": \"prod-6Gh2jKl8Zx\", \"quantity\": 4 } ], \"expectedTotal\": 275.01 } ], \"paymentCardId\": \"card-6Mn3bVc8Xz\" }")

  req, _ := http.NewRequest("POST", url, payload)

  req.Header.Add("Idempotency-Key", "4f0c2b7e-9a1d-4c36-b8e5-2d7a6f1e3c90")
  req.Header.Add("Authorization", "Bearer <token>")
  req.Header.Add("Content-Type", "application/json")

  res, _ := http.DefaultClient.Do(req)

  defer res.Body.Close()
  body, _ := io.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))

}

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{ \"orders\": [ { \"supplierId\": \"sup-1Ry6tUi3Op\", \"lines\": [ { \"productId\": \"prod-4Fz9QbX2kL\", \"quantity\": 6 }, { \"productId\": \"prod-6Gh2jKl8Zx\", \"quantity\": 4 } ], \"expectedTotal\": 275.01 } ], \"paymentCardId\": \"card-6Mn3bVc8Xz\" }");
Request request = new Request.Builder()
  .url("https://api.beautyrouter.com/v1/orders/batch")
  .post(body)
  .addHeader("Idempotency-Key", "4f0c2b7e-9a1d-4c36-b8e5-2d7a6f1e3c90")
  .addHeader("Authorization", "Bearer <token>")
  .addHeader("Content-Type", "application/json")
  .build();

Response response = client.newCall(request).execute();

import axios from 'axios';

const options = {
  method: 'POST',
  url: 'https://api.beautyrouter.com/v1/orders/batch',
  headers: {
    'Idempotency-Key': '4f0c2b7e-9a1d-4c36-b8e5-2d7a6f1e3c90',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  data: {
    orders: [
      {
        supplierId: 'sup-1Ry6tUi3Op',
        lines: [
          {productId: 'prod-4Fz9QbX2kL', quantity: 6},
          {productId: 'prod-6Gh2jKl8Zx', quantity: 4}
        ],
        expectedTotal: 275.01
      }
    ],
    paymentCardId: 'card-6Mn3bVc8Xz'
  }
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

const url = 'https://api.beautyrouter.com/v1/orders/batch';
const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '4f0c2b7e-9a1d-4c36-b8e5-2d7a6f1e3c90',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"orders":[{"supplierId":"sup-1Ry6tUi3Op","lines":[{"productId":"prod-4Fz9QbX2kL","quantity":6},{"productId":"prod-6Gh2jKl8Zx","quantity":4}],"expectedTotal":275.01}],"paymentCardId":"card-6Mn3bVc8Xz"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

val client = OkHttpClient()

val mediaType = MediaType.parse("application/json")
val body = RequestBody.create(mediaType, "{ \"orders\": [ { \"supplierId\": \"sup-1Ry6tUi3Op\", \"lines\": [ { \"productId\": \"prod-4Fz9QbX2kL\", \"quantity\": 6 }, { \"productId\": \"prod-6Gh2jKl8Zx\", \"quantity\": 4 } ], \"expectedTotal\": 275.01 } ], \"paymentCardId\": \"card-6Mn3bVc8Xz\" }")
val request = Request.Builder()
  .url("https://api.beautyrouter.com/v1/orders/batch")
  .post(body)
  .addHeader("Idempotency-Key", "4f0c2b7e-9a1d-4c36-b8e5-2d7a6f1e3c90")
  .addHeader("Authorization", "Bearer <token>")
  .addHeader("Content-Type", "application/json")
  .build()

val response = client.newCall(request).execute()

<?php

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.beautyrouter.com/v1/orders/batch', [
  'body' => '{ "orders": [ { "supplierId": "sup-1Ry6tUi3Op", "lines": [ { "productId": "prod-4Fz9QbX2kL", "quantity": 6 }, { "productId": "prod-6Gh2jKl8Zx", "quantity": 4 } ], "expectedTotal": 275.01 } ], "paymentCardId": "card-6Mn3bVc8Xz" }',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
    'Idempotency-Key' => '4f0c2b7e-9a1d-4c36-b8e5-2d7a6f1e3c90',
  ],
]);

echo $response->getBody();

import requests

url = "https://api.beautyrouter.com/v1/orders/batch"

payload = {
    "orders": [
        {
            "supplierId": "sup-1Ry6tUi3Op",
            "lines": [
                {
                    "productId": "prod-4Fz9QbX2kL",
                    "quantity": 6
                },
                {
                    "productId": "prod-6Gh2jKl8Zx",
                    "quantity": 4
                }
            ],
            "expectedTotal": 275.01
        }
    ],
    "paymentCardId": "card-6Mn3bVc8Xz"
}
headers = {
    "Idempotency-Key": "4f0c2b7e-9a1d-4c36-b8e5-2d7a6f1e3c90",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())

require 'uri'
require 'net/http'

url = URI("https://api.beautyrouter.com/v1/orders/batch")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '4f0c2b7e-9a1d-4c36-b8e5-2d7a6f1e3c90'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{ \"orders\": [ { \"supplierId\": \"sup-1Ry6tUi3Op\", \"lines\": [ { \"productId\": \"prod-4Fz9QbX2kL\", \"quantity\": 6 }, { \"productId\": \"prod-6Gh2jKl8Zx\", \"quantity\": 4 } ], \"expectedTotal\": 275.01 } ], \"paymentCardId\": \"card-6Mn3bVc8Xz\" }"

response = http.request(request)
puts response.read_body

curl --request POST \
  --url https://api.beautyrouter.com/v1/orders/batch \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: 4f0c2b7e-9a1d-4c36-b8e5-2d7a6f1e3c90' \
  --data '{ "orders": [ { "supplierId": "sup-1Ry6tUi3Op", "lines": [ { "productId": "prod-4Fz9QbX2kL", "quantity": 6 }, { "productId": "prod-6Gh2jKl8Zx", "quantity": 4 } ], "expectedTotal": 275.01 } ], "paymentCardId": "card-6Mn3bVc8Xz" }'

import Foundation

let headers = [
  "Idempotency-Key": "4f0c2b7e-9a1d-4c36-b8e5-2d7a6f1e3c90",
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "orders": [
    [
      "supplierId": "sup-1Ry6tUi3Op",
      "lines": [
        [
          "productId": "prod-4Fz9QbX2kL",
          "quantity": 6
        ],
        [
          "productId": "prod-6Gh2jKl8Zx",
          "quantity": 4
        ]
      ],
      "expectedTotal": 275.01
    ]
  ],
  "paymentCardId": "card-6Mn3bVc8Xz"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.beautyrouter.com/v1/orders/batch")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()

Creates one order per supplier. Beauty Router checks every group first, creates the orders together, and charges the card at once. The response has each order after its charge attempt, with its final status: placed, payment_failed, or pending_verification for a prequalified company. A failed charge never fails the request. The charge runs while the user is not present, so a card that needs 3-D Secure fails, and the user pays in showOrder(element, orderId).

Shipping is locked when the order is created. Until the order is placed, other amounts can still change, so keep the order up to date from order.updated.

With saveAsDraft: true, it saves each order as a draft instead, and expectedTotal is not needed. A draft holds no stock, the supplier never sees it, and it sends no webhook, email, or notification. Send draftOrderId to update a draft, or to place it with saveAsDraft: false. Values are not merged: an address, phone, or card you leave out falls back to the company’s default. See Drafts.

It needs canOrder, and only prequalified and verified companies can call it.

Authorizations

userToken

Parameters

Header Parameters

Idempotency-Key

required

string

>= 1 characters <= 128 characters

A new value for each order the user places, such as a UUID. It belongs to the company and lasts 24 hours. A repeat with the same key and body returns the first result.

Example

4f0c2b7e-9a1d-4c36-b8e5-2d7a6f1e3c90

Request Body^required

application/json

object

orders

required

Array<object>

>= 1 items

object

supplierId

required

string

draftOrderId

The draft to update or place. The supplier cannot change, and the lines are replaced.

string

lines

required

Array<object>

>= 1 items

object

productId

required

string

quantity

required

integer

>= 1

expectedTotal

The group’s total from the quote. A difference of $0.10 or more fails with order_total_changed. Required unless saveAsDraft is true.

number

deliveryAddress

The delivery address. Without it, Beauty Router uses the company’s.

object

line1

required

Street address.

string

line2

Suite, unit, or floor.

string

city

required

string

state

required

A two-letter US state code.

string

/^[A-Z]{2}$/

postalCode

required

ZIP code.

string

country

required

string

Allowed value: US

phone

Phone number for the delivery. Required on the company. Optional on an order, which then uses the company’s phone.

string

paymentCardId

The card that pays. Without it, the default card pays.

string

saveAsDraft

true saves the whole request as drafts.

boolean

Examples

{
  "orders": [
    {
      "supplierId": "sup-1Ry6tUi3Op",
      "lines": [
        {
          "productId": "prod-4Fz9QbX2kL",
          "quantity": 6
        },
        {
          "productId": "prod-6Gh2jKl8Zx",
          "quantity": 4
        }
      ],
      "expectedTotal": 275.01
    }
  ],
  "paymentCardId": "card-6Mn3bVc8Xz"
}

{
  "saveAsDraft": true,
  "orders": [
    {
      "supplierId": "sup-1Ry6tUi3Op",
      "lines": [
        {
          "productId": "prod-4Fz9QbX2kL",
          "quantity": 6
        }
      ]
    }
  ]
}

{
  "orders": [
    {
      "draftOrderId": "order-2Xc9vBn4Mq",
      "supplierId": "sup-1Ry6tUi3Op",
      "lines": [
        {
          "productId": "prod-4Fz9QbX2kL",
          "quantity": 6
        }
      ],
      "expectedTotal": 171.79
    }
  ],
  "paymentCardId": "card-6Mn3bVc8Xz"
}

Responses

201

The new orders. A repeat with the same key and body returns the same result.

application/json

object

data

required

Array<object>

object

required

The order ID.

string

number

required

The order number people see.

string

companyId

required

The company the order belongs to.

string

userId

required

The user who placed the order.

string

status

required

draft: the order is saved for later. It holds no stock, and the supplier does not see it. pending_verification: the company is prequalified, and the order waits until its verification ends, with no charge yet. payment_failed: the card charge failed, or a payment is waiting for 3-D Secure. Beauty Router tries once more after 24 hours when the failure can be retried. If that fails too, or the failure cannot be retried, it cancels the order at 24 hours. placed: the card was charged, and the brand or distributor starts preparing the order right after. ready_to_ship, in_transit, delivered, delivery_failed, and canceled follow the delivery. Only a placed order takes stock from the supplier.

string

Allowed values: draft pending_verification payment_failed placed ready_to_ship in_transit delivered delivery_failed canceled

cancelReason

Why the order was canceled. Only on canceled orders.

string

Allowed values: salon supplier payment verification

supplier

required

The brand or distributor that fulfills the order.

object

required

string

name

required

string

lines

required

Array<object>

object

productId

required

The product ID.

string

name

required

The product name.

string

quantity

required

integer

>= 1

unitPrice

required

The wholesale price of one unit before the discount, in US dollars.

number

discount

required

The discount on the whole line, in US dollars.

number

total

required

The line total, in US dollars.

number

productsTotal

required

The total of the lines, in US dollars.

number

discount

required

The discount on the order, in US dollars.

number

shipping

required

The shipping charge, in US dollars: a flat amount or a carrier quote, free above the supplier’s threshold. It is locked when the order is created. null on a draft with no address.

number | null

salesTax

required

The sales tax, in US dollars. null on a draft with no address.

number | null

total

required

The amount the salon pays, in US dollars. It can change until the order is placed. null on a draft with no address.

number | null

currency

required

Always usd.

string

Allowed value: usd

deliveryAddress

required

One of:

object
null

object

line1

required

Street address.

string

line2

Suite, unit, or floor.

string

city

required

string

state

required

A two-letter US state code.

string

/^[A-Z]{2}$/

postalCode

required

ZIP code.

string

country

required

string

Allowed value: US

phone

Phone number for the delivery. Required on the company. Optional on an order, which then uses the company’s phone.

string

trackingNumbers

required

Array<object>

object

number

required

string

url

The carrier’s tracking page. Left out when there is none.

string format: uri

carrier

The carrier. Left out when it is not known.

string

createdAt

required

string format: date-time

updatedAt

required

string format: date-time

deliveredAt

required

When the order was delivered, or null.

string | null format: date-time

Examples

One order

{
  "data": [
    {
      "id": "order-8Jd3kFs6Gh",
      "number": "4821-7730",
      "companyId": "loc-7Hk2pQx9Lm",
      "userId": "user-3Vb8nWq1Rt",
      "status": "placed",
      "supplier": {
        "id": "sup-1Ry6tUi3Op",
        "name": "Amberlin"
      },
      "lines": [
        {
          "productId": "prod-4Fz9QbX2kL",
          "name": "Amberlin Bond Repair Shampoo 33.8 fl oz",
          "quantity": 6,
          "unitPrice": 24.5,
          "discount": 0,
          "total": 147
        },
        {
          "productId": "prod-6Gh2jKl8Zx",
          "name": "Amberlin Bond Repair Conditioner 33.8 fl oz",
          "quantity": 4,
          "unitPrice": 26.5,
          "discount": 0,
          "total": 106
        }
      ],
      "productsTotal": 253,
      "discount": 0,
      "shipping": 0,
      "salesTax": 22.01,
      "total": 275.01,
      "currency": "usd",
      "deliveryAddress": {
        "line1": "1450 Larimer St",
        "line2": "Suite 200",
        "city": "Denver",
        "state": "CO",
        "postalCode": "80202",
        "country": "US",
        "phone": "+13035550142"
      },
      "trackingNumbers": [],
      "createdAt": "2026-10-26T15:42:10Z",
      "updatedAt": "2026-10-26T15:42:10Z",
      "deliveredAt": null
    }
  ]
}

400

validation_failed: a field is missing or has a wrong value. field names it.

application/json

The body of every error response.

object

error

required

object

code

required

A stable error code.

string

Allowed values: invalid_app_token invalid_user_token user_token_expired origin_not_allowed ip_not_allowed user_cannot_manage_company user_cannot_order company_blocked company_not_verified app_setup_incomplete not_found validation_failed email_invalid_format email_domain_not_found email_mailbox_not_found address_state_without_license hazmat_destination ship_to_restricted verification_data_missing document_locked document_already_uploaded file_too_large file_type_not_supported reply_not_expected order_action_not_allowed supplier_refused_cancel order_total_changed order_has_problems idempotency_key_reused idempotency_key_in_use rate_limit_exceeded internal_error

message

required

A sentence for developers. It can change, so do not match on it.

string

field

The request field that caused the error. Only some errors have it.

string

missing

Only on verification_data_missing and app_setup_incomplete. What still needs to be set.

Array<string>

quote

Only on order_total_changed and order_has_problems. A fresh quote.

object

groups

required

One group per supplier. Each group becomes one order.

Array<object>

object

supplierId

required

string

lines

required

Array<object>

object

productId

required

string

quantity

required

integer

unitPrice

required

An amount in dollars, with up to two decimal places.

number

discount

required

The discount on the whole line, in US dollars.

number

total

required

An amount in dollars, with up to two decimal places.

number

productsTotal

required

The total of the lines, in US dollars.

number

orderDiscount

required

The discount on the whole order, in US dollars.

number

shipping

required

object

amount

required

The shipping charge in US dollars, or null when it cannot be worked out.

number | null

kind

required

string

Allowed values: free flat carrier

freeShippingRemaining

required

How much more to order for free shipping, or null when it does not apply.

number | null

salesTax

required

The sales tax in US dollars, or null when it cannot be worked out.

number | null

taxExemption

required

object

certificateId

required

The exemption certificate used, or null.

string | null

notAppliedReason

required

Why no certificate applies, or null when one does.

string | null

Allowed values: no_certificate other_state not_reviewed

total

required

The amount the salon pays for this group in US dollars, or null when it cannot be worked out. Send it back as expectedTotal. A group with problems has no expectedTotal.

number | null

chargeTiming

required

now: Beauty Router charges the card when the order is created. after_verification: the company is prequalified, so the charge waits until its verification ends.

string

Allowed values: now after_verification

problems

required

Array<object>

object

code

required

What stops a group or the whole request. See Problems.

string

Allowed values: buying_suspended supplier_unavailable address_state_without_license ship_to_restricted hazmat_destination address_not_deliverable connection_required connection_blocked insufficient_stock product_unavailable shipping_unavailable tax_unavailable delivery_address_required delivery_phone_required payment_card_required payment_card_unusable quantity_limit_exceeded order_limit_exceeded order_below_minimum

message

required

A sentence you can show. It can change, so do not match on it.

string

productId

The product. Only on problems with one product.

string

supplierId

The supplier. Only on problems with one supplier.

string

available

How many units can be ordered. Only on insufficient_stock.

integer

unresolvedLines

required

The lines no supplier can take.

Array<object>

object

productId

required

string

quantity

required

integer

problems

required

Array<object>

object

code

required

What stops a group or the whole request. See Problems.

string

message

required

A sentence you can show. It can change, so do not match on it.

string

productId

The product. Only on problems with one product.

string

supplierId

The supplier. Only on problems with one supplier.

string

available

How many units can be ordered. Only on insufficient_stock.

integer

companyProblems

required

What stops every group.

Array<object>

object

code

required

What stops a group or the whole request. See Problems.

string

message

required

A sentence you can show. It can change, so do not match on it.

string

productId

The product. Only on problems with one product.

string

supplierId

The supplier. Only on problems with one supplier.

string

available

How many units can be ordered. Only on insufficient_stock.

integer

total

required

The sum of all the groups in US dollars, or null when a group’s total is.

number | null

currency

required

Always usd.

string

Allowed value: usd

Examples

validation_failed

{
  "error": {
    "code": "validation_failed",
    "message": "ein must have 9 digits.",
    "field": "ein"
  }
}

401

invalid_user_token: the user token is missing or wrong. user_token_expired: the user token expired. Log the user in again with POST /v1/login.

application/json

The body of every error response.

object

error

required

object

code

required

A stable error code.

string

message

required

A sentence for developers. It can change, so do not match on it.

string

field

The request field that caused the error. Only some errors have it.

string

missing

Only on verification_data_missing and app_setup_incomplete. What still needs to be set.

Array<string>

quote

Only on order_total_changed and order_has_problems. A fresh quote.

object

groups

required

One group per supplier. Each group becomes one order.

Array<object>

object

supplierId

required

string

lines

required

Array<object>

object

productId

required

string

quantity

required

integer

unitPrice

required

An amount in dollars, with up to two decimal places.

number

discount

required

The discount on the whole line, in US dollars.

number

total

required

An amount in dollars, with up to two decimal places.

number

productsTotal

required

The total of the lines, in US dollars.

number

orderDiscount

required

The discount on the whole order, in US dollars.

number

shipping

required

object

amount

required

The shipping charge in US dollars, or null when it cannot be worked out.

number | null

kind

required

string

Allowed values: free flat carrier

freeShippingRemaining

required

How much more to order for free shipping, or null when it does not apply.

number | null

salesTax

required

The sales tax in US dollars, or null when it cannot be worked out.

number | null

taxExemption

required

object

certificateId

required

The exemption certificate used, or null.

string | null

notAppliedReason

required

Why no certificate applies, or null when one does.

string | null

Allowed values: no_certificate other_state not_reviewed

total

required

The amount the salon pays for this group in US dollars, or null when it cannot be worked out. Send it back as expectedTotal. A group with problems has no expectedTotal.

number | null

chargeTiming

required

now: Beauty Router charges the card when the order is created. after_verification: the company is prequalified, so the charge waits until its verification ends.

string

Allowed values: now after_verification

problems

required

Array<object>

object

code

required

What stops a group or the whole request. See Problems.

string

message

required

A sentence you can show. It can change, so do not match on it.

string

productId

The product. Only on problems with one product.

string

supplierId

The supplier. Only on problems with one supplier.

string

available

How many units can be ordered. Only on insufficient_stock.

integer

unresolvedLines

required

The lines no supplier can take.

Array<object>

object

productId

required

string

quantity

required

integer

problems

required

Array<object>

object

code

required

What stops a group or the whole request. See Problems.

string

message

required

A sentence you can show. It can change, so do not match on it.

string

productId

The product. Only on problems with one product.

string

supplierId

The supplier. Only on problems with one supplier.

string

available

How many units can be ordered. Only on insufficient_stock.

integer

companyProblems

required

What stops every group.

Array<object>

object

code

required

What stops a group or the whole request. See Problems.

string

message

required

A sentence you can show. It can change, so do not match on it.

string

productId

The product. Only on problems with one product.

string

supplierId

The supplier. Only on problems with one supplier.

string

available

How many units can be ordered. Only on insufficient_stock.

integer

total

required

The sum of all the groups in US dollars, or null when a group’s total is.

number | null

currency

required

Always usd.

string

Allowed value: usd

Examples

{
  "error": {
    "code": "invalid_user_token",
    "message": "The user token is missing or not valid."
  }
}

{
  "error": {
    "code": "user_token_expired",
    "message": "The user token expired. Log the user in again."
  }
}

403

user_cannot_order: the user was logged in with canOrder: false. company_not_verified: the company is not prequalified or verified.

application/json

The body of every error response.

object

error

required

object

code

required

A stable error code.

string

message

required

A sentence for developers. It can change, so do not match on it.

string

field

The request field that caused the error. Only some errors have it.

string

missing

Only on verification_data_missing and app_setup_incomplete. What still needs to be set.

Array<string>

quote

Only on order_total_changed and order_has_problems. A fresh quote.

object

groups

required

One group per supplier. Each group becomes one order.

Array<object>

object

supplierId

required

string

lines

required

Array<object>

object

productId

required

string

quantity

required

integer

unitPrice

required

An amount in dollars, with up to two decimal places.

number

discount

required

The discount on the whole line, in US dollars.

number

total

required

An amount in dollars, with up to two decimal places.

number

productsTotal

required

The total of the lines, in US dollars.

number

orderDiscount

required

The discount on the whole order, in US dollars.

number

shipping

required

object

amount

required

The shipping charge in US dollars, or null when it cannot be worked out.

number | null

kind

required

string

Allowed values: free flat carrier

freeShippingRemaining

required

How much more to order for free shipping, or null when it does not apply.

number | null

salesTax

required

The sales tax in US dollars, or null when it cannot be worked out.

number | null

taxExemption

required

object

certificateId

required

The exemption certificate used, or null.

string | null

notAppliedReason

required

Why no certificate applies, or null when one does.

string | null

Allowed values: no_certificate other_state not_reviewed

total

required

The amount the salon pays for this group in US dollars, or null when it cannot be worked out. Send it back as expectedTotal. A group with problems has no expectedTotal.

number | null

chargeTiming

required

now: Beauty Router charges the card when the order is created. after_verification: the company is prequalified, so the charge waits until its verification ends.

string

Allowed values: now after_verification

problems

required

Array<object>

object

code

required

What stops a group or the whole request. See Problems.

string

message

required

A sentence you can show. It can change, so do not match on it.

string

productId

The product. Only on problems with one product.

string

supplierId

The supplier. Only on problems with one supplier.

string

available

How many units can be ordered. Only on insufficient_stock.

integer

unresolvedLines

required

The lines no supplier can take.

Array<object>

object

productId

required

string

quantity

required

integer

problems

required

Array<object>

object

code

required

What stops a group or the whole request. See Problems.

string

message

required

A sentence you can show. It can change, so do not match on it.

string

productId

The product. Only on problems with one product.

string

supplierId

The supplier. Only on problems with one supplier.

string

available

How many units can be ordered. Only on insufficient_stock.

integer

companyProblems

required

What stops every group.

Array<object>

object

code

required

What stops a group or the whole request. See Problems.

string

message

required

A sentence you can show. It can change, so do not match on it.

string

productId

The product. Only on problems with one product.

string

supplierId

The supplier. Only on problems with one supplier.

string

available

How many units can be ordered. Only on insufficient_stock.

integer

total

required

The sum of all the groups in US dollars, or null when a group’s total is.

number | null

currency

required

Always usd.

string

Allowed value: usd

Examples

{
  "error": {
    "code": "user_cannot_order",
    "message": "This user cannot place or change orders."
  }
}

{
  "error": {
    "code": "company_not_verified",
    "message": "The company must be prequalified or verified to see wholesale prices and order."
  }
}

404

not_found: the object does not exist, or the user has no access to it.

application/json

The body of every error response.

object

error

required

object

code

required

A stable error code.

string

message

required

A sentence for developers. It can change, so do not match on it.

string

field

The request field that caused the error. Only some errors have it.

string

missing

Only on verification_data_missing and app_setup_incomplete. What still needs to be set.

Array<string>

quote

Only on order_total_changed and order_has_problems. A fresh quote.

object

groups

required

One group per supplier. Each group becomes one order.

Array<object>

object

supplierId

required

string

lines

required

Array<object>

object

productId

required

string

quantity

required

integer

unitPrice

required

An amount in dollars, with up to two decimal places.

number

discount

required

The discount on the whole line, in US dollars.

number

total

required

An amount in dollars, with up to two decimal places.

number

productsTotal

required

The total of the lines, in US dollars.

number

orderDiscount

required

The discount on the whole order, in US dollars.

number

shipping

required

object

amount

required

The shipping charge in US dollars, or null when it cannot be worked out.

number | null

kind

required

string

Allowed values: free flat carrier

freeShippingRemaining

required

How much more to order for free shipping, or null when it does not apply.

number | null

salesTax

required

The sales tax in US dollars, or null when it cannot be worked out.

number | null

taxExemption

required

object

certificateId

required

The exemption certificate used, or null.

string | null

notAppliedReason

required

Why no certificate applies, or null when one does.

string | null

Allowed values: no_certificate other_state not_reviewed

total

required

The amount the salon pays for this group in US dollars, or null when it cannot be worked out. Send it back as expectedTotal. A group with problems has no expectedTotal.

number | null

chargeTiming

required

now: Beauty Router charges the card when the order is created. after_verification: the company is prequalified, so the charge waits until its verification ends.

string

Allowed values: now after_verification

problems

required

Array<object>

object

code

required

What stops a group or the whole request. See Problems.

string

message

required

A sentence you can show. It can change, so do not match on it.

string

productId

The product. Only on problems with one product.

string

supplierId

The supplier. Only on problems with one supplier.

string

available

How many units can be ordered. Only on insufficient_stock.

integer

unresolvedLines

required

The lines no supplier can take.

Array<object>

object

productId

required

string

quantity

required

integer

problems

required

Array<object>

object

code

required

What stops a group or the whole request. See Problems.

string

message

required

A sentence you can show. It can change, so do not match on it.

string

productId

The product. Only on problems with one product.

string

supplierId

The supplier. Only on problems with one supplier.

string

available

How many units can be ordered. Only on insufficient_stock.

integer

companyProblems

required

What stops every group.

Array<object>

object

code

required

What stops a group or the whole request. See Problems.

string

message

required

A sentence you can show. It can change, so do not match on it.

string

productId

The product. Only on problems with one product.

string

supplierId

The supplier. Only on problems with one supplier.

string

available

How many units can be ordered. Only on insufficient_stock.

integer

total

required

The sum of all the groups in US dollars, or null when a group’s total is.

number | null

currency

required

Always usd.

string

Allowed value: usd

Examples

not_found

{
  "error": {
    "code": "not_found",
    "message": "The object was not found."
  }
}

409

Nothing was created. order_total_changed: a group differs from expectedTotal by $0.10 or more. order_has_problems: a group or the company has a problem. Both have a fresh quote in quote. idempotency_key_reused: the key was already used with a different body. idempotency_key_in_use: an earlier request with this key is still finishing, so try again shortly. order_action_not_allowed: draftOrderId names an order that is not a draft.

application/json

The body of every error response.

object

error

required

object

code

required

A stable error code.

string

message

required

A sentence for developers. It can change, so do not match on it.

string

field

The request field that caused the error. Only some errors have it.

string

missing

Only on verification_data_missing and app_setup_incomplete. What still needs to be set.

Array<string>

quote

Only on order_total_changed and order_has_problems. A fresh quote.

object

groups

required

One group per supplier. Each group becomes one order.

Array<object>

object

supplierId

required

string

lines

required

Array<object>

object

productId

required

string

quantity

required

integer

unitPrice

required

An amount in dollars, with up to two decimal places.

number

discount

required

The discount on the whole line, in US dollars.

number

total

required

An amount in dollars, with up to two decimal places.

number

productsTotal

required

The total of the lines, in US dollars.

number

orderDiscount

required

The discount on the whole order, in US dollars.

number

shipping

required

object

amount

required

The shipping charge in US dollars, or null when it cannot be worked out.

number | null

kind

required

string

Allowed values: free flat carrier

freeShippingRemaining

required

How much more to order for free shipping, or null when it does not apply.

number | null

salesTax

required

The sales tax in US dollars, or null when it cannot be worked out.

number | null

taxExemption

required

object

certificateId

required

The exemption certificate used, or null.

string | null

notAppliedReason

required

Why no certificate applies, or null when one does.

string | null

Allowed values: no_certificate other_state not_reviewed

total

required

The amount the salon pays for this group in US dollars, or null when it cannot be worked out. Send it back as expectedTotal. A group with problems has no expectedTotal.

number | null

chargeTiming

required

now: Beauty Router charges the card when the order is created. after_verification: the company is prequalified, so the charge waits until its verification ends.

string

Allowed values: now after_verification

problems

required

Array<object>

object

code

required

What stops a group or the whole request. See Problems.

string

message

required

A sentence you can show. It can change, so do not match on it.

string

productId

The product. Only on problems with one product.

string

supplierId

The supplier. Only on problems with one supplier.

string

available

How many units can be ordered. Only on insufficient_stock.

integer

unresolvedLines

required

The lines no supplier can take.

Array<object>

object

productId

required

string

quantity

required

integer

problems

required

Array<object>

object

code

required

What stops a group or the whole request. See Problems.

string

message

required

A sentence you can show. It can change, so do not match on it.

string

productId

The product. Only on problems with one product.

string

supplierId

The supplier. Only on problems with one supplier.

string

available

How many units can be ordered. Only on insufficient_stock.

integer

companyProblems

required

What stops every group.

Array<object>

object

code

required

What stops a group or the whole request. See Problems.

string

message

required

A sentence you can show. It can change, so do not match on it.

string

productId

The product. Only on problems with one product.

string

supplierId

The supplier. Only on problems with one supplier.

string

available

How many units can be ordered. Only on insufficient_stock.

integer

total

required

The sum of all the groups in US dollars, or null when a group’s total is.

number | null

currency

required

Always usd.

string

Allowed value: usd

Examples

{
  "error": {
    "code": "order_total_changed",
    "message": "The total changed. Review the new quote.",
    "quote": {
      "groups": [
        {
          "supplierId": "sup-1Ry6tUi3Op",
          "lines": [
            {
              "productId": "prod-4Fz9QbX2kL",
              "quantity": 6,
              "unitPrice": 25,
              "discount": 0,
              "total": 150
            }
          ],
          "productsTotal": 150,
          "orderDiscount": 0,
          "shipping": {
            "amount": 0,
            "kind": "free"
          },
          "freeShippingRemaining": null,
          "salesTax": 13.05,
          "taxExemption": {
            "certificateId": null,
            "notAppliedReason": "no_certificate"
          },
          "total": 163.05,
          "chargeTiming": "now",
          "problems": []
        }
      ],
      "unresolvedLines": [],
      "companyProblems": [],
      "total": 163.05,
      "currency": "usd"
    }
  }
}

{
  "error": {
    "code": "order_has_problems",
    "message": "A group has a problem. See the quote.",
    "quote": {
      "groups": [
        {
          "supplierId": "sup-1Ry6tUi3Op",
          "lines": [
            {
              "productId": "prod-4Fz9QbX2kL",
              "quantity": 6,
              "unitPrice": 24.5,
              "discount": 0,
              "total": 147
            }
          ],
          "productsTotal": 147,
          "orderDiscount": 0,
          "shipping": {
            "amount": 12,
            "kind": "flat"
          },
          "freeShippingRemaining": 3,
          "salesTax": 12.79,
          "taxExemption": {
            "certificateId": null,
            "notAppliedReason": "no_certificate"
          },
          "total": 171.79,
          "chargeTiming": "now",
          "problems": [
            {
              "code": "insufficient_stock",
              "message": "Only 4 units are available.",
              "productId": "prod-4Fz9QbX2kL",
              "available": 4
            }
          ]
        }
      ],
      "unresolvedLines": [],
      "companyProblems": [],
      "total": 171.79,
      "currency": "usd"
    }
  }
}

{
  "error": {
    "code": "idempotency_key_reused",
    "message": "This Idempotency-Key was already used with a different body."
  }
}

{
  "error": {
    "code": "idempotency_key_in_use",
    "message": "An earlier request with this Idempotency-Key is still finishing. Try again shortly."
  }
}

{
  "error": {
    "code": "order_action_not_allowed",
    "message": "This order is not a draft."
  }
}

500

internal_error: something failed on Beauty Router’s side. Try again later.

application/json

The body of every error response.

object

error

required

object

code

required

A stable error code.

string

message

required

A sentence for developers. It can change, so do not match on it.

string

field

The request field that caused the error. Only some errors have it.

string

missing

Only on verification_data_missing and app_setup_incomplete. What still needs to be set.

Array<string>

quote

Only on order_total_changed and order_has_problems. A fresh quote.

object

groups

required

One group per supplier. Each group becomes one order.

Array<object>

object

supplierId

required

string

lines

required

Array<object>

object

productId

required

string

quantity

required

integer

unitPrice

required

An amount in dollars, with up to two decimal places.

number

discount

required

The discount on the whole line, in US dollars.

number

total

required

An amount in dollars, with up to two decimal places.

number

productsTotal

required

The total of the lines, in US dollars.

number

orderDiscount

required

The discount on the whole order, in US dollars.

number

shipping

required

object

amount

required

The shipping charge in US dollars, or null when it cannot be worked out.

number | null

kind

required

string

Allowed values: free flat carrier

freeShippingRemaining

required

How much more to order for free shipping, or null when it does not apply.

number | null

salesTax

required

The sales tax in US dollars, or null when it cannot be worked out.

number | null

taxExemption

required

object

certificateId

required

The exemption certificate used, or null.

string | null

notAppliedReason

required

Why no certificate applies, or null when one does.

string | null

Allowed values: no_certificate other_state not_reviewed

total

required

The amount the salon pays for this group in US dollars, or null when it cannot be worked out. Send it back as expectedTotal. A group with problems has no expectedTotal.

number | null

chargeTiming

required

now: Beauty Router charges the card when the order is created. after_verification: the company is prequalified, so the charge waits until its verification ends.

string

Allowed values: now after_verification

problems

required

Array<object>

object

code

required

What stops a group or the whole request. See Problems.

string

message

required

A sentence you can show. It can change, so do not match on it.

string

productId

The product. Only on problems with one product.

string

supplierId

The supplier. Only on problems with one supplier.

string

available

How many units can be ordered. Only on insufficient_stock.

integer

unresolvedLines

required

The lines no supplier can take.

Array<object>

object

productId

required

string

quantity

required

integer

problems

required

Array<object>

object

code

required

What stops a group or the whole request. See Problems.

string

message

required

A sentence you can show. It can change, so do not match on it.

string

productId

The product. Only on problems with one product.

string

supplierId

The supplier. Only on problems with one supplier.

string

available

How many units can be ordered. Only on insufficient_stock.

integer

companyProblems

required

What stops every group.

Array<object>

object

code

required

What stops a group or the whole request. See Problems.

string

message

required

A sentence you can show. It can change, so do not match on it.

string

productId

The product. Only on problems with one product.

string

supplierId

The supplier. Only on problems with one supplier.

string

available

How many units can be ordered. Only on insufficient_stock.

integer

total

required

The sum of all the groups in US dollars, or null when a group’s total is.

number | null

currency

required

Always usd.

string

Allowed value: usd

Examples

internal_error

{
  "error": {
    "code": "internal_error",
    "message": "Something went wrong. Try again later."
  }
}

Place orders

Authorizations

Parameters

Header Parameters

Example

Request Bodyrequired

Examples

Responses

201

Examples

400

Examples

401

Examples

403

Examples

404

Examples

409

Examples

500

Examples

Request Body^required