Skip to content

amerk84-zz/airbrite-api

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

73 Commits
getting-started
getting-started
 
 
README.md
README.md
 
 

Repository files navigation

Airbrite API

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.

  1. Authorization: {ACCESS_TOKEN}
  2. Authorization: Basic {BASE64_ENCODED_ACCESS_TOKEN}
  3. 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}.

These resources have full CRUD support:

  • Products
  • Orders
  • Customers

These resources have read-only CRUD support:

  • Events

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
    • Webhooks

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 and filters will respond with paging information about the collection. These are read from the passed in query string and can be mixed and matched as necessary.

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

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 charge 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."
}

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: none

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
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
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 the "customer" connection with the customer _id:

{
    "customer": {
        "_id": "XXXXXXXXXXXXXXXXXXXXXXXX"
    }
}

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, auth, hold
    charge - immediately capture the charge
    auth - place an authorization on the charge
    hold - no-op, this just creates a stub payment allowing you to charge or auth at a later time

Examples:

  1. 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"
     }],
     ...
 }

  2. 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": "auth"
     }],
     ...
 }

  3. 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
user_id:              string
order_id:             string
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
description:          string
metadata:             object
                      Store as many key-value pairs of extra data as you wish

Create payment

  1. 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
  1. 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

Capture payment

Endpoint

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

Arguments

Required: order_id, payment_id
Optional: none

Refund payment

Endpoint

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

Arguments

Required: order_id, payment_id
Optional: amount

Shipments

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, 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

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
default_address:  object
                  Contains name, line1, line2, city, state, zip, country, phone
card_token:       string
stripe:           object
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, card_token, addresses, shipping_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

Endpoint

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

Arguments

Required: customer_id
Optional: name, email, card_token, addresses, shipping_address, description, metadata

Tax

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
  • product.created
  • product.updated

About

Airbrite API documentation

www.airbriteinc.com

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published