swagger: '2.0'
info:
  title: Handy’s Partner Bookings Orders API
  description: "<p>The Handy Partner API offers retailers fixed price installation\nservices that can be added to their eCommerce site or in-store checkout experience.\nTo start using the Handy Partner API, contact partners-eng@handy.com in order to\n        get access to the Sandbox.</p>\n        <p>Once you are ready to move to prod, we will walk you through quick authentication steps.</p>"
  version: v1
  contact: partnerships@handy.com
host: partners.services.handy.com
schemes:
- https
tags:
- name: Orders
paths:
  /api/v1/orders:
    post:
      summary: Create Order
      description: "Creates an order using one or more product SKUs that correspond to Angi services.\n\n ### Multi-Item Orders \n **Multiple items with the same product SKU** - If a customer purchased multiple Angi services with the **same** product SKU in a single basket, **only create one object for this product SKU** in the `products` array and indicate the quantity within the product object in the `product[:order_details][:quantity]` field. \n\n *Example of three products with the same SKU (quantity set on `order_details`).* \n\n ``` \n\n \"products\": [\n    {\n        \"sku\": \"ANGI1234\",\n        \"product_info\": {...},\n        \"order_details\": {\n            \"quantity\": 3,\n            ...\n        },\n        \"scheduling_details\": {}\n    }\n] \n\n``` \n\n **Multiple items with different product SKUs** - If there are multiple product SKUs that correspond to more than one Angi service, create `product` objects for each of the SKUs indicating their associated quantities. \n\n *Example of three products with the same SKU (quantity set on `order_details`) and one product with a different SKU on the same order.*  \n\n ``` \n\n \"products\": [\n    {\n        \"sku\": \"ANGI1234\",\n        \"product_info\": {...},\n        \"order_details\": {\n            \"quantity\": 3,\n            ...\n        },\n        \"scheduling_details\": {}\n    },\n    {\n        \"sku\": \"ANGI5555\",\n        \"product_info\": {...},\n        \"order_details\": {\n            \"quantity\": 1,\n            ...\n        },\n        \"scheduling_details\": {}\n    }\n] \n\n``` \n\n \n\n **Do NOT** create product objects for product SKUs that do not map/correspond to an Angi service. \n\n ### Success and Webhooks \n When an order is successfully created you will receive the `201` status code which is an acknowledgment from Angi that your order was created successfully. If your partner configuration has been set up with webhooks, after submitting an order creation you will receive either `booking_confirmed`, `booking_rescheduled`, or both (depending on your configuration). These webhooks will provide you with the most up-to-date booking/scheduling information associated with the submitted order. (See the Webhooks tab for more information around webhooks request body structure and more)."
      tags:
      - Orders
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: HDY-PARTNER-ID
        in: header
        type: string
        description: Your assigned partner ID
        example: partner_name
      - name: HDY-TIMESTAMP
        in: header
        type: string
        description: Seconds since epoch UTC
        example: '1525361611'
      - name: HDY-SIGNATURE
        in: header
        type: string
        description: 'Signature generated using your private key.

          Click <a href=''https://github.com/Handybook/API-Request-Signing'' target=''_blank''>here</a> to learn how.'
        example: OF5xI0LbLXHkFBLyNa8l..XHk=
      - name: request_body
        in: body
        schema:
          $ref: '#/definitions/order_creation_params'
      responses:
        '201':
          description: Created. Order created with required bookings
          schema:
            type: object
            properties:
              order:
                $ref: '#/definitions/order_response'
        '400':
          description: Bad request error, check order details passed in on request.
          schema:
            type: object
            properties:
              message:
                type: string
                example: Invalid user details
              code:
                type: string
                example: user_details_invalid
              error_uuid:
                $ref: '#/definitions/error_uuid'
              more_info:
                type: object
                example:
                  email:
                  - is an invalid
            required:
            - message
            - code
            - error_uuid
            - more_info
        '401':
          description: Unauthorized error, check authentication mechanism.
          schema:
            type: object
            properties:
              message:
                type: string
                example: Unauthorized request
              code:
                type: string
                example: unauthorized
              error_uuid:
                $ref: '#/definitions/error_uuid'
            required:
            - message
            - code
            - error_uuid
        '422':
          description: Unprocessable entity error, check SKU provided on request.
          schema:
            type: object
            properties:
              message:
                type: string
                example: Invalid SKU provided
              code:
                type: string
                example: invalid_sku
              error_uuid:
                $ref: '#/definitions/error_uuid'
            required:
            - message
            - code
            - error_uuid
        '409':
          description: Conflict error, order has already been processed. No further action required.
          schema:
            type: object
            properties:
              message:
                type: string
                example: Order has already been processed. You do no need to do anything else.
              code:
                type: string
                example: order_already_processed
              error_uuid:
                $ref: '#/definitions/error_uuid'
            required:
            - message
            - code
            - error_uuid
        '500':
          description: Internal server error, order creation failed.
          schema:
            type: object
            properties:
              message:
                type: string
                example: Failed to create the order
              code:
                type: string
                example: order_creation_failed
              error_uuid:
                $ref: '#/definitions/error_uuid'
            required:
            - message
            - code
            - error_uuid
    get:
      summary: Recent Orders
      description: "Get a list of partner specific orders created in the API. A useful aspect of this endpoint is that you can check the status of an order that has been submitted as well as receiving the status of each individual `order_product` within the parent order. The endpoint is flexible in that you can query based on `order_id` (same as `partner_order_id`), `user_id` (the ID assigned to the consumer upon order creation and returned to the partner in the response), `booking_guid` (the ID assigned to the booking upon order creation and returned to the partner in the response). \n\n### Pagination \n\n The `page` and `size` query parameters can be used to receive paginated responses from the recent orders API. Example scenario: I have 4 orders in total that will be returned by this API call. If I call this endpoint with no query parameters I will receive all 4 orders. But if I want each page to have a size of 2 orders and I want to receive the 2nd page of orders, I would pass in query parameters `?size=2&page=2`. I will receive the last 2 orders in the response."
      tags:
      - Orders
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: HDY-PARTNER-ID
        in: header
        type: string
        description: Your assigned partner ID
        example: partner_name
      - name: HDY-TIMESTAMP
        in: header
        type: string
        description: Seconds since epoch UTC
        example: '1525361611'
      - name: HDY-SIGNATURE
        in: header
        type: string
        description: 'Signature generated using your private key.

          Click <a href=''https://github.com/Handybook/API-Request-Signing'' target=''_blank''>here</a> to learn how.'
        example: OF5xI0LbLXHkFBLyNa8l..XHk=
      - name: size
        in: query
        type: integer
        description: Number of orders per page (optional, used for pagination. See endpoint description above for more info).
        required: false
        default: 10
        example: 1
      - name: page
        in: query
        type: integer
        description: Page number for paginated list of orders (optional, see endpoint description above for more info).
        default: 1
        example: 2
      - name: order_id
        in: query
        type: string
        description: Filter orders by `partner_order_id` that was passed in on the order creation request (optional).
        example: '110001023'
      - name: user_id
        in: query
        type: string
        description: 'Filter orders by `user_id` (optional). This is the same `user_id` that is returned in the response from order creation. '
        example: xzvdfhryhbdbe
      - name: booking_guid
        in: query
        type: string
        description: Filter orders by booking_guid (optional). This is the same ID that is returned in the `booking_id` field on order creation.
        example: w813v41k6lxzj5g
      responses:
        '200':
          description: OK
          schema:
            type: object
            properties:
              orders:
                type: array
                items:
                  $ref: '#/definitions/recent_orders_response'
              total:
                type: integer
                description: The number of orders returned in the `orders` response array.
                example: 1
        '401':
          description: Unauthorized error, check authentication mechanism.
          schema:
            type: object
            properties:
              message:
                type: string
                example: Unauthorized request
              code:
                type: string
                example: unauthorized
              error_uuid:
                $ref: '#/definitions/error_uuid'
            required:
            - message
            - code
            - error_uuid
        '500':
          description: Internal server error.
          schema:
            type: object
            properties:
              message:
                type: string
                example: Internal server error.
              code:
                type: string
                example: order_creation_failed
              more_info:
                type: string
                example: An unexpected error has occurred.
              error_uuid:
                $ref: '#/definitions/error_uuid'
  /api/v1/orders/{partner_order_id}:
    get:
      summary: Retrieve Order
      description: Retrieve information about an order by `partner_order_id`. A useful aspect of this endpoint is that you can check the status of an order that has been submitted as well as receiving the status of each individual `order_product` within the parent order.
      tags:
      - Orders
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: HDY-PARTNER-ID
        in: header
        type: string
        description: Your assigned partner ID
        example: partner_name
      - name: HDY-TIMESTAMP
        in: header
        type: string
        description: Seconds since epoch UTC
        example: '1525361611'
      - name: HDY-SIGNATURE
        in: header
        type: string
        description: 'Signature generated using your private key.

          Click <a href=''https://github.com/Handybook/API-Request-Signing'' target=''_blank''>here</a> to learn how.'
        example: OF5xI0LbLXHkFBLyNa8l..XHk=
      - name: partner_order_id
        in: path
        type: string
        required: true
        description: The `partner_order_id` that was used on order creation.
        example: '110001023'
      responses:
        '200':
          description: OK. Order retrieved.
          schema:
            type: object
            properties:
              order:
                $ref: '#/definitions/retrieve_order_response'
        '401':
          description: Unauthorized error, check authentication mechanism.
          schema:
            type: object
            properties:
              message:
                type: string
                example: Unauthorized request
              code:
                type: string
                example: unauthorized
              error_uuid:
                $ref: '#/definitions/error_uuid'
            required:
            - message
            - code
            - error_uuid
        '404':
          description: Not found error.
          schema:
            type: object
            properties:
              message:
                type: string
                example: The order was not found
              code:
                type: string
                example: order_not_found
              error_uuid:
                $ref: '#/definitions/error_uuid'
            required:
            - message
            - code
            - error_uuid
        '500':
          description: Internal server error.
          schema:
            type: object
            properties:
              message:
                type: string
                example: Internal server error.
              code:
                type: string
                example: order_creation_failed
              more_info:
                type: string
                example: An unexpected error has occurred.
              error_uuid:
                $ref: '#/definitions/error_uuid'
    patch:
      summary: Update Order
      description: "Update `delivery_date`, `service_date` or `service_datetime` for products or service bookings associated with an order in the `scheduling_details` object. \n\n ### Multi-Item Orders \n\n When an order is originally created with multiple items, items that have a SKU that maps to the same service these will already be created as one booking. In the case of multiple products in the cart with SKUs that map to different services, multiple bookings will have been created. If the multi-item orders have not experienced any consolidation, updates to the order will impact all items in the booking. The update method will not allow for changing properties other than scheduling on the booking. In a case where the customer purchases more products, this should be created as a new order rather than trying to update items on the existing order. \n\n ### Updating Consolidated Orders \n\n When an order is submitted that can been consolidated into an existing booking for a consumer, an update on an individual order will operate on the elements of the booking that are associated with that particular order. For example, if I sent in a `delivery_date` update on the second order that is a week in the future but this order was consolidated into the first booking, a new booking will be created with the elements of the second partner order. (Webhooks will be sent for both partner orders). \n\n ### Success and Webhooks \n\n When an order is successfully updated you will receive the `200` status code which is an acknowledgment from Angi that your order was updated. If your partner configuration has been set up with webhooks, after submitting an order creation you will receive a `booking_rescheduled`. This webhook will provide you with the most up-to-date booking/scheduling information associated with the updated order. (See the Webhooks tab for more information around webhooks request body structure and more)."
      tags:
      - Orders
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: HDY-PARTNER-ID
        in: header
        type: string
        description: Your assigned partner ID
        example: partner_name
      - name: HDY-TIMESTAMP
        in: header
        type: string
        description: Seconds since epoch UTC
        example: '1525361611'
      - name: HDY-SIGNATURE
        in: header
        type: string
        description: 'Signature generated using your private key.

          Click <a href=''https://github.com/Handybook/API-Request-Signing'' target=''_blank''>here</a> to learn how.'
        example: OF5xI0LbLXHkFBLyNa8l..XHk=
      - name: partner_order_id
        in: path
        type: string
        required: true
        description: The partner_order_id that was used to create the order.
        example: 110001023xx455
      - name: request_body
        in: body
        schema:
          $ref: '#/definitions/update_order_req_body'
        required: true
      responses:
        '200':
          description: Order updated successfully.
          schema:
            type: object
            properties:
              order:
                $ref: '#/definitions/order_response'
        '400':
          description: Bad request error, check scheduling_details.
          schema:
            type: object
            properties:
              message:
                type: string
                example: requested reschedule time is in the past
              code:
                type: string
                example: reschedule_request_date_in_past
              error_uuid:
                $ref: '#/definitions/error_uuid'
              more_info:
                type: object
                example:
                  code: reschedule_request_date_in_past
                  data:
                  - detail: requested reschedule time is in the past
            required:
            - message
            - code
            - error_uuid
            - more_info
        '403':
          description: Forbidden. Check auth credentials for your partner.
          schema:
            type: object
            properties:
              message:
                type: string
                example: Access denied.
              code:
                type: string
                example: forbidden_access_denied
              error_uuid:
                $ref: '#/definitions/error_uuid'
              more_info:
                type: object
                example:
                  code: forbidden_access_denied
                  data:
                  - detail: Forbidden.
        '404':
          description: Order not found, check partner_order_id on request.
          schema:
            type: object
            properties:
              message:
                type: string
                example: 'Order #110001023 was not found'
              code:
                type: string
                example: order_not_found
              error_uuid:
                $ref: '#/definitions/error_uuid'
              more_info:
                type: string
                example: The order was not found
            required:
            - message
            - code
            - error_uuid
            - more_info
        '422':
          description: Unprocessable entity error, check scheduling details.
          schema:
            type: object
            properties:
              message:
                type: string
                example: reschedule requests must be made at least 24 hours before the booking start time
              code:
                type: string
                example: reschedule_request_not_within_reschedule_window
              error_uuid:
                $ref: '#/definitions/error_uuid'
              more_info:
                type: object
                example:
                  code: reschedule_request_not_within_reschedule_window
                  data:
                  - detail: reschedule requests must be made at least 24 hours before the booking start time
            required:
            - message
            - code
            - error_uuid
            - more_info
        '500':
          description: Internal server error. Order NOT updated.
          schema:
            type: object
            properties:
              message:
                type: string
                example: internal server error
              code:
                type: string
                example: internal_server_error
              error_uuid:
                $ref: '#/definitions/error_uuid'
              more_info:
                type: object
                example:
                  code: internal_server_error
                  data:
                  - detail: internal server error
            required:
            - message
            - code
            - error_uuid
            - more_info
    delete:
      summary: Cancel
      description: "The endpoint can be used to cancel a order which in turn will cancel bookings associated with the order. \n Endpoint has some restrictions which would mean a booking cannot be cancelled. Some of the restrictions are as follows `order_already_cancelled`, `booking_already_cancelled`, `booking_already_completed`, `booking_already_started`, can see the examples in the `422` block. \n\n **Note** The Api endpoint is a blanket delete call to cancel all bookings associated with an order, continue reading for different scenarios of cancellations. \n\n ### Multi-Product Order \n\n If the order has multiple products, the order might have multiple bookings. A cancellation request for a order that has two products, will result in cancelling of both bookings and a slightly different looking response body with a `200` status code \n\n \n\n ``` {\n    \"order\": {\n        \"partner_order_id\": \"110001023\",\n        \"user_id\": \"ojxyzrldy81gl28\",\n        \"address_id\": \"71npkxynjqog2w6\",\n        \"products\": [\n            {\n                \"booking_id\": \"v50r6460w43nd1p\",\n                \"charge_amount_in_cents\": 9099,\n                \"charge_currency\": \"USD\",\n                \"customer_price_in_cents\": null,\n                \"default_schedule\": false,\n                \"delivery_date\": \"2018-02-05\",\n                \"error\": null,\n                \"line_number\": \"1\",\n                \"name\": \"Shower System 1 Pro Installation\",\n                \"product_category\": null,\n                \"order_date\": \"2024-06-27T23:01:48.000Z\",\n                \"order_product_id\": \"k5o3pmrvq7x4qjg\",\n                \"partner_machine_name\": \"partner_name\",\n                \"partner_order_id\": \"110001023\",\n                \"product_status\": \"cancelled\",\n                \"product_weight_in_lbs\": 50,\n                \"quantity\": 1,\n                \"service_date\": \"2024-06-28\",\n                \"service_datetime\": null,\n                \"sku\": \"Example1\",\n                \"wholesale_price_in_cents\": null,\n                \"customer_scheduling_preferences\": null\n            },\n            {\n                \"booking_id\": \"rk3dx4wpy2q76o9\",\n                \"charge_amount_in_cents\": 9099,\n                \"charge_currency\": \"USD\",\n                \"customer_price_in_cents\": null,\n                \"default_schedule\": false,\n                \"delivery_date\": \"2018-02-05\",\n                \"error\": null,\n                \"line_number\": \"1\",\n                \"name\": \"Shower System 1 Pro Installation\",\n                \"product_category\": null,\n                \"order_date\": \"2024-06-27T23:01:48.000Z\",\n                \"order_product_id\": \"nxr0j1py31eoqpd\",\n                \"partner_machine_name\": \"partner_name\",\n                \"partner_order_id\": \"110001023\",\n                \"product_status\": \"cancelled\",\n                \"product_weight_in_lbs\": 50,\n                \"quantity\": 1,\n                \"service_date\": \"2024-06-28\",\n                \"service_datetime\": null,\n                \"sku\": \"Example2\",\n                \"wholesale_price_in_cents\": null,\n                \"customer_scheduling_preferences\": null\n            }\n        ],\n        \"created_at\": \"2024-06-27T23:01:48.000Z\",\n        \"processing_status\": \"complete\",\n        \"partner_machine_name\": \"partner_name\",\n        \"metadata\": {}\n    }\n} \n\n``` \n\n When a order contains multiple bookings and one of the bookings is completed or started and a `cancel` request is sent, the api will cancel booking that was not started and return the `booking_id` of the booking that was not cancelled with a `422` status code. \n\n ```\n {\n    \"message\": \"Some bookings within partner order 110001023 could not be cancelled: k1vy62j8940mo7e.\",\n    \"code\": \"booking_already_completed\",\n    \"more_info\": \"Booking has been completed\",\n    \"error_uuid\": \"f8db8791a9db3a71e06a5563901291ed\"\n} \n\n``` \n\n ### Success and Webhooks\n\n When an order is successfully cancelled you will receive the 200 status code which is an acknowledgment from Angi that your order was cancelled. If your partner configuration has been set up with webhooks, after order is cancelled you will receive one or more `booking_cancelled` events, depending on how many bookings the order had. This webhook will provide you with the info that has `booking_id`, `partner-order_id` and `event_time`. (See the Webhooks tab for more information around webhooks request body structure and more). "
      tags:
      - Orders
      consumes:
      - application/json
      produces:
      - application/json
      parameters:
      - name: HDY-PARTNER-ID
        in: header
        type: string
        description: Your assigned partner ID
        example: partner_name
      - name: HDY-TIMESTAMP
        in: header
        type: string
        description: Seconds since epoch UTC
        example: '1525361611'
      - name: HDY-SIGNATURE
        in: header
        type: string
        description: 'Signature generated using your private key.

          Click <a href=''https://github.com/Handybook/API-Request-Signing'' target=''_blank''>here</a> to learn how.'
        example: OF5xI0LbLXHkFBLyNa8l..XHk=
      - name: id
        in: path
        type: string
        required: true
        description: The Order's id
        example: '110001023'
      - name: reason
        in: query
        description: A reason for cancellation (optional). If passing a reason parameter it should be valid else will result in reason_not_found
        type: string
        example: partner_returned_item
      responses:
        '200':
          description: OK, Order cancelled successfully
          schema:
            type: object
            properties:
              order:
                $ref: '#/definitions/order_response'
        '400':
          description: Bad Request, Invalid reason code in query param
          schema:
            type: object
            properties:
              message:
                type: string
                example: Reason not found.
              code:
                type: string
                example: invalid_request_parameter
              error_uuid:
                $ref: '#/definitions/error_uuid'
            required:
            - message
            - code
            - error_uuid
        '404':
          description: Order Not found
          schema:
            type: object
            properties:
              message:
                type: string
                example: The order was not found
              code:
                type: string
                example: order_not_found
              error_uuid:
                $ref: '#/definitions/error_uuid'
            required:
            - message
            - code
            - error_uuid
        '409':
          description: Order already cancelled
          schema:
            type: object
            properties:
              message:
                type: string
                example: Order 1234567890 is already cancelled
              code:
                type: string
                example: order_already_cancelled
              error_uuid:
                $ref: '#/definitions/error_uuid'
            required:
            - message
            - code
            - error_uuid
        '500':
          description: Order Cancellation failed, Internal server error.
          schema:
            type: object
            properties:
              message:
                type: string
                example: Some bookings within partner order 1234567890 could not be cancelled
              code:
                type: string
                example: booking_cancellation_failed
              error_uuid:
                $ref: '#/definitions/error_uuid'
            required:
            - message
            - code
            - error_uuid
        '422':
          description: Order not cancelled, Booking already completed | Booking Already Cancelled | Booking already started
          schema:
            type: object
            properties:
              message:
                type: string
                example: Order 110001023 is already cancelled.
              code:
                type: string
                example: booking_already_cancelled
              error_uuid:
                $ref: '#/definitions/error_uuid'
            required:
            - message
            - code
            - error_uuid
definitions:
  sku:
    type: string
    example: HANDY1234
    description: The product identifier that has been allocated to the product you are submitting on this order request.
  order_creation_params:
    type: object
    properties:
      user:
        $ref: '#/definitions/user'
      address:
        $ref: '#/definitions/address'
      order:
        $ref: '#/definitions/order'
    required:
    - user
    - address
    - order
  retrieve_order_response:
    type: object
    properties:
      partner_order_id:
        type: string
        example: '110001023'
        description: The unique ID that is provided to Angi by the partner on order creation.
      user_id:
        type: string
        example: xzvdfhryhbdbe
        description: The unique ID that Angi has assigned to the consumer object that was created as a result of this order.
      address_id:
        type: string
        example: sfgethrethrt
        description: The unique ID that Angi has assigned the consumer's address object that was created as a result of this order.
      products:
        $ref: '#/definitions/recent_orders_product_responses'
      created_at:
        type: string
        example: '2018-05-02T22:21:49.000Z'
      processing_status:
        type: string
        example: complete
        description: "If a partner is unsure about what is going on with an order, this field can provide more detail. The following statuses can be returned in this field: \n\n`failed`: order creation has failed. \n\n`partial`: some order products within this order have been created but there are others that are still processing. To see the statuses of individual products within this order, find the product in the `products` array and look for its `product_status`. \n\n`complete`: order creation is complete. \n\n`in_progress`: order creation is in progress."
      partner_machine_name:
        type: string
        example: partner_name
        description: The unique partner name given to the partner (same one that is used in the HTTP headers).
      metadata:
        type: object
        x-nullable: true
        description: Metadata that was passed in by the partner.
  update_order_req_body:
    type: object
    description: Information about the order to update.
    properties:
      partner_order_id:
        description: This is optional. Be sure to put the `partner_order_id` in the path parameter, that one is required.
        type: string
        example: '110001023'
      products:
        type: array
        items:
          type: object
          properties:
            sku:
              $ref: '#/definitions/sku'
            order_details:
              $ref: '#/definitions/order_details_update'
            scheduling_details:
              $ref: '#/definitions/scheduling_details'
  product_info:
    type: object
    description: The information passed in this object will be used to create order product reference objects within our system. These references are then used to provide descriptions to the pro that is completing the service.
    properties:
      product_name:
        type: string
        example: A nice chair
      product_category:
        type: string
        example: built_from_recycled_materials
        description: A short text string to aid in grouping products in reporting (optional)
      product_weight_in_lbs:
        type: integer
        example: '50'
        description: The weight of the product in pounds (optional)
    required:
    - product_name
  address:
    type: object
    description: The address of where the service will be performed.
    properties:
      address1:
        type: string
        example: 1st street
      address2:
        type: string
        example: Apt 2
      city:
        type: string
        example: Queens
      state:
        type: string
        example: NY
      country:
        type: string
        example: US
      zipcode:
        type: string
        example: '10001'
      type:
        type: string
        example: RESIDENTIAL
    required:
    - address1
    - address2
    - zipcode
  user:
    type: object
    description: Details about the user that the order is being created for.
    properties:
      email:
        type: string
        example: example@handy.com
        description: Email address of the user the order is being created for.
      first_name:
        type: string
        example: John
      last_name:
        type: string
        example: Doe
      phone_number:
        type: string
        example: '2153214455'
    required:
    - first_name
    - last_name
    - phone_number
    - email
  order_details:
    type: object
    properties:
      quantity:
        type: integer
        example: 1
      delivery_date:
        type: string
        example: '2018-07-26'
        description: Passing in the date here works, but we recommended putting the `delivery_date` in the `scheduling_details` object (see below). The delivery date of the item associated with the order. The booking will be scheduled on an optimal date after the delivery_date.
      service_date:
        type: string
        example: '2018-07-26'
        description: Passing in the date here works, but we recommended putting the `service_date` in the `scheduling_details` object (see below). The required date of the booking. The booking will be scheduled at an optimal time on the service_date.
      service_datetime:
        type: string
        example: '2018-05-02T22:21:49.000Z'
        description: Passing in the datetime here works, but we recommended putting the `service_datetime` in the `scheduling_details` object (see below). The required datetime of the booking. The booking will be scheduled at exactly the time specified by service_datetime.
      price_amount_in_cents:
        type: integer
        example: '10099'
        description: Price in cents charged to the customer by the retailer
      charge_amount_in_cents:
        type: integer
        example: '9099'
        description: Price in cents to be paid to Handy by the retailer
      charge_currency:
        type: string
        example: USD
        description: The 3-letter ISO 4217 currency code for the transaction
      line_number:
        type: string
        example: '1'
        description: An identifier for a particular product in the order
    required:
    - quantity
  products:
    description: An array of products associated with the order. A booking is made for each product except in cases of order consolidation. For example, if two products have a SKU that will trigger the same service, our scheduling algorithm will attempt to combine these services into a consolidated booking. This also applies to future partner orders that are sent for the same consumer with SKUs that can be combined with existing services that have not been completed yet.
    type: array
    items:
      type: object
      properties:
        sku:
          $ref: '#/definitions/sku'
        product_info:
          $ref: '#/definitions/product_info'
        order_details:
          $ref: '#/definitions/order_details'
        scheduling_details:
          $ref: '#/definitions/scheduling_details'
      required:
      - sku
      - product_info
      - order_details
  recent_orders_product_responses:
    type: array
    items:
      $ref: '#/definitions/recent_order_product_response'
  order_response:
    type: object
    properties:
      partner_order_id:
        type: string
        example: '110001023'
      user_id:
        type: string
        example: xzvdfhryhbdbe
      address_id:
        type: string
        example: sfgethrethrt
      products:
        $ref: '#/definitions/product_responses'
      created_at:
        type: string
        example: '2018-05-02T22:21:49.000Z'
      processing_status:
        type: string
        example: complete
      partner_machine_name:
        type: string
        example: partner_name
      metadata:
        type: object
        x-nullable: true
        description: Metadata that was passed in by the partner.
    required:
    - partner_order_id
    - user_id
    - address_id
    - products
  order:
    type: object
    description: Information about the order to create.
    properties:
      partner_order_id:
        type: string
        example: '110001023'
      metadata:
        $ref: '#/definitions/metadata'
      products:
        $ref: '#/definitions/products'
    required:
    - partner_order_id
    - products
  metadata:
    type: object
    description: Hash for partner specific information. This is used when partners are using the optional PartnerPurchaseOrder data mapping. Passing in `purchase_order_number` as a property of this object will create a database record relationship between the passed in `purchase_order_number`, the `partner_order_id` and the `partner` itself.
  recent_orders_response:
    type: object
    properties:
      partner_order_id:
        type: string
        example: '110001023'
        description: The unique ID that is provided to Angi by the partner on order creation.
      user_id:
        type: string
        example: xzvdfhryhbdbe
        description: The unique ID that Angi has assigned to the consumer object that was created as a result of this order.
      address_id:
        type: string
        example: sfgethrethrt
        description: The unique ID that Angi has assigned the consumer's address object that was created as a result of this order.
      products:
        $ref: '#/definitions/recent_orders_product_responses'
      created_at:
        type: string
        example: '2018-05-02T22:21:49.000Z'
        description: The date the order was created.
      processing_status:
        type: string
        example: complete
        description: "If a partner is unsure about what is going on with an order, this field can provide more detail. The following statuses can be returned in this field: \n\n`failed`: order creation has failed. \n\n`partial`: some order products within this order have been created but there are others that are still processing. To see the statuses of individual products within this order, find the product in the `products` array and look for its `product_status`. \n\n`complete`: order creation is complete. \n\n`in_progress`: order creation is in progress."
      partner_machine_name:
        type: string
        example: partner_name
        description: The unique partner name given to the partner (same one that is used in the HTTP headers).
      metadata:
        $ref: '#/definitions/metadata'
  order_product_response:
    type: object
    properties:
      order_product_id:
        type: string
        example: wv3r2o7el14gj06
      partner_order_id:
        type: string
        example: '110001023'
      order_date:
        type: string
        example: '2018-10-22T12:11:50.000Z'
      booking_id:
        type: string
        example: dj327393v614875
      sku:
        $ref: '#/definitions/sku'
      name:
        type: string
        example: Product name
      line_number:
        type: integer
        example: 1
        x-nullable: true
      quantity:
        type: integer
        example: 1
      charge_amount_in_cents:
        type: integer
        x-nullable: true
      charge_currency:
        type: string
        x-nullable: true
      product_status:
        type: string
        example: complete
      delivery_date:
        type: string
        example: '2018-07-26'
        x-nullable: true
      service_date:
        type: string
        example: '2018-07-26'
        x-nullable: true
      service_datetime:
        type: string
        example: '2018-05-02T22:21:49.000Z'
        x-nullable: true
      error:
        type: string
        example: null
        x-nullable: true
    required:
    - order_product_id
    - partner_order_id
    - order_date
    - booking_id
    - sku
    - name
    - quantity
  recent_order_product_response:
    type: object
    properties:
      order_product_id:
        type: string
        example: wv3r2o7el14gj06
        description: The ID that was created for this product and order within the Angi system.
      partner_order_id:
        type: string
        example: '110001023'
        description: The unique order ID that the partner sends in on the creation request.
      order_date:
        type: string
        example: '2018-10-22T12:11:50.000Z'
        description: The date the order was created.
      booking_id:
        type: string
        example: dj327393v614875
        description: The ID of the booking that was created via this order product.
      sku:
        $ref: '#/definitions/sku'
      name:
        type: string
        example: Product name
        description: The name of the product that was submitted as part of this order.
      line_number:
        type: integer
        example: 1
        x-nullable: true
        description: The line number of the order product.
      quantity:
        type: integer
        example: 1
        description: The quantity of this product.
      charge_amount_in_cents:
        type: integer
        x-nullable: true
        description: The amount that was charged for the service.
      charge_currency:
        type: string
        x-nullable: true
        description: The currency that is being used to pay for this service.
      product_status:
        type: string
        example: completed
        description: "If a partner is unsure of what's going on with a particular order product that exists as part of the order, the `product_status` can provide info around what is currently happening with the order product. The following statuses can be returned in this property:  \n\n`cancellation_failure`: an attempt to cancel the service for this order product was made but it failed. \n\n`cancellation_processing`: a cancellation request has been made for the service associated with this order product and is pending. \n\n`cancelled`: the service associated with this order product has been cancelled. \n\n`completed`: the service associated with this order product has been completed. \n\n`failure`: there was a failure when attempting to create this order product during order creation. \n\n`pending`: the scheduling and creation of the service associated with this order product is pending. \n\n`processing`: the initial order creation is currently processing for this order product."
      delivery_date:
        type: string
        example: '2018-07-26'
        x-nullable: true
        description: The delivery_date that was passed in on order creation or order update.
      service_date:
        type: string
        example: '2018-07-26'
        x-nullable: true
        description: The service_date (no time) that was passed in on order creation or order update.
      service_datetime:
        type: string
        example: '2018-05-02T22:21:49.000Z'
        x-nullable: true
        description: The service_datetime that was passed in on order creation or order update.
      error:
        type: string
        example: null
        x-nullable: true
        description: Because there are often multiple products on a single order, there are scenarios where one product may successfully create a service and another fails. This is indicated in the `processing_status` of the parent order as `partial`. If the `product_status` of this order product is `failure` or `completed`, the context of this status will be provided in this `error` field. It gives more details around why this particular order product failed.
  order_details_update:
    type: object
    properties:
      line_number:
        type: string
        example: '1'
        description: An identifier for a particular product in the order
    required:
    - line_number
  error_uuid:
    type: string
    example: 90938b23-749f-4f66-972b-43ea3a7ca7f6
  product_responses:
    type: array
    items:
      $ref: '#/definitions/order_product_response'
  scheduling_details:
    type: object
    description: This is the recommended object where scheduling datetime should be passed in when creating an order. If no datetime is provided in this object or in the properties within the `order_details` object, a Smart Scheduler algorithm will be used to determine an optimal service date based on buffers and specific partner configurations.
    properties:
      date_type:
        type: string
        enum:
        - delivery_date
        - service_date
        - service_datetime
        - customer_local_datetime
        example: customer_local_datetime
        description: The type of date for which is being passed in. `delivery_date` will schedule the booking by adding the delivery date buffer for the partner to the date passed in. `service_date` will schedule the booking for the date passed in, and a time will be chosen based on pro availability. `service_datetime` will schedule the booking for the date and time that is passed in (UTC). `customer_local_datetime` will schedule the booking for the date and time passed in using the timezone requested.
      date:
        type: string
        example: '2018-05-02T22:21:49.000'
        description: The date value corresponding to the listed 'date_type'
    required:
    - date_type
    - date