Create, track, and manage orders in your web and mobile applications.
V3 Order APIs
Order API Features
| Feature | V3 | V2 | Description |
|---|---|---|---|
| Create Orders via API | ✅ | ✅ | PlanOmatic's Order API makes it easy speed up your workflow. When you identify a property that has marketing needs, request them via API. We will handle the rest! Order Create > |
| Retrieve Order Details via API | ✅ | ✅ | Need an update on the status of your order? Use our Retrieve API to get the latest details on your order. Order Retrieve > |
| Cancel Orders via API | ✅ | Order created by mistake? No biggie! Just send us a cancelation request via our NEW cancel API. Order Cancel > | |
| Send a Simple Services Array to Customize Your Property's Assets | ✅ | Pass a simple array of services that can be easily customized to reflect your marketing needs. Learn more > | |
| Send Metadata to Customize Each Order | ✅ | Pass up to 4 key/value pairs to customize your orders. Learn more > | |
| Use Organizational Entities to Keep Your Orders Organized | ✅ | Organize your billing notifications and details based on a customizable billing_entity_slug. Learn more | |
| Avoid Accidental Double Orders With Duplicate Protection | ✅ | Set a threshold of hours that need to have passed between orders with the same external_property_id. This is a great way to protect yourself against double ordering. |
Order API Request Example
Below is an example of what a request to the Create Order API would look like. For a details on each of these attributes, check out Order Create API >
{
api_key: 'your_api_key', // API Key
external_property_id: '{property_id}', // Custom Property ID passed by client
billing_entity_slug: 'investment_entity_1', // Custom Entity ID passed by client
external_order_id: '{external_order_id}',
metadata: {
'metadata_key1': 'abc123',
'metadata_key2': 'wxyz987'
},
property: {
location: {
street: '123 Fake St',
street2: 'Unit A',
city: 'Denver',
state: 'CO',
postal_code: 'XXXXX',
latitude: '95.784747',
longitude: '-43.848483'
},
property_type: 'single_family',
bedrooms: 3,
bathrooms: 2.5,
price: 3000,
square_footage: 1500
},
services: [
{
"slug": "photos",
"quantity": 15,
},
{
slug: 'zillow_3d_and_floor_plans',
quantity: 1
}
],
property_access: {
vacant: true,
method_of_access: 'lockbox_code',
access_code: 'XXXX',
lockbox_location: 'Behind A/C Unit',
preferred_date: 'YYYY-MM-DD',
onsite_contact_name: 'Jane Doe',
onsite_contact_phone: '+1 555-555-5555',
onsite_contact_email: '[email protected]'
},
order_notes: 'Some special instructions.'
}
Order API Response Example
Below is an example of the response object you would receive from the order retrieve API.
{
"order_id": "654321", // PlanOmatic Order ID
"external_property_id": "{property_id}", // Custom Property ID passed by client
"external_order_id": "{external_order_id}",
"created": "2021-05-18T18:03:30.000Z",
"order_status": "completed",
"event": "order.delivered",
"billing_entity": {
"slug": "investment_entity_1",
"name": "Investment Entity Number 1"
},
"property": {
"location": {
"address": "123 Fake St, Unit A, Denver, CO, 80205",
"street": "123 Fake St",
"street2": "Unit A",
"city": "Denver",
"state": "CO",
"postal_code": "80205",
"country": "US",
"market": "Denver",
"latitude": "95.784747",
"longitude": "-43.848483",
},
"property_type": "single_family",
"bedrooms": 3,
"bathrooms": 2.5,
"price": 3000,
"square_footage": 1500
},
"services": [
{
"slug": "photos",
"quantity": 15,
"name": "Photos",
"price": 12500
},
{
"slug": "zillow_3d_and_floor_plans",
"quantity": 1,
"name": "Zillow 3D Home Tour and Floor Plans",
"price": 12500
}
],
"property_access": {
"vacant": true,
"method_of_access": "lockbox_code",
"access_code": "4321",
"lockbox_location": "Behind A/C Unit",
"preferred_date": "YYYY-MM-DD",
"onsite_contact_name": "Jane Doe",
"onsite_contact_email": "[email protected]",
"onsite_contact_phone": "+1 555-555-5555"
},
"order_notes": "Some special instructions",
"appointments": [
{
"appointment_id": "7654321",
"start_datetime": "2021-05-20T18:00:00.000+00:00",
"end_datetime": "2021-05-20T18:30:00.000+00:00",
"duration_m": 30,
"planotech_name": "Bobby",
"cancelation_reason": null,
"cancelation_notes": null,
"canceled":false
}
],
"order_cancelation_reason": null,
"order_cancelation_notes": null,
"unable_to_complete_appt": false,
"unable_to_complete_appt_reason": null,
"unable_to_complete_appt_notes": null,
"links": {
"zillow_3d_link": "https: //www.zillow.com/view-3d-home/XXXXXXXXXX",
"photo_manage_link": "https: //go.planomatic.com/planox/manage_photos/XXXXXX"
},
"photos": [
{
"sequence": 1,
"caption": "Front View",
"full_size_url": "https://g2-tour-files.cdn.planomatic.com/XXXXX1.jpg",
"full_size_watermarked_url": "https://g2-tour-files.cdn.planomatic.com/XXXXX1/cw.jpg",
"uploaded_at": "2022-02-25T06:41:58.000Z",
"modified_at": "2022-03-25T21:07:56.000Z"
},
{
"sequence": 2,
"caption": "Kitchen",
"full_size_url": "https://g2-tour-files.cdn.planomatic.com/XXXXX2.jpg",
"full_size_watermarked_url": "https://g2-tour-files.cdn.planomatic.com/XXXXX2/cw.jpg",
"uploaded_at": "2022-02-25T06:41:58.000Z",
"modified_at": "2022-03-25T21:07:56.000Z"
},
{
"sequence": 3,
"caption": "Bedroom",
"full_size_url": "https://g2-tour-files.cdn.planomatic.com/XXXXX3.jpg",
"full_size_watermarked_url": "https://g2-tour-files.cdn.planomatic.com/XXXXX3/cw.jpg",
"uploaded_at": "2022-02-25T06:41:58.000Z",
"modified_at": "2022-03-25T21:07:56.000Z"
}
],
"legacy_order_id": "543210" //Orders before 2022 may have referenced a different ID which we call the "legacy_order_id"
}
How will I know if my property Is ready for photography?
Typically, the indication that a property is ready for photography will rely on one of the following:
- An important Date is entered into the system (e.g. “Construction Final Date”)
- A certain Property Status is reached (e.g. “Vacant Unrented Ready”)
Our team will help you identify other important criteria to consider when setting up the ordering logic.