NAV Navbar
shell ruby
  • Topics
  • Introduction
  • Authentication
  • Pagination
  • Errors
  • Webhooks
  • Resources
  • Coupons
  • Orders
  • Products
  • Product Groups
  • Queries
  • Selly Pay
  • Introduction

    Welcome to the Selly API. You can use our API to access Selly API endpoints to build your own systems on top of our platform.

    We have official API wrappers in Shell, Ruby. You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

    Authentication

    To authorize, use this code:

    curl "https://selly.gg/api/v2/"
      -H "Authorization: Basic eW91cmVtYWlsOnRoaXNpc3lvdXJBUElLZXk="
    
    require 'selly'
    
    # This library will automatically handle the Authorization header and encoding it
    Selly.api_key = 'your api key'
    Selly.api_email = 'your account email'
    

    Make sure to use the correct API authentication attributes

    Selly uses API keys via the Authorization header to allow access to the API. You can retrieve and receive a new Selly API key at your settings page.

    The Authorization header is made up of your account's email and API key in the format email:api_key and then encoded via base64.

    Selly expects a valid Authorization header to be included in all requests and that it looks like the following:

    Authorization: Basic eW91cmVtYWlsOnRoaXNpc3lvdXJBUElLZXk=

    In this example, if we decode the string we'll receive youremail:thisisyourAPIKey which when split would mean that the email provided is youremail and the API key is thisisyourAPIKey.

    Pagination

    An example of paginating orders:

    curl "https://selly.gg/api/v2/orders?page=10"
      -H "Authorization: Basic eW91cmVtYWlsOnRoaXNpc3lvdXJBUElLZXk="
    
    Selly::Orders::List(page: 10)
    

    Selly offers the ability to paginate any list or index resource. The X-Total-Pages header returns the total number of pages for the resources at the specific endpoint you're using.

    Query Parameters

    Parameter Default Description
    page 1 Used for pagination

    Errors

    Errors are returned in a JSON structured like this:

    {
      "message": "Order not found",
    }
    

    Validation errors also have an errors attribute

    {
      "message": "Validation failed",
      "errors": {
        "title": ["must be present"] 
      }
    }
    

    The errors attribute may also be a array if there are multiple errors stacked

    The Selly API uses the following error codes:

    Status Code Meaning
    400 Bad Request - Invalid parameters
    401 Unauthorized - Unable to authenticate
    403 Forbidden - The request is not allowed
    404 Not Found - The specified resource could not be found.
    406 Not Acceptable - You requested a format that isn't json.
    429 Too Many Requests - You have reached the rate limit
    500 Internal Server Error - We had a problem with our server. Try again later. These are rare.
    503 Service Unavailable - We're temporarily offline for maintenance. Please try again later.

    Webhooks

    A example webhook notification on a paid order event

    {
        "id": "fd87d909-fbfc-466c-964a-5478d5bc066a",
        "product_id": "upgrade",
        "email": "alishia@yahoo.com",
        "ip_address": "88.96.129.5",
        "country_code": "US",
        "user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/43.0.2357.124 Safari/537.36",
        "value": "0.03",
        "currency": "USD",
        "gateway": "Bitcoin",
        "risk_level": 10,
        "status": 100,
        "delivered": "SERIAL-12345-12345",
        "crypto_value": null,
        "crypto_address": null,
        "referral": null,
        "usd_value": "0.03",
        "exchange_rate": "1.0",
        "custom": {},
        "webhook_type": 1,
        "created_at": "2016-11-27T14:20:34.000Z",
        "updated_at": "2016-12-05T21:31:15.000Z"
      }
    

    Webhooks are a HTTP callback event that is sent to the Webhook URL specified for the affected order. All webhook requests are sent as a POST request and are handled independently from the event, asynchronously.

    The content sent in the webhook is a JSON object of the resource that the webhook is related to. If it was a order webhook, a order object will be sent.

    Each webhook request contains a webhook_type parameter

    Webhooks can be simulated via our webhook simulator.

    Webhook Type Meaning
    1 Order paid
    2 Order chargeback/reversal
    3 Dynamic product
    4 Product out of stock
    5 Product reached stock warning level

    Coupons

    Coupon Object

    {
        "id": "ba6a15",
        "code": "25OFF",
        "discount": 25,
        "max_uses": null,
        "product_ids": ["ac24a3"],
        "uses": 0,
        "created_at": "2016-05-15T14:02:47.000Z",
        "updated_at": "2017-08-12T23:37:13.000Z"
    }
    

    Attributes

    Get All Coupons

    curl "https://selly.gg/api/v2/coupons"
      -H "Authorization: Basic eW91cmVtYWlsOnRoaXNpc3lvdXJBUElLZXk="
    

    The above command returns JSON structured like this:

    [
        {
            "id": "ba6a15",
            "title": "Awesome Product Group",
            "discount": 25,
            "max_uses": null,
            "product_ids": ["ac24a3"],
            "uses": 0,
            "created_at": "2016-05-15T14:02:47.000Z",
            "updated_at": "2017-08-12T23:37:13.000Z"
        },
        {
            "id": "12abc3e",
            "title": "Another Product Group",
            "discount": 25,
            "max_uses": null,
            "product_ids": ["ac24a3"],
            "uses": 0,
            "created_at": "2016-05-15T14:02:47.000Z",
            "updated_at": "2017-08-12T23:37:13.000Z"
        }
    ]
    

    This endpoint retrieves all coupons.

    HTTP Request

    GET https://selly.gg/api/v2/coupons

    Query Parameters

    Parameter Default Description
    page 1 Used for pagination

    Get a Specific Coupon

    curl "https://selly.gg/api/v2/coupons/ba6a15"
      -H "Authorization: Basic eW91cmVtYWlsOnRoaXNpc3lvdXJBUElLZXk="
    

    The above command returns JSON structured like this:

    {
        "id": "ba6a15",
        "code": "25OFF",
        "discount": 25,
        "max_uses": null,
        "product_ids": ["ac24a3"],
        "created_at": "2016-05-15T14:02:47.000Z",
        "updated_at": "2017-08-12T23:37:13.000Z"
    }
    

    This endpoint retrieves a specific coupon.

    HTTP Request

    GET https://selly.gg/api/v2/coupons/:ID

    URL Parameters

    Parameter Description
    ID The ID of the coupon to retrieve

    Orders

    Order Object

    {
        "id": "fd87d909-fbfc-466c-964a-5478d5bc066a",
        "product_id": "upgrade",
        "email": "alishia@yahoo.com",
        "ip_address": "88.96.129.5",
        "country_code": "US",
        "user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/43.0.2357.124 Safari/537.36",
        "value": "0.03",
        "currency": "USD",
        "gateway": "Bitcoin",
        "risk_level": 10,
        "status": 100,
        "delivered": "SERIAL-12345-12345",
        "crypto_value": null,
        "crypto_address": null,
        "referral": null,
        "usd_value": "0.03",
        "exchange_rate": "1.0",
        "custom": {
          "0": "SomeInput"
        },
        "created_at": "2016-11-27T14:20:34.000Z",
        "updated_at": "2016-12-05T21:31:15.000Z"
      }
    

    Attributes

    Get All Orders

    Selly::Orders.list
    
    curl "https://selly.gg/api/v2/orders"
      -H "Authorization: Basic eW91cmVtYWlsOnRoaXNpc3lvdXJBUElLZXk="
    

    The above command returns JSON structured like this:

    [
        {
        "id": "89ac7499-efc3-4f5b-a2fd-c00fec6aa480",
        "product_id": "ac24a3",
        "email": "john@gmail.com",
        "ip_address": "132.26.9.4",
        "country_code": "US",
        "user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/53.0.2357.124 Safari/537.36",
        "value": "0.03",
        "currency": "USD",
        "gateway": "Bitcoin",
        "risk_level": 9,
        "status": 0,
        "delivered": null,
        "crypto_value": null,
        "crypto_address": null,
        "referral": null,
        "usd_value": "0.03",
        "exchange_rate": "1.0",
        "custom": {
          "0": "MyUsername"
        },
        "created_at": "2015-06-11T18:32:01.000Z",
        "updated_at": "2017-02-14T17:47:27.000Z"
      },
      {
        "id": "fd87d909-fbfc-466c-964a-5478d5bc066a",
        "product_id": "upgrade",
        "email": "alishia@yahoo.com",
        "ip_address": "88.96.129.5",
        "country_code": "US",
        "user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/43.0.2357.124 Safari/537.36",
        "value": "0.03",
        "currency": "USD",
        "gateway": "Bitcoin",
        "risk_level": 10,
        "status": 100,
        "delivered": "SERIAL-12345-12345",
        "crypto_value": null,
        "crypto_address": null,
        "referral": null,
        "usd_value": "0.03",
        "exchange_rate": "1.0",
        "custom": {
          "0": "SomeInput"
        },
        "created_at": "2016-11-27T14:20:34.000Z",
        "updated_at": "2016-12-05T21:31:15.000Z"
      }
    ]
    

    This endpoint retrieves all orders.

    HTTP Request

    GET https://selly.gg/api/v2/orders

    Query Parameters

    Parameter Default Description
    page 1 Used for pagination

    Get a Specific Order

    Selly::Orders.get('fd87d909-fbfc-466c-964a-5478d5bc066a')
    
    curl "https://selly.gg/api/v2/orders/fd87d909-fbfc-466c-964a-5478d5bc066a"
      -H "Authorization: Basic eW91cmVtYWlsOnRoaXNpc3lvdXJBUElLZXk="
    

    The above command returns JSON structured like this:

    {
        "id": "fd87d909-fbfc-466c-964a-5478d5bc066a",
        "product_id": "upgrade",
        "email": "alishia@yahoo.com",
        "ip_address": "88.96.129.5",
        "country_code": "US",
        "user_agent": "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/43.0.2357.124 Safari/537.36",
        "value": "0.03",
        "currency": "USD",
        "gateway": "Bitcoin",
        "risk_level": 10,
        "status": 100,
        "delivered": "SERIAL-12345-12345",
        "crypto_value": null,
        "crypto_address": null,
        "referral": null,
        "usd_value": "0.03",
        "exchange_rate": "1.0",
        "custom": {
          "0": "SomeInput"
        },
        "created_at": "2016-11-27T14:20:34.000Z",
        "updated_at": "2016-12-05T21:31:15.000Z"
      }
    

    This endpoint retrieves a specific order.

    HTTP Request

    GET https://selly.gg/api/v2/orders/:ID

    URL Parameters

    Parameter Description
    ID The ID of the order to retrieve

    Products

    Product Object

    {
        "id": "ac24a3",
        "title": "Awesome Product",
        "description": "My description",
        "stock": 2094,
        "price": "0.5",
        "currency": "EUR",
        "product_type": 2,
        "bitcoin": true,
        "paypal": true,
        "stripe": true,
        "litecoin": true,
        "dash": true,
        "ethereum": true,
        "perfect_money": true,
        "bitcoin_cash": true,
        "private": false,
        "unlisted": true,
        "seller_note": "Thanks for buying my product",
        "maximum_quantity": null,
        "minimum_quantity": 1,
        "custom": {},
        "created_at": "2016-05-15T14:02:47.000Z",
        "updated_at": "2017-08-12T23:37:13.000Z"
    }
    

    Attributes

    Get All Products

    Selly::Products.list
    
    curl "https://selly.gg/api/v2/products"
      -H "Authorization: Basic eW91cmVtYWlsOnRoaXNpc3lvdXJBUElLZXk="
    

    The above command returns JSON structured like this:

    [
        {
            "id": "ac24a3",
            "title": "Awesome Product",
            "description": "My description",
            "stock": 2094,
            "price": "0.5",
            "currency": "EUR",
            "product_type": 2,
            "bitcoin": true,
            "paypal": true,
            "stripe": true,
            "litecoin": true,
            "dash": true,
            "ethereum": true,
            "perfect_money": true,
            "bitcoin_cash": true,
            "private": false,
            "unlisted": true,
            "seller_note": "Thanks for buying my product",
            "maximum_quantity": null,
            "minimum_quantity": 1,
            "custom": {},
            "created_at": "2016-05-15T14:02:47.000Z",
            "updated_at": "2017-08-12T23:37:13.000Z"
        },
        {
            "id": "d8b3cdb7",
            "title": "Dynamic E-book",
            "description": "Testing the description",
            "stock": "∞",
            "price": "1.0",
            "currency": "USD",
            "product_type": 3,
            "bitcoin": true,
            "paypal": true,
            "stripe": true,
            "litecoin": false,
            "dash": false,
            "ethereum": false,
            "perfect_money": false,
            "bitcoin_cash": false,
            "private": true,
            "unlisted": true,
            "seller_note": "",
            "maximum_quantity": null,
            "minimum_quantity": 1,
            "custom": {},
            "created_at": "2017-03-25T20:12:20.000Z",
            "updated_at": "2017-03-25T20:14:14.000Z"
        }
    
    ]
    

    This endpoint retrieves all products.

    HTTP Request

    GET https://selly.gg/api/v2/products

    Query Parameters

    Parameter Default Description
    page 1 Used for pagination

    Get a Specific Product

    Selly::Products.get('ac24a3')
    
    curl "https://selly.gg/api/v2/products/ac24a3"
      -H "Authorization: Basic eW91cmVtYWlsOnRoaXNpc3lvdXJBUElLZXk="
    

    The above command returns JSON structured like this:

    {
        "id": "ac24a3",
        "title": "Awesome Product",
        "description": "My description",
        "stock": 2094,
        "price": "0.5",
        "currency": "EUR",
        "product_type": 2,
        "bitcoin": true,
        "paypal": true,
        "stripe": true,
        "litecoin": true,
        "dash": true,
        "ethereum": true,
        "perfect_money": true,
        "bitcoin_cash": true,
        "private": false,
        "unlisted": true,
        "seller_note": "Thanks for buying my product",
        "maximum_quantity": null,
        "minimum_quantity": 1,
        "custom": {},
        "created_at": "2016-05-15T14:02:47.000Z",
        "updated_at": "2017-08-12T23:37:13.000Z"
    }
    

    This endpoint retrieves a specific product.

    HTTP Request

    GET https://selly.gg/api/v2/products/:ID

    URL Parameters

    Parameter Description
    ID The ID of the product to retrieve

    Dynamic Products

    The Dynamic product type is a product type that is fetched externally. Selly will send a Webhook to the dynamic_url and will set the delivered_info of the Order to be the plain text response truncated to 500 characters.

    A common use case of a dynamic product would be license generation or any product that must be generated.

    Product Groups

    Product Group Object

    {
        "id": "ba6a15",
        "title": "Awesome Product Group",
        "product_ids": ["ac24a3"],
        "created_at": "2016-05-15T14:02:47.000Z",
        "updated_at": "2017-08-12T23:37:13.000Z"
    }
    

    Attributes

    Get All Product Groups

    Selly::ProductGroups.list
    
    curl "https://selly.gg/api/v2/product_groups"
      -H "Authorization: Basic eW91cmVtYWlsOnRoaXNpc3lvdXJBUElLZXk="
    

    The above command returns JSON structured like this:

    [
        {
            "id": "ba6a15",
            "title": "Awesome Product Group",
            "product_ids": ["ac24a3"],
            "created_at": "2016-05-15T14:02:47.000Z",
            "updated_at": "2017-08-12T23:37:13.000Z"
        },
        {
           "id": "12abc3e",
           "title": "Another Product Group",
           "product_ids": ["ac24a3", "32156a"],
           "created_at": "2016-05-15T14:02:47.000Z",
           "updated_at": "2017-08-12T23:37:13.000Z"
        }
    ]
    

    This endpoint retrieves all product groups.

    HTTP Request

    GET https://selly.gg/api/v2/product_groups

    Query Parameters

    Parameter Default Description
    page 1 Used for pagination

    Get a Specific Product Group

    Selly::ProductGroups.get('ba6a15')
    
    curl "https://selly.gg/api/v2/product_groups/ba6a15"
      -H "Authorization: Basic eW91cmVtYWlsOnRoaXNpc3lvdXJBUElLZXk="
    

    The above command returns JSON structured like this:

    {
        "id": "ba6a15",
        "title": "Awesome Product Group",
        "product_ids": ["ac24a3"],
        "created_at": "2016-05-15T14:02:47.000Z",
        "updated_at": "2017-08-12T23:37:13.000Z"
    }
    

    This endpoint retrieves a specific product group.

    HTTP Request

    GET https://selly.gg/api/v2/product_groups/:ID

    URL Parameters

    Parameter Description
    ID The ID of the product group to retrieve

    Queries

    Query Object

    {
        "id": "7xailomk",
        "secret": "ZevjsxefmknThE1LycJp7HAYZbGv4MNL3bcWU78Wzqxaw4CL7w",
        "title": "Help needed",
        "email": "demo@example.com",
        "message": "Do you have a coupon?",
        "status": 3,
        "country_code": "US",
        "ip_address": "10.0.2.2",
        "avatar_url": "https://camo.selly.gg/6c8b3527c682dcc614b5075218a1bce1b7f044b2/68747470733a2f2f67726176617461722e636f6d2f6176617461722f34303137383332333264396632303561306263333033663464313166633233352e706e673f733d31303026643d68747470733a2f2f73656c6c792e67672f696d616765732f64656661756c742d6176617461722e706e67",
        "created_at": "2017-12-29T00:21:53.000Z",
        "updated_at": "2017-12-29T13:31:08.000Z"
    }
    

    Attributes

    Get All Queries

    curl "https://selly.gg/api/v2/queries"
      -H "Authorization: Basic eW91cmVtYWlsOnRoaXNpc3lvdXJBUElLZXk="
    

    The above command returns JSON structured like this:

    [
        {
            "id": "yJni9oAy",
            "secret": "6Rkvz8Zpqo5vu23RSTtvrBQzx76q5a6_BVHvQBgsdR1DpE3esg",
            "title": "Product help",
            "email": "demo@example.com",
            "message": "Does this product include a manual?",
            "status": 3,
            "country_code": "US",
            "ip_address": "10.0.2.2",
            "avatar_url": "https://camo.selly.gg/6c8b3527c682dcc614b5075218a1bce1b7f044b2/68747470733a2f2f67726176617461722e636f6d2f6176617461722f34303137383332333264396632303561306263333033663464313166633233352e706e673f733d31303026643d68747470733a2f2f73656c6c792e67672f696d616765732f64656661756c742d6176617461722e706e67",
            "created_at": "2017-12-29T00:21:53.000Z",
            "updated_at": "2017-12-29T13:31:08.000Z"
        },
        {
            "id": "7xailomk",
            "secret": "ZevjsxefmknThE1LycJp7HAYZbGv4MNL3bcWU78Wzqxaw4CL7w",
            "title": "Help needed",
            "email": "demo@example.com",
            "message": "Do you have a coupon?",
            "status": 3,
            "country_code": "US",
            "ip_address": "10.0.2.2",
            "avatar_url": "https://camo.selly.gg/6c8b3527c682dcc614b5075218a1bce1b7f044b2/68747470733a2f2f67726176617461722e636f6d2f6176617461722f34303137383332333264396632303561306263333033663464313166633233352e706e673f733d31303026643d68747470733a2f2f73656c6c792e67672f696d616765732f64656661756c742d6176617461722e706e67",
            "created_at": "2017-12-29T00:21:53.000Z",
            "updated_at": "2017-12-29T13:31:08.000Z"
        }
    ]
    

    This endpoint retrieves all queries.

    HTTP Request

    GET https://selly.gg/api/v2/queries

    Query Parameters

    Parameter Default Description
    page 1 Used for pagination

    Get a Specific Query

    curl "https://selly.gg/api/v2/queries/7xailomk"
      -H "Authorization: Basic eW91cmVtYWlsOnRoaXNpc3lvdXJBUElLZXk="
    

    The above command returns JSON structured like this:

    {
        "id": "7xailomk",
        "secret": "ZevjsxefmknThE1LycJp7HAYZbGv4MNL3bcWU78Wzqxaw4CL7w",
        "title": "Help needed",
        "email": "demo@example.com",
        "message": "Do you have a coupon?",
        "status": 3,
        "country_code": "US",
        "ip_address": "10.0.2.2",
        "avatar_url": "https://camo.selly.gg/6c8b3527c682dcc614b5075218a1bce1b7f044b2/68747470733a2f2f67726176617461722e636f6d2f6176617461722f34303137383332333264396632303561306263333033663464313166633233352e706e673f733d31303026643d68747470733a2f2f73656c6c792e67672f696d616765732f64656661756c742d6176617461722e706e67",
        "query_message": [  
            {  
             "message": "No coupons are currently available.",
             "is_seller": true,
             "created_at": "2017-12-30T02:28:57.000Z",
             "updated_at": "2017-12-30T02:28:57.000Z"
            }
        ],
        "created_at": "2017-12-29T00:21:53.000Z",
        "updated_at": "2017-12-29T13:31:08.000Z"
    }
    

    This endpoint retrieves a specific query.

    HTTP Request

    GET https://selly.gg/api/v2/queries/:ID

    URL Parameters

    Parameter Description
    ID The ID of the query to retrieve

    Selly Pay

    Selly Pay provides a method of implementing a realtime checkout experience for any e-commerce platform and supporting a range of payment methods in one place.

    With Selly Pay there is no Product that the order bases some information off, which allows for complete access to our payment systems without having to create a unique Product for every alteration a Payment may have. This also means that Selly does not handle any delivery of the "product" purchased, we'll only send a Webhook.

    For the gateway chosen in the Payment, you must have the correct information (e.g your Bitcoin address if the gateway is Bitcoin) set in your settings.

    For each Payment a unique URL will be returned. The customer will have to be redirected to this URL in order to access the checkout page.

    Create a Payment

    curl -X POST "https://selly.gg/api/v2/pay"
      -H "Authorization: Basic eW91cmVtYWlsOnRoaXNpc3lvdXJBUElLZXk="
      -d '{"title:"Selly Pay Example", "gateway":"Bitcoin", "email":"customer@email.com", "value":"10", "currency":"USD", "return_url":"https://website.com/return", "webhook_url":"https://website.com/webhook?secret=cEZMeEVlTz"}'
    
    Selly::Pay.create(
      title: 'Selly Pay Example',
      gateway: 'Bitcoin',
      email: 'customer@email.com',
      value: 10.00,
      currency: 'USD',
      return_url: 'https://website.com/return',
      webhook_url: 'https://website.com/webhook?secret=cEZMeEVlTz'
    )
    

    The above command returns JSON structured like this:

    {
        "url": "https://selly.gg/pay/81971eae19ff0924026d7b2a7502b20372c15df5/bGU3Q09QSGtDNjR2cHJMYzhHdTd6Mm40bXpFNVdZOEtlaW9NckRySmxsVkZOSjhkb3N0SVM0cVF6UDJtU0NjejVrT0Q4ZFZKY1JVbi9ZTjJaSDhGRXc9PS0tdW5zUGptYjcrSGZSRjF5K0VmNUFNZz09--68ab83743fa057629b09bb9c7330841e54442784"
    }
    

    The customer should be redirected to this URL to activate the checkout experience. Click here for a preview

    Attributes

    Delete a Payment

    The ID is the first path on the URL returned when creating a payment. The ID for the above example is as follows:

    Selly::Pay.destroy('81971eae19ff0924026d7b2a7502b20372c15df5')
    
    curl -X DELETE "https://selly.gg/api/v2/pay/81971eae19ff0924026d7b2a7502b20372c15df5"
      -H "Authorization: Basic eW91cmVtYWlsOnRoaXNpc3lvdXJBUElLZXk="
    

    The above command returns JSON structured like this:

    {
        "status": true
    }
    

    This endpoint deletes a Selly Pay payment

    HTTP Request

    DELETE https://selly.gg/api/v2/pay/:ID