# Get an order `GET /v1/orders/{orderId}` Returns one order, which can be a draft. The order must belong to the company of the logged-in user, otherwise the request fails with `not_found`. ```yaml parameters: - name: orderId in: path required: true description: The order ID. schema: type: string example: order-8Jd3kFs6Gh responses: "200": description: The order. content: application/json: schema: type: object required: - id - number - companyId - userId - status - supplier - lines - productsTotal - discount - shipping - salesTax - total - currency - deliveryAddress - trackingNumbers - createdAt - updatedAt - deliveredAt properties: id: type: string description: The order ID. examples: - order-8Jd3kFs6Gh number: type: string description: The order number people see. examples: - 4821-7730 companyId: type: string description: The company the order belongs to. examples: - loc-7Hk2pQx9Lm userId: type: string description: The user who placed the order. examples: - user-3Vb8nWq1Rt status: type: string description: > `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. enum: - draft - pending_verification - payment_failed - placed - ready_to_ship - in_transit - delivered - delivery_failed - canceled cancelReason: type: string description: > `salon`: the salon canceled the order. `supplier`: the brand or distributor canceled it. `payment`: the card charge failed, or the payment was disputed or refunded. `verification`: the company did not pass verification. enum: - salon - supplier - payment - verification supplier: type: object description: The brand or distributor that fulfills the order. required: - id - name properties: id: type: string examples: - sup-1Ry6tUi3Op name: type: string lines: type: array items: type: object required: - productId - name - quantity - unitPrice - discount - total properties: productId: type: string description: The product ID. name: type: string description: The product name. quantity: type: integer minimum: 1 unitPrice: type: number description: An amount in dollars, with up to two decimal places. discount: type: number description: An amount in dollars, with up to two decimal places. total: type: number description: An amount in dollars, with up to two decimal places. productsTotal: type: number description: An amount in dollars, with up to two decimal places. discount: type: number description: An amount in dollars, with up to two decimal places. shipping: type: - number - "null" description: > 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. salesTax: type: - number - "null" description: The sales tax, in US dollars. `null` on a draft with no address. total: type: - number - "null" description: > The amount the salon pays, in US dollars. It can change until the order is `placed`. `null` on a draft with no address. currency: type: string const: usd description: Always `usd`. deliveryAddress: description: Where the order is delivered. `null` on a draft with no address. oneOf: - type: object required: - line1 - city - state - postalCode - country properties: line1: type: string description: Street address. line2: type: string description: Suite, unit, or floor. city: type: string state: type: string pattern: ^[A-Z]{2}$ description: A two-letter US state code. examples: - CO postalCode: type: string description: ZIP code. country: type: string const: US phone: type: string description: Phone number for the delivery. Required on the company. Optional on an order, which then uses the company's phone. - type: "null" trackingNumbers: type: array items: type: object required: - number properties: number: type: string url: type: string format: uri description: The carrier's tracking page. Left out when there is none. carrier: type: string description: The carrier. Left out when it is not known. createdAt: type: string format: date-time updatedAt: type: string format: date-time deliveredAt: type: - string - "null" format: date-time description: When the order was delivered, or `null`. examples: Order in transit: value: id: order-8Jd3kFs6Gh number: 4821-7730 companyId: loc-7Hk2pQx9Lm userId: user-3Vb8nWq1Rt status: in_transit 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: - number: 1Z999AA10123456784 url: https://www.ups.com/track?tracknum=1Z999AA10123456784 carrier: UPS createdAt: 2026-10-26T15:42:10Z updatedAt: 2026-10-28T19:03:55Z deliveredAt: null "401": description: > `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`. content: application/json: schema: type: object description: The body of every error response. required: - error properties: error: type: object required: - code - message properties: code: type: string description: A stable error code. enum: - 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: type: string description: A sentence for developers. It can change, so do not match on it. field: type: string description: The request field that caused the error. Only some errors have it. missing: type: array items: type: string description: Only on `verification_data_missing` and `app_setup_incomplete`. What still needs to be set. quote: type: object required: - groups - unresolvedLines - companyProblems - total - currency properties: groups: type: array description: One group per supplier. Each group becomes one order. items: type: object required: - supplierId - lines - productsTotal - orderDiscount - shipping - freeShippingRemaining - salesTax - taxExemption - total - chargeTiming - problems properties: supplierId: type: string examples: - sup-1Ry6tUi3Op lines: type: array items: type: object required: - productId - quantity - unitPrice - discount - total properties: productId: type: string quantity: type: integer unitPrice: type: number description: An amount in dollars, with up to two decimal places. discount: type: number description: An amount in dollars, with up to two decimal places. total: type: number description: An amount in dollars, with up to two decimal places. productsTotal: type: number description: An amount in dollars, with up to two decimal places. orderDiscount: type: number description: An amount in dollars, with up to two decimal places. shipping: type: object required: - amount - kind properties: amount: type: - number - "null" description: The shipping charge in US dollars, or `null` when it cannot be worked out. kind: type: string enum: - free - flat - carrier freeShippingRemaining: type: - number - "null" description: How much more to order for free shipping, or `null` when it does not apply. salesTax: type: - number - "null" description: The sales tax in US dollars, or `null` when it cannot be worked out. taxExemption: type: object required: - certificateId - notAppliedReason properties: certificateId: type: - string - "null" description: The exemption certificate used, or `null`. notAppliedReason: type: - string - "null" enum: - no_certificate - other_state - not_reviewed - null description: Why no certificate applies, or `null` when one does. total: type: - number - "null" description: > 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`. chargeTiming: type: string enum: - now - after_verification description: > `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. problems: type: array items: type: object required: - code - message properties: code: type: string description: What stops a group or the whole request. See [Problems](/create-orders/#problems). enum: - 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: type: string description: A sentence you can show. It can change, so do not match on it. productId: type: string description: The product. Only on problems with one product. supplierId: type: string description: The supplier. Only on problems with one supplier. available: type: integer description: How many units can be ordered. Only on `insufficient_stock`. unresolvedLines: type: array description: The lines no supplier can take. items: type: object required: - productId - quantity - problems properties: productId: type: string quantity: type: integer problems: type: array items: type: object required: - code - message properties: code: type: string description: What stops a group or the whole request. See [Problems](/create-orders/#problems). enum: - 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: type: string description: A sentence you can show. It can change, so do not match on it. productId: type: string description: The product. Only on problems with one product. supplierId: type: string description: The supplier. Only on problems with one supplier. available: type: integer description: How many units can be ordered. Only on `insufficient_stock`. companyProblems: type: array description: What stops every group. items: type: object required: - code - message properties: code: type: string description: What stops a group or the whole request. See [Problems](/create-orders/#problems). enum: - 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: type: string description: A sentence you can show. It can change, so do not match on it. productId: type: string description: The product. Only on problems with one product. supplierId: type: string description: The supplier. Only on problems with one supplier. available: type: integer description: How many units can be ordered. Only on `insufficient_stock`. total: type: - number - "null" description: The sum of all the groups in US dollars, or `null` when a group's total is. currency: type: string const: usd description: Always `usd`. examples: invalid_user_token: value: error: code: invalid_user_token message: The user token is missing or not valid. user_token_expired: value: error: code: user_token_expired message: The user token expired. Log the user in again. "404": description: "`not_found`: the object does not exist, or the user has no access to it." content: application/json: schema: type: object description: The body of every error response. required: - error properties: error: type: object required: - code - message properties: code: type: string description: A stable error code. enum: - 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: type: string description: A sentence for developers. It can change, so do not match on it. field: type: string description: The request field that caused the error. Only some errors have it. missing: type: array items: type: string description: Only on `verification_data_missing` and `app_setup_incomplete`. What still needs to be set. quote: type: object required: - groups - unresolvedLines - companyProblems - total - currency properties: groups: type: array description: One group per supplier. Each group becomes one order. items: type: object required: - supplierId - lines - productsTotal - orderDiscount - shipping - freeShippingRemaining - salesTax - taxExemption - total - chargeTiming - problems properties: supplierId: type: string examples: - sup-1Ry6tUi3Op lines: type: array items: type: object required: - productId - quantity - unitPrice - discount - total properties: productId: type: string quantity: type: integer unitPrice: type: number description: An amount in dollars, with up to two decimal places. discount: type: number description: An amount in dollars, with up to two decimal places. total: type: number description: An amount in dollars, with up to two decimal places. productsTotal: type: number description: An amount in dollars, with up to two decimal places. orderDiscount: type: number description: An amount in dollars, with up to two decimal places. shipping: type: object required: - amount - kind properties: amount: type: - number - "null" description: The shipping charge in US dollars, or `null` when it cannot be worked out. kind: type: string enum: - free - flat - carrier freeShippingRemaining: type: - number - "null" description: How much more to order for free shipping, or `null` when it does not apply. salesTax: type: - number - "null" description: The sales tax in US dollars, or `null` when it cannot be worked out. taxExemption: type: object required: - certificateId - notAppliedReason properties: certificateId: type: - string - "null" description: The exemption certificate used, or `null`. notAppliedReason: type: - string - "null" enum: - no_certificate - other_state - not_reviewed - null description: Why no certificate applies, or `null` when one does. total: type: - number - "null" description: > 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`. chargeTiming: type: string enum: - now - after_verification description: > `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. problems: type: array items: type: object required: - code - message properties: code: type: string description: What stops a group or the whole request. See [Problems](/create-orders/#problems). enum: - 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: type: string description: A sentence you can show. It can change, so do not match on it. productId: type: string description: The product. Only on problems with one product. supplierId: type: string description: The supplier. Only on problems with one supplier. available: type: integer description: How many units can be ordered. Only on `insufficient_stock`. unresolvedLines: type: array description: The lines no supplier can take. items: type: object required: - productId - quantity - problems properties: productId: type: string quantity: type: integer problems: type: array items: type: object required: - code - message properties: code: type: string description: What stops a group or the whole request. See [Problems](/create-orders/#problems). enum: - 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: type: string description: A sentence you can show. It can change, so do not match on it. productId: type: string description: The product. Only on problems with one product. supplierId: type: string description: The supplier. Only on problems with one supplier. available: type: integer description: How many units can be ordered. Only on `insufficient_stock`. companyProblems: type: array description: What stops every group. items: type: object required: - code - message properties: code: type: string description: What stops a group or the whole request. See [Problems](/create-orders/#problems). enum: - 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: type: string description: A sentence you can show. It can change, so do not match on it. productId: type: string description: The product. Only on problems with one product. supplierId: type: string description: The supplier. Only on problems with one supplier. available: type: integer description: How many units can be ordered. Only on `insufficient_stock`. total: type: - number - "null" description: The sum of all the groups in US dollars, or `null` when a group's total is. currency: type: string const: usd description: Always `usd`. examples: not_found: value: error: code: not_found message: The object was not found. "500": description: "`internal_error`: something failed on Beauty Router's side. Try again later." content: application/json: schema: type: object description: The body of every error response. required: - error properties: error: type: object required: - code - message properties: code: type: string description: A stable error code. enum: - 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: type: string description: A sentence for developers. It can change, so do not match on it. field: type: string description: The request field that caused the error. Only some errors have it. missing: type: array items: type: string description: Only on `verification_data_missing` and `app_setup_incomplete`. What still needs to be set. quote: type: object required: - groups - unresolvedLines - companyProblems - total - currency properties: groups: type: array description: One group per supplier. Each group becomes one order. items: type: object required: - supplierId - lines - productsTotal - orderDiscount - shipping - freeShippingRemaining - salesTax - taxExemption - total - chargeTiming - problems properties: supplierId: type: string examples: - sup-1Ry6tUi3Op lines: type: array items: type: object required: - productId - quantity - unitPrice - discount - total properties: productId: type: string quantity: type: integer unitPrice: type: number description: An amount in dollars, with up to two decimal places. discount: type: number description: An amount in dollars, with up to two decimal places. total: type: number description: An amount in dollars, with up to two decimal places. productsTotal: type: number description: An amount in dollars, with up to two decimal places. orderDiscount: type: number description: An amount in dollars, with up to two decimal places. shipping: type: object required: - amount - kind properties: amount: type: - number - "null" description: The shipping charge in US dollars, or `null` when it cannot be worked out. kind: type: string enum: - free - flat - carrier freeShippingRemaining: type: - number - "null" description: How much more to order for free shipping, or `null` when it does not apply. salesTax: type: - number - "null" description: The sales tax in US dollars, or `null` when it cannot be worked out. taxExemption: type: object required: - certificateId - notAppliedReason properties: certificateId: type: - string - "null" description: The exemption certificate used, or `null`. notAppliedReason: type: - string - "null" enum: - no_certificate - other_state - not_reviewed - null description: Why no certificate applies, or `null` when one does. total: type: - number - "null" description: > 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`. chargeTiming: type: string enum: - now - after_verification description: > `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. problems: type: array items: type: object required: - code - message properties: code: type: string description: What stops a group or the whole request. See [Problems](/create-orders/#problems). enum: - 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: type: string description: A sentence you can show. It can change, so do not match on it. productId: type: string description: The product. Only on problems with one product. supplierId: type: string description: The supplier. Only on problems with one supplier. available: type: integer description: How many units can be ordered. Only on `insufficient_stock`. unresolvedLines: type: array description: The lines no supplier can take. items: type: object required: - productId - quantity - problems properties: productId: type: string quantity: type: integer problems: type: array items: type: object required: - code - message properties: code: type: string description: What stops a group or the whole request. See [Problems](/create-orders/#problems). enum: - 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: type: string description: A sentence you can show. It can change, so do not match on it. productId: type: string description: The product. Only on problems with one product. supplierId: type: string description: The supplier. Only on problems with one supplier. available: type: integer description: How many units can be ordered. Only on `insufficient_stock`. companyProblems: type: array description: What stops every group. items: type: object required: - code - message properties: code: type: string description: What stops a group or the whole request. See [Problems](/create-orders/#problems). enum: - 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: type: string description: A sentence you can show. It can change, so do not match on it. productId: type: string description: The product. Only on problems with one product. supplierId: type: string description: The supplier. Only on problems with one supplier. available: type: integer description: How many units can be ordered. Only on `insufficient_stock`. total: type: - number - "null" description: The sum of all the groups in US dollars, or `null` when a group's total is. currency: type: string const: usd description: Always `usd`. examples: internal_error: value: error: code: internal_error message: Something went wrong. Try again later. ```