> ## Documentation Index
> Fetch the complete documentation index at: https://docs.byblend.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create an order
> Create a new order.
If a mergeable order exists for the provided patient, a new order request will be merged into the existing order, unless `force_new=true` is specified. Please see Order Merging for more details.
## OpenAPI
````yaml /openapi-public.yml post /api/v1/orders
openapi: 3.0.3
info:
title: Blend API
version: 1.0.0
description: API for Blend
servers:
- url: https://api.byblend.com
description: Blend production server
security:
- bearerAuth: []
tags:
- name: Orders
description: Order management endpoints
- name: Patients
description: Patient management endpoints
- name: Reports
description: Reporting endpoints
- name: Products and Materials
description: Product catalog and inventory endpoints
- name: Electronic Prescriptions
description: Electronic prescription management endpoints
- name: Authentication
description: Authentication endpoints
- name: Notifications
description: User management endpoints
- name: Prescribers
paths:
/api/v1/orders:
post:
tags:
- Orders
summary: Create an order
description: >
Create a new order.
If a mergeable order exists for the provided patient, a new order
request will be merged into the existing order, unless `force_new=true`
is specified. Please see Order
Merging for more details.
parameters:
- name: force_new
in: query
required: false
description: >-
If 'true', creates a new order even if a mergeable order exists for
the patient. Default is 'false', which merges into existing open
orders when available.
schema:
type: boolean
example: true
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OrderCreate'
responses:
'201':
description: Order created successfully
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/OrderWithProducts'
- type: object
properties:
merged_into_existing:
type: boolean
example: true
description: >-
Indicates if the order was merged into an existing
order. If so, the existing order details will have
populated the response.
components:
schemas:
OrderCreate:
type: object
required:
- patient_id
- patient
properties:
address:
$ref: '#/components/schemas/AddressCreate'
description: Order shipping address, if different from the patient's address
custom_shipping:
$ref: '#/components/schemas/OrderCreateCustomShipping'
description: >-
Custom shipping details for the order. Your account must have custom
shipping enabled to use this field; all subfields are required.
electronic_prescription_ids:
type: array
items:
type: string
example:
- BFCB96C9-F866-405E-A1B3-3ED031DFB423
- 3CBEED4B-695B-4E61-A71A-7E7FB22330EF
description: List of electronic prescription IDs to associate with the order.
format: uuid
description: >-
If you have created electronic prescription(s) using the Electronic
Prescriptions endpoint, you may optionally supply a list of
electronic prescription `id` values to associate. This is an
optional convenience field to assist with prescription matching.
external_id:
type: string
example: my-system-128318AA2
description: External (your own system's) ID to associate with the order.
patient_id:
type: string
format: uuid
example: 0227d1e5-ba9a-42b5-8fe2-38882aa65708
description: >-
Blend ID of an existing patient to associate with the order. (You
may pass this here or within the `patient` object.) One of a
`patient_id` or `patient` object must be provided.
patient:
oneOf:
- $ref: '#/components/schemas/PatientCreate'
- $ref: '#/components/schemas/OrderPatientReferenceID'
- $ref: '#/components/schemas/OrderPatientReferenceExternalID'
description: >-
A patient object. If you pass new patient data, a new patient will
be created. Or you may reference an existing patient by `id` or
`external_id`.
products:
type: object
description: >-
You may supply product references using a Blend `id` or your own
`sku`; or, for prescription products, a `product code`.
properties:
prescription:
type: array
items:
$ref: '#/components/schemas/ProductPrescriptionAdd'
non_prescription:
type: array
items:
$ref: '#/components/schemas/ProductAdd'
order_material:
type: array
items:
$ref: '#/components/schemas/ProductAdd'
shipping:
$ref: '#/components/schemas/OrderCreateShipping'
type: object
OrderWithProducts:
allOf:
- $ref: '#/components/schemas/Order'
- type: object
properties:
products:
type: object
properties:
prescription:
type: array
items:
$ref: '#/components/schemas/ProductPrescriptionOrder'
non_prescription:
type: array
items:
$ref: '#/components/schemas/ProductNonPrescriptionOrder'
order_material:
type: array
items:
$ref: '#/components/schemas/ProductOrderMaterialOrder'
AddressCreate:
type: object
required:
- address_1
- city
- state
- zip_code
properties:
address_1:
type: string
example: 140 Lindgren Streets
address_2:
type: string
example: Apt 227
city:
type: string
example: North Consueloburgh
state:
type: string
description: Two-letter state abbreviation
example: CA
country:
type: string
description: Two-letter country code, defaults to US
example: US
zip_code:
type: string
description: 5-digit ZIP code or 9-digit ZIP+4 code, e.g. 02108 or 02108-1234.
example: '02108'
OrderCreateCustomShipping:
type: object
required:
- label_url
- tracking_number
- tracking_url
- carrier
properties:
label_url:
type: string
example: https://example.com/label.pdf
description: URL of the printable (4x6) custom shipping label
tracking_number:
type: string
example: TEST123456
description: Tracking number from the custom shipping label
tracking_url:
type: string
example: https://example.com/track/TEST123456
description: Tracking URL of the custom shipping label
carrier:
type: string
example: UPS
description: Carrier of the custom shipping label
PatientCreate:
title: New Patient
allOf:
- $ref: '#/components/schemas/PatientCreateUpdateBase'
required:
- first_name
- last_name
- email
- phone
- date_of_birth
- address
OrderPatientReferenceID:
type: object
title: ID
properties:
id:
type: string
format: uuid
example: 0227d1e5-ba9a-42b5-8fe2-38882aa65708
description: Blend ID of an existing patient to associate.
OrderPatientReferenceExternalID:
type: object
title: External ID
properties:
external_id:
type: string
example: '1234567890'
description: External (your own) ID for an existing patient.
ProductPrescriptionAdd:
description: >-
For each prescription product, you must reference one of a Blend product
`id`, `sku`, or `product code`
allOf:
- oneOf:
- title: Product ID
type: object
properties:
id:
type: string
format: uuid
description: Blend ID for the product
example: 0227d1e5-ba9a-42b5-8fe2-38882aa65708
required:
- id
- title: Product SKU
type: object
properties:
sku:
type: string
description: >-
Your own unique inventory identifier for the product, if
already mapped to the product in Blend
example: '1234567890'
required:
- sku
- title: Product Code
type: object
properties:
product_code:
type: string
description: >-
For prescription products only, specific product code
identifier, if already mapped to the product in Blend
example: PROD-001
required:
- product_code
- type: object
properties:
quantity:
type: integer
example: 1
description: Quantity of product to add to the order
reasons:
type: array
description: Medical reasons for requiring the compounded product
items:
$ref: '#/components/schemas/ID'
ProductAdd:
description: >-
For each non-prescription product or order material item, you must
reference one of a Blend product `id` or `sku`.
allOf:
- oneOf:
- title: Product ID
type: object
properties:
id:
type: string
format: uuid
description: Blend ID for the product
example: 0227d1e5-ba9a-42b5-8fe2-38882aa65708
required:
- id
- title: Product SKU
type: object
properties:
sku:
type: string
description: >-
Your own unique inventory identifier for the product, if
already mapped to the product in Blend
example: '1234567890'
required:
- sku
- type: object
properties:
quantity:
type: integer
example: 1
description: >-
Quantity to add to the order. If not provided, quantity will
default to 1.
OrderCreateShipping:
type: object
description: >
Shipping preferences for the order. Please ensure you have established
the ability to use this feature with Blend administrators before using.
You may provide one or both fields. If you provide a "generic"
`service_level` only, we will use the most appropriate carrier to match
the service level. If you provide both, your `service_level` prefix
("usps_") must match your `carrier`.
Available carriers and service levels can be found in the Shipping
Options endpoint.
properties:
carrier:
type: string
enum:
- ups
- usps
- fedex
example: usps
description: Shipment carrier. Valid values are `ups`, `usps`, `fedex`.
service_level:
type: string
enum:
- usps_priority
- usps_ground_advantage
- usps_priority_express
- fedex_ground
- fedex_2_day
- fedex_express_saver
- fedex_standard_overnight
- fedex_priority_overnight
- fedex_first_overnight
- ups_ground
- ups_second_day_air
- ups_next_day_air
- ups_3_day_select
- ups_next_day_air_saver
- ground
- 2_day
- next_day
example: usps_ground_advantage
Order:
allOf:
- $ref: '#/components/schemas/ID'
- $ref: '#/components/schemas/Timestamps'
- type: object
properties:
address:
$ref: '#/components/schemas/Address'
custom_shipping:
$ref: '#/components/schemas/OrderCustomShipping'
description: >-
Custom shipping details for the order if your account has custom
shipping enabled, and you have provided prepaid label details.
customer_id:
type: string
format: uuid
example: b658f16f-819c-4503-aede-bd555fc4ebfb
external_id:
type: string
example: my-system-128318AA2
description: External (your own system's) ID associated with the order.
is_replacement:
type: boolean
example: false
description: Whether the order is a replacement order
order_number:
type: string
example: ORD250312003548IAU4
description: Friendlier identifier for the order. Auto-generated.
original_order_id:
type: string
format: uuid
example: 0227d1e5-ba9a-42b5-8fe2-38882aa65708
description: ID of the original order, if this is a replacement order
patient:
$ref: '#/components/schemas/PatientOrder'
prescription_count:
type: integer
example: 1
description: >-
Number of prescriptions associated with the order (expected to
be the same as the number of prescription products in the
products object)
priority_requested:
type: boolean
example: false
description: Whether the order has a priority request
cancellation_requested:
type: boolean
example: false
description: >-
Whether the customer has requested cancellation for an order in
picked or verified status
replacement_order_ids:
type: array
items:
type: string
format: uuid
example: 0227d1e5-ba9a-42b5-8fe2-38882aa65708
description: >-
IDs of any replacement orders, if they have been created from
this order
replacement_reason:
type: string
example: Product arrived damaged
description: If this is a replacement order, reason for the replacement
replacement_requested:
type: boolean
example: false
description: >-
Whether the order has a replacement request. This field is
deprecated and will be removed in a future version. Please use
replacement_request_status instead.
replacement_request_status:
type: string
example: pending
description: Status of the replacement request
enum:
- pending
- fulfilled
- declined
- cancelled
replacement_requested_at:
type: string
example: '2025-01-01T00:00:00Z'
description: Date and time a replacement request was made
replacement_requested_reason:
type: string
example: Product arrived damaged
description: Reason for the replacement request
shipments:
type: array
items:
$ref: '#/components/schemas/OrderShipment'
description: >-
Once an order has been shipped, details on its shipment(s)
will be provided in this array.
shipping:
type: object
properties:
carrier:
type: string
example: usps
description: Desired shipment carrier.
service_level:
type: string
example: usps_ground_advantage
description: Desired shipment service level.
status:
type: string
example: received
ProductPrescriptionOrder:
allOf:
- $ref: '#/components/schemas/ProductPrescriptionFull'
- type: object
properties:
has_prescription:
type: boolean
example: true
description: Whether the product is associated with a prescription.
quantity:
type: integer
description: Quantity of product in this specific order.
example: 2
reasons:
type: array
items:
$ref: '#/components/schemas/ReasonOrder'
ProductNonPrescriptionOrder:
allOf:
- $ref: '#/components/schemas/ProductNonPrescriptionFull'
- type: object
properties:
quantity:
type: integer
description: Quantity in this specific order.
example: 1
ProductOrderMaterialOrder:
description: Materials or packing items that may be included in a shipment
allOf:
- $ref: '#/components/schemas/ProductOrderMaterialFull'
- type: object
properties:
quantity:
type: integer
description: Quantity of the material in this specific order.
example: 1
PatientCreateUpdateBase:
type: object
allOf:
- $ref: '#/components/schemas/PatientBase'
- type: object
properties:
risk_factors:
type: object
description: >-
Raw text risk factors for the patient. These will be parsed and
automatically matched to standardized risk factors. Please
delimit with commas, semi-colons, or slashes. Discrete risk
factors can be added using the dedicated endpoints.
properties:
allergies:
type: string
example: peanuts, tree nuts, shellfish
conditions:
type: string
example: asthma, hypertension
medications:
type: string
example: albuterol, levothyroxine
ID:
type: object
properties:
id:
type: string
format: uuid
description: Unique identifier
example: 0227d1e5-ba9a-42b5-8fe2-38882aa65708
Timestamps:
type: object
properties:
created_at:
type: string
format: date-time
description: Date and time of creation
example: '2025-03-15T12:00:00Z'
updated_at:
type: string
format: date-time
description: Date and time of last update
example: '2025-03-15T12:00:00Z'
Address:
allOf:
- $ref: '#/components/schemas/ID'
- type: object
properties:
address_1:
type: string
example: 140 Lindgren Streets
address_2:
type: string
example: Apt 227
city:
type: string
example: North Consueloburgh
state:
type: string
description: Two-letter state abbreviation
example: CA
country:
type: string
description: Two-letter country code
example: US
type:
type: string
description: Type of address, if applicable
example: shipping
zip_code:
type: string
description: 5-digit ZIP code or ZIP+4 code, e.g. 02108 or 02108-1234
example: '02108'
OrderCustomShipping:
type: object
properties:
label_url:
type: string
example: https://example.com/label.pdf
description: URL of the printable (4x6) custom shipping label
tracking_number:
type: string
example: TEST123456
description: Tracking number from the custom shipping label
tracking_url:
type: string
example: https://example.com/track/TEST123456
description: Tracking URL of the custom shipping label
carrier:
type: string
example: UPS
description: Carrier of the custom shipping label
PatientOrder:
allOf:
- $ref: '#/components/schemas/ID'
- $ref: '#/components/schemas/Timestamps'
- $ref: '#/components/schemas/PatientBase'
OrderShipment:
type: object
properties:
carrier:
type: string
example: USPS
description: Shipment carrier.
created_at:
type: string
format: date-time
example: '2026-04-17T18:31:05.175498'
description: >-
Date and time the package label was purchased and the item marked
shipped.
delivered_at:
type: string
format: date-time
example: '2026-04-17T18:31:05.175498'
description: Date and time the shipment was delivered.
id:
type: string
format: uuid
example: 0239CA06-9A71-4FFE-8A8D-5403540A19E7
description: Blend internal shipment ID.
service_level:
type: string
example: Ground Advantage
description: Shipment service level.
status:
type: string
example: shipped
description: Status of the shipment.
enum:
- shipped
- cancelled
- delivered
tracking_number:
type: string
example: '9200190347375200467807'
description: Tracking number for the shipment.
tracking_url:
type: string
example: >-
https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=9200190347375200467807
description: Tracking URL for the shipment.
ProductPrescriptionFull:
allOf:
- $ref: '#/components/schemas/ProductBase'
- $ref: '#/components/schemas/ProductPrescription'
ReasonOrder:
type: object
properties:
id:
type: string
format: uuid
example: 00000000-0000-0000-0000-000000000201
name:
type: string
example: Palatability
description:
type: string
example: Commercial formulation has an unpleasant taste, texture, or odor.
ProductNonPrescriptionFull:
allOf:
- $ref: '#/components/schemas/ProductBase'
- $ref: '#/components/schemas/ProductNonPrescription'
ProductOrderMaterialFull:
allOf:
- $ref: '#/components/schemas/ProductBase'
- $ref: '#/components/schemas/ProductOrderMaterial'
PatientBase:
type: object
properties:
first_name:
type: string
example: Willard
middle_name:
type: string
example: Moises
last_name:
type: string
example: Donnelly
gender:
type: string
enum:
- male
- female
example: male
description: Gender of the patient
email:
type: string
example: Harmon43@gmail.com
phone:
type: string
description: 10-digit phone number without formatting, e.g. 6417383445
example: '6417383445'
date_of_birth:
type: string
format: date
example: '1990-01-01'
driver_license_number:
type: string
example: B49188319
driver_license_state:
type: string
example: CA
ssn:
type: string
example: '123456789'
description: Social Security number. Can be provided with or without hyphens.
primary_language:
type: string
description: ISO 639-1 language code
example: en
guardian_name:
type: string
description: Name of the patient's guardian. Required if patient is a minor.
example: John Guardian
guardian_phone:
type: string
example: '6417383445'
guardian_email:
type: string
example: parent@example.com
guardian_relationship:
type: string
description: >-
Relationship of the guardian to the patient. See relationship types
lookup for available values; most common are `parent` and
`legal_guardian`; and `other` can be used.
example: parent
height_inches:
type: integer
example: 72
description: Height of the patient in inches
weight_pounds:
type: integer
example: 180
description: Weight of the patient in pounds
external_id:
type: string
example: '1234567890'
description: >-
External (your own) ID for the patient, to be used for prescription
matching
is_smoker:
type: boolean
example: false
description: Whether the patient is a smoker
is_diabetic:
type: boolean
example: false
description: Whether the patient is diabetic
is_pregnant:
type: boolean
example: false
description: Whether the patient is pregnant
receive_sms:
type: boolean
example: true
description: >-
Whether the patient should receive SMS notifications for shipments.
This is only applicable if you have authorized Blend to send patient
communications on your behalf.
receive_email:
type: boolean
example: true
description: >-
Whether the patient should receive email notifications for
shipments. This is only applicable if you have authorized Blend to
send patient communications on your behalf.
address:
$ref: '#/components/schemas/AddressCreate'
ProductBase:
allOf:
- $ref: '#/components/schemas/ID'
- $ref: '#/components/schemas/Timestamps'
- type: object
properties:
sku:
type: string
example: '1234567890'
description: Unique inventory identifier for the product
ProductPrescription:
type: object
properties:
name:
type: string
example: Mupirocin
description:
type: string
example: A topical cream that is used to treat skin infections.
product_code:
type: string
example: SUPERSPRAY15
description: >-
Customer reference for the product for use in electronic
prescriptions.
form:
type: string
example: cream
description: Optional form of the product for customer use, if desired.
is_active:
type: boolean
example: true
description: Whether the product is currently active for purchase or prescription
label_orientation:
type: string
example: portrait
description: >-
Orientation of the printed product label, either `portrait` or
`landscape`.
strength:
type: string
example: 1%
description: Optional strength of the product for customer use, if desired.
ProductNonPrescription:
type: object
properties:
name:
type: string
example: Krill Farms Fish Oil
description:
type: string
example: A fish oil supplement complementary to prescribed products.
form:
type: string
example: liquid
description: Optional form of the product for customer use, if desired.
is_active:
type: boolean
example: true
description: Whether the product is currently active for purchase
ProductOrderMaterial:
type: object
properties:
name:
type: string
example: Referral Brochure
description:
type: string
example: Customer brochure included in every shipment.
category:
type: string
example: marketing
current_stock:
type: integer
example: 927
reorder_threshold:
type: integer
example: 100
has_inventory:
type: boolean
example: true
description: Whether the product has any inventory associated with it
is_global:
type: boolean
example: false
description: >-
Whether the material is customer-specific or Blend-wide (e.g.
regulatory inserts)
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
````