└── README.md
/README.md:
--------------------------------------------------------------------------------
1 | # Celery API
2 |
3 | The Celery API is an ecommerce logic and storage engine designed to be an essential tool for any developer.
4 |
5 | The API is currently in beta. Please contact [help@trycelery.com](mailto:help@trycelery.com) if you intend to deploy our API in production code.
6 |
7 | 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.
8 |
9 | To view `v1` API documentation, go to [https://legacy.trycelery.com/developer](https://legacy.trycelery.com/developer).
10 |
11 | ## Menu
12 |
13 | * [Getting Started](#getting-started)
14 | * [API Basics](#api-basics)
15 | * [Authentication](#authentication)
16 | * [Errors](#errors)
17 | * [Pagination](#pagination)
18 | * [Rate Limits] (#rate-limits)
19 | * [Orders Resource](#orders-resource)
20 | * [Checkout with Credit or Debit Card](#checkout-with-credit-or-debit-card)
21 | * [Checkout with PayPal](#checkout-with-paypal)
22 | * [Retrieve an Order](#retrieve-an-order)
23 | * [Retrieve a List of Orders](#retrieve-a-list-of-orders)
24 | * [Count Orders](#count-orders)
25 | * [Update an Order](#update-an-order)
26 | * [Cancel an Order](#cancel-an-order)
27 | * [Charge an Order](#charge-an-order)
28 | * [Refund an Order](#refund-an-order)
29 | * [Fulfill an Order](#fulfill-an-order)
30 | * [Products Resource](#products-resource)
31 | * [Retrieve a List of Products](#retrieve-a-list-of-products)
32 | * [Retrieve a Product](#retrieve-a-product)
33 | * [Collections Resource](#collections-resource)
34 | * [Retrieve a List of Collections](#retrieve-a-list-of-collections)
35 | * [Retrieve a Collection](#retrieve-a-collection)
36 | * [Coupons Resource](#coupons-resource)
37 | * [Create a Coupon](#create-a-coupon)
38 | * [Retrieve a List of Coupons](#retrieve-a-list-of-coupons)
39 | * [Retrieve a Coupon](#retrieve-a-coupon)
40 | * [Validate Coupon Code](#validate-coupon-code)
41 | * [Users Resource](#users-resource)
42 | * [Retrieve Tax Rate](#retrieve-tax-rate)
43 | * [Webhooks](#webhooks)
44 |
45 | ## Getting Started
46 |
47 | The base endpoint URL is `https://api.trycelery.com`. Celery is currently on version `v2`, so a request to retrieve all orders would resemble:
48 |
49 | ```
50 | GET https://api.trycelery.com/v2/orders
51 | ```
52 |
53 | To access the sandbox environment, create a new account at [https://dashboard-sandbox.trycelery.com](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.
54 |
55 | ### API Basics
56 |
57 | * **All requests must be made over HTTPS.**
58 | * **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`.
59 | * **All prices are in cents.** Prices are represented as integers in cents. Thus, an API response of `100` would represent `1.00`.
60 |
61 | ### Authentication
62 |
63 | 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:
64 |
65 | Authorization: ACCESS_TOKEN
66 |
67 | ### Errors
68 |
69 | 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.
70 |
71 | Our error responses have the format:
72 | ```json
73 | {
74 | "meta": {
75 | "code": 409,
76 | "error": {
77 | "code": 409,
78 | "message": "User with email already exists."
79 | }
80 | },
81 | "data": "User with email already exists."
82 | }
83 | ```
84 |
85 | ### Pagination
86 |
87 | Attributes | Type | Description
88 | -----------|------|------------
89 | total | integer | Total number of records in list.
90 | count | integer | Number of records on current page.
91 | limit | integer | A limit on the number of records to be returned. Default is `100`.
92 | offset | integer | Starting record to be returned. Default is `0`.
93 | page | integer | Current page number.
94 | pages | integer | Total number of pages.
95 | has_more | boolean | Whether current page is last page.
96 |
97 | 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:
98 |
99 | ```json
100 | {
101 | "meta": {
102 | "code": 200,
103 | "paging": {
104 | "total": 45,
105 | "count": 10,
106 | "limit": 10,
107 | "offset": 5,
108 | "page": 2,
109 | "pages": 5,
110 | "has_more": true
111 | }
112 | },
113 | "data": [
114 | {
115 | ...
116 | }
117 | ]
118 | }
119 | ```
120 |
121 | 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.
122 |
123 | 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`.
124 |
125 | ### Rate Limits
126 |
127 | There is a default rate limit of 120 requests per minute. If for any reason this is not enough, please contact us.
128 |
129 | ## Orders Resource
130 |
131 | Attributes | Type | Description
132 | -----------|------|------------
133 | _id | string | Order unique identifier.
134 | user_id | string | Seller unique identifier.
135 | order_status | string | Possible values: `open`, `completed`, `cancelled`.
136 | payment_status | string | Possible values: `unpaid`, `paid`, `refunded`, `failed`.
137 | fulfillment_status | string | Possible values: `unfulfilled`, `fulfilled`, `processing`, `failed`.
138 | currency | string | 3-letter ISO currency code (lowercase). Possible values: `usd`, `cad`, `gbp`, `eur`, `aud`.
139 | notes | string | Seller order notes.
140 | type | string | Possible values: `card`, `paypal_adaptive`, `paypal_adaptive_chained`, `affirm`.
141 | shipping_method | string | Shipping method for fulfillment partners.
142 | number | string | Human-readable order number.
143 | linetotal | integer | Sum of the line item amounts. Amount in cents.
144 | discount | integer | Discount amount applied to the order. Amount in cents.
145 | subtotal | integer | Sum of line totals less discount. Amount in cents.
146 | shipping | integer | Shipping cost applied. Amount in cents.
147 | taxes | integer | Sales tax applied. Amount in cents.
148 | adjustment | integer | Price adjustments applied. Amount in cents.
149 | total | integer | Total = subtotal + shipping + taxes + adjustments. Amount in cents.
150 | balance | integer | Amount owed to the seller. Amount in cents.
151 | paid | integer | Gross amount paid to the seller. Amount in cents.
152 | refunded | integer | Amount refunded by the seller. Amount in cents.
153 | fee | integer | Celery application fee. Amount in cents.
154 | created | integer | Unix timestamp in milliseconds.
155 | created_date | string | ISO 8601 timestamp.
156 | updated | integer | Unix timestamp in milliseconds.
157 | updated_date | string | ISO 8601 timestamp.
158 | **Buyer**|object|
159 | buyer.email | string | Buyer's email address.
160 | buyer.first_name | string | Buyer's first name.
161 | buyer.last_name | string | Buyer's last name.
162 | buyer.name | string | Buyer's combined first and last name.
163 | buyer.company | string | Buyer's company.
164 | buyer.phone | string | Buyer's phone number.
165 | buyer.notes | string | Buyer notes to the seller.
166 | **Shipping Address** |object|
167 | shipping_address.first_name | string | Shipping address first name.
168 | shipping_address.last_name | string | Shipping address last name.
169 | shipping_address.name | string | Shipping address first and last name.
170 | shipping_address.company | string | Shipping address company name.
171 | shipping_address.line1 | string | Shipping address street address.
172 | shipping_address.line2 | string | Shipping address building, apartment, unit, etc.
173 | shipping_address.city | string | Shipping address city.
174 | shipping_address.state | string | Shipping address state, province, or region.
175 | shipping_address.zip | string | Shipping address ZIP or postal code.
176 | shipping_address.country | string | Shipping address 2-letter ISO country code (lowercase).
177 | shipping_address.phone | string | Shipping address phone number.
178 | **Fulfillment**|object|
179 | fulfillment.created | integer | Date marked fulfilled (Unix timestamp in milliseconds).
180 | fulfillment.created_date | string | Date marked fulfilled (ISO 8601 timestamp).
181 | fulfillment.courier | string | Courier used. Possible values: `ups`, `usps`, `fedex`, `dhl`, `other`.
182 | fulfillment.number | string | Tracking number.
183 | **Payment Source** | object |
184 | payment_source.card.name | string | Name on credit/debit card. Stripe only.
185 | payment_source.card.celery_token | string | Stripe only.
186 | payment_source.card.exp_month | integer | Expiration month of credit/debit card. Stripe only.
187 | payment_source.card.exp_year | integer | Expiration year of credit/debit card. Stripe only.
188 | payment_source.card.last4 | string | Last 4 digits of credit/debit card. Stripe only.
189 | payment_source.card.type | string | Credit/debit card type.
190 | payment_source.card.country | string | Country of credit/debit card. Stripe only.
191 | payment_source.paypal.email | string | Buyer's paypal email address. PayPal only.
192 | payment_source.paypal.preapproval_key | string | PayPal only.
193 | payment_source.paypal.pay_key | string | PayPal only.
194 | payment_source.paypal.redirect_url | string | PayPal only.
195 | payment_source.paypal.ipn | string | PayPal only.
196 | payment_source.paypal.ending | integer | Preapproval expiration date (Unix timestamp in milliseconds). PayPal only.
197 | payment_source.paypal.ending_date | string | Preapproval expiration date (ISO 8601 timestamp). PayPal only.
198 | payment_source.paypal.seller_email | string | Seller's PayPal email address. PayPal only.
199 | payment_source.affirm.checkout_token | string | Affirm only.
200 | payment_source.affirm.charge_id | string | Affirm only.
201 | payment_source.airbrite.customer_token | string | Airbrite orders only.
202 | payment_source.airbrite.card_token | string | Airbrite orders only.
203 | payment_source.airbrite.fingerprint | string | Airbrite orders only.
204 | payment_source.airbrite.name | string | Airbrite orders only.
205 | payment_source.airbrite.exp_month | integer | Airbrite orders only.
206 | payment_source.airbrite.exp_year | integer | Airbrite orders only.
207 | payment_source.airbrite.last4 | string | Airbrite orders only.
208 | payment_source.airbrite.country | string | Airbrite orders only.
209 | payment_source.airbrite.type | string | Airbrite orders only.
210 | **Client Details** | object |
211 | client_details.ip | string | string | Browser IP from Celery checkout.
212 | client_details.user_agent | string | Browser user agent from Celery checkout.
213 | client_details.accept_language | string | Browser language from Celery checkout.
214 | client_details.referer | string | Browser referer from Celery checkout.
215 | **Line Items** | [objects] |
216 | line_items[].id | string | Line item identifier (uuid).
217 | line_items[].product_id | string | Product id.
218 | line_items[].product_name | string | Product name.
219 | line_items[].variant_id | string | Variant id.
220 | line_items[].variant_name | string | Variant name.
221 | line_items[].sku | string | Seller defined sku.
222 | line_items[].celery_sku | string | Celery's internal sku.
223 | line_items[].price | integer | Line_item unit price.
224 | line_items[].quantity | integer | Number of units ordered.
225 | line_items[].weight | integer | Line item unit weight.
226 | line_items[].enable_taxes | boolean | Whether taxes apply to line item.
227 | **Payments** | [objects] |
228 | payments[].id | string | Payment identifier.
229 | payments[].gateway | string | Gateway identifier. Possible values: `stripe`, `affirm`, `paypal`.
230 | payments[].charge_id | string | Gateway identifier for the charge (Stripe and Affirm only).
231 | payments[].balance_transaction | string | Stripe only.
232 | payments[].pay_key | string | PayPal only.
233 | payments[].preapproval_key | string | PayPal only.
234 | payments[].capture_id | string | Affirm only.
235 | payments[].transaction_id | string | Affirm only.
236 | payments[].currency | string | Currency.
237 | payments[].amount | integer | Amount captured.
238 | payments[].amount_refunded | integer | Amount refunded.
239 | payments[].paid | boolean | Whether payment was paid.
240 | payments[].captured | boolean | Whether payment was captured.
241 | payments[].refunded | boolean | Whether payment was refunded.
242 | payments[].created | integer | Charge date. Unix timestamp in milliseconds.
243 | payments[].created_date | string | Charge date. ISO 8601 timestamp.
244 | payments[].card.name | string | Stripe only.
245 | payments[].card.last4 | string | Stripe only.
246 | payments[].card.exp_month | integer | Stripe only.
247 | payments[].card.exp_year | integer | Stripe only.
248 | payments[].card.type | string | Stripe only.
249 | payments[].card.country | string | Stripe only.
250 | **Adjustments** | [objects] |
251 | adjustments[].id | string | Adjustment identifier.
252 | adjustments[].type | string | Possible values: `flat`.
253 | adjustments[].reason | string | Reasoning for price adjustment.
254 | adjustments[].issuer | string | Authorizer of price adjustment.
255 | adjustments[].amount | number | Amount of price adjustment.
256 | discount_codes | [strings]| Array of discount codes used.
257 | **Discounts** | [objects] |
258 | discounts[].code | string | Discount code applied.
259 | discounts[].type: | string | Discount type. Possible values: `flat`, `percent`.
260 | discounts[].amount | integer | Discount amount (5% off means 500 and $10 off means 1000).
261 | discounts[].product_id | string | Product id that discount belongs to.
262 | discounts[].apply | string | Possible values: `once`, `every_time`.
263 | **History** | [objects] |
264 | history[].type | string | [See events](#webhooks).
265 | history[].body | string | Brief description of history type.
266 | history[].created | integer | Unix timestamp in milliseconds.
267 | history[].created_date | string | ISO 8601 timestamp.
268 |
269 | ### Checkout with Credit or Debit Card
270 |
271 | This is a public endpoint to create a new order with a credit or debit card. It does not require authentication.
272 |
273 | For cross-browser compatibility with older versions of Internet Explorer, we recommend using [jQuery-ajaxTransport-XDomainRequest](https://github.com/MoonScript/jQuery-ajaxTransport-XDomainRequest).
274 |
275 | To place an order with a credit/debit card in the sandbox environment, please use [Stripe test cards](https://stripe.com/docs/testing).
276 |
277 | ```
278 | POST /v2/orders/checkout
279 | ```
280 |
281 | ##### Arguments
282 |
283 | Attributes | Type | Description
284 | -----------|------|------------
285 | user_id | string | **Required**. Your user id.
286 | currency | string | 3-letter ISO currency code (lowercase). Possible values: `usd`, `cad`, `gbp`, `eur`, `aud`.
287 | **Buyer**|object|
288 | buyer.email | string | **Required**. Buyer's email address (used for Celery's email notifications).
289 | buyer.first_name | string | Buyer's first name.
290 | buyer.last_name | string | Buyer's last name.
291 | buyer.company | string | Buyer's company.
292 | buyer.phone | string | Buyer's phone number.
293 | buyer.notes | string | Buyer notes to the seller.
294 | **Shipping Address** |object|
295 | shipping_address.first_name | string | Shipping address first name.
296 | shipping_address.last_name | string | Shipping address last name.
297 | shipping_address.name | string | Shipping address full name.
298 | shipping_address.company | string | Shipping address company name.
299 | shipping_address.line1 | string | Shipping address street address.
300 | shipping_address.line2 | string | Shipping address building, apartment, unit, etc.
301 | shipping_address.city | string | Shipping address city.
302 | shipping_address.state | string | Shipping address state, province, or region. If country US or CA, use 2-letter ISO state code (lowercase).
303 | shipping_address.zip | string | Shipping address ZIP or postal code.
304 | shipping_address.country | string | Shipping address 2-letter ISO country code (lowercase).
305 | shipping_address.phone | string | Shipping address phone number.
306 | **Billing Address** |object|
307 | billing_address.first_name | string | Billing address first name.
308 | billing_address.last_name | string | Billing address last name.
309 | billing_address.line1 | string | Billing address street address.
310 | billing_address.line2 | string | Billing address building, apartment, unit, etc.
311 | billing_address.city | string | Billing address city.
312 | billing_address.state | string | Billing address state, province, or region. If country US or CA, use 2-letter ISO state code (lowercase).
313 | billing_address.zip | string | Billing address ZIP or postal code.
314 | billing_address.country | string | Billing address 2-letter ISO country code (lowercase).
315 | billing_address.phone | string | Billing address phone number.
316 | **Line Items** | [objects] |
317 | line_items[].product_id | string | **Required**. Product id.
318 | line_items[].variant_id | string | Variant id (required if product has variants).
319 | line_items[].quantity | integer | Number of units ordered.
320 | **Payment Source** | object |
321 | payment_source.card.name | string | Name on credit/debit card. Stripe only.
322 | payment_source.card.number | string | Credit/debit card number. Stripe only.
323 | payment_source.card.exp_month | integer | **Required**. Expiration month of credit/debit card. Stripe only.
324 | payment_source.card.exp_year | integer | **Required**. Expiration year of credit/debit card. Stripe only.
325 | payment_source.card.cvc | string | **Required**. Credit/debit card CVC. Stripe only.
326 | discount_codes | [strings] | List of coupon codes to be applied to order.
327 |
328 | ##### Example Request
329 | ```
330 | $ curl -X POST -H Content-Type:application/json -H \
331 | https://api.trycelery.com/v2/orders/checkout \
332 | -d'
333 | {
334 | "user_id": "514a114080feb60200000001",
335 | "buyer": {
336 | "email": "first@last.com",
337 | "first_name": "First",
338 | "last_name": "Last",
339 | "phone": "555-555-5555"
340 | },
341 | "shipping_address": {
342 | "first_name": "First",
343 | "last_name": "Last",
344 | "company": "Celery",
345 | "line1": "123 Street",
346 | "line2": null,
347 | "city": "New York",
348 | "state": "ny",
349 | "zip": "10012",
350 | "country": "us",
351 | "phone": "555-555-5555"
352 | },
353 | "billing_address": {
354 | "first_name": "First",
355 | "last_name": "Last",
356 | "line1": "123 Main Street",
357 | "line2": null,
358 | "city": "San Francisco",
359 | "state": "ca",
360 | "zip": "94105",
361 | "country": "us",
362 | "phone": "555-555-5555"
363 | },
364 | "line_items": [
365 | {
366 | "product_id": "531e0b012cf9766885f781b7",
367 | "variant_id": "",
368 | "quantity": 1
369 | }
370 | ],
371 | "payment_source": {
372 | "card": {
373 | "name": "First Last",
374 | "number": "4242 4242 4242 4242",
375 | "exp_month": 12,
376 | "exp_year": 2020,
377 | "cvc": "123"
378 | }
379 | },
380 | "discount_codes": [
381 | "10dollarsoff"
382 | ]
383 | }
384 | ```
385 |
386 | ##### Example Response
387 | ```json
388 | {
389 | "meta": {
390 | "code": 200
391 | },
392 | "data": {
393 | "_id": "544c220151feb60200000002",
394 | "user_id": "514a114080feb60200000001",
395 | "order_status": "open",
396 | "payment_status": "unpaid",
397 | "fulfillment_status": "unfulfilled",
398 | ...,
399 | "history": [
400 | {
401 | "type": "order.created",
402 | "created": 1393476995707,
403 | "created_date": "2014-02-27T04:56:35.707Z",
404 | "body": "Your order was created."
405 | }
406 | ],
407 | ...
408 | }
409 | }
410 | ```
411 |
412 | ### Checkout with PayPal
413 |
414 | This is a public endpoint to create a new order with PayPal. It does not require authentication. Celery uses [PayPal Adaptive Payments](https://developer.paypal.com/docs/classic/products/adaptive-payments/).
415 |
416 | For cross-browser compatibility with older versions of Internet Explorer, we recommend using [jQuery-ajaxTransport-XDomainRequest](https://github.com/MoonScript/jQuery-ajaxTransport-XDomainRequest).
417 |
418 | 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.
419 |
420 | ```
421 | POST /v2/orders/checkout/paypal
422 | ```
423 |
424 | ##### Arguments
425 |
426 | Attributes | Type | Description
427 | -----------|------|------------
428 | user_id | string | **Required**. Your user id.
429 | cancel_url | string | **Required.** URL that buyer will go to if they cancel order.
430 | return_url | string | **Required.** URL that buyer will go to after they complete PayPal payment flow.
431 | currency | string | 3-letter ISO currency code (lowercase). Possible values: `usd`, `cad`, `gbp`, `eur`, `aud`.
432 | **Buyer**|object|
433 | buyer.email | string | **Required**. Buyer's email address (used for Celery's email notifications).
434 | buyer.first_name | string | Buyer's first name.
435 | buyer.last_name | string | Buyer's last name.
436 | buyer.company | string | Buyer's company.
437 | buyer.phone | string | Buyer's phone number.
438 | buyer.notes | string | Buyer notes to the seller.
439 | **Shipping Address** |object|
440 | shipping_address.first_name | string | Shipping address first name.
441 | shipping_address.last_name | string | Shipping address last name.
442 | shipping_address.company | string | Shipping address company name.
443 | shipping_address.line1 | string | Shipping address street address.
444 | shipping_address.line2 | string | Shipping address building, apartment, unit, etc.
445 | shipping_address.city | string | Shipping address city.
446 | shipping_address.state | string | Shipping address state, province, or region. If country US or CA, use 2-letter ISO state code (lowercase).
447 | shipping_address.zip | string | Shipping address ZIP or postal code.
448 | shipping_address.country | string | Shipping address 2-letter ISO country code (lowercase).
449 | shipping_address.phone | string | Shipping address phone number.
450 | **Line Items** | [objects] |
451 | line_items[].product_id | string | **Required**. Product id.
452 | line_items[].variant_id | string | Variant id (required if product has variants).
453 | line_items[].quantity | integer | Number of units ordered.
454 | discount_codes | [strings] | List of coupon codes to be applied to order.
455 |
456 | ##### Example Request
457 | ```
458 | $ curl -X POST -H Content-Type:application/json -H \
459 | https://api.trycelery.com/v2/orders/checkout/paypal \
460 | -d'
461 | {
462 | "user_id": "514a114080feb60200000001",
463 | "cancel_url": "https://www.yourshop.com",
464 | "return_url": "https://www.yourshop.com/confirmation",
465 | "buyer": {
466 | "email": "first@last.com",
467 | "first_name": "First",
468 | "last_name": "Last",
469 | "phone": "555-555-5555"
470 | },
471 | "shipping_address": {
472 | "first_name": "First",
473 | "last_name": "Last",
474 | "company": "Celery",
475 | "line1": "123 Street",
476 | "line2": null,
477 | "city": "New York",
478 | "state": "ny",
479 | "zip": "10012",
480 | "country": "us",
481 | "phone": "555-555-5555"
482 | },
483 | "line_items": [
484 | {
485 | "product_id": "531e0b012cf9766885f781b7",
486 | "quantity": 1
487 | }
488 | ]
489 | }
490 | ```
491 |
492 | ##### Example Response
493 | ```json
494 | {
495 | "meta": {
496 | "code": 200
497 | },
498 | "data": {
499 | "_id": null,
500 | "user_id": "514a114080feb60200000001",
501 | "number": "101340827",
502 | "order_status": "open",
503 | "payment_status": "unpaid",
504 | "fulfillment_status": "unfulfilled",
505 | "type": "paypal_adaptive",
506 | "cancel_url": "https://www.yourshop.com/101340827",
507 | "return_url": "https://www.yourshop.com/confirmation/101340827",
508 | "payment_source": {
509 | "paypal": {
510 | "redirect_url": "https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_ap-preapproval&preapprovalkey=PA-3KC050249N5937812",
511 | "preapproval_key": "PA-3KC050249N5937812"
512 | }
513 | },
514 | ...
515 | }
516 | }
517 | ```
518 |
519 |
520 | ### Retrieve an Order
521 |
522 | ```
523 | GET /v2/orders/{id}
524 | ```
525 | ##### Arguments
526 |
527 | Attributes | Type | Description
528 | -----------|------|------------
529 | id | string | **Required**. Order unique identifier.
530 |
531 | ##### Example Request
532 | ```
533 | $ curl -X GET -H Content-Type:application/json -H Authorization:ACCESS_TOKEN \
534 | https://api.trycelery.com/v2/orders/530ec58358b6ee0000f5d440
535 | ```
536 |
537 | ##### Example Response
538 |
539 | ```json
540 | {
541 | "meta": {
542 | "code": 200
543 | },
544 | "data": {
545 | "locked": false,
546 | "order_status": "open",
547 | "payment_status": "paid",
548 | "fulfillment_status": "unfulfilled",
549 | "currency": "usd",
550 | "notes": null,
551 | "type": "card",
552 | "number": "101335478",
553 | "cancel_url": null,
554 | "return_url": null,
555 | "shipping_method": null,
556 | "deposit": 0,
557 | "discount": 0,
558 | "balance": 0,
559 | "subtotal": 1000,
560 | "total": 2075,
561 | "paid": 2075,
562 | "refunded": 0,
563 | "adjustment": 0,
564 | "shipping": 1000,
565 | "taxes": 75,
566 | "linetotal": 1000,
567 | "fee": 42,
568 | "seller": {
569 | "_id": "514a114080feb60200000001",
570 | "email": null,
571 | "name": null,
572 | "paypal_email": null
573 | },
574 | "buyer": {
575 | "sort_name": "brian nguyen",
576 | "email": "brian@trycelery.com",
577 | "first_name": "Brian",
578 | "last_name": "Nguyen",
579 | "name": "Brian Nguyen",
580 | "phone": null,
581 | "company": null,
582 | "notes": null
583 | },
584 | "shipping_address": {
585 | "email": "brian@trycelery.com",
586 | "first_name": "Brian",
587 | "last_name": "Nguyen",
588 | "name": "Brian Nguyen",
589 | "line1": "123 Main Street",
590 | "line2": "Unit 101",
591 | "city": "San Francisco",
592 | "state": "ca",
593 | "zip": "94105",
594 | "country": "us",
595 | "phone": null,
596 | "company": null
597 | },
598 | "billing_address": {
599 | "email": null,
600 | "first_name": null,
601 | "last_name": null,
602 | "name": null,
603 | "line1": null,
604 | "line2": null,
605 | "city": null,
606 | "state": null,
607 | "zip": null,
608 | "country": null,
609 | "phone": null
610 | },
611 | "fulfillment": {
612 | "courier": null,
613 | "number": null,
614 | "created": null,
615 | "created_date": null
616 | },
617 | "payment_source": {
618 | "card": {
619 | "name": null,
620 | "celery_token": "c31310e652f5a7d7254484668c52686d09cd665414c6d3cae04f92660c3d930cad55a378cfa2c76fcbf8dc0b129a4f0baac0e3794c4485510a36cfbef7461c45dfc1d52d6e03a28d03af86f7ec405577f0d1c7c7a0487ca780003f86b595bca0",
621 | "exp_month": 11,
622 | "exp_year": 20,
623 | "last4": "4242",
624 | "country": "us",
625 | "type": "visa"
626 | },
627 | "paypal": {
628 | "email": null,
629 | "preapproval_key": null,
630 | "pay_key": null,
631 | "redirect_url": null,
632 | "ipn": null,
633 | "ending": null,
634 | "ending_date": null
635 | },
636 | "affirm": {
637 | "checkout_token": null,
638 | "charge_id": null
639 | },
640 | "airbrite": {
641 | "customer_token": null,
642 | "card_token": null,
643 | "fingerprint": null,
644 | "name": null,
645 | "exp_month": 0,
646 | "exp_year": 0,
647 | "last4": null,
648 | "country": null,
649 | "type": null
650 | }
651 | },
652 | "discount_codes": [],
653 | "line_items": [
654 | {
655 | "id": "0fcfa92c-5214-d4bf-ac41-86f26fb9c9b9",
656 | "product_id": "531e0b012cf9766885f781b7",
657 | "product_name": "koala 10",
658 | "variant_id": null,
659 | "variant_name": null,
660 | "sku": "koala_10",
661 | "celery_sku": "531e0b012cf9766885f781b7",
662 | "price": 1000,
663 | "quantity": 1,
664 | "weight": 0.5,
665 | "enable_taxes": true
666 | }
667 | ],
668 | "adjustments": [],
669 | "discounts": [],
670 | "payments": [
671 | {
672 | "id": "9969f10f-6c29-4d36-ba84-c60abd4bd7ed",
673 | "charge_id": "ch_4OrpNFZKd4NOBz",
674 | "balance_transaction": "txn_4Orp4IPXvI0QCc",
675 | "pay_key": null,
676 | "preapproval_key": null,
677 | "capture_id": null,
678 | "transaction_id": null,
679 | "currency": "usd",
680 | "amount": 2075,
681 | "amount_refunded": 0,
682 | "fee": 132,
683 | "paid": true,
684 | "captured": true,
685 | "created": 1405323722000,
686 | "created_date": "2014-07-14T07:42:02.000Z",
687 | "refunded": null,
688 | "refunded_date": null,
689 | "card": {
690 | "name": "",
691 | "last4": "4242",
692 | "exp_month": null,
693 | "exp_year": null,
694 | "type": "visa",
695 | "country": "us"
696 | }
697 | }
698 | ],
699 | "history": [
700 | {
701 | "type": "order.created",
702 | "body": "Order was created.",
703 | "created": 1405323703464,
704 | "created_date": "2014-07-14T07:41:43.464Z"
705 | },
706 | {
707 | "type": "order.charge.succeeded",
708 | "body": "Order was charged.",
709 | "created": 1405323723032,
710 | "created_date": "2014-07-14T07:42:03.032Z"
711 | }
712 | ],
713 | "_id": "53c389b7eba65a000061e12f",
714 | "user_id": "514a114080feb60200000001",
715 | "version": "v2",
716 | "created": 1405323701278,
717 | "updated": 1405323722893,
718 | "created_date": "2014-07-14T07:41:41.278Z",
719 | "updated_date": "2014-07-14T07:42:02.893Z",
720 | "metadata": {}
721 | }
722 | }
723 | ```
724 |
725 | ### Retrieve a List of Orders
726 |
727 | ```
728 | GET /v2/orders
729 | ```
730 | ##### Arguments
731 |
732 | Attributes | Type | Description
733 | -----------|------|------------
734 | sort | string | Sort by. Default is `created`.
735 | order | string | Order by. Default is `desc`. Possible values: `desc`, `asc`.
736 | offset | string | Default is `0`.
737 | page | integer | Current page number.
738 | limit | string | A limit on the number of objects to be returned. Default is `100`.
739 | 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`.
740 | 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`.
741 | order_status | string | Possible values: `open`, `completed`, `cancelled`.
742 | payment_status | string | Possible values: `unpaid`, `paid`, `failed`, `refunded`.
743 | fulfillment_status | string | Possible values: `unfulfilled`, `fulfilled`, `procesing`, `failed`.
744 | buyer.name | string | A filter on the list based on buyer name. This filter will perform a regex on the value.
745 | buyer.email | string | A filter on the list based on buyer email. This filter will perform a regex on the value.
746 | line_items.product_id | string | A filter on the list based on product id.
747 | line_items.variant_id | string | A filter on the list based on product variant id.
748 | line_items.sku | string | A filter on the list based on sku.
749 | type | string | A filter on order type: `card`, `paypal_adaptive`, `paypal_adaptive_chained`, `affirm`.
750 | shipping_method | string | A filter on shipping method.
751 | discounts.code | string | A filter on discount code.
752 | currency | string | A filter on currency code.
753 |
754 | - gt: Return values where the relevant field is after this timestamp (in ms).
755 | - gte: Return values where the relevant field is after or equal to this timestamp (in ms).
756 | - lt: Return values where the relevant field is before this timestamp (in ms).
757 | - lte: Return values where the relevant field is before or equal to this timestamp (in ms).
758 |
759 | 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`.
760 |
761 | If I wanted to query for orders purchased by `Brian Nguyen`, my query string would include `buyer.name=Brian+Nguyen`.
762 |
763 | ##### Example Request
764 | ```
765 | $ curl -X POST -H Content-Type:application/json -H Authorization:ACCESS_TOKEN \
766 | https://api.trycelery.com/v2/orders?created[gte]=1388534400000
767 | ```
768 |
769 | ##### Example Response
770 | ```json
771 | {
772 | "meta": {
773 | "code": 200,
774 | "paging": {
775 | "total": 2,
776 | "count": 2,
777 | "offset": 0,
778 | "page": 1,
779 | "pages": 1,
780 | "limit": 100,
781 | "has_more": false
782 | }
783 | },
784 | "data": [
785 | {
786 | ...
787 | },
788 | {
789 | ...
790 | }
791 | ]
792 | }
793 | ```
794 |
795 | ### Count orders
796 |
797 | ```
798 | GET /v2/orders/count
799 | ```
800 | ##### Arguments
801 |
802 | Attributes | Type | Description
803 | -----------|------|------------
804 | 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`.
805 | 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`.
806 | order_status | string | Possible values: `open`, `completed`, `cancelled`.
807 | payment_status | string | Possible values: `unpaid`, `paid`, `failed`, `refunded`.
808 | fulfillment_status | string | Possible values: `unfulfilled`, `fulfilled`, `procesing`, `failed`.
809 | buyer.name | string | A filter on the list based on buyer name. This filter will perform a regex on the value.
810 | buyer.email | string | A filter on the list based on buyer email. This filter will perform a regex on the value.
811 | line_items.product_id | string | A filter on the list based on product id.
812 | line_items.variant_id | string | A filter on the list based on product variant id.
813 | line_items.sku | string | A filter on the list based on sku.
814 | type | string | A filter on order type: `card`, `paypal_adaptive`, `paypal_adaptive_chained`, `affirm`.
815 | shipping_method | string | A filter on shipping method.
816 | discounts.code | string | A filter on discount code.
817 | currency | string | A filter on currency code.
818 |
819 | - gt: Return values where the relevant field is after this timestamp (in ms).
820 | - gte: Return values where the relevant field is after or equal to this timestamp (in ms).
821 | - lt: Return values where the relevant field is before this timestamp (in ms).
822 | - lte: Return values where the relevant field is before or equal to this timestamp (in ms).
823 |
824 | 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`.
825 |
826 | If I wanted to count how many orders were purchased by `Brian Nguyen`, my query string would include `buyer.name=Brian+Nguyen`.
827 |
828 | 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`.
829 |
830 | ##### Example Request
831 | ```
832 | $ curl -X POST -H Content-Type:application/json -H Authorization:ACCESS_TOKEN \
833 | https://api.trycelery.com/v2/orders/count?created[gte]=1388534400000
834 | ```
835 |
836 | ##### Example Response
837 | ```json
838 | {
839 | "meta": {
840 | "code": 200
841 | },
842 | "data": {
843 | "total": 507
844 | }
845 | }
846 | ```
847 |
848 | ### Update an Order
849 |
850 | 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.
851 |
852 | ```
853 | PUT /v2/orders/{id}
854 | ```
855 | ##### Arguments
856 |
857 | Attributes | Type | Description
858 | -----------|------|------------
859 | _id | string | **Required**. Order unique identifier.
860 | **Buyer** | object |
861 | buyer.email | string | Buyer's email address.
862 | buyer.first_name | string | Buyer's first name.
863 | buyer.last_name | string | Buyer's last name.
864 | buyer.phone | string | Buyer's phone number.
865 | buyer.notes | string | Buyer notes to the seller.
866 | **Shipping Address** | object |
867 | shipping_address.first_name | string | Shipping address first name.
868 | shipping_address.last_name | string | Shipping address last name.
869 | shipping_address.company | string | Shipping address company name.
870 | shipping_address.line1 | string | Shipping address street address.
871 | shipping_address.line2 | string | Shipping address building, apartment, unit, etc.
872 | shipping_address.city | string | Shipping address city.
873 | 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.
874 | shipping_address.zip | string | Shipping address ZIP or postal code.
875 | shipping_address.country | string | Shipping address 2-letter ISO country code (lowercase).
876 | shipping_address.phone | string | Shipping address phone number.
877 | **Line Items** | [object] |
878 | line_items[].id | string | Line item identifier (uuid).
879 | line_items[].product_id | string | Product id.
880 | line_items[].variant_id | string | Variant id.
881 | line_items[].quantity | integer | Number of units ordered.
882 |
883 | ##### Example Request
884 | This example request updates both the buyer and shipping_address information.
885 |
886 | ```
887 | $ curl -X PUT -H Content-Type:application/json -H Authorization:ACCESS_TOKEN \
888 | https://api.trycelery.com/v2/orders/530ec58358b6ee0000f5d440 \
889 | -d'
890 | {
891 | "buyer": {
892 | "email": "first@last.com",
893 | "first_name": "First",
894 | "last_name": "Last",
895 | "phone": "555-555-5555"
896 | },
897 | "shipping_address": {
898 | "first_name": "First"
899 | "last_name": "Last",
900 | "company": "Celery",
901 | "line1": "123 Street",
902 | "line2": null,
903 | "city": "New York",
904 | "state": "ny",
905 | "zip": "10012",
906 | "country": "us",
907 | "phone": "555-555-5555"
908 | }
909 | }
910 | ```
911 |
912 | ##### Example Response
913 |
914 | ```json
915 | {
916 | "meta": {
917 | "code": 200
918 | },
919 | "data": {
920 | "buyer": {
921 | "email": "first@last.com",
922 | "first_name": "First",
923 | "last_name": "Last",
924 | "name": "First Last",
925 | "sort_name": "first last",
926 | "phone": "555-555-5555"
927 | },
928 | "shipping_address": {
929 | "first_name": "First",
930 | "last_name": "Last",
931 | "name": "First Last",
932 | "company": "Celery",
933 | "line1": "123 Street",
934 | "line2": null,
935 | "city": "New York",
936 | "state": "ny",
937 | "zip": "10012",
938 | "country": "us",
939 | "phone": "555-555-5555"
940 | },
941 | ...
942 | }
943 | }
944 | ```
945 |
946 | ##### Example Request
947 |
948 | 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).
949 |
950 | WARNING: Updating line items will fetch the latest product details and may cause order prices (subtotal, taxes, shipping, total, balance) to change.
951 |
952 | ```
953 | $ curl -X PUT -H Content-Type:application/json -H Authorization:ACCESS_TOKEN \
954 | https://api.trycelery.com/v2/orders/530ec58358b6ee0000f5d440 \
955 | -d'
956 | {
957 | "line_items":
958 | [
959 | {
960 | "id": "550e8400-e29b-41d4-a716-446655440000",
961 | "product_id": "530e40d428ee4100002bfa78",
962 | "quantity": 2
963 | }
964 | ]
965 | }
966 | ```
967 |
968 | ##### Example Response
969 |
970 | ```json
971 | {
972 | "meta": {
973 | "code": 200
974 | },
975 | "data": {
976 | ...,
977 | "line_items": [
978 | {
979 | "id": "550e8400-e29b-41d4-a716-446655440000",
980 | "product_id": "530e40d428ee4100002bfa78",
981 | "quantity": 2,
982 | "price": 1000,
983 | "weight": 0,
984 | "enable_taxes": true,
985 | "product_name": "Koala Bears",
986 | "variant_name": null,
987 | "variant_id": null,
988 | "celery_sku": "530e40d428ee4100002bfa78",
989 | "sku": "KOALA-1"
990 | }
991 | ],
992 | ...
993 | }
994 | }
995 | ```
996 |
997 | ### Cancel an Order
998 |
999 | This will cancel the order. This endpoint will trigger email notifications to the buyer (if enabled).
1000 |
1001 | ```
1002 | POST /v2/orders/{id}/order_cancel
1003 | ```
1004 |
1005 | ##### Arguments
1006 |
1007 | Attributes | Type | Description
1008 | -----------|------|------------
1009 | id | string | **Required**. Order unique identifier.
1010 |
1011 | ##### Example Request
1012 | ```
1013 | $ curl -X POST -H Content-Type:application/json -H Authorization:ACCESS_TOKEN \
1014 | https://api.trycelery.com/v2/orders/530ec58358b6ee0000f5d440/order_cancel
1015 | ```
1016 |
1017 | ##### Example Response
1018 | ```json
1019 | {
1020 | "meta": {
1021 | "code": 200
1022 | },
1023 | "data": {
1024 | "order_status": "cancelled",
1025 | "history": [
1026 | {
1027 | "type": "order.created",
1028 | "created": 1393476995707,
1029 | "created_date": "2014-02-27T04:56:35.707Z",
1030 | "body": "Your order was created."
1031 | },
1032 | {
1033 | "type": "order.cancelled",
1034 | "created": 1401993491000,
1035 | "created_date": "2014-06-05T06:38:00.000Z",
1036 | "body": "Your order was cancelled."
1037 | }
1038 | ],
1039 | ...
1040 | }
1041 | }
1042 | ```
1043 |
1044 |
1045 | ### Charge an Order
1046 |
1047 | This will charge payment for the order. This endpoint will trigger email notifications to the buyer (if enabled).
1048 |
1049 | ```
1050 | POST /v2/orders/{id}/payment_charge
1051 | ```
1052 |
1053 | ##### Arguments
1054 |
1055 | Attributes | Type | Description
1056 | -----------|------|------------
1057 | id | string | **Required**. Order unique identifier.
1058 |
1059 | ##### Example Request
1060 |
1061 | ```
1062 | $ curl -X POST -H Content-Type:application/json -H Authorization:ACCESS_TOKEN \
1063 | https://api.trycelery.com/v2/orders/53c389b7eba65a000061e12f/payment_charge
1064 | ```
1065 |
1066 | ##### Example Response
1067 |
1068 | ```json
1069 | {
1070 | "meta": {
1071 | "code": 200
1072 | },
1073 | "data": {
1074 | "payment_status": "paid",
1075 | "payments": [
1076 | {
1077 | "id": "9969f10f-6c29-4d36-ba84-c60abd4bd7ed",
1078 | "charge_id": "ch_4OrpNFZKd4NOBz",
1079 | "balance_transaction": "txn_4Orp4IPXvI0QCc",
1080 | "pay_key": null,
1081 | "preapproval_key": null,
1082 | "capture_id": null,
1083 | "transaction_id": null,
1084 | "currency": "usd",
1085 | "amount": 2075,
1086 | "amount_refunded": 0,
1087 | "fee": 132,
1088 | "paid": true,
1089 | "captured": true,
1090 | "created": 1405323722000,
1091 | "created_date": "2014-07-14T07:42:02.000Z",
1092 | "refunded": null,
1093 | "refunded_date": null,
1094 | "card": {
1095 | "name": "",
1096 | "last4": "4242",
1097 | "exp_month": null,
1098 | "exp_year": null,
1099 | "type": "visa",
1100 | "country": "us"
1101 | }
1102 | }
1103 | ],
1104 | "history": [
1105 | {
1106 | "type": "order.created",
1107 | "created": 1393476995707,
1108 | "created_date": "2014-02-27T04:56:35.707Z",
1109 | "body": "Your order was created."
1110 | },
1111 | {
1112 | "type": "order.charge.succeeded",
1113 | "created": 1401993491000,
1114 | "created_date": "2014-06-05T06:38:00.000Z",
1115 | "body": "Your order was charged."
1116 | }
1117 | ],
1118 | "balance": 0,
1119 | "paid": 2075,
1120 | ...
1121 | }
1122 | }
1123 | ```
1124 |
1125 | ### Refund an Order
1126 |
1127 | This will refund payment for the order. This endpoint will trigger email notifications to the buyer (if enabled).
1128 |
1129 | ```
1130 | POST /v2/orders/{id}/payment_refund
1131 | ```
1132 |
1133 | ##### Arguments
1134 |
1135 | Attributes | Type | Description
1136 | -----------|------|------------
1137 | id | string | **Required**. Order unique identifier.
1138 |
1139 | ##### Example Request
1140 | ```
1141 | $ curl -X POST -H Content-Type:application/json -H Authorization:ACCESS_TOKEN \
1142 | https://api.trycelery.com/v2/orders/53c389b7eba65a000061e12f/payment_refund
1143 | ```
1144 |
1145 | ##### Example Response
1146 | ```json
1147 | {
1148 | "meta": {
1149 | "code": 200
1150 | },
1151 | "data": {
1152 | "payment_status": "refunded",
1153 | "payments": [
1154 | {
1155 | "id": "9969f10f-6c29-4d36-ba84-c60abd4bd7ed",
1156 | "charge_id": "ch_4OrpNFZKd4NOBz",
1157 | "balance_transaction": "txn_4Orp4IPXvI0QCc",
1158 | "pay_key": null,
1159 | "preapproval_key": null,
1160 | "capture_id": null,
1161 | "transaction_id": null,
1162 | "currency": "usd",
1163 | "amount": 2075,
1164 | "amount_refunded": 2075,
1165 | "fee": 132,
1166 | "paid": true,
1167 | "captured": true,
1168 | "created": 1405323722000,
1169 | "created_date": "2014-07-14T07:42:02.000Z",
1170 | "refunded": 1405377769000,
1171 | "refunded_date": "2014-07-14T22:42:49.000Z",
1172 | "card": {
1173 | "name": "",
1174 | "last4": "4242",
1175 | "exp_month": null,
1176 | "exp_year": null,
1177 | "type": "visa",
1178 | "country": "us"
1179 | }
1180 | }
1181 | ],
1182 | "history": [
1183 | {
1184 | "type": "order.created",
1185 | "created": 1393476995707,
1186 | "created_date": "2014-02-27T04:56:35.707Z",
1187 | "body": "Your order was created."
1188 | },
1189 | {
1190 | "type": "order.charge.succeeded",
1191 | "created": 1401993491000,
1192 | "created_date": "2014-06-05T06:38:00.000Z",
1193 | "body": "Your order was charged."
1194 | },
1195 | {
1196 | "type": "order.refund.succeeded",
1197 | "created": 1401993491000,
1198 | "created_date": "2014-06-05T06:38:00.000Z",
1199 | "body": "Your order was refunded."
1200 | }
1201 |
1202 | ],
1203 | "balance": 0,
1204 | "paid": 2075,
1205 | "refunded": 2075,
1206 | ...
1207 | }
1208 | }
1209 | ```
1210 |
1211 |
1212 | ### Fulfill an Order
1213 |
1214 | 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).
1215 |
1216 | ```
1217 | POST /v2/orders/{id}/fulfillment_succeed
1218 | ```
1219 |
1220 | ##### Arguments
1221 |
1222 | Attributes | Type | Description
1223 | -----------|------|------------
1224 | id | string | **Required**. Order unique identifier.
1225 | courier | string | Courier that will fulfill order. Possible values: `ups`, `usps`, `fedex`, `dhl`, `other`.
1226 | number | string | Tracking number.
1227 | serial_numbers | [string] | Serial numbers associated with the order.
1228 |
1229 | ##### Example Request
1230 |
1231 | ```
1232 | $ curl -X POST -H Content-Type:application/json -H Authorization:ACCESS_TOKEN \
1233 | https://api.trycelery.com/v2/orders/530ec58358b6ee0000f5d440/fulfillment_succeed \
1234 | -d'
1235 | {
1236 | "courier" : "ups",
1237 | "number" : "1zasdfajkfsdljasdf",
1238 | "serial_numbers": [
1239 | "abc123"
1240 | ]
1241 | }
1242 | ```
1243 |
1244 | ##### Example Response
1245 |
1246 | ```json
1247 | {
1248 | "meta": {
1249 | "code": 200
1250 | },
1251 | "data": {
1252 | ...,
1253 | "fulfillment_status": "fulfilled",
1254 | "fulfillment": {
1255 | "created": 1401993491000,
1256 | "created_date": "2014-06-05T06:38:00.000Z",
1257 | "courier": "ups",
1258 | "number": "1zasdfajkfsdljasdf",
1259 | "serial_numbers": [
1260 | "abc123"
1261 | ]
1262 | },
1263 | "history": [
1264 | {
1265 | "type": "order.created",
1266 | "created": 1393476995707,
1267 | "created_date": "2014-02-27T04:56:35.707Z",
1268 | "body": "Your order was created."
1269 | },
1270 | {
1271 | "type": "order.fulfillment.succeeded",
1272 | "created": 1401993491000,
1273 | "created_date": "2014-06-05T06:38:00.000Z",
1274 | "body": "Your order was fulfilled."
1275 | }
1276 | ],
1277 | ...
1278 | }
1279 | }
1280 | ```
1281 |
1282 | ## Products Resource
1283 |
1284 | Attributes | Type | Description
1285 | -----------|------|------------
1286 | _id | value | Product unique identifier.
1287 | slug | string | Seller-defined identifier for hosted shop page.
1288 | name | string | Product name.
1289 | description | string | Description of Product and supports `HTML` markup.
1290 | sku | integer | Base product sku.
1291 | price | integer | Base product price.
1292 | weight | float | Default value is `0`.
1293 | published | boolean | Defines whether a product is shown.
1294 | created | integer | Product created date. Unix timestamp in milliseconds.
1295 | updated | integer | Product updated date. Unix timestamp in milliseconds.
1296 | created_date | string | Product created date. ISO 8601 timestamp.
1297 | updated_date | string | Product updated date. ISO 8601 timestamp.
1298 | **Flags** | object |
1299 | flags.enable_taxes | boolean | Whether to collect tax.
1300 | flags.enable_options | boolean | Whether product has variants.
1301 | **Images** | object |
1302 | images[].url | string | Product image URL.
1303 | **Options** | objects |
1304 | options[].id | string | Option id.
1305 | options[].name | string | Option group name (e.g., size)
1306 | options[].values | object | Option group values (e.g., small, medium, large)
1307 | **Variants** | object |
1308 | variants[].id | string | Variant id. Used to checkout products with variants.
1309 | variants[].name | string | Variant name.
1310 | variants[].sku | string | Variant sku.
1311 | variants[].price | integer | Variant price.
1312 | variants[].weight | integer | Variant weight.
1313 | variants[].options | object | Variant settings.
1314 |
1315 | ### Retrieve a list of products
1316 |
1317 | ```
1318 | GET /v2/products
1319 | ```
1320 | ##### Arguments
1321 |
1322 | Attributes | Type | Description
1323 | -----------|------|------------
1324 | sort | string | Sort by. Default is `created`.
1325 | order | string | Order by. Default is `desc`. Possible values: `desc`, `asc`.
1326 | offset | string | Default is `0`.
1327 | page | integer | Current page number.
1328 | limit | string | A limit on the number of objects to be returned. Default is `100`.
1329 |
1330 |
1331 | ##### Example Request
1332 |
1333 | ```
1334 | $ curl -X GET -H Content-Type:application/json -H Authorization:ACCESS_TOKEN \
1335 | https://api.trycelery.com/v2/products
1336 | ```
1337 |
1338 | ##### Example Response
1339 |
1340 | ```json
1341 | {
1342 | "meta": {
1343 | "code": 200,
1344 | "paging": {
1345 | "total": 3,
1346 | "count": 3,
1347 | "limit": 100,
1348 | "offset": 0,
1349 | "page": 1,
1350 | "pages": 1,
1351 | "has_more": false
1352 | }
1353 | },
1354 | "data": [
1355 | {
1356 | "_id": "546aab7b1657500600a781bc",
1357 | "slug": "90ca88bd-3830-4ee0-b39f-e5f200d0a489",
1358 | "name": "Koala 1",
1359 | "description": "Koala party
",
1360 | "sku": null,
1361 | "price": 1500,
1362 | "deposit": 0,
1363 | "weight": 0,
1364 | "inventory": 0,
1365 | "published": true,
1366 | "flags": {
1367 | "enable_taxes": true,
1368 | "enable_options": false,
1369 | "enable_inventory": false
1370 | },
1371 | "images": [],
1372 | "options": [],
1373 | "variants": [],
1374 | "user_id": "54629b565f388707003de6ea",
1375 | "version": "v2",
1376 | "created": 1416276859872,
1377 | "updated": 1416276859970,
1378 | "created_date": "2014-11-18T02:14:19.872Z",
1379 | "updated_date": "2014-11-18T02:14:19.970Z",
1380 | "locked": false,
1381 | "metadata": {}
1382 | },
1383 | {
1384 | "_id": "546a9d731657500600a781ba",
1385 | "slug": "12b1f0a1-b18c-407a-9f9c-470f262f1853",
1386 | "name": "Koala 2",
1387 | "description": null,
1388 | "sku": null,
1389 | "price": 2000,
1390 | "deposit": 0,
1391 | "weight": 0,
1392 | "inventory": 0,
1393 | "published": true,
1394 | "flags": {
1395 | "enable_taxes": true,
1396 | "enable_options": false,
1397 | "enable_inventory": false
1398 | },
1399 | "images": [],
1400 | "options": [],
1401 | "variants": [],
1402 | "user_id": "54629b565f388707003de6ea",
1403 | "version": "v2",
1404 | "created": 1416273267130,
1405 | "updated": 1416273287831,
1406 | "created_date": "2014-11-18T01:14:27.130Z",
1407 | "updated_date": "2014-11-18T01:14:47.831Z",
1408 | "locked": false,
1409 | "metadata": {}
1410 | },
1411 | {
1412 | "_id": "546540f2793b4c050015d96c",
1413 | "slug": "7dc66c4a-99ca-48b2-b584-23de515272c0",
1414 | "name": "Koala 3",
1415 | "description": null,
1416 | "sku": null,
1417 | "price": 2500,
1418 | "deposit": 0,
1419 | "weight": 0,
1420 | "inventory": 0,
1421 | "published": true,
1422 | "flags": {
1423 | "enable_taxes": true,
1424 | "enable_options": false,
1425 | "enable_inventory": false
1426 | },
1427 | "images": [],
1428 | "options": [],
1429 | "variants": [],
1430 | "user_id": "54629b565f388707003de6ea",
1431 | "version": "v2",
1432 | "created": 1415921906675,
1433 | "updated": 1415922135705,
1434 | "created_date": "2014-11-13T23:38:26.675Z",
1435 | "updated_date": "2014-11-13T23:42:15.705Z",
1436 | "locked": false,
1437 | "metadata": {}
1438 | }
1439 | ]
1440 | }
1441 | ```
1442 |
1443 | ### Retrieve a Product
1444 |
1445 | ```
1446 | GET /v2/products/{id}
1447 | ```
1448 |
1449 | ##### Arguments
1450 |
1451 | Attributes | Type | Description
1452 | -----------|------|------------
1453 | id | string | **Required**. Product unique identifier.
1454 |
1455 |
1456 | ##### Example Request
1457 | ```
1458 | $ curl -X GET -H Content-Type:application/json -H Authorization:ACCESS_TOKEN \
1459 | https://api.trycelery.com/v2/products/546540f2793b4c050015d96c
1460 | ```
1461 |
1462 | ##### Example Response
1463 |
1464 | ```json
1465 | {
1466 | "meta": {
1467 | "code": 200
1468 | },
1469 | "data": {
1470 | "slug": "7dc66c4a-99ca-48b2-b584-23de515272c0",
1471 | "name": "Koala Bears",
1472 | "description": "Cute but dangerous.
",
1473 | "sku": null,
1474 | "price": 1000,
1475 | "deposit": 0,
1476 | "weight": 0,
1477 | "inventory": 0,
1478 | "published": true,
1479 | "flags": {
1480 | "enable_taxes": true,
1481 | "enable_options": false,
1482 | "enable_inventory": false
1483 | },
1484 | "images": [],
1485 | "options": [],
1486 | "variants": [],
1487 | "_id": "546540f2793b4c050015d96c",
1488 | "user_id": "54629b565f388707003de6ea",
1489 | "version": "v2",
1490 | "created": 1415921906675,
1491 | "updated": 1415922135705,
1492 | "created_date": "2014-11-13T23:38:26.675Z",
1493 | "updated_date": "2014-11-13T23:42:15.705Z",
1494 | "locked": false,
1495 | "metadata": {}
1496 | }
1497 | }
1498 | ```
1499 |
1500 | ## Collections Resource
1501 |
1502 | Attributes | Type | Description
1503 | -----------|------|------------
1504 | _id | string | **Required**. Collections unique identifier.
1505 | slug | string | Seller-defined identifier for hosted shop page.
1506 | name | string | Collection name.
1507 | published | boolean | Defines whether collection is shown.
1508 | product_ids | [objects] | List of product ids in collection.
1509 | user_id | string | Seller unique identifier.
1510 | created | integer | Collection created date. Unix timestamp in milliseconds.
1511 | updated | integer | Collection updated date. Unix timestamp in milliseconds.
1512 | created_date | string | Collection created date. ISO 8601 timestamp.
1513 | updated_date | string | Collection updated date. ISO 8601 timestamp.
1514 | products | [objects] | List of products in collection.
1515 |
1516 |
1517 | ### Retrieve a list of Collections
1518 |
1519 | ```
1520 | GET /v2/collections/
1521 | ```
1522 |
1523 | ##### Arguments
1524 |
1525 | Attributes | Type | Description
1526 | -----------|------|------------
1527 | sort | string | Sort by. Default is `created`.
1528 | order | string | Order by. Default is `desc`. Possible values: `desc`, `asc`.
1529 | offset | string | Default is `0`.
1530 | page | integer | Current page number.
1531 | limit | string | A limit on the number of objects to be returned. Default is `100`.
1532 |
1533 |
1534 | ##### Example Request
1535 | ```
1536 | $ curl -X GET -H Content-Type:application/json -H Authorization:ACCESS_TOKEN \
1537 | https://api.trycelery.com/v2/collections
1538 | ```
1539 |
1540 | ##### Example Response
1541 |
1542 | ```json
1543 | {
1544 | "meta": {
1545 | "code": 200,
1546 | "paging": {
1547 | "total": 1,
1548 | "count": 1,
1549 | "limit": 100,
1550 | "offset": 0,
1551 | "page": 1,
1552 | "pages": 1,
1553 | "has_more": false
1554 | }
1555 | },
1556 | "data": {
1557 | "slug": "53171e1a-a272-4a73-9f91-214159672197",
1558 | "name": "Christmas Koala Collection",
1559 | "published": true,
1560 | "product_ids": [
1561 | "546540f2793b4c050015d96c",
1562 | "54653d6e793b4c050015d96a",
1563 | "54653d42793b4c050015d969"
1564 | ],
1565 | "_id": "54736eb0b588d10400fbe7cc",
1566 | "user_id": "54629b565f388707003de6ea",
1567 | "version": "v2",
1568 | "created": 1416851120197,
1569 | "updated": 1416851141330,
1570 | "created_date": "2014-11-24T17:45:20.197Z",
1571 | "updated_date": "2014-11-24T17:45:41.330Z",
1572 | "locked": false,
1573 | "metadata": {},
1574 | "products": [
1575 | {
1576 | "_id": "546540f2793b4c050015d96c",
1577 | "slug": "7dc66c4a-99ca-48b2-b584-23de515272c0",
1578 | "name": "Koala Two-Pack",
1579 | "description": "A mommy koala with baby koala packed inside.
",
1580 | "sku": null,
1581 | "price": 1000,
1582 | "deposit": 0,
1583 | "weight": 0,
1584 | "inventory": 0,
1585 | "published": true,
1586 | "flags": {
1587 | "enable_taxes": true,
1588 | "enable_options": false,
1589 | "enable_inventory": false
1590 | },
1591 | "images": [],
1592 | "options": [],
1593 | "variants": [],
1594 | "user_id": "54629b565f388707003de6ea",
1595 | "version": "v2",
1596 | "created": 1415921906675,
1597 | "updated": 1415922135705,
1598 | "created_date": "2014-11-13T23:38:26.675Z",
1599 | "updated_date": "2014-11-13T23:42:15.705Z",
1600 | "locked": false,
1601 | "metadata": {}
1602 | },
1603 | ...
1604 | ]
1605 | }
1606 | }
1607 | ```
1608 |
1609 | ### Retrieve a Collection
1610 |
1611 | ```
1612 | GET /v2/collections/{id}
1613 | ```
1614 |
1615 | ##### Example Request
1616 | ```
1617 | $ curl -X GET -H Content-Type:application/json -H Authorization:ACCESS_TOKEN \
1618 | https://api.trycelery.com/v2/collections/{id}
1619 | ```
1620 |
1621 | ##### Arguments
1622 |
1623 | Attributes | Type | Description
1624 | -----------|------|------------
1625 | id | string | **Required** Collection unique identifier.
1626 |
1627 |
1628 | ##### Example Response
1629 |
1630 | ```json
1631 | {
1632 | "meta": {
1633 | "code": 200
1634 | },
1635 | "data": {
1636 | "slug": "53171e1a-a272-4a73-9f91-214159672197",
1637 | "name": "Christmas Koala Collection",
1638 | "published": true,
1639 | "product_ids": [
1640 | "546540f2793b4c050015d96c",
1641 | "54653d6e793b4c050015d96a",
1642 | "54653d42793b4c050015d969"
1643 | ],
1644 | "_id": "54736eb0b588d10400fbe7cc",
1645 | "user_id": "54629b565f388707003de6ea",
1646 | "version": "v2",
1647 | "created": 1416851120197,
1648 | "updated": 1416851141330,
1649 | "created_date": "2014-11-24T17:45:20.197Z",
1650 | "updated_date": "2014-11-24T17:45:41.330Z",
1651 | "locked": false,
1652 | "metadata": {},
1653 | "products": [
1654 | {
1655 | ...
1656 | },
1657 | ]
1658 | }
1659 | }
1660 | ```
1661 |
1662 |
1663 | ## Coupons Resource
1664 |
1665 | Attributes | Type | Description
1666 | -----------|------|------------
1667 | _id | string | Coupon unique identifier.
1668 | user_id | string | Seller unique identifier.
1669 | type | string | Possible values: `flat`, `percent`.
1670 | code | string | Coupon code (must be unique).
1671 | filter | string | Possible values: `order`, `order_with_minimum`, `product`.
1672 | apply | string | Possible values: `once`, `every_item`.
1673 | free_shipping | boolean | Possible values: `true`, `false`.
1674 | product_id | string | Product id for product-specific coupons.
1675 | enabled | boolean | Whether coupon is valid.
1676 | amount | integer | Coupon amount. $5 should be `500` (prices in cents). 10% should be `10`.
1677 | order_minimum | integer | Minimum line item amount before coupon can be applied (amount in cents). Filter must be set to `order_with_minimum`.
1678 | quantity | integer | How many times coupon can be redeemed. (`null` or `undefined` represents unlimited usage)
1679 | times_used | integer | Number of times coupon was redeemed.
1680 | begins | integer | Coupon begin date. Unix timestamp in milliseconds.
1681 | begins_date | string | Coupon begin date. ISO 8601 timestamp.
1682 | expires | integer | Coupon expiration date. Unix timestamp in milliseconds.
1683 | expires_date | string | Coupon expiration date. ISO 8601 timestamp.
1684 | used_emails | [string] | List of buyer email addresses who have redeemed coupon.
1685 | created | integer | Unix timestamp in milliseconds.
1686 | created_date | string | ISO 8601 timestamp.
1687 | updated | integer | Unix timestamp in milliseconds.
1688 | updated_date | string | ISO 8601 timestamp.
1689 |
1690 |
1691 | ### Create a Coupon
1692 |
1693 | ```
1694 | POST /v2/coupons
1695 | ```
1696 |
1697 | ##### Arguments
1698 |
1699 | Attributes | Type | Description
1700 | -----------|------|------------
1701 | type | string | **Required** Possible values: `flat`, `percent`.
1702 | code | string | **Required** Coupon code (must be unique).
1703 | filter | string | **Required** Possible values: `order`, order_with_minimum, `product`.
1704 | apply | string | **Required** Possible values: `once`, `every_item`.
1705 | product_id | string | Product id for product-specific coupons.
1706 | enabled | boolean | Whether coupon is valid. Defaults to `true`.
1707 | free_shipping | boolean | **Required** Possible values: `true`, `false`.
1708 | amount | integer | **Required** Coupon amount. $5 should be `500` (prices in cents). 10% should be `10`.
1709 | order_minimum | integer | Minimum line item amount before coupon can be applied (amount in cents). Filter must be set to `order_with_minimum`.
1710 | quantity | integer | How many times coupon can be redeemed. (`null` or `undefined` represents unlimited usage)
1711 | begins | integer | Coupon begin date. Unix timestamp in milliseconds.
1712 | expires | integer | Coupon expiration date. Unix timestamp in milliseconds.
1713 |
1714 |
1715 | ##### Example Request
1716 | ```
1717 | $ curl -X POST -H Content-Type:application/json -H Authorization:ACCESS_TOKEN \
1718 | https://api.trycelery.com/v2/coupons
1719 | -d'
1720 | {
1721 | "type": "flat",
1722 | "code": "15off-1",
1723 | "filter": "flat",
1724 | "free_shipping": false,
1725 | "amount": 1500,
1726 | "expired": 1461705000000
1727 | }
1728 | ```
1729 |
1730 | ##### Example Response
1731 |
1732 | ```json
1733 | {
1734 | "meta": {
1735 | "code": 200,
1736 | },
1737 | "data": {
1738 | "_id": "571fd4b900598e208992eed8",
1739 | "version": "v2",
1740 | "created": 1461703865552,
1741 | "updated": 1461703865556,
1742 | "created_date": "2016-04-26T20:51:05.552Z",
1743 | "updated_date": "2016-04-26T20:51:05.556Z",
1744 | "locked": false,
1745 | "metadata": {},
1746 | "user_id": "514a114080feb60200000001",
1747 | "type": "flat",
1748 | "code": "15off-1",
1749 | "filter": "order",
1750 | "apply": "once",
1751 | "product_id": null,
1752 | "enabled": true,
1753 | "free_shipping": false,
1754 | "amount": 1500,
1755 | "quantity": null,
1756 | "times_used": 0,
1757 | "order_minimum": 0,
1758 | "begins": 1461703865552,
1759 | "begins_date": "2016-04-26T20:51:05.552Z",
1760 | "expires": 1461705000000,
1761 | "expires_date": null,
1762 | "used_emails": []
1763 | }
1764 | }
1765 | ```
1766 |
1767 |
1768 | ### Retrieve a List of Coupons
1769 |
1770 | ```
1771 | GET /v2/coupons
1772 | ```
1773 |
1774 | ##### Arguments
1775 |
1776 | Attributes | Type | Description
1777 | -----------|------|------------
1778 | sort | string | Sort by. Default is `created`.
1779 | order | string | Order by. Default is `desc`. Possible values: `desc`, `asc`.
1780 | offset | string | Default is `0`.
1781 | page | integer | Current page number.
1782 | limit | string | A limit on the number of objects to be returned. Default is `100`.
1783 |
1784 | ##### Example Request
1785 | ```
1786 | $ curl -X GET -H Content-Type:application/json -H Authorization:ACCESS_TOKEN \
1787 | https://api.trycelery.com/v2/coupons
1788 | ```
1789 |
1790 | ##### Example Response
1791 |
1792 | ```json
1793 | {
1794 | "meta": {
1795 | "code": 200,
1796 | "paging": {
1797 | "total": 3,
1798 | "count": 3,
1799 | "limit": 100,
1800 | "offset": 0,
1801 | "page": 1,
1802 | "pages": 1,
1803 | "has_more": false
1804 | }
1805 | },
1806 | "data": [
1807 | {
1808 | "_id": "5488e5689b43260400cb3d1a",
1809 | "type": "percent",
1810 | "code": "566e8816d360",
1811 | "filter": "order",
1812 | "apply": "once",
1813 | "free_shipping": false,
1814 | "product_id": null,
1815 | "enabled": true,
1816 | "amount": 20,
1817 | "quantity": null,
1818 | "times_used": 0,
1819 | "order_minimum": 0,
1820 | "begins": 1418198400000,
1821 | "begins_date": "2014-12-11T00:29:28.108Z",
1822 | "expires": null,
1823 | "expires_date": null,
1824 | "used_emails": [],
1825 | "user_id": "54629b565f388707003de6ea",
1826 | "version": "v2",
1827 | "created": 1418257768108,
1828 | "updated": 1418257768108,
1829 | "created_date": "2014-12-11T00:29:28.108Z",
1830 | "updated_date": "2014-12-11T00:29:28.108Z",
1831 | "locked": false,
1832 | "metadata": {}
1833 | },
1834 | {
1835 | "_id": "5488e559fe3e2a0500b82556",
1836 | "type": "flat",
1837 | "code": "94cf61c4d205",
1838 | "filter": "order",
1839 | "apply": "once",
1840 | "free_shipping": false,
1841 | "product_id": null,
1842 | "enabled": true,
1843 | "amount": 2000,
1844 | "quantity": null,
1845 | "times_used": 0,
1846 | "order_minimum": 0,
1847 | "begins": 1418198400000,
1848 | "begins_date": "2014-12-11T00:29:13.319Z",
1849 | "expires": null,
1850 | "expires_date": null,
1851 | "used_emails": [],
1852 | "user_id": "54629b565f388707003de6ea",
1853 | "version": "v2",
1854 | "created": 1418257753319,
1855 | "updated": 1418257753319,
1856 | "created_date": "2014-12-11T00:29:13.319Z",
1857 | "updated_date": "2014-12-11T00:29:13.319Z",
1858 | "locked": false,
1859 | "metadata": {}
1860 | }
1861 | ]
1862 | }
1863 | ```
1864 |
1865 |
1866 | ### Retrieve a Coupon
1867 |
1868 | ```
1869 | GET /v2/coupons/{id}
1870 | ```
1871 |
1872 | ##### Example Request
1873 | ```
1874 | $ curl -X GET -H Content-Type:application/json -H Authorization:ACCESS_TOKEN \
1875 | https://api.trycelery.com/v2/coupons/{id}
1876 | ```
1877 |
1878 | ##### Arguments
1879 |
1880 | Attributes | Type | Description
1881 | -----------|------|------------
1882 | id | string | **Required** Coupon unique identifier.
1883 |
1884 |
1885 | ##### Example Response
1886 |
1887 | ```json
1888 | {
1889 | "meta": {
1890 | "code": 200
1891 | },
1892 | "data": {
1893 | "type": "flat",
1894 | "code": "93000fdb71fc",
1895 | "filter": "order",
1896 | "apply": "once",
1897 | "free_shipping": true,
1898 | "product_id": null,
1899 | "enabled": true,
1900 | "amount": 0,
1901 | "quantity": null,
1902 | "times_used": 0,
1903 | "order_minimum": 0,
1904 | "begins": 1418198400000,
1905 | "begins_date": "2014-12-11T00:29:35.785Z",
1906 | "expires": null,
1907 | "expires_date": null,
1908 | "used_emails": [],
1909 | "_id": "5488e56ffe3e2a0500b82557",
1910 | "user_id": "54629b565f388707003de6ea",
1911 | "version": "v2",
1912 | "created": 1418257775785,
1913 | "updated": 1418257775785,
1914 | "created_date": "2014-12-11T00:29:35.785Z",
1915 | "updated_date": "2014-12-11T00:29:35.785Z",
1916 | "locked": false,
1917 | "metadata": {}
1918 | }
1919 | }
1920 | ```
1921 |
1922 |
1923 | ### Validate coupon code
1924 |
1925 | 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.
1926 |
1927 | ```
1928 | POST /v2/coupons/validate
1929 | ```
1930 |
1931 | ##### Arguments
1932 |
1933 | Attributes | Type | Description
1934 | -----------|------|------------
1935 | user_id | string | **Required**. Seller unique identifier.
1936 | code | string | **Required**. Coupon code to validate.
1937 | **Line Items** | [object] |
1938 | line_items[].product_id | string | Product id to validate against product-specific coupons.
1939 |
1940 |
1941 | ##### Example Request
1942 | ```
1943 | $ curl -X POST -H Content-Type:application/json \
1944 | https://api.trycelery.com/v2/coupons/validate
1945 | -d'
1946 | {
1947 | "user_id": "514a114080feb60200000001",
1948 | "code": "036dabee2bd3",
1949 | "line_items": [
1950 | {
1951 | "product_id": null
1952 | }
1953 | ]
1954 | }
1955 | ```
1956 |
1957 |
1958 | ##### Example Response
1959 |
1960 | ```json
1961 | {
1962 | "meta": {
1963 | "code": 200
1964 | },
1965 | "data": {
1966 | "type": "flat",
1967 | "code": "036dabee2bd3",
1968 | "filter": "order",
1969 | "apply": "once",
1970 | "free_shipping": false,
1971 | "product_id": null,
1972 | "enabled": true,
1973 | "amount": 10000,
1974 | "quantity": 0,
1975 | "times_used": 1,
1976 | "order_minimum": 0,
1977 | "begins": 1412146800000,
1978 | "begins_date": "2014-08-08T21:52:37.055Z",
1979 | "expires": 1413010800000,
1980 | "expires_date": null,
1981 | "used_emails": [],
1982 | "_id": "53e546a5fc08e40400631da9",
1983 | "user_id": "5330bc8c5ade8207002df9f6",
1984 | "version": "v2",
1985 | "created": 1407534757055,
1986 | "updated": 1407534757055,
1987 | "created_date": "2014-08-08T21:52:37.055Z",
1988 | "updated_date": "2014-08-08T21:52:37.055Z",
1989 | "locked": false,
1990 | "metadata": {}
1991 | }
1992 | }
1993 | ```
1994 |
1995 | ##### Error Example Response
1996 |
1997 | ```json
1998 | {
1999 | "meta": {
2000 | "code": 400,
2001 | "error": {
2002 | "message": "Coupon code is expired.",
2003 | "code": 400
2004 | }
2005 | },
2006 | "data": "Coupon code is expired."
2007 | }
2008 | ```
2009 |
2010 | ## Users Resource
2011 |
2012 | ### Retrieve tax rate
2013 |
2014 | 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.
2015 |
2016 | ```
2017 | GET /v2/users/{id}/tax_rates
2018 | ```
2019 |
2020 | ##### Arguments
2021 |
2022 | Attributes | Type | Description
2023 | -----------|------|------------
2024 | id | string | **Required**. Seller unique identifier.
2025 | shipping_country | string | **Required**. 2-letter ISO country code (lowercase).
2026 | shipping_state | string | 2-letter ISO state code if United States or Canada (lowercase).
2027 | shipping_zip | string | 5-digit zip code if United States. Supports optional 4 digits.
2028 |
2029 | ##### Example Request
2030 | ```
2031 | $ curl -X GET -H Content-Type:application/json \
2032 | https://api.trycelery.com/v2/users/530ec58358b6ee0000f5d440/tax_rates?shipping_country=us&shipping_state=ca&shipping_zip=94105
2033 | ```
2034 |
2035 | ##### Example Response
2036 |
2037 | ```json
2038 | {
2039 | "meta": {
2040 | "code": 200
2041 | },
2042 | "data": {
2043 | "base": 0.0875
2044 | }
2045 | }
2046 | ```
2047 |
2048 |
2049 | ## Webhooks
2050 |
2051 | 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.
2052 |
2053 | 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.
2054 |
2055 | 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.
2056 |
2057 | * order.created
2058 | * order.completed
2059 | * order.cancelled
2060 | * order.line_items.updated
2061 | * order.shipping_address.updated
2062 | * order.adjustments.updated
2063 | * order.payment_source.updated
2064 | * order.notes.updated
2065 | * order.charge.succeeded
2066 | * order.charge.failed
2067 | * order.refund.succeeded
2068 | * order.refund.failed
2069 | * order.fulfillment.succeeded
2070 | * order.fulfillment.processing
2071 | * order.fulfillment.failed
2072 |
2073 | ##### Example Response
2074 |
2075 | ```json
2076 | {
2077 | "type": "order.created",
2078 | "data": {
2079 | "_id": "530ec58358b6ee0000f5d440",
2080 | "order_status": "open",
2081 | "payment_status": "unpaid",
2082 | "fulfillment_status": "unfulfilled",
2083 | ...
2084 | }
2085 | }
2086 |
--------------------------------------------------------------------------------