Group Orders

An order is a customer’s completed request to purchase one or more boxes with items from some shop.

Order resource fields

  • primary_id [string] (required) - The alphanumeric primary identifier for the order: this identifier should be unique within a single order fulfilment system. This identifier can be visible on generated shipping documents both as text and barcodes, if selected by the user.
  • unique_id [string] - Unique identifier is an id which is unique globally in the ReadyCloud platform. It can be provided by the API client for special purposes but it is usually generated and assigned automatically by ReadyCloud when an order is created.
  • order_number [integer] - The numerical identifier serves a similar purpose as the primary identifier. The main difference is that the numerical identifier must be entirely numerical, while the primary identifier can be alpha-numeric.
  • customer_number [string] - The recipient’s customer number.
  • po_number [string] - The purchase order number if available.
  • message [string] - A message for the order recipient. This should be a short string. The number of possible characters may vary depending on printing format and font, among other things. Typically the message may be no longer than 220 characters. This will be printed on Ready Shipper’s standard shipping document.
  • terms [string] - A short terms of payment description for an order. Examples include ‘Prepaid’ or ‘COD’.
  • ordered_at [datetime]† - the time the order was finalized.
  • printed_at [datetime]† - the time at which order label was printed by ReadyCloud shipping software.
  • updated_at (read only) [datetime]† - the time the order was updated in ReadyCloud.
  • created_at (read only) [datetime]† - the time the order was created in ReadyCloud.
  • nested_updated_at [datetime]† - the last time that resource related to order was updated in ReadyCloud.
  • boxes - Packages in the order. Most orders will only have one box, but any number of boxes can be specified for each order, for more info refer to Box documentation. Note: for handling multiple box shipments and returns with ReadyShipper and ReadyReturns multiple orders with split relations (see below) are used, not a single order with multiple boxes.
  • custom_fields - A custom field is a name-value pair for storing additional data, for more info refer to order custom field documentation.
  • notes - Order notes contain some useful info about the order, for more info refer to order note documentation.
  • tags - Orders can have tags, which are simple text labels which help to categorize orders, for more info refer to order tags documentation.
  • relations - Order can have relations to other orders, for more info refer to order relations documentation.
  • source - Describes the origin of the order.
    • name [string] - Name of the source.
    • account [string] - Account associated to order (usually an email or URL).
    • channel [string] - Channel through order was imported.
    • retrieved_at [datetime]† - the time the order was retrieved from the remote source.
    • updated_at (read only) [datetime]† - the time the order source was updated.
    • id [string] - Internal ID of an order in the source platform.
  • billing - Describes order billing information.
    • status [string] - Indicates billing status of an order. Choices are “pending”, “paid”, “partially_paid”, “refunded”, “partially_refunded” and “cancelled”.
    • subtotal [money]‡ - The price of the goods billed to the recipient excluding shipping and tax.
    • shipping [money]‡ - The shipping and handling billed to the recipient.
    • tax [money]‡ - The taxes billed to the recipient.
    • total [money]‡ - The order total.
    • bill_to - Address to bill to, for more info refer to address resource documentation.
  • shipping - Describes order shipping information.
    • status [string] - Indicates shipping status of an order. Choices are “unfulfilled”, “fulfilled” and “partially_fulfilled”.
    • to_ship_at [datetime]† - the time the order will be actually shipped by carrier.
    • shipped_at [datetime]† - the time when the orders was prepared for shipping by ReadyShipper or a third party shipping software.
    • ship_agent [string] - The name of the shipping software for the order.
    • ship_via [string] - The name of the shipping agency for the order. If this field assume the exact values of: “UPS”, “USPS” or “FedEx” tracking features will be enabled.
    • ship_type [string] - The shipping type, or service level, used to ship the item. The types supported depend on the ship_via. If ship_via has been specified as ‘UPS’, ‘Ground’ or ‘Next Day Air’ would be examples of valid ship types. For international shipments, an example of a valid ship type would be ‘Worldwide Expedited’.
    • ship_cost [money]‡ - The actual ship cost once known.
    • warehouse [string] - A pick location for the item, i.e. an identifier for where to find the item in a warehouse. This text is added to the item list of Ready Shipper’s standard shipping document to facilitate order fulfillment.
    • ship_to - Address to ship to, for more info refer to address resource documentation.
    • ship_from - Address to ship from, for more info refer to address resource documentation.

† - the expected format is an ISO-8601 formatted string, with timezone. If timezone is missing, UTC is assumed. Microseconds are parsed and saved if provided, but not required. Sample: 2019-11-22T09:51:06.120606+00:00.

‡ - the expected format is a string with decimal value and ISO-4127 currency code is expected. Sample: 123.43 USD.

Address resource fields

  • company [string] - The company name.
  • first_name [string] - The first name of the addressed person.
  • last_name [string] - The last name.
  • address_1 [string] - The first address line.
  • address_2 [string] - Any second address line if available. Sometimes used for the apartment, room or suite number.
  • city [string] - The city.
  • region [string] - The state or province.
  • post_code [string] - The ZIP code for US addresses or the postal code for international addresses where available.
  • country [string] - The country.
  • phone [string] - The phone number.
  • email [string] - The email address.
  • residential [boolean] - An indicator which if present indicates the address is a residential address.
  • validated [boolean] - An indicator which if true indicates the address has been validated.
  • updated_at (read only) [datetime]† - time the address was updated in ReadyCloud.
  • created_at (read only) [datetime]† - time the address was created in ReadyCloud.

† - the expected format is an ISO-8601 formatted string, with timezone. If timezone is missing, UTC is assumed. Microseconds are parsed and saved if provided, but not required. Sample: 2019-11-22T09:51:06.120606+00:00.

Orders collection

GET

Retrieve list of orders of specific organization

GET /orgs/{org_pk}/orders/{?expand}{?suggestions}{?only}{?q}{?**filters}/

  • Parameters

    • expand: boxes (enum[string], optional)

      Include full boxes/items responses inside of the order body.

      • Members
        • boxes - include full boxes
        • items - include full items
        • boxes,items - include both boxes and items inside

    • suggestions: 1 (enum[number], optional) - Include suggested values with ? suffix.

      0 - no suggestions. 1 - show suggestions for fields without a known value. 2 - always show suggestion fields.

      • Default: 0
      • Members
        • 0 - no suggestions
        • 1 - show suggestions for fields without a known value
        • 2 - always show suggestion fields
      • Available suggestion fields:
        • message?, weight?, po_number?, customer_number?, terms_auto?
        • billing.subtotal?, billing.status?, billing.shipping?, billing.tax?, billing.total?
        • shipping.status?, shipping.ship_via?, shipping.ship_type?, shipping.warehouse?

    • only: Return only specified fields (compact response). Fields list should be separated by comma. Supported fields: nested_updated_at, url.

      Example: only=url,nested_updated_at

    • q: search_string (string, optional)

    Perform full text search through orders based on given search_string (filter results based on full text search)

    note: Returns at most 70 results.

    Free text search is combined with regular ordering and filtering parameters, 70 possible results will be chosen arbitrarily prior to ordering and filtering. This can result in less than 70 results being returned even if there are more matching orders, and it also means that the ordering is only applied to the arbitrary subset of free text results, not the total set of possible results

    • filters: GET parameters to filter results.

      Filters will limit the Orders returned, all filters are optional, multiple filters can be specified.

      • billing_status__in - pending|paid|partially_paid|refunded|partially_refunded|cancelled Example. Get orders with paid or partially paid billing status: ?billing_status__in=paid,partially_paid Example. Get orders with any billing status, excluding cancelled and refunded: ?billing_status__in=!cancelled,!refunded

      • shipping_status__in - unfulfilled|fulfilled|partially_fulfilled Example. Get orders with fulfilled shipping status: ?shipping_status__in=fulfilled Example. Get orders with any shipping status, excluding unfulfilled: ?shipping_status__in=!unfulfilled

      • primary_id - #758392R (string, optional). Orders with exact primary_id.

      • order_number - 442663 (integer, optional). Orders with exact order_number.

      • unique_id - 00002~KZCpm2-z~f8gVVIfGB (string, optional). Order with exact unique_id.

      • po_number - PO-178866 (string, optional). Orders with exact po_number.

      • customer_number - CN-339921 (string, optional).

      • sources__name - Shopify (string, optional).

      • sources__account - bluedress123.example.com (string, optional).

      • sources__account__in - bluedress123.example.com,goodgame345.example.com (string, optional). Example. Get orders with bluedress123.example.com or goodgame345.example.com source accounts: ?sources__account__in=bluedress123.example.com,goodgame345.example.com. Example. Get orders with any source account, excluding coolstory.example.com: ?sources__account__in=!coolstory.example.com.

      • ship_via - FedEx (string, optional).

      • ship_via__in - FedEx,UPS,USPS (string, optional). Example. Get orders with FedEx or USPS ship via: ?ship_via__in=FedEx,USPS. Example. Get orders with any ship via, excluding Mail Innovations: ?ship_via__in=!Mail%20Innovations.

      • ship_type - UPS Ground (string, optional).

      • tag - Completed (string, optional). Orders with given tag.

      • relation__kind - return-child|return-parent|split-child|split-parent|combine-child|combine-parent. Return only orders that has given relations. The filter can be inverted (!return-child).

      • email - test@example.com (string, optional). Orders with exact billing or shipping email

      • Datetime filters

        All filters for datetime properties accept ISO 8601 timestamp, with timezone defaulting to UTC, such as: 2016-09-26T07:45:14Z. If the specified filter is the property name, orders matching exactly the supplied value will be returned. If the filter suffix is either __gte or __lte orders with values greater than or lower than the supplied value will be returned, respectively. Example: ?created_at__gte=2016-09-26T07:45:14Z orders created after Sep. 26th 2016 at 7:45:14 UTC time will be returned. Example: ?printed_at__lte=2016-09-26T07:45:14Z orders printed before Sep. 26th 2016 at 7:45:14 UTC time will be returned.

        • ordered_at | ordered_at__gte | ordered_at__lte - Order creation time (by the end-user)
        • printed_at | printed_at__gte | printed_at__lte - Order print time
        • shipped_at | shipped_at__gte | shipped_at__lte - Order ship time
        • to_ship_at | to_ship_at__gte | to_ship_at__lte - Expected or planned ship time
        • created_at | created_at__gte | created_at__lte - Order creation time (in ReadyCloud)
        • updated_at | updated_at__gte | updated_at__lte - Order update time (in ReadyCloud)
        • nested_updated_at | nested_updated_at__gte | nested_updated_at__lte - Latest update of the order and any of its primary components, such as boxes, addresses and items

    • order_by: These options determine which field to order the records by. Prefix with - for a descending sort or use as is for an ascending sort.

      • created_at (-created_at is default)
      • updated_at
      • nested_updated_at
      • primary_id
      • delivered_at
      • printed_at
      • is_delivered
      • message
      • po_number
      • ordered_at
      • order_number
      • terms
      • tags
      • weight_auto (ordering by weight? field)
      • shipping__ship_via
      • shipping__ship_type
      • shipping__shipped_at
      • shipping__to_ship_at
      • shipping__ship_cost
      • shipping__status
      • sources__name
      • sources__account
      • billing__shipping
      • boxes__insured_value
      • boxes (ordering by number of boxes)
      • boxes__items (ordering by number of line items)
      • boxes__items__description
      • boxes__items__part_number
      • boxes__items__pick_location
      • boxes__items__link
      • boxes__tracking_number
      • billing__status
      • shipping__ship_to__address_1
      • shipping__ship_to__address_2
      • shipping__ship_to__city
      • shipping__ship_to__company
      • shipping__ship_to__country
      • shipping__ship_to__email
      • shipping__ship_to__phone
      • shipping__ship_to__region
      • shipping__ship_to__post_code
      • billing__bill_to__address_1
      • billing__bill_to__address_2
      • billing__bill_to__city
      • billing__bill_to__company
      • billing__bill_to__country
      • billing__bill_to__email
      • billing__bill_to__phone
      • billing__bill_to__region
      • billing__bill_to__post_code
      • billing__total

    • lazy fields:

      Custom fields for orders, boxes and items can be requested in a “lazy” format. When the lazy GET parameter is given, any field with a value longer than 512 bytes will omit the value key in the response.

      This makes the response much shorter since certain custom fields can be many kilobytes long and you might not be interested in their value in your case.

      You can always come back and get the value with a GET for that specific custom field later (see the Order, Box and Item custom field resources).

      Examples:

      • lazy=custom_fields - collapse order custom fields where value is more than 512 bytes
      • lazy=boxes__custom_fields - collapse box custom fields where value is more than 512 bytes
      • lazy=boxes__items__custom_fields - collapse item custom fields where value is more than 512 bytes
      • lazy=custom_fields,boxes__custom_fields - collapse order and box custom fields (useful when ?expand=boxes parameter specified to Orders resource)
      • lazy=custom_fields,boxes__custom_fields,boxes__items__custom_fields - collapse order, box and item custom fields (useful when ?expand=boxes,items parameter specified for Orders resource)

Example request

curl -iL --request GET "https://www.readycloud.com/api/v2/orgs/1/orders/?bearer_token=4ef5b29b1f4f35c383bebfccf4bf4d01"

Response 200 (application/json):

{
    "count": 3,
    "next": null,
    "previous": null,
    "results": [
        {
            "billing": {
                "bill_to": {
                    "address_1": "2010 Warsaw Rd",
                    "address_2": "Apt 4",
                    "city": "Roswell",
                    "company": "UPS",
                    "country": "United States",
                    "created_at": "2014-10-09T16:21:10.290000Z",
                    "email": "o\uff52\uff52\u00ed\uff43\[email protected]",
                    "first_name": "Pat",
                    "last_name": "O\uff52\uff52\u00ed\uff43\uff4f",
                    "phone": "6785851113",
                    "post_code": "56001",
                    "region": "Georgia",
                    "residential": false,
                    "updated_at": "2014-10-09T16:21:10.290000Z",
                    "validated": false
                },
                "shipping": "300.00 USD",
                "status": null,
                "subtotal": "300.00 USD",
                "tax": "300.00 USD",
                "total": "300.00 USD"
            },
            "boxes": [
                {
                    "items": [
                        {
                            "url": "/api/v2/orgs/1/orders/3/boxes/4/items/4/"
                        }
                    ],
                    "url": "/api/v2/orgs/1/orders/3/boxes/4/"
                }
            ],
            "created_at": "2014-10-09T16:21:10.301000Z",
            "custom_fields": {
                "Check": {
                    "value": "15"
                }
            },
            "customer_number": "CN-15",
            "message": "Order message",
            "nested_updated_at": "2014-10-09T16:21:10.301000Z",
            "notes": [],
            "order_number": 15,
            "ordered_at": "2012-01-07T01:24:59Z",
            "po_number": "PO-15",
            "primary_id": "15",
            "printed_at": "2012-01-07T01:24:59Z",
            "relations": [],
            "shipping": {
                "ship_cost": "300.00 USD",
                "ship_from": {
                    "address_1": "8449 E Edgemont",
                    "address_2": "Apt 4",
                    "city": "New York",
                    "company": "FedEx",
                    "country": "United States",
                    "created_at": "2014-10-09T16:21:10.296000Z",
                    "email": "s\u03fb\uff49\uff54\[email protected]",
                    "first_name": "Ann",
                    "last_name": "S\u03fb\uff49\uff54\u0266",
                    "phone": "6785851113",
                    "post_code": "10019",
                    "region": "NY",
                    "residential": false,
                    "updated_at": "2014-10-09T16:21:10.296000Z",
                    "validated": null
                },
                "ship_to": {
                    "address_1": "900 Lincoln Dr",
                    "address_2": "Apt 4",
                    "city": "Scottsdale",
                    "company": "USPS",
                    "country": "United States",
                    "created_at": "2014-10-09T16:21:10.293000Z",
                    "email": "j\u00e5\uff42\uff52\[email protected]",
                    "first_name": "Nick",
                    "last_name": "J\u00e5\uff42\uff52\u07c0",
                    "phone": "6785851113",
                    "post_code": "85257",
                    "region": "AZ",
                    "residential": false,
                    "updated_at": "2014-10-09T16:21:10.293000Z",
                    "validated": true
                },
                "ship_agent": "ReadyShipper 10.0.1",
                "ship_type": "Priority",
                "ship_via": "Form Only",
                "shipped_at": "2014-10-12T11:48:04.825000Z",
                "status": "fulfilled",
                "to_ship_at": "2012-01-09T01:24:59Z",
                "warehouse": "test warehouse"
            },
            "source": {
                "account": null,
                "channel": null,
                "id": null,
                "name": "FedEx",
                "retrieved_at": "2012-01-07T01:24:59Z",
                "updated_at": "2012-01-07T01:24:59Z"
            },
            "tags": [],
            "terms": "Order test terms",
            "unique_id": "00002vBtLSBCD2yzMRJ301Z7",
            "updated_at": "2014-10-09T16:21:10.301000Z",
            "url": "/api/v2/orgs/1/orders/3/"
        },
        {
            "billing": {
                "bill_to": {
                    "address_1": "2010 Warsaw Rd",
                    "address_2": "Apt 4",
                    "city": "Roswell",
                    "company": "UPS",
                    "country": "United States",
                    "created_at": "2014-10-09T16:21:10.268000Z",
                    "email": "o\uff52\uff52\u00ed\uff43\[email protected]",
                    "first_name": "Pat",
                    "last_name": "O\uff52\uff52\u00ed\uff43\uff4f",
                    "phone": "6785851113",
                    "post_code": "56001",
                    "region": "Georgia",
                    "residential": false,
                    "updated_at": "2014-10-09T16:21:10.268000Z",
                    "validated": false
                },
                "shipping": "200.00 USD",
                "status": null,
                "subtotal": "200.00 USD",
                "tax": "200.00 USD",
                "total": "200.00 USD"
            },
            "boxes": [
                {
                    "items": [
                        {
                            "url": "/api/v2/orgs/1/orders/2/boxes/3/items/3/"
                        }
                    ],
                    "url": "/api/v2/orgs/1/orders/2/boxes/3/"
                }
            ],
            "created_at": "2014-10-09T16:21:10.279000Z",
            "custom_fields": {
                "Gift": {
                    "value": "14"
                }
            },
            "customer_number": "CN-14",
            "message": "Order message",
            "nested_updated_at": "2014-10-09T16:21:10.279000Z",
            "notes": [],
            "order_number": 14,
            "ordered_at": "2012-01-07T01:24:59Z",
            "po_number": "PO-14",
            "primary_id": "14",
            "printed_at": "2012-01-07T01:24:59Z",
            "relations": [],
            "shipping": {
                "ship_cost": "200.00 USD",
                "ship_from": {
                    "address_1": "8449 E Edgemont",
                    "address_2": "Apt 4",
                    "city": "New York",
                    "company": "FedEx",
                    "country": "United States",
                    "created_at": "2014-10-09T16:21:10.275000Z",
                    "email": "s\u03fb\uff49\uff54\[email protected]",
                    "first_name": "Ann",
                    "last_name": "S\u03fb\uff49\uff54\u0266",
                    "phone": "6785851113",
                    "post_code": "10019",
                    "region": "NY",
                    "residential": false,
                    "updated_at": "2014-10-09T16:21:10.275000Z",
                    "validated": null
                },
                "ship_to": {
                    "address_1": "900 Lincoln Dr",
                    "address_2": "Apt 4",
                    "city": "Scottsdale",
                    "company": "USPS",
                    "country": "United States",
                    "created_at": "2014-10-09T16:21:10.271000Z",
                    "email": "j\u00e5\uff42\uff52\[email protected]",
                    "first_name": "Nick",
                    "last_name": "J\u00e5\uff42\uff52\u07c0",
                    "phone": "6785851113",
                    "post_code": "85257",
                    "region": "AZ",
                    "residential": false,
                    "updated_at": "2014-10-09T16:21:10.271000Z",
                    "validated": true
                },
                "ship_agent": "ReadyShipper 10.0.1",
                "ship_type": "Standard",
                "ship_via": "Mail Innovations",
                "shipped_at": "2014-05-12T11:48:04.825000Z",
                "status": "unfulfilled",
                "to_ship_at": "2012-01-09T01:24:59Z",
                "warehouse": "test warehouse"
            },
            "source": {
                "account": "shirts-store",
                "channel": null,
                "id": "300021",
                "name": "Shopify",
                "retrieved_at": "2012-01-07T01:24:59Z",
                "updated_at": "2012-01-07T01:24:59Z"
            },
            "tags": [],
            "terms": "Order test terms",
            "unique_id": "00002vBtLSBCD2yzMRJ301Z6",
            "updated_at": "2014-10-09T16:21:10.279000Z",
            "url": "/api/v2/orgs/1/orders/2/"
        },
        {
            "billing": {
                "bill_to": {
                    "address_1": "2010 Warsaw Rd",
                    "address_2": "Apt 4",
                    "city": "Roswell",
                    "company": "UPS",
                    "country": "United States",
                    "created_at": "2014-10-09T16:21:10.229000Z",
                    "email": "o\uff52\uff52\u00ed\uff43\[email protected]",
                    "first_name": "Pat",
                    "last_name": "O\uff52\uff52\u00ed\uff43\uff4f",
                    "phone": "6785851113",
                    "post_code": "56001",
                    "region": "Georgia",
                    "residential": false,
                    "updated_at": "2014-10-09T16:21:10.229000Z",
                    "validated": false
                },
                "shipping": "100.00 USD",
                "status": null,
                "subtotal": "100.00 USD",
                "tax": "100.00 USD",
                "total": "100.00 USD"
            },
            "boxes": [
                {
                    "items": [
                        {
                            "url": "/api/v2/orgs/1/orders/1/boxes/1/items/1/"
                        }
                    ],
                    "url": "/api/v2/orgs/1/orders/1/boxes/1/"
                },
                {
                    "items": [
                        {
                            "url": "/api/v2/orgs/1/orders/1/boxes/2/items/2/"
                        }
                    ],
                    "url": "/api/v2/orgs/1/orders/1/boxes/2/"
                }
            ],
            "created_at": "2014-10-09T16:21:10.247000Z",
            "custom_fields": {
                "Export": {
                    "value": "13"
                }
            },
            "customer_number": "CN-13",
            "message": "Order message",
            "nested_updated_at": "2014-10-09T16:21:10.247000Z",
            "notes": [],
            "order_number": 13,
            "ordered_at": "2012-01-07T01:24:59Z",
            "po_number": "PO-13",
            "primary_id": "13",
            "printed_at": "2012-01-07T01:24:59Z",
            "relations": [],
            "shipping": {
                "ship_cost": "100.00 USD",
                "ship_from": {
                    "address_1": "8449 E Edgemont",
                    "address_2": "Apt 4",
                    "city": "New York",
                    "company": "FedEx",
                    "country": "United States",
                    "created_at": "2014-10-09T16:21:10.239000Z",
                    "email": "s\u03fb\uff49\uff54\[email protected]",
                    "first_name": "Ann",
                    "last_name": "S\u03fb\uff49\uff54\u0266",
                    "phone": "6785851113",
                    "post_code": "10019",
                    "region": "NY",
                    "residential": false,
                    "updated_at": "2014-10-09T16:21:10.239000Z",
                    "validated": null
                },
                "ship_to": {
                    "address_1": "900 Lincoln Dr",
                    "address_2": "Apt 4",
                    "city": "Scottsdale",
                    "company": "USPS",
                    "country": "United States",
                    "created_at": "2014-10-09T16:21:10.234000Z",
                    "email": "j\u00e5\uff42\uff52\[email protected]",
                    "first_name": "Nick",
                    "last_name": "J\u00e5\uff42\uff52\u07c0",
                    "phone": "6785851113",
                    "post_code": "85257",
                    "region": "AZ",
                    "residential": false,
                    "updated_at": "2014-10-09T16:21:10.234000Z",
                    "validated": true
                },
                "ship_agent": "ReadyShipper 10.0.1",
                "ship_type": "UPS Ground",
                "ship_via": "New Mail",
                "shipped_at": "2014-05-12T11:48:04.825000Z",
                "status": "fulfilled",
                "to_ship_at": "2012-01-09T01:24:59Z",
                "warehouse": "test warehouse"
            },
            "source": {
                "account": null,
                "channel": null,
                "id": null,
                "name": "UPS",
                "retrieved_at": "2012-01-07T01:24:59Z",
                "updated_at": "2012-01-07T01:24:59Z"
            },
            "tags": [],
            "terms": "Order test terms",
            "unique_id": "00002vBtLSBCD2yzMRJ301Z5",
            "updated_at": "2014-10-09T16:21:10.247000Z",
            "url": "/api/v2/orgs/1/orders/1/"
        }
    ]
}

POST

Create new order

  • Attributes
    • billing (object, required) - order billing information
      • billing.bill_to (object, required) - order billing to address
      • billing.status: “paid” (string) - pending, paid, partially_paid, refunded, partially_refunded, cancelled
    • shipping (object, required) - order shipping information
      • shipping.ship_to (object, required) - order shipping destination address
      • shipping.ship_from (object, required) - order shipping from address
      • shipping.status: “fulfilled” (string) - unshipped, fulfilled, partially_fulfilled
    • relations (object) - relations to other orders
    • custom_fields (object) - any data you need to save for the order
      • value (string, required) - a value you want to save
      • type (string) - mime type of a value, default: text/plain
      • encoding (string) - base64 or none
    • notes (object) - some note about the order
      • notes.content (string) - content of a note
      • notes.author.email (string) - author’s email
      • notes.author.name (string) - author’s name
      • notes.author.system (bool) - is this note created by the system

POST /orgs/{org_pk}/orders/

Example request:

curl -iL --request POST -H "Content-Type: application/json" --upload-file data.json "https://www.readycloud.com/api/v2/orgs/1/orders/?bearer_token=4ef5b29b1f4f35c383bebfccf4bf4d01"

data.json:

{
    "primary_id": "127283",
    "ordered_at": "2014-12-17T15:34:11Z",
    "shipping": {
        "ship_agent": "ReadyShipper 10.0.1",
        "ship_to": {
            "first_name": "Nicholas",
            "last_name": "Testla",
            "address_1": "900 Lincoln Dr",
            "address_2": "Apt 4",
            "city": "Scottsvale",
            "post_code": "85257",
            "region": "AZ",
            "country": "United States",
            "email": "[email protected]",
            "phone": "6785851113"
        },
        "ship_from": {
            "company": "Toys R U",
            "first_name": "Shipping",
            "last_name": "Department",
            "address_1": "Belmont Street 45",
            "address_2": "Suite 56",
            "city": "New York",
            "post_code": "10019",
            "region": "NY",
            "country": "United States",
            "email": "[email protected]",
            "phone": "6785851113"
        }
    },
    "custom_fields": {
        "additional_xml": {
            "type": "application/xml",
            "value": "<order>112233</order>"
        },
        "Bank deposit": {
            "value": "Can not check"
        },
        "Custom icon": {
            "type": "image/png",
            "value": "aGVsbG8sIHRoaXMgaXMgY3VzdG9tIGZpZWxk==",
            "encoding": "base64"
        }
    },
    "tags": ["new", "processed"]
}

Response 201 (application/json):

{
    "billing": {
        "bill_to": null,
        "shipping": null,
        "status": null,
        "subtotal": null,
        "tax": null,
        "total": null
    },
    "boxes": [
        {
            "items": [],
            "url": "/api/v2/orgs/1/orders/4/boxes/5/"
        }
    ],
    "created_at": "2015-08-13T09:33:07Z",
    "custom_fields": {
        "additional_xml": {
            "type": "application/xml",
            "value": "<order>112233</order>"
        },
        "Bank deposit": {
            "value": "Can not check"
        },
        "Custom icon": {
            "type": "image/png",
            "value": "aGVsbG8sIHRoaXMgaXMgY3VzdG9tIGZpZWxk==",
            "encoding": "base64"
        }
    },
    "customer_number": null,
    "message": null,
    "nested_updated_at": "2015-08-13T09:33:07Z",
    "notes": [],
    "order_number": null,
    "ordered_at": "2014-12-17T15:34:11Z",
    "po_number": null,
    "primary_id": "127283",
    "printed_at": null,
    "relations": [],
    "shipping": {
        "ship_cost": null,
        "ship_from": {
            "address_1": "Belmont Street 45",
            "address_2": "Suite 56",
            "city": "New York",
            "company": "Toys R U",
            "country": "United States",
            "created_at": "2015-08-13T09:33:07Z",
            "email": "[email protected]",
            "first_name": "Shipping",
            "last_name": "Department",
            "phone": "6785851113",
            "post_code": "10019",
            "region": "NY",
            "residential": null,
            "updated_at": "2015-08-13T09:33:07Z",
            "validated": false
        },
        "ship_to": {
            "address_1": "900 Lincoln Dr",
            "address_2": "Apt 4",
            "city": "Scottsvale",
            "company": null,
            "country": "United States",
            "created_at": "2015-08-13T09:33:07Z",
            "email": "[email protected]",
            "first_name": "Nicholas",
            "last_name": "Testla",
            "phone": "6785851113",
            "post_code": "85257",
            "region": "AZ",
            "residential": null,
            "updated_at": "2015-08-13T09:33:07Z",
            "validated": false
        },
        "ship_agent": "ReadyShipper 10.0.1",
        "ship_type": null,
        "ship_via": null,
        "shipped_at": null,
        "status": null,
        "to_ship_at": null,
        "warehouse": null
    },
    "source": {
        "account": null,
        "channel": null,
        "id": null,
        "name": null,
        "retrieved_at": "2015-08-13T09:33:07Z",
        "updated_at": "2015-08-13T09:33:07Z"
    },
    "tags": ["new", "processed"],
    "terms": null,
    "unique_id": "00002yeYogO~zaetH-RlAqLY",
    "updated_at": "2015-08-13T09:33:07Z",
    "url": "/api/v2/orgs/1/orders/4/"
}

Order

GET

Retrieve details of specific order

GET /orgs/{org_pk}/orders/{order_pk}/

Example request:

curl -iL --request GET "https://www.readycloud.com/api/v2/orgs/1/orders/1/?bearer_token=4ef5b29b1f4f35c383bebfccf4bf4d01"

Response 200 (application/json):

{
    "billing": {
        "bill_to": {
            "address_1": "2010 Warsaw Rd",
            "address_2": "Apt 4",
            "city": "Roswell",
            "company": "UPS",
            "country": "United States",
            "created_at": "2014-10-09T16:21:10.229000Z",
            "email": "oｒｒíｃｏ@mail.com",
            "first_name": "Pat",
            "last_name": "Oｒｒíｃｏ",
            "phone": "6785851113",
            "post_code": "56001",
            "region": "Georgia",
            "residential": false,
            "updated_at": "2014-10-09T16:21:10.229000Z",
            "validated": false
        },
        "shipping": "100.00 USD",
        "status": null,
        "subtotal": "100.00 USD",
        "tax": "100.00 USD",
        "total": "100.00 USD"
    },
    "boxes": [
        {
            "items": [
                {
                    "url": "/api/v2/orgs/1/orders/1/boxes/1/items/1/"
                }
            ],
            "url": "/api/v2/orgs/1/orders/1/boxes/1/"
        },
        {
            "items": [
                {
                    "url": "/api/v2/orgs/1/orders/1/boxes/2/items/2/"
                }
            ],
            "url": "/api/v2/orgs/1/orders/1/boxes/2/"
        }
    ],
    "created_at": "2014-10-09T16:21:10.247000Z",
    "custom_fields": {
        "Export": {
            "value": "13"
        }
    },
    "customer_number": "CN-13",
    "message": "Order message",
    "nested_updated_at": "2014-10-09T16:21:10.247000Z",
    "notes": [],
    "order_number": 13,
    "ordered_at": "2012-01-07T01:24:59Z",
    "po_number": "PO-13",
    "primary_id": "13",
    "printed_at": "2012-01-07T01:24:59Z",
    "relations": [],
    "shipping": {
        "ship_cost": "100.00 USD",
        "ship_from": {
            "address_1": "8449 E Edgemont",
            "address_2": "Apt 4",
            "city": "New York",
            "company": "FedEx",
            "country": "United States",
            "created_at": "2014-10-09T16:21:10.239000Z",
            "email": "s\u03fb\uff49\uff54\[email protected]",
            "first_name": "Ann",
            "last_name": "S\u03fb\uff49\uff54\u0266",
            "phone": "6785851113",
            "post_code": "10019",
            "region": "NY",
            "residential": false,
            "updated_at": "2014-10-09T16:21:10.239000Z",
            "validated": null
        },
        "ship_to": {
            "address_1": "900 Lincoln Dr",
            "address_2": "Apt 4",
            "city": "Scottsdale",
            "company": "USPS",
            "country": "United States",
            "created_at": "2014-10-09T16:21:10.234000Z",
            "email": "j\u00e5\uff42\uff52\[email protected]",
            "first_name": "Nick",
            "last_name": "J\u00e5\uff42\uff52\u07c0",
            "phone": "6785851113",
            "post_code": "85257",
            "region": "AZ",
            "residential": false,
            "updated_at": "2014-10-09T16:21:10.234000Z",
            "validated": true
        },
        "ship_agent": "ReadyShipper 10.0.1",
        "ship_type": "UPS Ground",
        "ship_via": "New Mail",
        "shipped_at": "2014-05-12T11:48:04.825000Z",
        "status": "fulfilled",
        "to_ship_at": "2012-01-09T01:24:59Z",
        "warehouse": "test warehouse"
    },
    "source": {
        "account": null,
        "channel": null,
        "id": null,
        "name": "UPS",
        "retrieved_at": "2012-01-07T01:24:59Z",
        "updated_at": "2012-01-07T01:24:59Z"
    },
    "tags": [],
    "terms": "Order test terms",
    "unique_id": "00002vBtLSBCD2yzMRJ301Z5",
    "updated_at": "2014-10-09T16:21:10.247000Z",
    "url": "/api/v2/orgs/1/orders/1/"
}

PATCH

Update specific order

PATCH /orgs/{org_pk}/orders/{order_pk}/

Example request:

curl -iL --request PATCH -H "Content-Type: application/json" --upload-file data.json "https://www.readycloud.com/api/v2/orgs/1/orders/1/?bearer_token=4ef5b29b1f4f35c383bebfccf4bf4d01"

data.json:

{
    "message": "Updated order message",
    "custom_fields": {
        "gift": {
            "type": "text/x-markdown",
            "value": "**two** items of `random gift`"
        },
        "postcard": {
            "value": "no"
        }
    },
    "tags": ["closed", "tracked", "tagged"]
}

Response 200 (application/json):

{
    "billing": {
        "bill_to": {
            "address_1": "2010 Warsaw Rd",
            "address_2": "Apt 4",
            "city": "Roswell",
            "company": "UPS",
            "country": "United States",
            "created_at": "2014-10-09T16:21:10.229000Z",
            "email": "o\uff52\uff52\u00ed\uff43\[email protected]",
            "first_name": "Pat",
            "last_name": "O\uff52\uff52\u00ed\uff43\uff4f",
            "phone": "6785851113",
            "post_code": "56001",
            "region": "Georgia",
            "residential": false,
            "updated_at": "2014-10-09T16:21:10.229000Z",
            "validated": false
        },
        "shipping": "100.00 USD",
        "status": null,
        "subtotal": "100.00 USD",
        "tax": "100.00 USD",
        "total": "100.00 USD"
    },
    "boxes": [
        {
            "items": [
                {
                    "url": "/api/v2/orgs/1/orders/1/boxes/1/items/1/"
                }
            ],
            "url": "/api/v2/orgs/1/orders/1/boxes/1/"
        },
        {
            "items": [
                {
                    "url": "/api/v2/orgs/1/orders/1/boxes/2/items/2/"
                }
            ],
            "url": "/api/v2/orgs/1/orders/1/boxes/2/"
        }
    ],
    "created_at": "2014-10-09T16:21:10.247000Z",
    "custom_fields": {
        "Export": {
            "value": "13"
        },
        "gift": {
            "type": "text/x-markdown",
            "value": "**two** items of `random gift`"
        },
        "postcard": {
            "value": "no"
        }
    },
    "customer_number": "CN-13",
    "message": "Updated order message",
    "nested_updated_at": "2015-08-13T09:33:07Z",
    "notes": [],
    "order_number": 13,
    "ordered_at": "2012-01-07T01:24:59Z",
    "po_number": "PO-13",
    "primary_id": "13",
    "printed_at": "2012-01-07T01:24:59Z",
    "relations": [],
    "shipping": {
        "ship_cost": "100.00 USD",
        "ship_from": {
            "address_1": "8449 E Edgemont",
            "address_2": "Apt 4",
            "city": "New York",
            "company": "FedEx",
            "country": "United States",
            "created_at": "2014-10-09T16:21:10.239000Z",
            "email": "s\u03fb\uff49\uff54\[email protected]",
            "first_name": "Ann",
            "last_name": "S\u03fb\uff49\uff54\u0266",
            "phone": "6785851113",
            "post_code": "10019",
            "region": "NY",
            "residential": false,
            "updated_at": "2014-10-09T16:21:10.239000Z",
            "validated": null
        },
        "ship_to": {
            "address_1": "900 Lincoln Dr",
            "address_2": "Apt 4",
            "city": "Scottsdale",
            "company": "USPS",
            "country": "United States",
            "created_at": "2014-10-09T16:21:10.234000Z",
            "email": "j\u00e5\uff42\uff52\[email protected]",
            "first_name": "Nick",
            "last_name": "J\u00e5\uff42\uff52\u07c0",
            "phone": "6785851113",
            "post_code": "85257",
            "region": "AZ",
            "residential": false,
            "updated_at": "2014-10-09T16:21:10.234000Z",
            "validated": true
        },
        "ship_agent": "ReadyShipper 10.0.1",
        "ship_type": "UPS Ground",
        "ship_via": "New Mail",
        "shipped_at": "2014-05-12T11:48:04.825000Z",
        "status": "fulfilled",
        "to_ship_at": "2012-01-09T01:24:59Z",
        "warehouse": "test warehouse"
    },
    "source": {
        "account": null,
        "channel": null,
        "id": null,
        "name": "UPS",
        "retrieved_at": "2012-01-07T01:24:59Z",
        "updated_at": "2012-01-07T01:24:59Z"
    },
    "tags": ["closed", "tagged", "tracked"],
    "terms": "Order test terms",
    "unique_id": "00002vBtLSBCD2yzMRJ301Z5",
    "updated_at": "2015-08-13T09:33:07Z",
    "url": "/api/v2/orgs/1/orders/1/"
}

To create multi shipment order, first, create an order for every shipment, then update order to create split relation:

curl -iL --request PATCH -H "Content-Type: application/json" --upload-file data.json "https://www.readycloud.com/api/v2/orgs/1/orders/1/?bearer_token=4ef5b29b1f4f35c383bebfccf4bf4d01"

data.json:

{
    "relations": [{
        "kind": "split-parent",
        "order": {
            "unique_id": "00002.vWa65OgyZMxYZ10oCC"
        }
    }]
}

Response 200 (application/json):

{
    "billing": {
        "bill_to": {
            "address_1": "2010 Warsaw Rd",
            "address_2": "Apt 4",
            "city": "Roswell",
            "company": "UPS",
            "country": "United States",
            "created_at": "2014-10-09T16:21:10.229000Z",
            "email": "o\uff52\uff52\u00ed\uff43\[email protected]",
            "first_name": "Pat",
            "last_name": "O\uff52\uff52\u00ed\uff43\uff4f",
            "phone": "6785851113",
            "post_code": "56001",
            "region": "Georgia",
            "residential": false,
            "updated_at": "2014-10-09T16:21:10.229000Z",
            "validated": false
        },
        "shipping": "100.00 USD",
        "status": null,
        "subtotal": "100.00 USD",
        "tax": "100.00 USD",
        "total": "100.00 USD"
    },
    "boxes": [
        {
            "items": [
                {
                    "url": "/api/v2/orgs/1/orders/1/boxes/1/items/1/"
                }
            ],
            "url": "/api/v2/orgs/1/orders/1/boxes/1/"
        },
        {
            "items": [
                {
                    "url": "/api/v2/orgs/1/orders/1/boxes/2/items/2/"
                }
            ],
            "url": "/api/v2/orgs/1/orders/1/boxes/2/"
        }
    ],
    "created_at": "2014-10-09T16:21:10.247000Z",
    "custom_fields": {
        "Export": {
            "value": "13"
        }
    },
    "customer_number": "CN-13",
    "message": "Order message",
    "nested_updated_at": "2015-08-13T09:33:07Z",
    "notes": [],
    "order_number": 13,
    "ordered_at": "2012-01-07T01:24:59Z",
    "po_number": "PO-13",
    "primary_id": "13",
    "printed_at": "2012-01-07T01:24:59Z",
    "relations": [{
        "kind": "split-parent",
        "order": {
            "url": "/api/v2/orgs/1/orders/4/",
            "unique_id": "00002.vWa65OgyZMxYZ10oCC"
        }
    }],
    "shipping": {
        "ship_cost": "100.00 USD",
        "ship_from": {
            "address_1": "8449 E Edgemont",
            "address_2": "Apt 4",
            "city": "New York",
            "company": "FedEx",
            "country": "United States",
            "created_at": "2014-10-09T16:21:10.239000Z",
            "email": "s\u03fb\uff49\uff54\[email protected]",
            "first_name": "Ann",
            "last_name": "S\u03fb\uff49\uff54\u0266",
            "phone": "6785851113",
            "post_code": "10019",
            "region": "NY",
            "residential": false,
            "updated_at": "2014-10-09T16:21:10.239000Z",
            "validated": null
        },
        "ship_to": {
            "address_1": "900 Lincoln Dr",
            "address_2": "Apt 4",
            "city": "Scottsdale",
            "company": "USPS",
            "country": "United States",
            "created_at": "2014-10-09T16:21:10.234000Z",
            "email": "j\u00e5\uff42\uff52\[email protected]",
            "first_name": "Nick",
            "last_name": "J\u00e5\uff42\uff52\u07c0",
            "phone": "6785851113",
            "post_code": "85257",
            "region": "AZ",
            "residential": false,
            "updated_at": "2014-10-09T16:21:10.234000Z",
            "validated": true
        },
        "ship_agent": "ReadyShipper 10.0.1",
        "ship_type": "UPS Ground",
        "ship_via": "New Mail",
        "shipped_at": "2014-05-12T11:48:04.825000Z",
        "status": "fulfilled",
        "to_ship_at": "2012-01-09T01:24:59Z",
        "warehouse": "test warehouse"
    },
    "source": {
        "account": null,
        "channel": null,
        "id": null,
        "name": "UPS",
        "retrieved_at": "2012-01-07T01:24:59Z",
        "updated_at": "2012-01-07T01:24:59Z"
    },
    "tags": [],
    "terms": "Order test terms",
    "unique_id": "00002vBtLSBCD2yzMRJ301Z5",
    "updated_at": "2015-08-13T09:33:07Z",
    "url": "/api/v2/orgs/1/orders/1/"
}

DELETE

Delete specific order

DELETE /orgs/{org_pk}/orders/{order_pk}/

Response 204 (application/json)

Order custom fields

GET

Retrieve full custom fields data

GET /orgs/{org_pk}/orders/{order_pk}/custom-fields/{field_name}/

Example request:

curl -iL --request GET "https://www.readycloud.com/api/v2/orgs/1/orders/1/custom-fields/ENDICIA_LABEL/?bearer_token=4ef5b29b1f4f35c383bebfccf4bf4d01"

Response 200 (application/json):

{
    "name": "ENDICIA_LABEL",
    "value": "there is some data",
    "type": "text/plain",
    "encoding": null
}