Skip to content

Instantly share code, notes, and snippets.

@liuhui998

liuhui998/gist:f2c857005e7df8b5145b

Forked from asabaylus/gist:3071099
Last active August 29, 2015 14:22
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save liuhui998/f2c857005e7df8b5145b to your computer and use it in GitHub Desktop.
Save liuhui998/f2c857005e7df8b5145b to your computer and use it in GitHub Desktop.
Download ZIP
Raw
gistfile1.md

Celery API

The Celery API is an ecommerce logic and storage engine designed to be an essential tool for any developer.

The API is currently in beta. Please contact help@trycelery.com if you intend to deploy our API in production code.

Our API is organized around REST and designed to have predictable, resource-oriented URLs, and to use HTTP response codes to indicate API errors. We support cross-origin resource sharing to allow you to interact securely with our API from a client-side web application (though you should remember that you should never expose your secret API key in any public website's client-side code). Although both JSON and XML are supported, JSON is the preferred method for API consumption. By default, JSON will be returned in all responses from the API and webhooks.

To view v1 API documentation, go to https://legacy.trycelery.com/developer.

Menu

Getting Started

The base endpoint URL is https://api.trycelery.com. Celery is currently on version v2, so a request to retrieve all orders would resemble:

GET https://api.trycelery.com/v2/orders

To access the sandbox environment, create a new account at https://dashboard-sandbox.trycelery.com. The sandbox base endpoint URL is https://api-sandbox.trycelery.com. The sandbox environment is separate from production and does not use live money.

API Basics

  • All requests must be made over HTTPS.
  • Always set required headers. The API expects requests to be sent with the header Content-Type and Accept set to application/json or application/xml.
  • All prices are in cents. Prices are represented as integers in cents. Thus, an API response of 100 would represent 1.00.

Authentication

Tokens are used to authenticate your requests. Your access token can be retrieved in the Celery dashboard. Endpoints require authentication over HTTPS. The preferred method is to authenticate with HTTP header:

Authorization: {ACCESS_TOKEN}

Errors

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 payment failed, etc.), and codes in the 5xx range indicate an error with Celery's servers.

Our error responses have the format:

{
    "meta": {
        "code": 409,
        "error": {
           "code": 409,
           "message": "User with email already exists."
         }
    },
    "data": "User with email already exists."
}

Pagination

Attributes Type Description
total integer Total number of records in list.
count integer Number of records on current page.
limit integer A limit on the number of records to be returned. Default is 100.
offset integer Starting record to be returned. Default is 0.
page integer Current page number.
pages integer Total number of pages.
has_more boolean Whether current page is last page.

All responses return with a similar structure. Collections returns an array and single objects return an object. Here's an example of a collection response:

{
    "meta": {
        "code": 200,
        "paging": {
            "total": 45,
            "count": 10,
            "limit": 10,
            "offset": 5,
            "page": 2,
            "pages": 5,
            "has_more": true
        }
    },
    "data": [
        {
            ...
        }
    ]
}

By default, requests return a limit of 100 records per page. You can change this by setting the limit parameter in the request. For example, "limit": 10 will return 10 records per page. The Celery API returns a maximum of 100 records per page.

When there are more records available than can be returned in a single page, you can paginate through them by setting the offset or page.

Rate Limits

There is a default rate limit of 120 requests per minute. If for any reason this is not enough, please contact us.

Orders Resource

Attributes Type Description
_id string Order unique identifier.
user_id string Seller unique identifier.
order_status string Possible values: open, completed, cancelled.
payment_status string Possible values: unpaid, paid, refunded, failed.
fulfillment_status string Possible values: unfulfilled, fulfilled, processing, failed.
currency string 3-letter ISO currency code (lowercase). Possible values: usd, cad, gbp, eur, aud.
notes string Seller order notes.
type string Possible values: card, paypal_adaptive, paypal_adaptive_chained, affirm.
shipping_method string Shipping method for fulfillment partners.
number string Human-readable order number.
linetotal integer Sum of the line item amounts. Amount in cents.
discount integer Discount amount applied to the order. Amount in cents.
subtotal integer Sum of line totals less discount. Amount in cents.
shipping integer Shipping cost applied. Amount in cents.
taxes integer Sales tax applied. Amount in cents.
adjustment integer Price adjustments applied. Amount in cents.
total integer Total = subtotal + shipping + taxes + adjustments. Amount in cents.
balance integer Amount owed to the seller. Amount in cents.
paid integer Gross amount paid to the seller. Amount in cents.
refunded integer Amount refunded by the seller. Amount in cents.
fee integer Celery application fee. Amount in cents.
created integer Unix timestamp in milliseconds.
created_date string ISO 8601 timestamp.
updated integer Unix timestamp in milliseconds.
updated_date string ISO 8601 timestamp.
Buyer object
buyer.email string Buyer's email address.
buyer.first_name string Buyer's first name.
buyer.last_name string Buyer's last name.
buyer.name string Buyer's combined first and last name.
buyer.company string Buyer's company.
buyer.phone string Buyer's phone number.
buyer.notes string Buyer notes to the seller.
Shipping Address object
shipping_address.first_name string Shipping address first name.
shipping_address.last_name string Shipping address last name.
shipping_address.name string Shipping address first and last name.
shipping_address.company string Shipping address company name.
shipping_address.line1 string Shipping address street address.
shipping_address.line2 string Shipping address building, apartment, unit, etc.
shipping_address.city string Shipping address city.
shipping_address.state string Shipping address state, province, or region.
shipping_address.zip string Shipping address ZIP or postal code.
shipping_address.country string Shipping address 2-letter ISO country code (lowercase).
shipping_address.phone string Shipping address phone number.
Fulfillment object
fulfillment.created integer Date marked fulfilled (Unix timestamp in milliseconds).
fulfillment.created_date string Date marked fulfilled (ISO 8601 timestamp).
fulfillment.courier string Courier used. Possible values: ups, usps, fedex, dhl, other.
fulfillment.number string Tracking number.
Payment Source object
payment_source.card.name string Name on credit/debit card. Stripe only.
payment_source.card.celery_token string Stripe only.
payment_source.card.exp_month integer Expiration month of credit/debit card. Stripe only.
payment_source.card.exp_year integer Expiration year of credit/debit card. Stripe only.
payment_source.card.last4 string Last 4 digits of credit/debit card. Stripe only.
payment_source.card.type string Credit/debit card type.
payment_source.card.country string Country of credit/debit card. Stripe only.
payment_source.paypal.email string Buyer's paypal email address. PayPal only.
payment_source.paypal.preapproval_key string PayPal only.
payment_source.paypal.pay_key string PayPal only.
payment_source.paypal.redirect_url string PayPal only.
payment_source.paypal.ipn string PayPal only.
payment_source.paypal.ending integer Preapproval expiration date (Unix timestamp in milliseconds). PayPal only.
payment_source.paypal.ending_date string Preapproval expiration date (ISO 8601 timestamp). PayPal only.
payment_source.paypal.seller_email string Seller's PayPal email address. PayPal only.
payment_source.affirm.checkout_token string Affirm only.
payment_source.affirm.charge_id string Affirm only.
payment_source.airbrite.customer_token string Airbrite orders only.
payment_source.airbrite.card_token string Airbrite orders only.
payment_source.airbrite.fingerprint string Airbrite orders only.
payment_source.airbrite.name string Airbrite orders only.
payment_source.airbrite.exp_month integer Airbrite orders only.
payment_source.airbrite.exp_year integer Airbrite orders only.
payment_source.airbrite.last4 string Airbrite orders only.
payment_source.airbrite.country string Airbrite orders only.
payment_source.airbrite.type string Airbrite orders only.
Client Details object
client_details.ip string string
client_details.user_agent string Browser user agent from Celery checkout.
client_details.accept_language string Browser language from Celery checkout.
client_details.referer string Browser referer from Celery checkout.
Line Items [objects]
line_items[].id string Line item identifier (uuid).
line_items[].product_id string Product id.
line_items[].product_name string Product name.
line_items[].variant_id string Variant id.
line_items[].variant_name string Variant name.
line_items[].sku string Seller defined sku.
line_items[].celery_sku string Celery's internal sku.
line_items[].price integer Line_item unit price.
line_items[].quantity integer Number of units ordered.
line_items[].weight integer Line item unit weight.
line_items[].enable_taxes boolean Whether taxes apply to line item.
Payments [objects]
payments[].id string Payment identifier.
payments[].gateway string Gateway identifier. Possible values: stripe, affirm, paypal.
payments[].charge_id string Gateway identifier for the charge (Stripe and Affirm only).
payments[].balance_transaction string Stripe only.
payments[].pay_key string PayPal only.
payments[].preapproval_key string PayPal only.
payments[].capture_id string Affirm only.
payments[].transaction_id string Affirm only.
payments[].currency string Currency.
payments[].amount integer Amount captured.
payments[].amount_refunded integer Amount refunded.
payments[].paid boolean Whether payment was paid.
payments[].captured boolean Whether payment was captured.
payments[].refunded boolean Whether payment was refunded.
payments[].created integer Charge date. Unix timestamp in milliseconds.
payments[].created_date string Charge date. ISO 8601 timestamp.
payments[].card.name string Stripe only.
payments[].card.last4 string Stripe only.
payments[].card.exp_month integer Stripe only.
payments[].card.exp_year integer Stripe only.
payments[].card.type string Stripe only.
payments[].card.country string Stripe only.
Adjustments [objects]
adjustments[].id string Adjustment identifier.
adjustments[].type string Possible values: flat.
adjustments[].reason string Reasoning for price adjustment.
adjustments[].issuer string Authorizer of price adjustment.
adjustments[].amount number Amount of price adjustment.
discount_codes [strings] Array of discount codes used.
Discounts [objects]
discounts[].code string Discount code applied.
discounts[].type: string Discount type. Possible values: flat, percent.
discounts[].amount integer Discount amount (5% off means 500 and $10 off means 1000).
discounts[].product_id string Product id that discount belongs to.
discounts[].apply string Possible values: once, every_time.
History [objects]
history[].type string See events.
history[].body string Brief description of history type.
history[].created integer Unix timestamp in milliseconds.
history[].created_date string ISO 8601 timestamp.

Checkout with Credit or Debit Card

This is a public endpoint to create a new order with a credit or debit card. It does not require authentication.

For cross-browser compatibility with older versions of Internet Explorer, we recommend using jQuery-ajaxTransport-XDomainRequest.

To place an order with a credit/debit card in the sandbox environment, please use Stripe test cards.

POST /v2/orders/checkout
Arguments
Attributes Type Description
user_id string Required. Your user id.
currency string 3-letter ISO currency code (lowercase). Possible values: usd, cad, gbp, eur, aud.
Buyer object
buyer.email string Required. Buyer's email address (used for Celery's email notifications).
buyer.first_name string Buyer's first name.
buyer.last_name string Buyer's last name.
buyer.company string Buyer's company.
buyer.phone string Buyer's phone number.
buyer.notes string Buyer notes to the seller.
Shipping Address object
shipping_address.first_name string Shipping address first name.
shipping_address.last_name string Shipping address last name.
shipping_address.company string Shipping address company name.
shipping_address.line1 string Shipping address street address.
shipping_address.line2 string Shipping address building, apartment, unit, etc.
shipping_address.city string Shipping address city.
shipping_address.state string Shipping address state, province, or region. If country US or CA, use 2-letter ISO state code (lowercase).
shipping_address.zip string Shipping address ZIP or postal code.
shipping_address.country string Shipping address 2-letter ISO country code (lowercase).
shipping_address.phone string Shipping address phone number.
Line Items [objects]
line_items[].product_id string Required. Product id.
line_items[].variant_id string Variant id (required if product has variants).
line_items[].quantity integer Number of units ordered.
Payment Source object
payment_source.card.name string Name on credit/debit card. Stripe only.
payment_source.card.number string Credit/debit card number. Stripe only.
payment_source.card.exp_month integer Required. Expiration month of credit/debit card. Stripe only.
payment_source.card.exp_year integer Required. Expiration year of credit/debit card. Stripe only.
payment_source.card.cvc string Required. Credit/debit card CVC. Stripe only.
discount_codes [strings] List of coupon codes to be applied to order.
Example Request
$ curl -X POST -H Content-Type:application/json -H \
https://api.trycelery.com/v2/orders/checkout \
-d'
{
    "user_id": "514a114080feb60200000001",
    "buyer": {
        "email": "first@last.com",
        "first_name": "First",
        "last_name": "Last",
        "phone": "555-555-5555"
    },
    "shipping_address": {
        "first_name": "First",
        "last_name": "Last",
        "company": "Celery",
        "line1": "123 Street",
        "line2": null,
        "city": "New York",
        "state": "ny",
        "zip": "10012",
        "country": "us",
        "phone": "555-555-5555"
    },
    "line_items": [
        {
            "product_id": "531e0b012cf9766885f781b7",
            "variant_id": "",
            "quantity": 1
        }
    ],
    "payment_source": {
        "card": {
            "name": "First Last",
            "number": "4242 4242 4242 4242",
            "exp_month": 12,
            "exp_year": 2020,
            "cvc": "123"
        }
    },
    "discount_codes": [
        "10dollarsoff"
    ]
}
Example Response
{
    "meta": {
        "code": 200
    },
    "data": {
        "_id": "544c220151feb60200000002",
        "user_id": "514a114080feb60200000001",
        "order_status": "open",
        "payment_status": "unpaid",
        "fulfillment_status": "unfulfilled",
        ...,
        "history": [
            {
                "type": "order.created",
                "created": 1393476995707,
                "created_date": "2014-02-27T04:56:35.707Z",
                "body": "Your order was created."
            }
        ],
        ...
    }
}

Checkout with PayPal

This is a public endpoint to create a new order with PayPal. It does not require authentication. Celery uses PayPal Adaptive Payments.

For cross-browser compatibility with older versions of Internet Explorer, we recommend using jQuery-ajaxTransport-XDomainRequest.

The response will include a URL that the buyer needs to be redirected to initiate the PayPal payment flow. This URL can be found found in data.payment_source.paypal.redirect_url. After the buyer completes the PayPal payments flow, they will be redirected back to return URL provided. Please note that the Celery appends the order number to the return URL. Thus, if you set the return URL to be https://yourshop.com/confirmation, then the buyer will be redirected to https://yourshop.com/confirmation/101340827. If the buyer cancels during the PayPal payment flow, then they will be redirected to the cancel URL.

POST /v2/orders/checkout/paypal
Arguments
Attributes Type Description
user_id string Required. Your user id.
cancel_url string Required. URL that buyer will go to if they cancel order.
return_url string Required. URL that buyer will go to after they complete PayPal payment flow.
currency string 3-letter ISO currency code (lowercase). Possible values: usd, cad, gbp, eur, aud.
Buyer object
buyer.email string Required. Buyer's email address (used for Celery's email notifications).
buyer.first_name string Buyer's first name.
buyer.last_name string Buyer's last name.
buyer.company string Buyer's company.
buyer.phone string Buyer's phone number.
buyer.notes string Buyer notes to the seller.
Shipping Address object
shipping_address.first_name string Shipping address first name.
shipping_address.last_name string Shipping address last name.
shipping_address.company string Shipping address company name.
shipping_address.line1 string Shipping address street address.
shipping_address.line2 string Shipping address building, apartment, unit, etc.
shipping_address.city string Shipping address city.
shipping_address.state string Shipping address state, province, or region. If country US or CA, use 2-letter ISO state code (lowercase).
shipping_address.zip string Shipping address ZIP or postal code.
shipping_address.country string Shipping address 2-letter ISO country code (lowercase).
shipping_address.phone string Shipping address phone number.
Line Items [objects]
line_items[].product_id string Required. Product id.
line_items[].variant_id string Variant id (required if product has variants).
line_items[].quantity integer Number of units ordered.
discount_codes [strings] List of coupon codes to be applied to order.
Example Request
$ curl -X POST -H Content-Type:application/json -H \
https://api.trycelery.com/v2/orders/checkout/paypal \
-d'
{
    "user_id": "514a114080feb60200000001",
    "cancel_url": "https://www.yourshop.com",
    "return_url": "https://www.yourshop.com/confirmation",
    "buyer": {
        "email": "first@last.com",
        "first_name": "First",
        "last_name": "Last",
        "phone": "555-555-5555"
    },
    "shipping_address": {
        "first_name": "First",
        "last_name": "Last",
        "company": "Celery",
        "line1": "123 Street",
        "line2": null,
        "city": "New York",
        "state": "ny",
        "zip": "10012",
        "country": "us",
        "phone": "555-555-5555"
    },
    "line_items": [
        {
            "product_id": "531e0b012cf9766885f781b7",
            "quantity": 1
        }
    ]
}
Example Response
{
    "meta": {
        "code": 200
    },
    "data": {
        "_id": null,
        "user_id": "514a114080feb60200000001",
        "number": "101340827",
        "order_status": "open",
        "payment_status": "unpaid",
        "fulfillment_status": "unfulfilled",
        "type": "paypal_adaptive",
        "cancel_url": "https://www.yourshop.com/101340827",
        "return_url": "https://www.yourshop.com/confirmation/101340827",
        "payment_source": {
            "paypal": {
                "redirect_url": "https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_ap-preapproval&preapprovalkey=PA-3KC050249N5937812",
                "preapproval_key": "PA-3KC050249N5937812"
            }
        },
        ...
    }
}

Retrieve an Order

GET /v2/orders/{id}
Arguments
Attributes Type Description
id string Required. Order unique identifier.
Example Request
$ curl -X GET -H Content-Type:application/json -H Authorization:{ACCESS_TOKEN} \
https://api.trycelery.com/v2/orders/530ec58358b6ee0000f5d440
Example Response
{
    "meta": {
        "code": 200
    },
    "data": {
        "locked": false,
        "order_status": "open",
        "payment_status": "paid",
        "fulfillment_status": "unfulfilled",
        "currency": "usd",
        "notes": null,
        "type": "card",
        "number": "101335478",
        "cancel_url": null,
        "return_url": null,
        "shipping_method": null,
        "deposit": 0,
        "discount": 0,
        "balance": 0,
        "subtotal": 1000,
        "total": 2075,
        "paid": 2075,
        "refunded": 0,
        "adjustment": 0,
        "shipping": 1000,
        "taxes": 75,
        "linetotal": 1000,
        "fee": 42,
        "seller": {
            "_id": "514a114080feb60200000001",
            "email": null,
            "name": null,
            "paypal_email": null
        },
        "buyer": {
            "sort_name": "brian nguyen",
            "email": "brian@trycelery.com",
            "first_name": "Brian",
            "last_name": "Nguyen",
            "name": "Brian Nguyen",
            "phone": null,
            "company": null,
            "notes": null
        },
        "shipping_address": {
            "email": "brian@trycelery.com",
            "first_name": "Brian",
            "last_name": "Nguyen",
            "name": "Brian Nguyen",
            "line1": "123 Main Street",
            "line2": "Unit 101",
            "city": "San Francisco",
            "state": "ca",
            "zip": "94105",
            "country": "us",
            "phone": null,
            "company": null
        },
        "billing_address": {
            "email": null,
            "first_name": null,
            "last_name": null,
            "name": null,
            "line1": null,
            "line2": null,
            "city": null,
            "state": null,
            "zip": null,
            "country": null,
            "phone": null
        },
        "fulfillment": {
            "courier": null,
            "number": null,
            "created": null,
            "created_date": null
        },
        "payment_source": {
            "card": {
                "name": null,
                "celery_token": "c31310e652f5a7d7254484668c52686d09cd665414c6d3cae04f92660c3d930cad55a378cfa2c76fcbf8dc0b129a4f0baac0e3794c4485510a36cfbef7461c45dfc1d52d6e03a28d03af86f7ec405577f0d1c7c7a0487ca780003f86b595bca0",
                "exp_month": 11,
                "exp_year": 20,
                "last4": "4242",
                "country": "us",
                "type": "visa"
            },
            "paypal": {
                "email": null,
                "preapproval_key": null,
                "pay_key": null,
                "redirect_url": null,
                "ipn": null,
                "ending": null,
                "ending_date": null
            },
            "affirm": {
                "checkout_token": null,
                "charge_id": null
            },
            "airbrite": {
                "customer_token": null,
                "card_token": null,
                "fingerprint": null,
                "name": null,
                "exp_month": 0,
                "exp_year": 0,
                "last4": null,
                "country": null,
                "type": null
            }
        },
        "discount_codes": [],
        "line_items": [
            {
                "id": "0fcfa92c-5214-d4bf-ac41-86f26fb9c9b9",
                "product_id": "531e0b012cf9766885f781b7",
                "product_name": "koala 10",
                "variant_id": null,
                "variant_name": null,
                "sku": "koala_10",
                "celery_sku": "531e0b012cf9766885f781b7",
                "price": 1000,
                "quantity": 1,
                "weight": 0.5,
                "enable_taxes": true
            }
        ],
        "adjustments": [],
        "discounts": [],
        "payments": [
            {
                "id": "9969f10f-6c29-4d36-ba84-c60abd4bd7ed",
                "charge_id": "ch_4OrpNFZKd4NOBz",
                "balance_transaction": "txn_4Orp4IPXvI0QCc",
                "pay_key": null,
                "preapproval_key": null,
                "capture_id": null,
                "transaction_id": null,
                "currency": "usd",
                "amount": 2075,
                "amount_refunded": 0,
                "fee": 132,
                "paid": true,
                "captured": true,
                "created": 1405323722000,
                "created_date": "2014-07-14T07:42:02.000Z",
                "refunded": null,
                "refunded_date": null,
                "card": {
                    "name": "",
                    "last4": "4242",
                    "exp_month": null,
                    "exp_year": null,
                    "type": "visa",
                    "country": "us"
                }
            }
        ],
        "history": [
            {
                "type": "order.created",
                "body": "Order was created.",
                "created": 1405323703464,
                "created_date": "2014-07-14T07:41:43.464Z"
            },
            {
                "type": "order.charge.succeeded",
                "body": "Order was charged.",
                "created": 1405323723032,
                "created_date": "2014-07-14T07:42:03.032Z"
            }
        ],
        "_id": "53c389b7eba65a000061e12f",
        "user_id": "514a114080feb60200000001",
        "version": "v2",
        "created": 1405323701278,
        "updated": 1405323722893,
        "created_date": "2014-07-14T07:41:41.278Z",
        "updated_date": "2014-07-14T07:42:02.893Z",
        "metadata": {}
    }
}

Retrieve a List of Orders

GET /v2/orders
Arguments
Attributes Type Description
sort string Sort by. Default is created.
order string Order by. Default is desc. Possible values: desc, asc.
offset string Default is 0.
page integer Current page number.
limit string A limit on the number of objects to be returned. Default is 100.
created integer A filter on the list based on object created field. The value can be a string with an integer timestamp (in ms), or it can be a dictionary with the following options: gt, gte, lt, lte.
updated integer A filter on the list based on object updated field. The value can be a string with an integer timestamp (in ms), or it can be a dictionary with the following options: gt, gte, lt, lte.
order_status string Possible values: open, completed, cancelled.
payment_status string Possible values: unpaid, paid, failed, refunded.
fulfillment_status string Possible values: unfulfilled, fulfilled, procesing, failed.
buyer.name string A filter on the list based on buyer name. This filter will perform a regex on the value.
buyer.email string A filter on the list based on buyer email. This filter will perform a regex on the value.
line_items.product_id string A filter on the list based on product id.
line_items.variant_id string A filter on the list based on product variant id.
line_items.sku string A filter on the list based on sku.
type string A filter on order type: card, paypal_adaptive, paypal_adaptive_chained, affirm.
shipping_method string A filter on shipping method.
discounts.code string A filter on discount code.
currency string A filter on currency code.
  • gt: Return values where the relevant field is after this timestamp (in ms).
  • gte: Return values where the relevant field is after or equal to this timestamp (in ms).
  • lt: Return values where the relevant field is before this timestamp (in ms).
  • lte: Return values where the relevant field is before or equal to this timestamp (in ms).

If I wanted to query for orders created at or after January 1, 2014 12:00 AM UTC, my query string would include created[gte]=1388534400000.

If I wanted to query for orders purchased by Brian Nguyen, my query string would include buyer.name=Brian+Nguyen.

Example Request
$ curl -X POST -H Content-Type:application/json -H Authorization:{ACCESS_TOKEN} \
https://api.trycelery.com/v2/orders?created[gte]=1388534400000
Example Response
{
    "meta": {
        "code": 200,
        "paging": {
            "total": 2,
            "count": 2,
            "offset": 0,
            "page": 1,
            "pages": 1,
            "limit": 100,
            "has_more": false
        }
    },
    "data": [
        {
            ...
        },
        {
            ...
        }
    ]
}

Count orders

GET /v2/orders/count
Arguments
Attributes Type Description
created integer A filter on the list based on object created field. The value can be a string with an integer timestamp (in ms), or it can be a dictionary with the following options: gt, gte, lt, lte.
updated integer A filter on the list based on object updated field. The value can be a string with an integer timestamp (in ms), or it can be a dictionary with the following options: gt, gte, lt, lte.
order_status string Possible values: open, completed, cancelled.
payment_status string Possible values: unpaid, paid, failed, refunded.
fulfillment_status string Possible values: unfulfilled, fulfilled, procesing, failed.
buyer.name string A filter on the list based on buyer name. This filter will perform a regex on the value.
buyer.email string A filter on the list based on buyer email. This filter will perform a regex on the value.
line_items.product_id string A filter on the list based on product id.
line_items.variant_id string A filter on the list based on product variant id.
line_items.sku string A filter on the list based on sku.
type string A filter on order type: card, paypal_adaptive, paypal_adaptive_chained, affirm.
shipping_method string A filter on shipping method.
discounts.code string A filter on discount code.
currency string A filter on currency code.
  • gt: Return values where the relevant field is after this timestamp (in ms).
  • gte: Return values where the relevant field is after or equal to this timestamp (in ms).
  • lt: Return values where the relevant field is before this timestamp (in ms).
  • lte: Return values where the relevant field is before or equal to this timestamp (in ms).

If I wanted to count how many orders were created at or after January 1, 2014 12:00 AM UTC, my query string would include created[gte]=1388534400000.

If I wanted to count how many orders were purchased by Brian Nguyen, my query string would include buyer.name=Brian+Nguyen.

If I wanted to count how many orders include the product with id 531e0b012cf9766885f781b7, my query string would be include line_items.product_id=531e0b012cf9766885f781b7.

Example Request
$ curl -X POST -H Content-Type:application/json -H Authorization:{ACCESS_TOKEN} \
https://api.trycelery.com/v2/orders/count?created[gte]=1388534400000
Example Response
{
    "meta": {
        "code": 200
    },
    "data": {
        "total": 507
    }
}

Update an Order

Warning! Modifying data that is not buyer, shipping_address, or line items may have unintended effects on the order. If you are modifying these objects, please be sure to include entire object.

PUT /v2/orders/{id}
Arguments
Attributes Type Description
_id string Required. Order unique identifier.
Buyer object
buyer.email string Buyer's email address.
buyer.first_name string Buyer's first name.
buyer.last_name string Buyer's last name.
buyer.phone string Buyer's phone number.
buyer.notes string Buyer notes to the seller.
Shipping Address object
shipping_address.first_name string Shipping address first name.
shipping_address.last_name string Shipping address last name.
shipping_address.company string Shipping address company name.
shipping_address.line1 string Shipping address street address.
shipping_address.line2 string Shipping address building, apartment, unit, etc.
shipping_address.city string Shipping address city.
shipping_address.state string Shipping address state, province, or region. US or CA states should use their 2-letter ISO state code and be lowercase.
shipping_address.zip string Shipping address ZIP or postal code.
shipping_address.country string Shipping address 2-letter ISO country code (lowercase).
shipping_address.phone string Shipping address phone number.
Line Items [object]
line_items[].id string Line item identifier (uuid).
line_items[].product_id string Product id.
line_items[].variant_id string Variant id.
line_items[].quantity integer Number of units ordered.
Example Request

This example request updates both the buyer and shipping_address information.

$ curl -X PUT -H Content-Type:application/json -H Authorization:{ACCESS_TOKEN} \
https://api.trycelery.com/v2/orders/530ec58358b6ee0000f5d440 \
-d'
{
    "buyer": {
        "email": "first@last.com",
        "first_name": "First",
        "last_name": "Last",
        "phone": "555-555-5555"
    },
    "shipping_address": {
        "first_name": "First"
        "last_name": "Last",
        "company": "Celery",
        "line1": "123 Street",
        "line2": null,
        "city": "New York",
        "state": "ny",
        "zip": "10012",
        "country": "us",
        "phone": "555-555-5555"
    }
}
Example Response
{
    "meta": {
        "code": 200
    },
    "data": {
        "buyer": {
            "email": "first@last.com",
            "first_name": "First",
            "last_name": "Last",
            "name": "First Last",
            "sort_name": "first last",
            "phone": "555-555-5555"
        },
        "shipping_address": {
            "first_name": "First",
            "last_name": "Last",
            "name": "First Last",
            "company": "Celery",
            "line1": "123 Street",
            "line2": null,
            "city": "New York",
            "state": "ny",
            "zip": "10012",
            "country": "us",
            "phone": "555-555-5555"
        },
        ...
    }
}
Example Request

This example request updates the quantity of a line item to 2 units. Please be sure to include the entire line_items array, even if updating only one line item; otherwise, you may accidentally delete any others. At minimum, the required line item properties include id, product_id, quantity, and variant_id (if applicable).

WARNING: Updating line items will fetch the latest product details and may cause order prices (subtotal, taxes, shipping, total, balance) to change.

$ curl -X PUT -H Content-Type:application/json -H Authorization:{ACCESS_TOKEN} \
https://api.trycelery.com/v2/orders/530ec58358b6ee0000f5d440 \
-d'
{
    "line_items":
    [
        {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "product_id": "530e40d428ee4100002bfa78",
            "quantity": 2
        }
    ]
}
Example Response
{
    "meta": {
        "code": 200
    },
    "data": {
        ...,
        "line_items": [
            {
                "id": "550e8400-e29b-41d4-a716-446655440000",
                "product_id": "530e40d428ee4100002bfa78",
                "quantity": 2,
                "price": 1000,
                "weight": 0,
                "enable_taxes": true,
                "product_name": "Koala Bears",
                "variant_name": null,
                "variant_id": null,
                "celery_sku": "530e40d428ee4100002bfa78",
                "sku": "KOALA-1"
            }
        ],
        ...
    }
}

Cancel an Order

This will cancel the order. This endpoint will trigger email notifications to the buyer (if enabled).

POST /v2/orders/{id}/order_cancel
Arguments
Attributes Type Description
id string Required. Order unique identifier.
Example Request
$ curl -X POST -H Content-Type:application/json -H Authorization:{ACCESS_TOKEN} \
https://api.trycelery.com/v2/orders/530ec58358b6ee0000f5d440/order_cancel
Example Response
{
    "meta": {
        "code": 200
    },
    "data": {
        "order_status": "cancelled",
        "history": [
            {
                "type": "order.created",
                "created": 1393476995707,
                "created_date": "2014-02-27T04:56:35.707Z",
                "body": "Your order was created."
            },
            {
                "type": "order.cancelled",
                "created": 1401993491000,
                "created_date": "2014-06-05T06:38:00.000Z",
                "body": "Your order was cancelled."
            }
        ],
        ...
    }
}

Charge an Order

This will charge payment for the order. This endpoint will trigger email notifications to the buyer (if enabled).

POST /v2/orders/{id}/payment_charge
Arguments
Attributes Type Description
id string Required. Order unique identifier.
Example Request
$ curl -X POST -H Content-Type:application/json -H Authorization:{ACCESS_TOKEN} \
https://api.trycelery.com/v2/orders/53c389b7eba65a000061e12f/payment_charge
Example Response
{
    "meta": {
        "code": 200
    },
    "data": {
        "payment_status": "paid",
        "payments": [
            {
                "id": "9969f10f-6c29-4d36-ba84-c60abd4bd7ed",
                "charge_id": "ch_4OrpNFZKd4NOBz",
                "balance_transaction": "txn_4Orp4IPXvI0QCc",
                "pay_key": null,
                "preapproval_key": null,
                "capture_id": null,
                "transaction_id": null,
                "currency": "usd",
                "amount": 2075,
                "amount_refunded": 0,
                "fee": 132,
                "paid": true,
                "captured": true,
                "created": 1405323722000,
                "created_date": "2014-07-14T07:42:02.000Z",
                "refunded": null,
                "refunded_date": null,
                "card": {
                    "name": "",
                    "last4": "4242",
                    "exp_month": null,
                    "exp_year": null,
                    "type": "visa",
                    "country": "us"
                }
            }
        ],
        "history": [
            {
                "type": "order.created",
                "created": 1393476995707,
                "created_date": "2014-02-27T04:56:35.707Z",
                "body": "Your order was created."
            },
            {
                "type": "order.charge.succeeded",
                "created": 1401993491000,
                "created_date": "2014-06-05T06:38:00.000Z",
                "body": "Your order was charged."
            }
        ],
        "balance": 0,
        "paid": 2075,
        ...
    }
}

Refund an Order

This will refund payment for the order. This endpoint will trigger email notifications to the buyer (if enabled).

POST /v2/orders/{id}/payment_refund
Arguments
Attributes Type Description
id string Required. Order unique identifier.
Example Request
$ curl -X POST -H Content-Type:application/json -H Authorization:{ACCESS_TOKEN} \
https://api.trycelery.com/v2/orders/53c389b7eba65a000061e12f/payment_refund
Example Response
{
    "meta": {
        "code": 200
    },
    "data": {
        "payment_status": "refunded",
        "payments": [
            {
                "id": "9969f10f-6c29-4d36-ba84-c60abd4bd7ed",
                "charge_id": "ch_4OrpNFZKd4NOBz",
                "balance_transaction": "txn_4Orp4IPXvI0QCc",
                "pay_key": null,
                "preapproval_key": null,
                "capture_id": null,
                "transaction_id": null,
                "currency": "usd",
                "amount": 2075,
                "amount_refunded": 2075,
                "fee": 132,
                "paid": true,
                "captured": true,
                "created": 1405323722000,
                "created_date": "2014-07-14T07:42:02.000Z",
                "refunded": 1405377769000,
                "refunded_date": "2014-07-14T22:42:49.000Z",
                "card": {
                    "name": "",
                    "last4": "4242",
                    "exp_month": null,
                    "exp_year": null,
                    "type": "visa",
                    "country": "us"
                }
            }
        ],
        "history": [
            {
                "type": "order.created",
                "created": 1393476995707,
                "created_date": "2014-02-27T04:56:35.707Z",
                "body": "Your order was created."
            },
            {
                "type": "order.charge.succeeded",
                "created": 1401993491000,
                "created_date": "2014-06-05T06:38:00.000Z",
                "body": "Your order was charged."
            },
            {
                "type": "order.refund.succeeded",
                "created": 1401993491000,
                "created_date": "2014-06-05T06:38:00.000Z",
                "body": "Your order was refunded."
            }

        ],
        "balance": 0,
        "paid": 2075,
        "refunded": 2075,
        ...
    }
}

Fulfill an Order

This convenience endpoint will mark the fulfillment_status as fulfilled and allow you to optionally add courier and number. This endpoint will trigger email notifications to the buyer (if enabled).

POST /v2/orders/{id}/fulfillment_succeed
Arguments
Attributes Type Description
id string Required. Order unique identifier.
courier string Courier that will fulfill order. Possible values: ups, usps, fedex, dhl, other.
number string Tracking number.
serial_numbers [string] Serial numbers associated with the order.
Example Request
$ curl -X POST -H Content-Type:application/json -H Authorization:{ACCESS_TOKEN} \
https://api.trycelery.com/v2/orders/530ec58358b6ee0000f5d440/fulfillment_succeed \
-d'
{
    "courier" : "ups",
    "number" : "1zasdfajkfsdljasdf",
    "serial_numbers": [
        "abc123"
    ]
}
Example Response
{
    "meta": {
        "code": 200
    },
    "data": {
        ...,
        "fulfillment_status": "fulfilled",
        "fulfillment": {
            "created": 1401993491000,
            "created_date": "2014-06-05T06:38:00.000Z",
            "courier": "ups",
            "number": "1zasdfajkfsdljasdf",
            "serial_numbers": [
                "abc123"
            ]
        },
        "history": [
            {
                "type": "order.created",
                "created": 1393476995707,
                "created_date": "2014-02-27T04:56:35.707Z",
                "body": "Your order was created."
            },
            {
                "type": "order.fulfillment.succeeded",
                "created": 1401993491000,
                "created_date": "2014-06-05T06:38:00.000Z",
                "body": "Your order was fulfilled."
            }
        ],
        ...
    }
}

Products Resource

Attributes Type Description
_id value Product unique identifier.
slug string Seller-defined identifier for hosted shop page.
name string Product name.
description string Description of Product and supports HTML markup.
sku integer Base product sku.
price integer Base product price.
weight float Default value is 0.
published boolean Defines whether a product is shown.
created integer Product created date. Unix timestamp in milliseconds.
updated integer Product updated date. Unix timestamp in milliseconds.
created_date string Product created date. ISO 8601 timestamp.
updated_date string Product updated date. ISO 8601 timestamp.
Flags object
flags.enable_taxes boolean Whether to collect tax.
flags.enable_options boolean Whether product has variants.
Images object
images[].url string Product image URL.
Options objects
options[].id string Option id.
options[].name string Option group name (e.g., size)
options[].values object Option group values (e.g., small, medium, large)
Variants object
variants[].id string Variant id. Used to checkout products with variants.
variants[].name string Variant name.
variants[].sku string Variant sku.
variants[].price integer Variant price.
variants[].weight integer Variant weight.
variants[].options object Variant settings.

Retrieve a list of products

GET /v2/products
Arguments
Attributes Type Description
sort string Sort by. Default is created.
order string Order by. Default is desc. Possible values: desc, asc.
offset string Default is 0.
page integer Current page number.
limit string A limit on the number of objects to be returned. Default is 100.
Example Request
$ curl -X GET -H Content-Type:application/json -H Authorization:{ACCESS_TOKEN} \
https://api.trycelery.com/v2/products
Example Response
{
    "meta": {
        "code": 200,
        "paging": {
            "total": 3,
            "count": 3,
            "limit": 100,
            "offset": 0,
            "page": 1,
            "pages": 1,
            "has_more": false
        }
    },
    "data": [
        {
            "_id": "546aab7b1657500600a781bc",
            "slug": "90ca88bd-3830-4ee0-b39f-e5f200d0a489",
            "name": "Koala 1",
            "description": "<p>Koala party</p>",
            "sku": null,
            "price": 1500,
            "deposit": 0,
            "weight": 0,
            "inventory": 0,
            "published": true,
            "flags": {
                "enable_taxes": true,
                "enable_options": false,
                "enable_inventory": false
            },
            "images": [],
            "options": [],
            "variants": [],
            "user_id": "54629b565f388707003de6ea",
            "version": "v2",
            "created": 1416276859872,
            "updated": 1416276859970,
            "created_date": "2014-11-18T02:14:19.872Z",
            "updated_date": "2014-11-18T02:14:19.970Z",
            "locked": false,
            "metadata": {}
        },
        {
            "_id": "546a9d731657500600a781ba",
            "slug": "12b1f0a1-b18c-407a-9f9c-470f262f1853",
            "name": "Koala 2",
            "description": null,
            "sku": null,
            "price": 2000,
            "deposit": 0,
            "weight": 0,
            "inventory": 0,
            "published": true,
            "flags": {
                "enable_taxes": true,
                "enable_options": false,
                "enable_inventory": false
            },
            "images": [],
            "options": [],
            "variants": [],
            "user_id": "54629b565f388707003de6ea",
            "version": "v2",
            "created": 1416273267130,
            "updated": 1416273287831,
            "created_date": "2014-11-18T01:14:27.130Z",
            "updated_date": "2014-11-18T01:14:47.831Z",
            "locked": false,
            "metadata": {}
        },
        {
            "_id": "546540f2793b4c050015d96c",
            "slug": "7dc66c4a-99ca-48b2-b584-23de515272c0",
            "name": "Koala 3",
            "description": null,
            "sku": null,
            "price": 2500,
            "deposit": 0,
            "weight": 0,
            "inventory": 0,
            "published": true,
            "flags": {
                "enable_taxes": true,
                "enable_options": false,
                "enable_inventory": false
            },
            "images": [],
            "options": [],
            "variants": [],
            "user_id": "54629b565f388707003de6ea",
            "version": "v2",
            "created": 1415921906675,
            "updated": 1415922135705,
            "created_date": "2014-11-13T23:38:26.675Z",
            "updated_date": "2014-11-13T23:42:15.705Z",
            "locked": false,
            "metadata": {}
        }
    ]
}

Retrieve a Product

GET /v2/products/{id}
Arguments
Attributes Type Description
id string Required. Product unique identifier.
Example Request
$ curl -X GET -H Content-Type:application/json -H Authorization:{ACCESS_TOKEN} \
https://api.trycelery.com/v2/products/546540f2793b4c050015d96c
Example Response
{
    "meta": {
        "code": 200
    },
    "data": {
        "slug": "7dc66c4a-99ca-48b2-b584-23de515272c0",
        "name": "Koala Bears",
        "description": "<p>Cute but dangerous.</p>",
        "sku": null,
        "price": 1000,
        "deposit": 0,
        "weight": 0,
        "inventory": 0,
        "published": true,
        "flags": {
            "enable_taxes": true,
            "enable_options": false,
            "enable_inventory": false
        },
        "images": [],
        "options": [],
        "variants": [],
        "_id": "546540f2793b4c050015d96c",
        "user_id": "54629b565f388707003de6ea",
        "version": "v2",
        "created": 1415921906675,
        "updated": 1415922135705,
        "created_date": "2014-11-13T23:38:26.675Z",
        "updated_date": "2014-11-13T23:42:15.705Z",
        "locked": false,
        "metadata": {}
    }
}

Collections Resource

Attributes Type Description
_id string Required. Collections unique identifier.
slug string Seller-defined identifier for hosted shop page.
name string Collection name.
published boolean Defines whether collection is shown.
product_ids [objects] List of product ids in collection.
user_id string Seller unique identifier.
created integer Collection created date. Unix timestamp in milliseconds.
updated integer Collection updated date. Unix timestamp in milliseconds.
created_date string Collection created date. ISO 8601 timestamp.
updated_date string Collection updated date. ISO 8601 timestamp.
products [objects] List of products in collection.

Retrieve a list of Collections

GET /v2/collections/
Arguments
Attributes Type Description
sort string Sort by. Default is created.
order string Order by. Default is desc. Possible values: desc, asc.
offset string Default is 0.
page integer Current page number.
limit string A limit on the number of objects to be returned. Default is 100.
Example Request
$ curl -X GET -H Content-Type:application/json -H Authorization:{ACCESS_TOKEN} \
https://api.trycelery.com/v2/collections
Example Response
{
    "meta": {
        "code": 200,
        "paging": {
            "total": 1,
            "count": 1,
            "limit": 100,
            "offset": 0,
            "page": 1,
            "pages": 1,
            "has_more": false
        }
    },
    "data": {
        "slug": "53171e1a-a272-4a73-9f91-214159672197",
        "name": "Christmas Koala Collection",
        "published": true,
        "product_ids": [
            "546540f2793b4c050015d96c",
            "54653d6e793b4c050015d96a",
            "54653d42793b4c050015d969"
        ],
        "_id": "54736eb0b588d10400fbe7cc",
        "user_id": "54629b565f388707003de6ea",
        "version": "v2",
        "created": 1416851120197,
        "updated": 1416851141330,
        "created_date": "2014-11-24T17:45:20.197Z",
        "updated_date": "2014-11-24T17:45:41.330Z",
        "locked": false,
        "metadata": {},
        "products": [
            {
                "_id": "546540f2793b4c050015d96c",
                "slug": "7dc66c4a-99ca-48b2-b584-23de515272c0",
                "name": "Koala Two-Pack",
                "description": "<p>A mommy koala with baby koala packed inside.</p>",
                "sku": null,
                "price": 1000,
                "deposit": 0,
                "weight": 0,
                "inventory": 0,
                "published": true,
                "flags": {
                    "enable_taxes": true,
                    "enable_options": false,
                    "enable_inventory": false
                },
                "images": [],
                "options": [],
                "variants": [],
                "user_id": "54629b565f388707003de6ea",
                "version": "v2",
                "created": 1415921906675,
                "updated": 1415922135705,
                "created_date": "2014-11-13T23:38:26.675Z",
                "updated_date": "2014-11-13T23:42:15.705Z",
                "locked": false,
                "metadata": {}
            },
            ...
        ]
    }
}

Retrieve a Collection

GET /v2/collections/{id}
Example Request
$ curl -X GET -H Content-Type:application/json -H Authorization:{ACCESS_TOKEN} \
https://api.trycelery.com/v2/collections/{id}
Arguments
Attributes Type Description
id string Required Collection unique identifier.
Example Response
{
    "meta": {
        "code": 200
    },
    "data": {
        "slug": "53171e1a-a272-4a73-9f91-214159672197",
        "name": "Christmas Koala Collection",
        "published": true,
        "product_ids": [
            "546540f2793b4c050015d96c",
            "54653d6e793b4c050015d96a",
            "54653d42793b4c050015d969"
        ],
        "_id": "54736eb0b588d10400fbe7cc",
        "user_id": "54629b565f388707003de6ea",
        "version": "v2",
        "created": 1416851120197,
        "updated": 1416851141330,
        "created_date": "2014-11-24T17:45:20.197Z",
        "updated_date": "2014-11-24T17:45:41.330Z",
        "locked": false,
        "metadata": {},
        "products": [
            {
                ...
            },
        ]
    }
}

Coupons Resource

Attributes Type Description
_id string Coupon unique identifier.
user_id string Seller unique identifier.
type string Possible values: flat, percent, free_shipping.
code string Coupon code (must be unique).
filter string Possible values: order, product.
apply string Possible values: once, every_item.
product_id string Product id for product-specific coupons.
enabled boolean Whether coupon is valid.
amount integer Coupon amount. $5 should be 500 (prices in cents). 10% should be 10.
times_used integer Number of times coupon was redeemed.
begins integer Coupon begin date. Unix timestamp in milliseconds.
begins_date string Coupon begin date. ISO 8601 timestamp.
expires integer Coupon expiration date. Unix timestamp in milliseconds.
expires_date string Coupon expiration date. ISO 8601 timestamp.
used_emails [string] List of buyer email addresses who have redeemed coupon.
created integer Unix timestamp in milliseconds.
created_date string ISO 8601 timestamp.
updated integer Unix timestamp in milliseconds.
updated_date string ISO 8601 timestamp.

Retrieve a List of Coupons

GET /v2/coupons
Arguments
Attributes Type Description
sort string Sort by. Default is created.
order string Order by. Default is desc. Possible values: desc, asc.
offset string Default is 0.
page integer Current page number.
limit string A limit on the number of objects to be returned. Default is 100.
Example Request
$ curl -X GET -H Content-Type:application/json -H Authorization:{ACCESS_TOKEN} \
https://api.trycelery.com/v2/coupons
Example Response
{
    "meta": {
        "code": 200,
        "paging": {
            "total": 3,
            "count": 3,
            "limit": 100,
            "offset": 0,
            "page": 1,
            "pages": 1,
            "has_more": false
        }
    },
    "data": [
        {
            "_id": "5488e56ffe3e2a0500b82557",
            "type": "free_shipping",
            "code": "93000fdb71fc",
            "filter": "order",
            "apply": "once",
            "product_id": null,
            "enabled": true,
            "amount": 0,
            "quantity": null,
            "times_used": 0,
            "order_minimum": 0,
            "begins": 1418198400000,
            "begins_date": "2014-12-11T00:29:35.785Z",
            "expires": null,
            "expires_date": null,
            "used_emails": [],
            "user_id": "54629b565f388707003de6ea",
            "version": "v2",
            "created": 1418257775785,
            "updated": 1418257775785,
            "created_date": "2014-12-11T00:29:35.785Z",
            "updated_date": "2014-12-11T00:29:35.785Z",
            "locked": false,
            "metadata": {}
        },
        {
            "_id": "5488e5689b43260400cb3d1a",
            "type": "percent",
            "code": "566e8816d360",
            "filter": "order",
            "apply": "once",
            "product_id": null,
            "enabled": true,
            "amount": 20,
            "quantity": null,
            "times_used": 0,
            "order_minimum": 0,
            "begins": 1418198400000,
            "begins_date": "2014-12-11T00:29:28.108Z",
            "expires": null,
            "expires_date": null,
            "used_emails": [],
            "user_id": "54629b565f388707003de6ea",
            "version": "v2",
            "created": 1418257768108,
            "updated": 1418257768108,
            "created_date": "2014-12-11T00:29:28.108Z",
            "updated_date": "2014-12-11T00:29:28.108Z",
            "locked": false,
            "metadata": {}
        },
        {
            "_id": "5488e559fe3e2a0500b82556",
            "type": "flat",
            "code": "94cf61c4d205",
            "filter": "order",
            "apply": "once",
            "product_id": null,
            "enabled": true,
            "amount": 2000,
            "quantity": null,
            "times_used": 0,
            "order_minimum": 0,
            "begins": 1418198400000,
            "begins_date": "2014-12-11T00:29:13.319Z",
            "expires": null,
            "expires_date": null,
            "used_emails": [],
            "user_id": "54629b565f388707003de6ea",
            "version": "v2",
            "created": 1418257753319,
            "updated": 1418257753319,
            "created_date": "2014-12-11T00:29:13.319Z",
            "updated_date": "2014-12-11T00:29:13.319Z",
            "locked": false,
            "metadata": {}
        }
    ]
}

Retrieve a Coupon

GET /v2/coupons/{id}
Example Request
$ curl -X GET -H Content-Type:application/json -H Authorization:{ACCESS_TOKEN} \
https://api.trycelery.com/v2/coupons/{id}
Arguments
Attributes Type Description
id string Required Coupon unique identifier.
Example Response
{
    "meta": {
        "code": 200
    },
    "data": {
        "type": "free_shipping",
        "code": "93000fdb71fc",
        "filter": "order",
        "apply": "once",
        "product_id": null,
        "enabled": true,
        "amount": 0,
        "quantity": null,
        "times_used": 0,
        "order_minimum": 0,
        "begins": 1418198400000,
        "begins_date": "2014-12-11T00:29:35.785Z",
        "expires": null,
        "expires_date": null,
        "used_emails": [],
        "_id": "5488e56ffe3e2a0500b82557",
        "user_id": "54629b565f388707003de6ea",
        "version": "v2",
        "created": 1418257775785,
        "updated": 1418257775785,
        "created_date": "2014-12-11T00:29:35.785Z",
        "updated_date": "2014-12-11T00:29:35.785Z",
        "locked": false,
        "metadata": {}
    }
}

Validate coupon code

This public endpoint returns whether a coupon code is valid. If the coupon is not valid, then the endpoint will respond with an error. This endpoint does not require authentication.

POST /v2/coupons/validate
Arguments
Attributes Type Description
user_id string Required. Seller unique identifier.
code string Required. Coupon code to validate.
line_items [string] List of product ids to validate against product-specific coupons.
Example Request
$ curl -X POST -H Content-Type:application/json \
https://api.trycelery.com/v2/coupons/validate
Example Response
{
    "meta": {
        "code": 200
    },
    "data": {
        "type": "flat",
        "code": "036dabee2bd3",
        "filter": "order",
        "apply": "once",
        "product_id": null,
        "enabled": true,
        "amount": 10000,
        "quantity": 0,
        "times_used": 1,
        "order_minimum": 0,
        "begins": 1412146800000,
        "begins_date": "2014-08-08T21:52:37.055Z",
        "expires": 1413010800000,
        "expires_date": null,
        "used_emails": [],
        "_id": "53e546a5fc08e40400631da9",
        "user_id": "5330bc8c5ade8207002df9f6",
        "version": "v2",
        "created": 1407534757055,
        "updated": 1407534757055,
        "created_date": "2014-08-08T21:52:37.055Z",
        "updated_date": "2014-08-08T21:52:37.055Z",
        "locked": false,
        "metadata": {}
    }
}
Error Example Response
{
    "meta": {
        "code": 400,
        "error": {
            "message": "Coupon code is expired.",
            "code": 400
        }
    },
    "data": "Coupon code is expired."
}

Users Resource

Retrieve tax rate

This public endpoint returns the sales tax rate based on the seller's tax rules and the shipping address provided. This endpoint does not require authentication.

GET /v2/users/{id}/tax_rates
Arguments
Attributes Type Description
id string Required. Seller unique identifier.
shipping_country string Required. 2-letter ISO country code (lowercase).
shipping_state string 2-letter ISO state code if United States or Canada (lowercase).
shipping_zip string 5-digit zip code if United States. Supports optional 4 digits.
Example Request
$ curl -X GET -H Content-Type:application/json \
https://api.trycelery.com/v2/users/530ec58358b6ee0000f5d440/tax_rates?shipping_country=us&shipping_state=ca&shipping_zip=94105
Example Response
{
    "meta": {
        "code": 200
    },
    "data": {
        "base": 0.0875
    }
}

Webhooks

Events are our way of letting you know about something interesting has happened with your order. The Celery API can send events directly to your server using webhooks. Please contact Celery if you would like to implement webhooks.

To acknowledge that you received the webhook without any problem, your server should return a 200 HTTP status code. Any response code outside the 2xx and 3xx range will indicate to Celery that you did not receive the webhook. When a webhook is not received for whatever reason, Celery will continue trying to send the webhook for up to 3 times.

This is a list of all the types of events we currently send. We may add more at any time, so you shouldn't rely on only these types existing in your code.

  • order.created
  • order.completed
  • order.cancelled
  • order.line_items.updated
  • order.shipping_address.updated
  • order.adjustments.updated
  • order.payment_source.updated
  • order.charge.succeeded
  • order.charge.failed
  • order.refund.succeeded
  • order.refund.failed
  • order.fulfillment.succeeded
  • order.fulfillment.processing
  • order.fulfillment.failed
Example Response
{
    "type": "order.created",
    "data": {
        "_id": "530ec58358b6ee0000f5d440",
        "order_status": "open",
        "payment_status": "unpaid",
        "fulfillment_status": "unfulfilled",
        ...
    }
}


# Anchors in Markdown

To create an anchor to a heading in github flavored markdown.
Add __-__ characters between each word in the heading and wrap the value in  parens ```(#some-markdown-heading)``` so your link should look like so:

```[create an anchor](#anchors-in-markdown)```
* [Category1](#cat1)
* [Category2](#cat2)
* [Category3](#cat3)
* [Category4](#cat4)

# Category1

Hello

Hello

Hello2

# Category2

dfkjsdlf
dsfdsf
sdf


# Category4

dflsjd

# Category4
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment