Orders API

Orders represent a purchase someone has made from a store, and contains all of the information required to review the order, ship it to the buyer, and track it’s shipping and payment status.

Order object

Attribute Type Description
id string The unique identifier for the order.
item_count integer The number of items in the order.
item_total decimal The total price of all items.
discount_total decimal The total price of all discounts.
shipping_total decimal The total price of all shipping costs.
tax_total decimal The total price of all taxes.
total decimal The total price of everything.
customer_first_name string The first name of the buyer.
customer_last_name string The last name of the buyer.
customer_email string The email address of the buyer.
customer_note string An optional note from the buyer.
shipping_address_1 string The street address for shipping.
shipping_address_2 string An optional addition to the street address for shipping.
shipping_city string The city of the shipping address.
shipping_state string The state or province of the shipping address.
shipping_zip string The zip or postal code of the shipping address.
shipping_country.id string The unique 2-letter code for the order’s country.
shipping_country.name string The name of the order’s country.
shipping_latitude integer The latitude of the shipping address.
shipping_longitude integer The longitude of the shipping address.
shipping_status string The status of shipping the order. Possible values are shipped and unshipped.
payment_status string The status of payment for the order. Possible values are unpaid, pending, completed, failed, and invalid.
created_at timestamp When the order was created.
updated_at timestamp When the order was last updated.
completed_at timestamp When the order was placed and paid for.
currency.id string The unique 3-letter code for the order’s currency.
currency.name string The name of the order’s currency.
currency.sign string The symbol used for the order’s currency.
currency.locale string The locale associated with the order’s currency.
events[].id integer The unique identifier of the order event.
events[].message string A message describing the order event.
events[].created_at timestamp When the order event was created.
items[].id integer The unique identifier of the order item.
items[].product_name string The name of the item’s product.
items[].product_option_name string The name of the item’s product option.
items[].quantity integer The quantity of the item.
items[].price decimal The price of the item.
items[].total decimal The total price of the item, quantity multiplied by price.
items[].image_url string The customizable URL of the product image.
items[].product.id integer The unique identifier of the product.
items[].product_option.id integer The unique identifier of the product option.
transactions[].id integer The unique identifier of the order transaction.
transactions[].label string A message describing the transaction.
transactions[].amount decimal The total price of the transaction.
transactions[].processor string The name of the payment processor. Possible values are cash, paypal_standard, paypal_express, and stripe.
transactions[].processor_id string The payment processor’s transaction ID.
transactions[].processor_url string The URL to view the transaction on the processor’s website.
transactions[].currency.id integer The unique 3-letter code for the transaction’s currency.
transactions[].currency.name string The name of the transaction’s currency.
transactions[].currency.sign string The symbol used for the transaction’s currency.
transactions[].currency.locale string The locale associated with the transaction’s currency.
adjustments[].id integer The unique identifier of the order adjustment.
adjustments[].amount decimal The price of the adjustment.
adjustments[].label string A message describing the adjustment.

Get all orders

Get all orders for an account.

GET /v1/accounts/{account-id}/orders
{
  "data": [
    {
      "id": "LMFN-543196",
      "type": "orders",
      "attributes": {
        "item_count": 1,
        "item_total": "100.1",
        "discount_total": "10.0",
        "shipping_total": "10.0",
        "tax_total": "0.0",
        "total": "100.1",
        "customer_first_name": "Joe",
        "customer_last_name": "Somebody",
        "customer_email": "joe@somebody.com",
        "customer_note": "Created by Joe",
        "shipping_address_1": "123 some street",
        "shipping_address_2": "#123",
        "shipping_city": "Somewhere",
        "shipping_state": "UT",
        "shipping_zip": "64801",
        "shipping_latitude": null,
        "shipping_longitude": null,
        "shipping_status": "unshipped",
        "payment_status": "completed",
        "created_at": "2014-12-25T00:00:00.000Z",
        "updated_at": "2014-12-25T00:00:00.000Z",
        "completed_at": "2014-12-25T00:00:00.000Z"
      },
      "links": {
        "self": "https://api.bigcartel.com/v1/accounts/1/orders/LMFN-543196"
      },
      "relationships": {
        "currency": {
          "data": {
            "type": "currencies",
            "id": "USD"
          }
        },
        "shipping_country": {
          "data": {
            "type": "countries",
            "id": "US"
          }
        },
        "events": {
          "data": [
            {
              "type": "order_events",
              "id": "1"
            }
          ]
        },
        "items": {
          "data": [
            {
              "type": "order_line_items",
              "id": "2"
            }
          ]
        },
        "transactions": {
          "data": [
            {
              "type": "order_transactions/payments",
              "id": "3"
            }
          ]
        },
        "adjustments": {
          "data": [
            {
              "type": "order_adjustments/shipping",
              "id": "4"
            },
            {
              "type": "order_adjustments/tax",
              "id": "5"
            },
            {
              "type": "order_adjustments/discount",
              "id": "6"
            }
          ]
        }
      }
    }
  ],
  "meta": {
    "count": 25
  },
  "included": [
    {
      "id": "USD",
      "type": "currencies",
      "attributes": {
        "name": "U.S. Dollar",
        "sign": "$",
        "locale": "en-US"
      }
    },
    {
      "id": "US",
      "type": "countries",
      "attributes": {
        "name": "United States"
      }
    },
    {
      "id": "1",
      "type": "order_events",
      "attributes": {
        "created_at": "2014-12-25T00:00:00.000Z",
        "message": "Payment completed"
      }
    },
    {
      "id": "2",
      "type": "order_line_items",
      "attributes": {
        "product_name": "This product",
        "product_option_name": "This option",
        "quantity": 1,
        "price": "100.0",
        "total": "100.0",
        "image_url": "https://images.bigcartel.com/some_resource/12345/-/example.jpg"
      },
      "relationships": {
        "product": {
          "data": {
            "type": "product",
            "id": "7"
          }
        },
        "product_option": {
          "data": {
            "type": "product_option",
            "id": "8"
          }
        }
      }
    },
    {
      "id": "3",
      "type": "order_transactions/payments",
      "attributes": {
        "label": "Visa ending in 1234",
        "amount": "100.0",
        "processor": "stripe",
        "processor_id": "ex_123456789",
        "processor_url": "https://manage.stripe.com/test/payments/ex_123456789"
      },
      "data": {
        "currency": {
          "data": {
            "type": "currencies",
            "id": "USD"
          }
        }
      }
    },
    {
      "id": "4",
      "type": "order_adjustments/shipping",
      "attributes": {
        "amount": "10.0",
        "label": "Shipping charges"
      }
    },
    {
      "id": "5",
      "type": "order_adjustments/tax",
      "attributes": {
        "amount": "0.1"
      }
    },
    {
      "id": "6",
      "type": "order_adjustments/discount",
      "attributes": {
        "amount": "10.0",
        "label": "[FREESHIPPING] Free shipping discount"
      }
    }
  ],
  "links": {
    "next": "https://api.bigcartel.com/v1/accounts/1/orders?page%5Blimit%5D=10&page%5Boffset%5D=10",
    "last": "https://api.bigcartel.com/v1/accounts/1/orders?page%5Blimit%5D=10&page%5Boffset%5D=10"
  }
}

Parameters

Name Type Required Description
search string false Search orders that match the customer name (customer_first_name + customer_last_name), customer_email, and id attributes.
filter string false Filter orders using the shipping_status attribute. Allowed values are shipped or unshipped.
sort string false Sort orders using the specified attribute, in ascending order by default. Prefix the value with - to specify descending order. Allowed values are completed_at, created_at, and updated_at.
Search example

Get all orders that match example@example.com.

GET /v1/accounts/{account-id}/orders?search=example@example.com
Filter example

Get all orders with the shipping_status of unshipped.

GET /v1/accounts/{account-id}/orders?filter[shipping_status]=unshipped
Sort example

Get all orders, sorted by the time they were created, in descending order.

GET /v1/accounts/{account-id}/orders?sort=-created_at

Get an order

Get a specific order for an account.

GET /v1/accounts/{account-id}/orders/{order-id}
{
  "data": {
    "id": "LMFN-543196",
    "type": "orders",
    "attributes": {
      "item_count": 1,
      "item_total": "100.1",
      "discount_total": "10.0",
      "shipping_total": "10.0",
      "tax_total": "0.0",
      "total": "100.1",
      "customer_first_name": "Joe",
      "customer_last_name": "Somebody",
      "customer_email": "joe@somebody.com",
      "customer_note": "Created by Joe",
      "shipping_address_1": "123 some street",
      "shipping_address_2": "#123",
      "shipping_city": "Somewhere",
      "shipping_state": "UT",
      "shipping_zip": "64801",
      "shipping_latitude": null,
      "shipping_longitude": null,
      "shipping_status": "unshipped",
      "payment_status": "completed",
      "created_at": "2014-12-25T00:00:00.000Z",
      "updated_at": "2014-12-25T00:00:00.000Z",
      "completed_at": "2014-12-25T00:00:00.000Z"
    },
    "links": {
      "self": "https://api.bigcartel.com/v1/accounts/1/orders/LMFN-543196"
    },
    "relationships": {
      "currency": {
        "data": {
          "type": "currencies",
          "id": "USD"
        }
      },
      "shipping_country": {
        "data": {
          "type": "countries",
          "id": "US"
        }
      },
      "events": {
        "data": [
          {
            "type": "order_events",
            "id": "1"
          }
        ]
      },
      "items": {
        "data": [
          {
            "type": "order_line_items",
            "id": "2"
          }
        ]
      },
      "transactions": {
        "data": [
          {
            "type": "order_transactions/payments",
            "id": "3"
          }
        ]
      },
      "adjustments": {
        "data": [
          {
            "type": "order_adjustments/shipping",
            "id": "4"
          },
          {
            "type": "order_adjustments/tax",
            "id": "5"
          },
          {
            "type": "order_adjustments/discount",
            "id": "6"
          }
        ]
      }
    }
  },
  "included": [
    {
      "id": "USD",
      "type": "currencies",
      "attributes": {
        "name": "U.S. Dollar",
        "sign": "$",
        "locale": "en-US"
      }
    },
    {
      "id": "US",
      "type": "countries",
      "attributes": {
        "name": "United States"
      }
    },
    {
      "id": "1",
      "type": "order_events",
      "attributes": {
        "created_at": "2014-12-25T00:00:00.000Z",
        "message": "Payment completed"
      }
    },
    {
      "id": "2",
      "type": "order_line_items",
      "attributes": {
        "product_name": "This product",
        "product_option_name": "This option",
        "quantity": 1,
        "price": "100.0",
        "total": "100.0",
        "image_url": "https://images.bigcartel.com/some_resource/12345/-/example.jpg"
      },
      "relationships": {
        "product": {
          "data": {
            "type": "product",
            "id": "7"
          }
        },
        "product_option": {
          "data": {
            "type": "product_option",
            "id": "8"
          }
        }
      }
    },
    {
      "id": "3",
      "type": "order_transactions/payments",
      "attributes": {
        "label": "Visa ending in 1234",
        "amount": "100.0",
        "processor": "stripe",
        "processor_id": "ex_123456789",
        "processor_url": "https://manage.stripe.com/test/payments/ex_123456789"
      },
      "relationships": {
        "currency": {
          "data": {
            "type": "currencies",
            "id": "USD"
          }
        }
      }
    },
    {
      "id": "4",
      "type": "order_adjustments/shipping",
      "attributes": {
        "amount": "10.0",
        "label": "Shipping charges"
      }
    },
    {
      "id": "5",
      "type": "order_adjustments/tax",
      "attributes": {
        "amount": "0.1"
      }
    },
    {
      "id": "6",
      "type": "order_adjustments/discount",
      "attributes": {
        "amount": "10.0",
        "label": "[FREESHIPPING] Free shipping discount"
      }
    }
  ]
}

Parameters

None.

Update an order

Updates a specific order’s details.

PATCH /v1/accounts/{account-id}/orders/{order-id}

Parameters

Name Type Required Description
id string true The unique identifier for the order.
type string true The only option right now is orders.
customer_first_name string false The first name of the buyer.
customer_last_name string false The last name of the buyer.
customer_email string false The email address of the buyer.
shipping_address_1 string false The street address for shipping.
shipping_address_2 string false An optional addition to the street address for shipping.
shipping_city string false The city of the shipping address.
shipping_state string false The state or province of the shipping address.
shipping_zip string false The zip or postal code of the shipping address.
shipping_country_id string false The unique 2-letter code for the order’s country.
shipping_status string false The status of shipping the order. Possible values are shipped or unshipped.

Example request

Update an order to change the shipping_status from unshipped to shipped.

{
  "data": {
    "id": "LMFN-543196",
    "type": "orders",
    "attributes": {
      "shipping_status": "shipped"
    }
  }
}

If successful, we’ll return a 200 OK and the same body as getting the order.