Developer : Orders

Manage applications

The /orders resource represents orders that customers have made on the store.

Resource URI

By default, the resource returns pages of 20 orders each. Without any query parameters, the resource returns the first 20 orders (page 0) found:

/api/v1/orders

To get the next page of orders, include a page query parameter:

/api/v1/orders?page=1

To specify the number of orders per page, include a count parameter:

/api/v1/orders?count=50

The count and page parameters can be combined to create pages of arbitrary size:

/api/v1/orders?count=10&page=0
/api/v1/orders?count=10&page=1
/api/v1/orders?count=10&page=2
... and so on ...

Subresource lists also accept page and count parameters:

/api/v1/orders/unfulfilled?count=100

To get only orders created after a certain time, include a created_since timestamp parameter:

/api/v1/orders?created_since=1325185881

The created_since parameter is useful when you want to check for orders that were created since the last time you called the API. You can record the last time you made the API call and use that for created_since, or use the latest created property from the last set of results you received.

Method Scope Required
GET admin
POST admin

Properties

Property Methods Description
billing_address GET The order's billing address
cancelled PUT For API orders only. A boolean that sets the order state to "cancelled". Once an order has been marked as cancelled, it cannot be undone. See Updating order status below
coupon GET, POST The Coupon that was used with this order, if any
created GET Timestamp of when the order was created
custom_id GET, POST Custom identifier for this order
currency GET Prices in the order use this currency
discount GET, POST A description of the discount given, if a coupon was used
fulfilled GET, PUT Whether the order has been fulfilled (boolean). See Updating order status below
line_items GET A list of the line items that make up this order. See Line Item Properties below
order_number GET The unique order number
payment_gateway GET The payment gateway/processor the customer used to check out. One of paypal, google, braintree, or authorizenet
payment_state GET The state of the payment for this order. One of paid, pending, or failed
shipping GET, POST The amount charged for shipping as a formatted string
shipping_raw GET The amount charged for shipping in float format
shipping_address GET The order's shipping address
subtotal GET The order's subtotal (sum of line items, not including shipping, tax, or discount) as a formatted string
subtotal_raw GET The order's subtotal in float format
tax GET, POST The amount charged for tax as a formatted string
tax_raw GET The amount charged for tax in float format
total GET, POST The order total, including extras, shipping, tax, and discounts, as a formatted string
total_raw GET The order total in float format
shipments GET A list of shipments for the order. See Shipment Properties below
url GET The URL of the order on Goodsie
send_notifications POST Boolean value that, when set to false, will prevent email notifications from being sent for this order
ship_first_name POST Shipping first name on this order
ship_last_name POST Shipping last name on this order
ship_street1 POST Shipping street Address line 1 on this order
ship_street2 POST Shipping street Address line 2 on this order
ship_city POST Shipping city on this order
ship_state POST Shipping state on this order
ship_postal_code POST Shipping postal code on this order
ship_country POST Shipping country code on this order
ship_email POST Shipping email address on this order
ship_phone POST Shipping phone number on this order
bill_first_name POST Billing first name on this order
bill_last_name POST Billing last name on this order
bill_street1 POST Billing street Address line 1 on this order
bill_street2 POST Billing street Address line 2 on this order
bill_city POST Billing city on this order
bill_state POST Billing state on this order
bill_postal_code POST Billing postal code on this order
bill_country POST Billing country code on this order
bill_email POST Billing email address on this order
bill_phone POST Billing phone number on this order
line_1_product_option POST Line item 1 product option key. See Products for details on how to locate the product option key. Each block of "line_x_" properties may be repeated for each line item on this order.
line_1_total POST Line item 1 total
line_1_unit_price POST Line item 1 unit price
line_1_quantity POST Line item 1 quantity
line_1_product_extras POST Line item 1 product extras (comma separated list of product extra keys). See Products for details on how to locate the product extra key.

Line Item Properties

Property Methods Description
currency GET The line item's price is in this currency
extras GET A list of extras chosen for this item
name GET The line item's name
price GET The line item's base price, without extras, as a formatted string
price_raw GET The line item's base price in float format
product GET The line item's Product
product_option GET The specific product option chosen by the customer
quantity GET The number of products requested
subtotal GET Subtotal for the line item (quantity multiplied by base price) as a formatted string
subtotal_raw GET Subtotal for the line item in float format

Shipment Properties

Property Methods Description
label_created GET Timestamp of when the shipping label for this shipment was created
ship_date GET The date this shipment was shipped, in YYYY-MM-DD format
carrier GET The shipping carrier used (ie USPS, UPS, FedEx)
service GET The shipping service used (ie UPS Ground, Next Day Delivery)
tracking_number GET The tracking number for this shipment
shipping_cost GET The shipping cost for this shipment in float format

Subresources

Methods Path Description
GET /api/v1/orders/count The count of all orders
GET, PUT /api/v1/orders/{order_number} An order
GET /api/v1/orders/fulfilled Fulfilled orders
GET /api/v1/orders/unfulfilled Orders that have not yet been fulfilled
GET /api/v1/orders/paid Orders where the payment has been completed
GET /api/v1/orders/pending Orders where the payment is still pending
GET /api/v1/orders/failed Orders where the payment failed
GET /api/v1/orders/{state}/count The count of orders in a specific state (fulfilled, etc.)

Example

curl -H "Authorization: Bearer ba125ac086" \
    https://goodsie.com/api/v1/orders
[
    {
        "billing_address": {
            "city": "Minneapolis",
            "country": "US",
            "email": "hans@hiidef.com",
            "first_name": "Hans",
            "last_name": "Kuder",
            "phone": "",
            "postal_code": "55410",
            "state": "MN",
            "street1": "3211 Test St",
            "street2": ""
        },
        "coupon": {
            ...
        },
        "created": 1324405601,
        "currency": "USD",
        "discount": "$1.00 off",
        "fulfilled": false,
        "line_items": [
            {
                "currency": "USD",
                "extras": [
                    {
                        "currency": "USD",
                        "key": "2eeabf4c-2b18-11e1-97fe-002500a0451c",
                        "metadata": {
                            "EXTRAS": "Gift Wrap"
                        },
                        "order": 0,
                        "quantity": -1,
                        "surcharge": "$2.00",
                        "surcharge_raw": 2.0
                    }
                ],
                "name": "An ugly sweater (Red)",
                "price": "$55.00",
                "price_raw": 55.0,
                "product": {
                    "name": "An ugly sweater",
                    ...
                },
                "product_option": {
                    "currency": "USD",
                    "default": false,
                    "fetch_sku": "",
                    "key": "2ee684a3-2b18-11e1-8102-002500a0451c",
                    "metadata": {
                        "Color": "Red"
                    },
                    "order": 0,
                    "quantity": 10,
                    "surcharge": "$0.00",
                    "surcharge_raw": 0.0
                },
                "quantity": 1,
                "subtotal": "$57.00",
                "subtotal_raw": 57.0
            },
            {
                "currency": "USD",
                "extras": [],
                "name": "The Ugly Sweaters Podcast",
                "price": "$20.00",
                "price_raw": 20.0,
                "product": {
                    "name": "The Ugly Sweaters Podcast",
                    ...
                },
                "product_option": {
                    "currency": "USD",
                    "default": true,
                    "fetch_sku": "10021",
                    "key": "df19d185-145d-11e1-aa5e-002500a0451c",
                    "metadata": {},
                    "order": 0,
                    "quantity": -1,
                    "surcharge": "$0.00",
                    "surcharge_raw": 0.0
                },
                "quantity": 1,
                "subtotal": "$20.00",
                "subtotal_raw": 20.0
            }
        ],
        "order_number": 1,
        "payment_gateway": "braintree",
        "payment_state": "pending",
        "shipping": "$1.14",
        "shipping_address": {
            "city": "Minneapolis",
            "country": "US",
            "email": "hans@hiidef.com",
            "first_name": "Hans",
            "last_name": "Kuder",
            "phone": "",
            "postal_code": "55410",
            "state": "MN",
            "street1": "3211 Test St",
            "street2": ""
        },
        "shipping_raw": 1.14,
        "subtotal": "$77.00",
        "subtotal_raw": 77.0,
        "tax": "$0.00",
        "tax_raw": 0.0,
        "total": "$77.14",
        "total_raw": 77.14,
        "url": "http://goodsie.com/admin/orders/detail/1"
    },
    ...
]

Updating order status

curl -H "Authorization: Bearer ba125ac086" -X PUT \
    -F 'fulfilled=true' \
    https://goodsie.com/api/v1/orders/1234567
[
    {
        ... order result ..
    }
]
curl -H "Authorization: Bearer ba125ac086" -X PUT \
    -F 'cancelled=true' \
    https://goodsie.com/api/v1/orders/1234567
[
    {
        ... order result ..
    }
]

Creating order

curl -i -H "Authorization: Bearer ba125ac086" -X POST \
    -F 'send_notifications=1' \
    -F 'custom_id=ALT_ORDER_ID' \
    -F 'total=30' \
    -F 'shipping=5' \
    -F 'tax=0' \
    -F 'discount=2' \
    -F 'coupon=COUPON_CODE' \
    -F 'ship_street1=3211 Test St' \
    -F 'ship_street2=Room 321' \
    -F 'ship_city=Minneapolis' \
    -F 'ship_state=MN' \
    -F 'ship_postal_code=55410' \
    -F 'ship_country=US' \
    -F 'ship_first_name=Hans' \
    -F 'ship_last_name=Kuder' \
    -F 'ship_email=hans@hiidef.com' \
    -F 'ship_phone=123-123-1234' \
    -F 'bill_street1=3211 Test St' \
    -F 'bill_street2=Room 321' \
    -F 'bill_city=Minneapolis' \
    -F 'bill_state=MN' \
    -F 'bill_postal_code=55410' \
    -F 'bill_country=US' \
    -F 'bill_first_name=Hans' \
    -F 'bill_last_name=Kuder' \
    -F 'bill_email=hans@hiidef.com' \
    -F 'bill_phone=123-123-1234' \
    -F 'line_1_product_option=58f9c351-eb74-4c5f-ad56-b3f92edc0e87' \
    -F 'line_1_total=12' \
    -F 'line_1_unit_price=12' \
    -F 'line_1_quantity=1' \
    -F 'line_2_product_option=61565768-e8d4-11e2-ac16-8049710fefd7' \
    -F 'line_2_total=15' \
    -F 'line_2_unit_price=15' \
    -F 'line_2_quantity=1' \
    -F 'line_2_product_extras=5ef7a219-e8d4-11e2-a718-8049710fefd7' \
    'http://goodsie.com/api/v1/orders'
[
    {
        ... order result ..
    }
]