Airbrite API

Introduction
Getting Started
Authentication
Organization
Response Format
Errors
Webhooks
Resource Methods

Introduction

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

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). JSON will be returned in all responses from the API, including errors.

To make the Airbrite API as explorable as possible, accounts have test API keys as well as live API keys. These keys can be active at the same time. Data created with test credentials do not access live money.

Getting Started

The base endpoint URL is: https://api.airbrite.io
All requests must be made over SSL
To create new orders, you should setup your product first
To process payments, you must connect to Stripe, which can be done in your account settings

Authentication

Tokens are used to authenticate your requests. There are two sets of tokens (public and secret) for each environment (live and test). Public keys are used only on the client-side and will authenticate for only POST requests for Orders. Secret keys are used by your servers to make requests to the Airbrite API.

All endpoints require authentication. To authenticate with HTTP header, there are 3 ways you can set your header, where {ACCESS_TOKEN} is sk_test_xxxxxx or sk_live_xxxxxx.

Authorization: {ACCESS_TOKEN}
Authorization: Basic {BASE64_ENCODED_ACCESS_TOKEN}
Authorization: Bearer {ACCESS_TOKEN}

Alternatively, you can authenticate via query string by simply adding ?access_token={ACCESS_TOKEN} to any request.

Organization

The API is organized by version of the API and resource: /{VERSION}/{RESOURCE}. The current version of the API is v2. For example, to reach the Products endpoint, you would access /v2/products. To access a resource with a specific ID, the route is /{VERSION}/{RESOURCE}/{ID}.

The API also has a number of child resources (or subcollections). Child resources are accessible via the route /{VERSION}/{RESOURCE}/{RESOURCE_ID}/{CHILD_RESOURCE}. A specific resource can be accessed at ../{CHILD_RESOURCE}/{CHILD_RESOURCE_ID}.

Below are the parent and their respective child resources.

Products
- Events
Orders
- Payments
- Shipments
- Events
Customers
- Orders
- Events
Account
Events

Response Format

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

Response

{
  "meta": {
    "code": 200,
    "env": "test"
  },
  "paging": {
    "total": 7,
    "count": 1,
    "offset": 5,
    "limit": 1,
    "has_more": true
  },
  "data": [
    {
      "user_id": "522a72380ac3590000000001",
      "_id": "522e4eeccf84bd0000000007",
      "name": "Awesome Product",                    
      "sku": "awesome",
      "price": 1000,
      "created": 1378766572,
      "created_date": "2013-09-09T22:42:52.781Z",
      "updated": 1378766572,
      "updated_date": "2013-09-09T22:42:52.781Z",
      "description": null,
      "metadata": null
    }
  ]
}

All collections accept pagination parameters. Filters will respond with paging information about the collection.

Example Endpoint

GET https://api.airbrite.io/v2/products?limit=10&skip=5&sort=sku&order=asc

Arguments

limit:  optional
        Maximum number of objects to return. Defaults to 100.
skip:   optional
        Number of objects to skip over before returning results
sort:   optional
        Which field to sort by
order:  optional
        Which way to sort (1 or -1 and asc or desc are the same, respectively)
since:  optional
        Matches all items updated after unix timestamp
until:  optional
        Matches all items updated before unix timestamp

Example Response

{ 
    ...,
    "paging": {
        "total": 45,
        "count": 10,
        "offset": 5,
        "limit": 10,
        "has_more": true
    },
    "data": {
      ...  
    }
}

Errors

Airbrite 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 Airbrite's servers.

Our error responses have the format:

{
    "meta": {
        "code": 400,
        "error_message": "User with email already exists.",
        "error_type": "client_error"
    },
    "data": "User with email already exists."
}

Webhooks

Use webhooks to be notified about events that happen in your Airbrite account. Webhooks can be configured in the webhooks section of your Account Settings.

Webhook data is sent as JSON in the request's body. The full event details are included and can be used directly. Alternatively, the event is also available in the Airbrite API. If security is a concern, or if it's important to confirm that Airbrite sent the webhook, you should only use the ID sent in your webhook and should request the remaining details from the Airbrite API directly. We also advise you to guard against replay-attacks by recording which events you receive, and never processing events twice.

To acknowledge that you received the webhook without any problem, your server should return a 200 HTTP status code. Any other information you return in the request headers or request body will be ignored. Any response code outside the 200 range, including 3xx codes, will indicate to Airbrite that you did not receive the webhook. When a webhook is not received for whatever reason, Airbrite will continue trying to send the webhook 3 times (30 seconds apart).

Please note that Airbrite intends to move to a system where we'll continue trying to send the webhook once an hour for up to 3 days until the webhook is received.

Resource Methods

List of Routes

Products
- /v2/products
- /v2/products/{PRODUCT_ID}
Orders
- /v2/orders
- /v2/orders/{ORDER_ID}
- /v2/orders/{ORDER_ID}/payments
- /v2/orders/{ORDER_ID}/payments/{PAYMENT_ID}
- /v2/orders/{ORDER_ID}/payments/{PAYMENT_ID}/capture
- /v2/orders/{ORDER_ID}/payments/{PAYMENT_ID}/refund
- /v2/orders/{ORDER_ID}/shipments
- /v2/orders/{ORDER_ID}/shipments/{SHIPMENT_ID}
Customers
- /v2/customers
- /v2/customers/{CUSTOMER_ID}
Taxes
- /v2/tax
Events
- /v2/events
- /v2/events/{EVENT_ID}
- /v2/events/{EVENT_ID}/webhooks

Products

Arguments

_id:          string
user_id:      string
created:      timestamp (Unix)
created_date: timestamp (ISO_8601)
updated:      timestamp (Unix)
updated_date: timestamp (ISO_8601)
sku:          string
              Unique identifier for your product
name:         string
price:        positive integer or zero
              Amount in cents
description:  string
metadata:     object
              Store as many key-value pairs of extra data as you wish

Create product

Endpoint

POST https://api.airbrite.io/v2/products

Arguments

Required: sku, price
Optional: name, description, metadata

Retrieve product

Endpoint

GET https://api.airbrite.io/v2/products/{PRODUCT_ID}

Arguments

Required: product_id
Optional: none

List all products

Endpoint

GET https://api.airbrite.io/v2/products

Arguments

Required: none
Optional: limit, skip, sort, order, since, until

Update product

Endpoint

PUT https://api.airbrite.io/v2/products/{PRODUCT_ID}

Arguments

Required: product_id
Optional: sku, price, name, description, metadata

Orders

Arguments

_id:              string (id)
user_id:          string (id)
customer_id:      string (id)
created:          timestamp (Unix)
created_date:     timestamp (ISO_8601)
updated:          timestamp (Unix)
updated_date:     timestamp (ISO_8601)
currency:         string (3-letter ISO currency code)
order_number:     integer
                  Automatically designated by Airbrite
status:           string
                  Order state
line_items:       array
                  Contains sku, quantity
shipping_address: object
                  Contains name, line1, line2, city, state, zip, country, phone
                  Country must be a 2-letter ISO country code
discount:         object
                  Contains cost (integer)
shipping:         object
                  Contains cost (integer)
tax:              object
                  Contains cost (integer)
description:      string
metadata:         object
                  Store as many key-value pairs of extra data as you wish

Connections (optional)

customer:         object (only if you did not provide a customer_id)
payments:         array
                  Contains gateway, amount, charge_token, capture (optional)
shipments:        array

Create Order

Note: If you'd like to add line_items, your product needs to be already created.

Assigning an Order to an existing Customer

If you want to assign the Order to an existing Airbrite Customer record at the time of creation, make sure to include either "customer_id" or the "customer" connection with the customer "_id":

{
    "customer_id": "XXXXXXXXXXXXXXXXXXXXXXXX"
}

OR if you want to also update something about the Customer:

{
    "customer": {
        "_id": "XXXXXXXXXXXXXXXXXXXXXXXX",
        "description": "updated customer!"
    }
}

If you want to import an existing Stripe Customer (i.e., saved payment cards), you can pass the "stripe_customer_id" as part of the customer object.

{
    "customer": {
        "stripe_customer_id": "cus_xxxxxxxxxxxxx"
    }
}

If you want to create a new Airbrite Customer record at the time of creation, include the "customer" connection and do not include an _id:

This can also include additional properties you would like to associate with the customer...

{
    ...,
    "customer": {
        "name": "Kanye East",
        "email": "kanye.east@west.com",
        "card_token": "tok_xxxxxxxx",
        "metadata": {
            "gender": "male",
            "occupation": "rapper"
        },
        ...
    }
}

Note: The card_token property allows you to assign and save a Stripe tokenized credit card to the Customer. This will create a Stripe customer object, which allows you to perform recurring charges and track multiple charges that are associated with the same customer.

Attaching a Payment at the time of Order creation:

If using Stripe, the payment card must be tokenized with stripe.js before the order is created.

You can immediately attach a Payment to the newly created Order by including the "payments" connection. There are 3 way to create a Payment:

1) One-time-use Stripe Charge using a tokenized credit card
2) Use the default Credit Card belonging to the Airbrite Customer on the Order
3) Use a specific Credit Card belonging to the Airbrite Customer on the Order

When creating a Payment, you have the option of capturing funds immediately or placing an authorization on the payment card. If capture is not specified, it will default to capturing funds immediately.

__capture__ has 3 possible values: charge, authorize, hold
    charge - immediately capture the charge
    authorize - place an authorization on the charge
    hold - no-op, this just creates a stub payment allowing you to charge or authorize at a later time

Examples:

At order creation, use a one-time-use card token and capture funds immediately

 {
     ...,
     "payments": [{
         "gateway": "stripe",
         "amount": 1337,
         "currency": "usd",
         "capture": "charge",
         "card_token": "tok_XXXXXXXXXXXXXX"
     }],
     ...
 }

At order creation, place an authorization on the default card belonging to the customer (will drop off after ~7 days unless captured)

 {
     ...,
     "payments": [{
         "gateway": "stripe",
         "amount": 1337,
         "currency": "usd",
         "capture": "authorize"
     }],
     ...
 }

At order creation, place a hold (stub payment) on a specific card belonging to the customer

{ ..., "payments": [{ "gateway": "stripe", "amount": 1337, "currency": "usd", "capture": "hold", "customer_card_token": "card_XXXXXXXXXXXX" }], ... }

Endpoint

POST https://api.airbrite.io/v2/orders

Arguments

Required: none
Optional: customer, line_items, shipping_address, shipping, tax, discount, payments, shipments, status, description, metadata

Body

{
    "customer": {
        "name": "Jack Dagnels",
        "email": "jack@dagnels.ru"
    },
    "line_items": [
        {
            "sku": "12345ABC",
            "quantity": 1
        }
    ],
    "shipping_address": {
        "name": "Jack Dagnels",
        "phone": "4151234567",
        "line1": "123 Main St",
        "line2": "Unit 3A",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94105",
        "country": "US"  // two-letter ISO code
    },
    "tax": {
        "cost": 89
    },
    "shipping": {
        "cost": 595
    },
    "discount": {
        "cost": 500,
        "code": "5DOLLARSOFF"
    },
    "payments": [{
        "gateway": "stripe",
        "amount": 1337,
        "currency": "usd",
        "card_token": "tok_XXXXXXXXXXXXXX",
        "capture": "charge"
    }],
    "status": "open",
    "metadata": {
        "ref": "facebook"
    }
}

Retrieve order

Endpoint

GET https://api.airbrite.io/v2/orders/{ORDER_ID}

Arguments

Required: order_id
Optional: none

List all orders

Endpoint

GET https://api.airbrite.io/v2/orders

Arguments

Required: none
Optional: limit, skip, sort, order, since, until

Update order

To update an order (with the exception of customer, payments, and shipping), make a PUT request to the endpoint in this section. To create or update customer, payments, or shipments, use the following endpoints:

Endpoint

PUT https://api.airbrite.io/v2/orders/{ORDER_ID}

Arguments

Required: order_id
Optional: line_items, shipping_address, shipping, tax, discount, status, description, metadata

Payments

Arguments

_id:                  string (id)
user_id:              string (id)
order_id:             string (id)
created:              timestamp (Unix)
created_date:         timestamp (ISO_8601)
updated:              timestamp (Unix)
updated_date:         timestamp (ISO_8601)
currency:             string (3-letter ISO currency code)
gateway:              string
charge_token:         string
amount:               integer
customer_token:       string
customer_card_token:  string
capture:              string
paid:                 boolean
refunded:             boolean
captured:             boolean
charge_created:       timestamp (Unix)
processed:            boolean
card:                 object
                      Contains last4, type, exp_month, exp_year
billing_address:      object
metadata:             object
                      Store as many key-value pairs of extra data as you wish

Create payment

If you're creating a new charge, pass in the card_token.

Endpoint

POST https://api.airbrite.io/v2/orders/{ORDER_ID}/payments

Arguments

Required: order_id, gateway, currency, amount, card_token
Optional: capture, metadata

If you're adding an existing charge, pass in the charge_token.

Endpoint

POST https://api.airbrite.io/v2/orders/{ORDER_ID}/payments

Arguments

Required: order_id, gateway, charge_token
Optional: metadata

Retrieve payment

Endpoint

GET https://api.airbrite.io/v2/orders/{ORDER_ID}/payments/{PAYMENT_ID}

Arguments

Required: order_id, payment_id
Optional: none

List all payments

Endpoint

GET https://api.airbrite.io/v2/orders/{ORDER_ID}/payments

Arguments

Required: order_id
Optional: limit, skip, sort, order, since, until

Charge pre-order

This endpoint works if you previously created a payment stub (hold) and need to charge it.

Endpoint

POST https://api.airbrite.io/v2/orders/{ORDER_ID}/payments/{PAYMENT_ID}/charge

Arguments

Required: order_id, payment_id
Optional: none

Authorize payment

This endpoint works if you previously created a payment stub (hold) and need to place a hold / authorize the payment card.

Endpoint

POST https://api.airbrite.io/v2/orders/{ORDER_ID}/payments/{PAYMENT_ID}/authorize

Arguments

Required: order_id, payment_id
Optional: none

Capture payment

This endpoint works if you've previously authorized a charge.

Endpoint

POST https://api.airbrite.io/v2/orders/{ORDER_ID}/payments/{PAYMENT_ID}/capture

Arguments

Required: order_id, payment_id
Optional: none

Refund payment

Endpoint

POST https://api.airbrite.io/v2/orders/{ORDER_ID}/payments/{PAYMENT_ID}/refund

Arguments

Required: order_id, payment_id
Optional: amount

Shipments

Arguments

_id:                  string (id)
order_id:             string (id)
created:              timestamp (Unix)
created_date:         timestamp (ISO_8601)
updated:              timestamp (Unix)
updated_date:         timestamp (ISO_8601)
courier:              string
shipping_address:     object
tracking:             string
method:               string
status:               string
metadata:             object
                      Store as many key-value pairs of extra data as you wish

Create shipment

Endpoint

POST https://api.airbrite.io/v2/orders/{ORDER_ID}/shipments

Arguments

Required: order_id, line_items
Optional: courier, shipping_address, tracking, method, status, metadata

Retrieve shipment

Endpoint

GET https://api.airbrite.io/v2/orders/{ORDER_ID}/shipments/{SHIPMENT_ID}

Arguments

Required: order_id, shipment_id
Optional: none

List all shipments

Endpoint

GET https://api.airbrite.io/v2/orders/{ORDER_ID}/shipments

Arguments

Required: order_id
Optional: limit, skip, sort, order, since, until

Update shipment

Endpoint

PUT https://api.airbrite.io/v2/orders/{ORDER_ID}/shipments/{SHIPMENT_ID}

Arguments

Required: order_id, shipment_id
Optional: line_items, courier, shipping_address, tracking, method, status, metadata

Customers

Arguments

_id:                string
user_id:            string
created:            timestamp (Unix)
created_date:       timestamp (ISO_8601)
updated:            timestamp (Unix)
updated_date:       timestamp (ISO_8601)
name:               string
email:              string
addresses:          array
address:            object
default_address:    object
                    Contains name, line1, line2, city, state, zip, country, phone
card_token:         string
stripe:             object
stripe_customer_id: string
match:              string (e.g. email)
description:        string
metadata:           object
                    Store as many key-value pairs of extra data as you wish

Create customer

Endpoint

POST https://api.airbrite.io/v2/customers

Arguments

Required: none
Optional: name, email, match, card_token, stripe_customer_id, addresses, address, description, metadata

Retrieve customer

Endpoint

GET https://api.airbrite.io/v2/customers/{CUSTOMER_ID}

Arguments

Required: customer_id
Optional: none

List all customers

Endpoint

GET https://api.airbrite.io/v2/customers

Arguments

Required: none
Optional: limit, skip, sort, order, since, until

Update customer

Please note that if you update an existing Airbrite customer with stripe_customer_id, it will replace the previous values of the customer.

Endpoint

PUT https://api.airbrite.io/v2/customers/{CUSTOMER_ID}

Arguments

Required: customer_id
Optional: name, email, match, card_token, stripe_customer_id, addresses, address, description, metadata

Tax

Arguments

zip:           zip
amount:        integer
nexus_zips:    string
tax_amount:    integer
tax_rate:      float
state_rate:    float
county_rate:   float
city_rate:     float
special_rate:  float

To calculate sales tax, you should add your business' zip codes in your account settings. Otherwise, you must specify them as part of the request.

Retrieve sales tax

Endpoint

GET https://api.airbrite.io/v2/tax

Arguments

Required: zip
Optional: amount, nexus_zips (comma separated)

Body

{
    "meta": {
        "code": 200,
    },
    "data": {
        "amount": "1000",
        "tax_amount": "88",
        "tax_rate": "0.0875",
        "state_rate": "0.065",
        "county_rate": "0.01",
        "city_rate": "0",
        "special_rate": "0.0125"
    }
}

Account

Retrieve account

Endpoint

GET https://api.airbrite.io/v2/account

Arguments

Required: none
Optional: none

Events

Events are our way of letting you know about something interesting that has just happened in your account. When an interesting event occurs, we create a new event object. For example, when a payment is successfully charged, we create a order.payment.succeeded event. Note that many API requests may cause multiple events to be created.

Like our other API resources, you can retrieve an individual event or a list of events from the API. We also have a system for sending the events directly to your server, called webhooks. Webhooks are managed in your account settings.

Retrieve event

Endpoint

GET https://api.airbrite.io/v2/events/{EVENT_ID}

Arguments

Required: event_id
Optional: none

List all events

Endpoint

GET https://api.airbrite.io/v2/events

Arguments

Required: none
Optional: limit, skip, sort, order, since, until

Types of events

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.

You'll notice that these events follow a pattern: resource.event. Our goal is to design a consistent system that makes things easier to anticipate and code against.

Events

customer.created
customer.updated
order.created
order.updated
order.payment.succeeded
order.payment.authorized
order.payment.captured
order.payment.refunded
order.shipment.created
order.shipment.updated
product.created
product.updated

adamantivm/airbrite-api

Airbrite API

Introduction

Getting Started

Authentication

Organization

Response Format

Errors

Webhooks

Resource Methods

List of Routes

Products

Create product

Retrieve product

List all products

Update product

Orders

Create Order

Retrieve order

List all orders

Update order

Payments

Create payment

Retrieve payment

List all payments

Charge pre-order

Authorize payment

Capture payment

Refund payment

Shipments

Create shipment

Retrieve shipment

List all shipments

Update shipment

Customers

Create customer

Retrieve customer

List all customers

Update customer

Tax

Retrieve sales tax

Account

Retrieve account

Events

Retrieve event

List all events

Types of events