Overview

The Celery API is organized around REST. Our API is designed to have predictable, resource-oriented URLs and uses HTTP response codes to indicate any API errors.

Response Format

All API responses follow JSON root conventions.

Versioning

We are currently on Version 1 (v1) of the API.

Cross Origin Resource Sharing (CORS)

For Javascript usage with XMLHttpRequest, we support cross-origin resource sharing.

JSONP

Our API supports JSONP for all endpoints.

If you're writing an AJAX application, and you'd like to wrap our response with a callback, all you have to do is specify a callback parameter with any API call:

https://api.trycelery.com/v1/users/me?callback=callbackFunction

Will respond with:

callbackFunction({
  ...
});
Important Notice

The Celery API is currently in beta. Documentation for request formats and example response formats will be available soon. To get an Access Token, register an account and your Access Token will be listed below.

Please contact support@trycelery.com if you intend to deploy our API in production code.

API Endpoint
https://api.trycelery.com

Summary of Resource URL Patterns

No authentication required:

  • /v1/shop/{SLUG}
  • /v1/slugify
  • /v1/checkout
  • /v1/checkout/paypal

Authentication required:

  • /v1/products
  • /v1/products/{PRODUCT_ID}
  • /v1/orders
  • /v1/orders/{ORDER_ID}
  • /v1/coupons
  • /v1/coupons/{COUPON_ID}
  • /v1/users/me

Authentication

To authenticate with the Celery API, you should append your access token to the query string:

https://api.trycelery.com/v1/users/me?access_token={ACCESS_TOKEN}

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. Unless specifically noted, you must authenticate for all requests.

Register to get an Access Token

Sign up for an account and we'll give you an access token.

Register Your Application

Errors

All errors are responded in JSON.

A descriptive error message will always be provided as a string with the key 'error'.

Celery uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing, a charge failed, etc.), and codes in the 5xx range indicate an error with Celery's servers.

HTTP Status Codes
  • 200 OK - Everything worked as expected
  • 400 Bad Request - You are probably missing a required parameter
  • 401 Unauthorized - Invalid or missing API token
  • 404 Not Found - The endpoint or resource does not exist
  • 500 Celery Error - Something happened on our end
Sample Response
{"error": "Bad Request"}

Retrieve a shop

Retrieves the public details of a Product or Collection that has previously been created. This endpoint does not require authentication.

Arguments
slug:
required

The identifier of the Product or Collection to be retrieved.

Returns

Returns a product object if a valid identifier was provided, and returns an error otherwise.

Definition
GET https://api.trycelery.com/v1/shop/{SLUG}
Example Response
{
  "product": {
    "_id": "...",
    "analytics": {
      "ga_id": "UA-XXXXXXXX-X"
    },
    "notes": "...",
    "campaign": {
      "enabled": false,
      "revenue_goal": 0,
      "sold_goal": 0
    },
    "created": 1370570431753,
    "created_date": "2013-06-07T02:00:31.753Z",
    "css": "...",
    "deposit": 2000,  // in cents
    "description": "...",
    "extras": [],
    "flags": {
        "hide_payment": false,
        "hide_shipping": false,
        "na_only": false,
        "show_coupon": false,
        "us_only": false
    },
    "image": "...",
    "metadata": {},
    "name": "Test Product",
    "options": [],
    "pitch": "...",
    "price": 20000,
    "published": true,
    "quantity_limit": 10,
    "shipping": 0,
    "slug": "test-product",
    "tagline": "",
    "updated": 1370570481773,
    "updated_date": "2013-06-07T02:01:21.773Z",
    "user_id": "...",
    "video": "..."
  }
}

Check if product slug exists

Returns whether a product slug is being used. This AJAX endpoint does not require authentication.

Arguments
slug:
required

The identifier of the slug to check.

Returns

A boolean whether the product slug exists.

Definition
GET https://api.trycelery.com/v1/slugify?slug={SLUG}
Example Response
{
  "slugify": true
}

Checkout with Credit Card

Checkout with credit card and creates a new order object. This endpoint does not require authentication. This request must use HTTPS with the following header Content-Type="application/json". The HTTP BODY must by a JSON string with root object "order".

Arguments
seller_id:
required

The identifier of the seller.

buyer:
required -- object

See below for child parameters.

buyer.email:
required
buyer.name:
optional
buyer.shipping:
optional -- object

See below for child parameters.

buyer.shipping.street:
optional
buyer.shipping.city:
optional
buyer.shipping.state:
optional

Use 2-letter state code if in United States.

buyer.shipping.zip:
optional
buyer.shipping.country:
optional

Use ISO 3166-1 alpha-2 code.

products:
required -- array

Products is an array of Product objects. In each Product object, the required key is slug and recommened key is quantity.

payment:
required -- object

See below for child paramaters.

payment.card_number:
required
payment.card_exp_month:
required
payment.card_exp_year:
required
payment.card_exp_cvc:
required
coupon:
optional
metadata:
optional

Store anything you want.

Returns

Returns an order object if the checkout succeeded. An error will be returned if something goes wrong.

Definition
POST https://api.trycelery.com/v1/checkout
Example Response
{
  "order": {
    "seller_id": "5149052516b6139690000001",
    "buyer": {
      "email": "buyer@trycelery.com",
      "name": "buyer",
      "address": {
        "street": "1337 Noob St"
        "city": "San Francisco"
        "state": "CA"
        "zip": "12345"
        "country": "US"
      },
      "billing": {
        "street": "1337 Noob St"
        "city": "San Francisco"
        "state": "CA"
        "zip": "12345"
        "country": "US"
      }
    },
    "products": [
      {
        "slug": "slugger",
        "quantity": 2,
        "options": [
          {
            "name": "color",
            "value": "red"
          }
        ]
      },
      ...
    ],
    "payment": {
      "card_number": "4242424242424242",
        "card_exp_month": "05",
        "card_exp_year": "2015",
        "card_cvc": "123"
    },
    "metadata": {
      ...
    }
  }
}

Create a new order with PayPal

Checkout with PayPal and creates a new order object with PayPal. This endpoint does not require authentication. This request must use HTTPS with the following header Content-Type="application/json". The HTTP BODY must by a JSON string with root object "order".

Arguments
seller_id:
required

The identifier of the seller.

buyer:
required -- object

See below for child parameters.

buyer.email:
required
buyer.name:
optional
buyer.shipping:
optional -- object

See below for child parameters.

buyer.shipping.street:
optional
buyer.shipping.city:
optional
buyer.shipping.state:
optional

Use 2-letter state code if in United States.

buyer.shipping.zip:
optional
buyer.shipping.country:
optional

Use ISO 3166-1 alpha-2 code.

products:
required -- array

Products is an array of Product objects. In each Product object, the required key is slug and recommened key is quantity.

coupon:
optional
metadata:
optional

Store anything you want.

Returns

Returns an order object if the checkout succeeded. An error will be returned if something goes wrong.

Definition
POST https://api.trycelery.com/v1/checkout/paypal
Example Response
{
  "order": {
    "seller_id": "5149052516b6139690000001",
    "products": [
    {
      "slug": "slugger",
      "quantity": 2,
      "options": [
        {
          "name": "color",
          "value": "red"
        }
      ]
    },
    ...
    ],
    "metadata": {
      ...
    }
  }
}

List all products

Returns a list of products you have.

Arguments
limit:
optional

Limit the number of products.

skip:
optional

Skip N products.

sort:
optional

Field name, such as updated and created.

order:
optional

asc | desc

Returns

An array of up to limit products, starting at skip offset. Each entry in the array is a separate product object.

Definition
GET https://api.trycelery.com/v1/products
Example Response
{
  "total": 3,
  "count": 3,
  "offset": 0,
  "limit": 0,
  "has_more": false,
  "products": [
    {
      "_id": "51ad40901a7e9b0200000004",
      ...
    },
    {
      "_id": "51ad40901a7e9b0200000005",
      ...
    },
    {
      "_id": "51ad40901a7e9b0200000006",
      ...
    }
  ]
}

Retrieve a single product

Retrieves a product that has previously been created.

Arguments
product_id:
required

The identifier of the Product to be retrieved.

Returns

Returns a product object if a valid identifier was provided, and returns an error otherwise.

Definition
GET https://api.trycelery.com/v1/products/{PRODUCT_ID}
Example Response
{
  "product": {
      "_id": "51ad40901a7e9b0200000004",
      "slug": "test-product",
      ...
    }
}

Create a new product

Creates a new product object. This request must use HTTPS with the following header Content-Type="application/json". The HTTP BODY must by a JSON string with root object "product".

Arguments
name:
optional
price:
optional

In cents.

deposit:
optional

In cents.

options:
optional -- array
Returns

Returns a product object if the call succeeded. An error will be returned if something goes wrong.

Definition
POST https://api.trycelery.com/v1/products
Example Response
{
  [TBD]
}

Update a product

Updates an existing product object. This request must use HTTPS with the following header Content-Type="application/json". The HTTP BODY must by a JSON string with root object "product".

Arguments
product_id:
required

The identifier of the Product to be updated.

Returns

Returns a product object if the call succeeded. An error will be returned if something goes wrong.

Definition
PUT https://api.trycelery.com/v1/products/{PRODUCT_ID}
Example Response
{
  [TBD]
}

Delete a product

Deletes an existing product object. This action is permanent and any product deleted is not recoverable.

Arguments
product_id:
required

The identifier of the Product to be deleted.

Returns

Returns a {"status": true} if successful.

Definition
DELETE https://api.trycelery.com/v1/products/{PRODUCT_ID}
Example Response
{
  [TBD]
}

List all orders

Returns a list of orders you have. The orders are returned in sorted order, with the most recent order appearing first.

Arguments
limit:
optional

Limit the number of products.

skip:
optional

Skip N products.

sort:
optional

Field name, such as updated and created.

order:
optional

asc | desc

since:
optional

Based on updated date. Unix time in milliseconds (ms)

until:
optional

Based on updated date. Unix time in milliseconds (ms)

status:
optional

paid, paid_balance, paid_deposit, refunded, shipped

Returns

An array of up to limit orders, starting at skip offset. Each entry in the array is a separate order object.

Definition
GET https://api.trycelery.com/v1/orders
Example Response
{
  "total": 3,
  "count": 3,
  "offset": 0,
  "limit": 0,
  "has_more": false,
  "orders": [
    {
      "_id": "51ad40901a7e9b0200000004",
      ...
    },
    {
      "_id": "51ad40901a7e9b0200000005",
      ...
    },
    {
      "_id": "51ad40901a7e9b0200000006",
      ...
    }
  ]
}

Retrieve a single order

Retrieves a order that has previously been created.

Arguments
order_id:
required

The identifier of the Order to be retrieved.

Returns

Returns a order object if a valid identifier was provided, and returns an error otherwise.

Definition
GET https://api.trycelery.com/v1/orders/{ORDER_ID}
Example Response
{
  "order": {
    "_id": "51ad40901a7e9b0200000006",
    ...
  }
}

Create a new order

Creates a new order object. This request must use HTTPS with the following header Content-Type="application/json". The HTTP BODY must by a JSON string with root object "order".

seller_id:
required

The identifier of the seller.

buyer:
required -- object

See below for child parameters.

buyer.email:
required
buyer.name:
optional
buyer.shipping:
optional -- object

See below for child parameters.

buyer.shipping.street:
optional
buyer.shipping.city:
optional
buyer.shipping.state:
optional

Use 2-letter state code if in United States.

buyer.shipping.zip:
optional
buyer.shipping.country:
optional

Use ISO 3166-1 alpha-2 code.

products:
required -- array

Products is an array of Product objects. In each Product object, the required key is slug and recommened key is quantity.

payment:
required -- object

See below for child paramaters.

payment.card_number:
optional
payment.card_exp_month:
optional
payment.card_exp_year:
optional
payment.card_exp_cvc:
optional
coupon:
optional
metadata:
optional

Store anything you want.

Returns

Returns an order object if the call succeeded. An error will be returned if something goes wrong.

Definition
POST https://api.trycelery.com/v1/orders
Example Response
{
  [TBD]
}

Update an order

Updates an existing order object. This request must use HTTPS with the following header Content-Type="application/json". The HTTP BODY must by a JSON string with root object "order".

order_id:
required

The identifier of the Order to be updated.

buyer:
optional -- object

See below for child parameters.

buyer.email:
optional
buyer.name:
optional
buyer.shipping:
optional -- object

See below for child parameters.

buyer.shipping.street:
optional
buyer.shipping.city:
optional
buyer.shipping.state:
optional

Use 2-letter state code if in United States.

buyer.shipping.zip:
optional
buyer.shipping.country:
optional

Use ISO 3166-1 alpha-2 code.

fulfillment:
optional -- object

See below for child paramaters.

fulfillment.courier:
optional
fulfillment.number:
optional
status:
optional
metadata:
optional
Returns

Returns an order object if the call succeeded. An error will be returned if something goes wrong.

Definition
PUT https://api.trycelery.com/v1/orders/{ORDER_ID}
Example Response
{
  [TBD]
}

Delete an order

Deletes an existing order object. This action is permanent and any product deleted is not recoverable.

order_id:
required

The identifier of the Order to be deleted.

Returns

Returns a {"status": true} if successful.

Definition
DELETE https://api.trycelery.com/v1/orders/{ORDER_ID}
Example Response
{
  [TBD]
}

Cancel order

Cancels order.

order_id:
required

The identifier of the Order to be cancelled.

Returns

Returns order object. An error will be returned if something goes wrong.

Definition
GET https://api.trycelery.com/v1/orders/{ORDER_ID}/cancel
Example Response
{
  [TBD]
}

Charge deposit

Charges deposit.

order_id:
required

The identifier of the Order that will have its deposit charged.

Returns

Returns order object. An error will be returned if something goes wrong.

Definition
POST https://api.trycelery.com/v1/orders/{ORDER_ID}/charge_deposit
Example Response
{
  [TBD]
}

Charge balance

Charges balance.

order_id:
required

The identifier of the Order that will have its balance charged.

Returns

Returns order object. An error will be returned if something goes wrong.

Definition
POST https://api.trycelery.com/v1/orders/{ORDER_ID}/charge_balance
Example Response
{
  [TBD]
}

Refund deposit

Refunds deposit.

order_id:
required

The identifier of the Order that will have its deposit refunded.

Returns

Returns order object. An error will be returned if something goes wrong.

Definition
POST https://api.trycelery.com/v1/orders/{ORDER_ID}/refund_deposit
Example Response
{
  [TBD]
}

Refund balance

Refunds balance.

order_id:
required

The identifier of the Order that will have its balance refunded.

Returns

Returns order object. An error will be returned if something goes wrong.

Definition
POST https://api.trycelery.com/v1/orders/{ORDER_ID}/refund_balance
Example Response
{
  [TBD]
}

Ship order

Changes order status to "shipped".

order_id:
required

The identifier of the Order to be mark shipped. Fires off email notification to buyer unless silenced in User Settings.

courier:
optional

ups, fedex, usps, or other.

number:
optional

Returns

Returns order object. An error will be returned if something goes wrong.

Definition
POST https://api.trycelery.com/v1/orders/{ORDER_ID}/ship
Example Response
{
  [TBD]
}

List all coupons

Returns a list of coupons you have. The coupons are returned in sorted order, with the most recent coupons appearing first.

Arguments
limit:
optional

Limit the number of products.

skip:
optional

Skip N products.

sort:
optional

Field name, such as updated and created.

order:
optional

asc | desc

Returns

An array of up to limit coupons, starting at skip offset. Each entry in the array is a separate coupons object.

Definition
GET https://api.trycelery.com/v1/coupons
Example Response
{
  "total": 3,
  "count": 3,
  "offset": 0,
  "limit": 0,
  "has_more": false,
  "coupons": [
    {
      "_id": "51ad40901a7e9b0200000004",
      ...
    },
    {
      "_id": "51ad40901a7e9b0200000005",
      ...
    },
    {
      "_id": "51ad40901a7e9b0200000006",
      ...
    }
  ]
}

Retrieve a single coupon

Retrieves a coupon that has previously been created.

order_id:
required

The identifier of the Coupon to be retrieved.

Returns

Returns a coupon object if a valid identifier was provided, and returns an error otherwise.

Definition
GET https://api.trycelery.com/v1/coupons/{COUPON_ID}
Example R
Example Response
{
  "coupon": {
    "code": "bacon strips",
    "type": "percent",
    "discount": 10
    }
}

Create a new coupon

Creates a new coupon object. This request must use HTTPS with the following header Content-Type="application/json". The HTTP BODY must by a JSON string with root object "coupon".

code:
required

Coupon code.

type:
required

percent, flat.

discount:
required

Amount discounted.

Returns

Returns a coupon object if the call succeeded. An error will be returned if something goes wrong.

Definition
POST https://api.trycelery.com/v1/coupons
Example Response
{
  "coupon": {
    "code": "bacon strips",
    "type": "percent",
    "discount": 10
    }
}

Update a coupon

Updates an existing coupon object. This request must use HTTPS with the following header Content-Type="application/json". The HTTP BODY must by a JSON string with root object "coupon".

order_id:
required

The identifier of the Coupon to be updated.

code:
optional

Coupon code.

type:
optional

percent, flat.

discount:
optional

Amount discounted.

Returns

Returns a coupon object if the call succeeded. An error will be returned if something goes wrong.

Definition
PUT https://api.trycelery.com/v1/coupons/{COUPON_ID}
Example Response
{
  "coupon": {
    "code": "bacon strips",
    "type": "percent",
    "discount": 10
    }
}

Delete a coupon

Deletes an existing coupon object. This action is permanent and any product deleted is not recoverable.

order_id:
required

The identifier of the Coupon to be updated.

Returns

Returns a {"status": true} if successful.

Definition
DELETE https://api.trycelery.com/v1/coupons/{COUPON_ID}
Example Response
{
  {"status": true}
}

Retrieve information about yourself

Retrieves seller information about yourself.

Returns

Returns a user object if a valid identifier was provided, and returns an error otherwise.

Definition
GET https://api.trycelery.com/v1/users/me
Example Response
{
  "user": {
    ...
}

Update information about yourself

Updates seller information about yourself.

Returns

Returns a user object if a valid identifier was provided, and returns an error otherwise.

Definition
PUT https://api.trycelery.com/v1/users/me
Example Response
{
  "user": {
    ...
}