Group Items¶

An item is an individual instance from some shop. Items are often physical, but don’t have to be; a digital download (such as a movie, music or ebook file) also qualifies as an item.

Item resource fields¶

quantity [integer] (required) - The quantity of this item, i.e. the number of times this particular item is to be found within this box.
custom_fields - A custom field is a name-value pair for storing additional data, for more info refer to item custom field documentation.
kind [string] - Choices are “goods”, “discount”, “tax” and “adjustment”.
part_number [string] - SKU of an item.
code [string] - The code of the item. The value can be numeric or alphanumeric and should uniquely identify the type of item described.
description [string] - A short descriptive text for the item.
unit_price [money]‡ - The price for a single item of this type. The unit price is multiplied by the quantity to find the total price for this line item.
unit_weight [weight]‡‡ - The weight of a single item of this type. The unit weight is multiplied by the quantity to find the total weight of this item.
image_link [string] - URL of an image of the item.
pick_location [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.
link [string] - A URL linking to further information about this particular type of item.
origin_country_code [string] - Origin country code for customs paperwork.
joint_production [string] - Joint production flag for customs paperwork.
commodity_code [string] - Commodity code for customs paperwork.
net_cost_code [string] - NetCost code for customs paperwork.
net_cost_begin_date [datetime]† - the NetCost begin date for customs paperwork.
net_cost_end_date [datetime]† - the NetCost end date for customs paperwork.
producer_info_code [string] - Producer info code for customs paperwork.
preference_criteria_code[string] - Preference criteria code for customs paperwork.
scheduleb_commodity_code[string] - Schedule B commodity code for customs paperwork. Note: this value is for goods exported from the US, if international returns to the US are to be processed by ReadyReturns, the HTSUS custom field should also be specified with the correct value for reimport, as in this sample: "custom_fields": { "HTSUS": { "value": "6203.22.30.50" } }
export_type_code [string] - Export type code for customs paperwork.
updated_at (read only) [datetime]† - the time the item was updated in ReadyCloud.
created_at (read only) [datetime]† - the time the item was created in ReadyCloud.
ups [string] - UPS barcode of item.
ean [string] - EAN barcode of item.
isbn [string] - ISBN barcode of item.

† - 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.

‡‡ - the expected format is a string with decimal value and a unit of measure of the following (lbs, g, kg, mg, oz) is expected. Sample: 454.34 g.

Items collection¶

GET¶

Retrieve list of items of specific box

GET /orgs/{org_pk}/orders/{order_pk}/boxes/{box_pk}/items/

Example request:

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

Response 200 (application/json):

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "code": "1",
            "commodity_code": "C-1",
            "created_at": "2013-07-11T20:49:00Z",
            "custom_fields": {},
            "description": "Item Description",
            "export_type_code": "SIM",
            "image_link": null,
            "joint_production": true,
            "kind": null,
            "link": "http://box.url",
            "net_cost_begin_date": "2013-07-11T20:49:00Z",
            "net_cost_code": "NCC",
            "net_cost_end_date": "2013-07-11T20:49:00Z",
            "origin_country_code": "US",
            "part_number": "PN-1",
            "pick_location": "Some location",
            "preference_criteria_code": "Criteria-5",
            "producer_info_code": "Yes",
            "quantity": 3,
            "scheduleb_commodity_code": "SCC-5",
            "unit_price": "15.00 USD",
            "unit_weight": "170.0000 g",
            "updated_at": "2013-07-11T20:49:00Z",
            "url": "/api/v2/orgs/1/orders/1/boxes/1/items/1/",
            "ups": "ups123",
            "ean": "ean123",
            "isbn": "isbn123"
        }
    ]
}

POST¶

Create new item for specific box

POST /orgs/{org_pk}/orders/{order_pk}/boxes/{box_pk}/items/

Attributes:
- kind (string, required) - goods, discount, tax, adjustment

Example request:

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

data.json:

{
    "code": "ES-4335-64667-7565",
    "commodity_code": "C-1",
    "created_at": "2015-05-14T09:59:44.290553Z",
    "custom_fields": {
        "Special customer type": {
            "value": "Guest"
        },
        "Top color": {
            "value": "Deep purple"
        },
        "xml": {
            "type": "application/xml",
            "value": "<custom>Field</custom>"
        }
    },
    "description": "T-Shirt Unisex Black",
    "export_type_code": "SIM",
    "image_link": "http://example.com/tshirt.png",
    "joint_production": true,
    "kind": "goods",
    "link": "http://www.test.com/item",
    "net_cost_begin_date": "2014-10-10T06:49:50Z",
    "net_cost_end_date": "2014-10-12T06:49:50Z",
    "origin_country_code": "US",
    "part_number": "PN-3",
    "pick_location": "Some location",
    "preference_criteria_code": "Criteria-5",
    "producer_info_code": "No[2]",
    "quantity": 15,
    "scheduleb_commodity_code": "SCC-5",
    "unit_price": "88.00 USD",
    "unit_weight": "29.00 g",
    "ups": "ups123",
    "ean": "ean123",
    "isbn": "isbn123"
}

Response 201 (application/json):

{
    "code": "ES-4335-64667-7565",
    "commodity_code": "C-1",
    "created_at": "2015-08-13T09:33:07Z",
    "custom_fields": {
        "Special customer type": {
            "value": "Guest"
        },
        "Top color": {
            "value": "Deep purple"
        },
        "xml": {
            "type": "application/xml",
            "value": "<custom>Field</custom>"
        }
    },
    "description": "T-Shirt Unisex Black",
    "export_type_code": "SIM",
    "image_link": "http://example.com/tshirt.png",
    "joint_production": true,
    "kind": "goods",
    "link": "http://www.test.com/item",
    "net_cost_begin_date": "2014-10-10T06:49:50Z",
    "net_cost_code": null,
    "net_cost_end_date": "2014-10-12T06:49:50Z",
    "origin_country_code": "US",
    "part_number": "PN-3",
    "pick_location": "Some location",
    "preference_criteria_code": "Criteria-5",
    "producer_info_code": "No[2]",
    "quantity": 15,
    "scheduleb_commodity_code": "SCC-5",
    "unit_price": "88.00 USD",
    "unit_weight": "29.0000 g",
    "updated_at": "2015-08-13T09:33:07Z",
    "url": "/api/v2/orgs/1/orders/1/boxes/1/items/2/",
    "ups": "ups123",
    "ean": "ean123",
    "isbn": "isbn123"
}

Item¶

ReadyCloud API lets you do the following with the Item resource:

GET¶

Retrieve details of specific item

GET /orgs/{org_pk}/orders/{order_pk}/boxes/{box_pk}/items/{item_pk}/

Example request:

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

Response 200 (application/json):

{
    "code": "1",
    "commodity_code": "C-1",
    "created_at": "2013-07-11T20:49:00Z",
    "custom_fields": {},
    "description": "Item Description",
    "export_type_code": "SIM",
    "image_link": null,
    "joint_production": true,
    "kind": null,
    "link": "http://box.url",
    "net_cost_begin_date": "2013-07-11T20:49:00Z",
    "net_cost_code": "NCC",
    "net_cost_end_date": "2013-07-11T20:49:00Z",
    "origin_country_code": "US",
    "part_number": "PN-1",
    "pick_location": "Some location",
    "preference_criteria_code": "Criteria-5",
    "producer_info_code": "Yes",
    "quantity": 3,
    "scheduleb_commodity_code": "SCC-5",
    "unit_price": "15.00 USD",
    "unit_weight": "170.0000 g",
    "updated_at": "2013-07-11T20:49:00Z",
    "url": "/api/v2/orgs/1/orders/1/boxes/1/items/1/",
    "ups": "ups123",
    "ean": "ean123",
    "isbn": "isbn123"
}

PATCH¶

Updated specific item

PATCH /orgs/{org_pk}/orders/{order_pk}/boxes/{box_pk}/items/{item_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/boxes/1/items/1/?bearer_token=4ef5b29b1f4f35c383bebfccf4bf4d01"

data.json:

{
    "custom_fields": {
        "Operator": {
            "value": "smooth"
        }
    },
    "image_link": "http://example.com/goods/img-2.png",
    "kind": "goods",
    "origin_countr_code": "CN",
    "quantity": 19,
    "unit_weight": "180 g"
}

Response 200 (application/json):

{
    "code": "1",
    "commodity_code": "C-1",
    "created_at": "2013-07-11T20:49:00Z",
    "custom_fields": {
        "Operator": {
            "value": "smooth"
        }
    },
    "description": "Item Description",
    "export_type_code": "SIM",
    "image_link": "http://example.com/goods/img-2.png",
    "joint_production": true,
    "kind": "goods",
    "link": "http://box.url",
    "net_cost_begin_date": "2013-07-11T20:49:00Z",
    "net_cost_code": "NCC",
    "net_cost_end_date": "2013-07-11T20:49:00Z",
    "origin_country_code": "US",
    "part_number": "PN-1",
    "pick_location": "Some location",
    "preference_criteria_code": "Criteria-5",
    "producer_info_code": "Yes",
    "quantity": 19,
    "scheduleb_commodity_code": "SCC-5",
    "unit_price": "15.00 USD",
    "unit_weight": "180.0000 g",
    "updated_at": "2015-08-13T09:33:07Z",
    "url": "/api/v2/orgs/1/orders/1/boxes/1/items/1/",
    "ups": "ups123",
    "ean": "ean123",
    "isbn": "isbn123"
}

DELETE¶

Delete specific item

DELETE /orgs/{org_pk}/orders/{order_pk}/boxes/{box_pk}/items/{item_pk}/

Response 204 (application/json)

Item custom fields¶

GET¶

Retrieve full custom fields data

GET /orgs/{org_pk}/orders/{order_pk}/boxes/{box_pk}/items/{item_pk}/custom-fields/{field_name}/

Example request:

curl -iL --request GET "https://www.readycloud.com/api/v2/orgs/1/orders/1/boxes/1/items/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
}