Helium Documentation

REST API

The Helium REST API available to developers is the same API that Helium is built on; it powers both Helium.js and user dashboard. Each request returns JSON, and uses HTTP response codes to communicate successful requests and/or errors.

Authentication

Each request to the API must be made over HTTPS and must use HTTP basic authentication with your private key. You can find your private key in Settings.

You should never share your private key. If you suspect that your key may have been compromised, you can also reset it in Settings.

Example: Making an authenticated request using Curl

curl https://gethelium.com/api/v1/items/ \
    -u YOUR PRIVATE KEY:

Items

https://gethelium.com/api/v1/items/{SKU}

This resource represents items (products) that you plan to sell.

The Item Object

As returned by GET and PUT methods.

sku
The unique identifier you chose for this item
price
This is the price (in cents) that item is selling for
name
The name of this item, as visible to the customer
type
“general”, “file”, or “plan”
The name of this item, as visible to the customer
file
If the item type is “file”, this object describes the file. This file will be sent to the customer upon order completion
name
The name of the file
size
The size of the file, in bytes
location
The URL where you can view/download the file
interval
“month” or “year”
If the item type is “plan” (subscription), this represents the period on which the user will be billed

GET

If no SKU is defined, returns a list of all items. To filter the items returned, you can add one of more SKUs (delimited by semicolons) to the URL

Parameters

None

Example: Returns a list of all items

>> curl https://gethelium.com/api/v1/items/ \
    -u YOUR PRIVATE KEY:
>> [
    {
        "sku": "product-1",
        "name": "Breath Mints",
        "price": 100,
        "type": "general"
    },
    {
        "sku": "product-2",
        "name": "Story of My Life",
        "price": 999,
        "type": "file",
        "file": {
            "name": "my-book.epub",
            "location": "/api/v1/items/product-2/file"
        }
    },
    {
        "sku": "product-3",
        "name": "Monthly Newsletter",
        "price": 50,
        "type": "plan",
        "interval": "month"
    }
]

Example: Returns only items “product-1” and “product-3”

>> curl https://gethelium.com/api/v1/items/product-1;product-3/ \
    -u YOUR PRIVATE KEY:
>> [
    {
        "sku": "product-1",
        "name": "Breath Mints",
        "price": 100,
        "type": "general"
    },
    {
        "sku": "product-3",
        "name": "Monthly Newsletter",
        "price": 50,
        "type": "plan",
        "interval": "month"
    }
]

PUT

To create a new item, or to edit an existing item, call PUT on this resource.

If the PUT is successful, the newly created/updated item will be returned. If there is an error, a description of the fields in error is returned.

Below is a list of the applicable parameters. Note, if you are calling a PUT on an item that already exists, you should only send across the parameters for which you are modifying.

Note, for subscriptions (that is, items where type="plan"), you may only alter the item’s name after its been created. You can't alter its price or interval. If you need to alter these values, simply create an item with a new SKU and new values.

Parameters

price
required
Price is always communicated in cents (i.e., price=100 is $1)
name
required
The name of this item, as visible to the customer
type
required “general”, “file”, or “plan”
The name of this item, as visible to the customer
file
required if type="file"
This is the file that the customer will be purchasing. Note that the file's name will be kept intact
interval
required if type="plan" "month" or "year"
If the item type is “plan” (subscription), this represents the period on which the user will be billed

Example: Creating a new item

>> curl https://gethelium.com/api/v1/items/product-4 \
    -u YOUR PRIVATE KEY:
    -X PUT
    -d "name=Breath Mints (jumbo pack)"
    -d "price=200"
    -d "type=general"
>>  {
        "sku": "product-4",
        "name": "Breath Mints (jumbo pack)",
        "price": 200,
        "type": "general"
    }

Example: Editing the price of an item

>> curl https://gethelium.com/api/v1/items/product-4 \
    -u YOUR PRIVATE KEY:
    -X PUT
    -d "price=400"
>>  {
        "sku": "product-4",
        "name": "Breath Mints (jumbo pack)",
        "price": 400,
        "type": "general"
    }

Example: Bad request, missing required values

>> curl https://gethelium.com/api/v1/items/product-5 \
    -u YOUR PRIVATE KEY:
    -X PUT
    -d "name=Something random"
>>  {
        "errors": {
            "price": "Price is required and must be at least 50",
            "type": "Item type is required"
        }
    }

DELETE

Deletes an item. Once deleted, the item can no longer be purchased by customers. If successful, this resource will return an HTTP response code of 204 and nothing will be returned in its body.

Example: Deleting an item

>> curl https://gethelium.com/api/v1/items/product-1 \
    -u YOUR PRIVATE KEY:
    -X DELETE
>>

Charges

https://gethelium.com/api/v1/charges/{ID}

This resource represents charges to customers’ credit cards (orders).

The Charge Object

id
The unique ID for this charge
created
The timestamp (seconds from the epoch) at which this charge was created
amount
The total order amount (all items + shipping, in cents)
customer
Describes the customer as:
id
The customer’s email address.
card
Unique ID for the customer
address
If the customer supplied an address, it’s represented as:
recipient
The name of the recipient
street
Street address (e.g. “123 Main St.”)
city
The city (e.g. “San Francisco”)
state
The state (2 character abbreviation, e.g. “CA”)
zipcode
The zip code (e.g. “94118”)
items
An array of items purcahsed. Each item is represented as:
sku
The item’s unique SKU
name
The name of this item
price
The price paid for this item
card
Describes the credit card used for this purchase as:
type
The type of credit card (e.g. Visa, MasterCard, etc)
last4
The last 4 digits of the credit card number
shipping
The amount paid for shipping, in cents
fee
The application fee for this charge, in cents

GET

If no ID is defined, returns a list charges ordered by most recent to oldest. Specify an ID to retrieve only a given charges information.

Get Parameters

page
Optional default is 1
Controls pagination. Each page contains 10 charges ordered from newest to oldest. That is, page 1 contains the 10 most recent charges.
customer.email
Optional
Filter charges by the email address of the customer.

Example: Returns a list of all charges

>> curl https://gethelium.com/api/v1/charges/ \
    -u YOUR PRIVATE KEY:
>> [
    {
      "id": "NY3U2V5U9E2",
      "card": {
        "last4": "4242",
        "type": "Visa"
      },
      "customer": {
        "id": "LU1U2V5U9E2",
        "email": "demo@gmail.com"
      },
      "fee": 0,
      "created": 1351890105,
      "items": [
        {"sku": "laptop-stand", "price": 19900, "name": "Laptop Stand"},
        {"sku": "laptop-bag", "price": 9900, "name": "Laptop Bag"}
      ],
      "live": 1,
      "shipping": 0,
      "amount": 398
    }
]

Use of this site and associated services acknowledges your acceptance of the GDPR / Terms of Service