# List orders `GET /v1/orders` Lists the orders of the logged-in user's company, newest first, including drafts. `status` is an optional filter. ```yaml parameters: - name: status in: query required: false description: Return only orders with this status. schema: 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 example: draft - name: limit in: query required: false description: How many items to return. schema: type: integer minimum: 1 maximum: 200 default: 50 - name: startingAfter in: query required: false description: The ID of the last item on the previous page. Leave it out for the first page. schema: type: string responses: "200": description: A page of orders. content: application/json: schema: type: object required: - data - hasMore properties: data: type: array items: 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`. hasMore: type: boolean description: "`true` when another page follows." "400": description: "`validation_failed`: a field is missing or has a wrong value. `field` names 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: validation_failed: value: error: code: validation_failed message: ein must have 9 digits. field: ein "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. "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. ```