📘
V3 Order APIs

Order Create >

Order Retrieve >

Order Cancel >

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: 'jdoe@example.com'
  },
  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": "jdoe@example.com",
    "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.