NAV
shell

Introduction

API Endpoint

https://plugin.buycraft.net

Welcome to the Buycraft Plugin API documentation.

The Plugin API is for implementing command execution on Minecraft Servers or other custom clients - an example of this would be the official Buycraft Bukkit Plugin.

Are you a developer? If you’ve created an SDK in your favourite language we’d love to officially support it. Drop us an email via support@buycraft.net.

Authentication

To access the API all requests need to be authenticated via a Servers secret key.

Supply the secret key by setting the X-Buycraft-Secret header in all requests to the API.

Error Handling

Example Error

{
  "error_code": 403,
  "error_message": "No server could be found with the specified secret key."
}

Errors are JSON format and are based around the standard HTTP status codes.

For example when an invalid secret key is provided the HTTP status code 403 Forbidden will be returned along with the JSON error as shown on the right.

The error_message object will always be user friendly and should be shown directly to the client.

Information

Endpoint

GET https://plugin.buycraft.net/information

Example Request

curl -X GET -H 'X-Buycraft-Secret: b510b084c9b7ca746c8713ade7003cc6ea6279dc' "https://plugin.buycraft.net/information"

Example Response

{
  "account": {
    "id": 123,
    "domain": "http://example.buycraft.net",
    "name": "Example Webstore",
    "currency": {
      "iso_4217": "GBP",
      "symbol": "£"
    },
    "online_mode": true
  },
  "server": {
    "id": 123,
    "name": "Minecraft Server"
  },
  "analytics": {
    "internal": {
      "project": "<internal usage only>",
      "key": "<internal usage only>"
    }
  }
}

Returns general information about the authenticated account and server.

Command Queue

Get due players

Endpoint

GET https://plugin.buycraft.net/queue

Example Request

curl -X GET -H 'X-Buycraft-Secret: b510b084c9b7ca746c8713ade7003cc6ea6279dc' "https://plugin.buycraft.net/queue"

Example Response

{
  "meta": {
    "execute_offline": false,
    "next_check": 90,
    "more": false
  },
  "players": [
    {
      "id": 1,
      "name": "Notch",
      "uuid": "365bfa21803249ee9b634fe890c9d43f"
    },
    {
      "id": 2,
      "name": "7n",
      "uuid": "ef01f2da1b284ad6ba8ba2aaf4432e22"
    },
    {
      "id": 3,
      "name": "hfmx",
      "uuid": "897a2737777a4776909a0148919c376a"
    }
  ]
}

List the players who have commands due to be executed when they next login to the Minecraft Server. This endpoint also returns if there are any offline commands to be processed and the amount of seconds to wait before performing the queue check again. All clients should strictly follow the response of next_check, failure to do so would result in your secret key being revoked or IP address being banned from accessing the API.

Results are paginated using the page and limit request parameters. The more parameter returned in the response body indicates if there is another page to request.

Get offline commands

Endpoint

GET https://plugin.buycraft.net/queue/offline-commands

Example Request

curl -X GET -H 'X-Buycraft-Secret: b510b084c9b7ca746c8713ade7003cc6ea6279dc' "https://plugin.buycraft.net/queue/offline-commands"

Example Response

{
  "meta": {
    "limited": false
  },
  "commands": [
    {
      "id": 1,
      "command": "say Thank you for purchasing, {name}.",
      "payment": 123,
      "package": 123,
      "conditions": {
        "delay": 60
      },
      "player": {
        "id": 1,
        "name": "Notch",
        "uuid": "365bfa21803249ee9b634fe890c9d43f"
      }
    },
    {
      "id": 2,
      "command": "say Thank you for purchasing, {name}.",
      "payment": 123,
      "package": 123,
      "conditions": {
        "delay": 0
      },
      "player": {
        "id": 2,
        "name": "7n",
        "uuid": "ef01f2da1b284ad6ba8ba2aaf4432e22"
      }
    },
    {
      "id": 3,
      "command": "say Thank you for purchasing, {name}.",
      "payment": 123,
      "package": 123,
      "conditions": {
        "delay": 0
      },
      "player": {
        "id": 3,
        "name": "hfmx",
        "uuid": "897a2737777a4776909a0148919c376a"
      }
    }
  ]
}

Get the offline commands which are due to be executed.

These commands should be executed immediately and no checks are required against the related players.

Get online commands

Endpoint

GET https://plugin.buycraft.net/queue/online-commands/{player-id}

Example Request

curl -X GET -H 'X-Buycraft-Secret: b510b084c9b7ca746c8713ade7003cc6ea6279dc' "https://plugin.buycraft.net/queue/online-commands/50"

Example Response

{
  "commands": [
    {
      "id": 1,
      "command": "give {name} TNT",
      "payment": 123,
      "package": 123,
      "conditions": {
        "delay": 0,
        "slots": 0
      }
    },
    {
      "id": 2,
      "command": "give {name} DIRT",
      "payment": 123,
      "package": 123,
      "conditions": {
        "delay": 0,
        "slots": 0
      }
    },
    {
      "id": 3,
      "command": "give {name} STONE",
      "payment": 123,
      "package": 123,
      "conditions": {
        "delay": 0,
        "slots": 0
      }
    }
  ]
}

List the due online commands for a specific player.

These commands should only be executed when the player is online and all conditions have been met (such as if the player has the required amount of inventory slots).

Delete commands

Endpoint

DELETE https://plugin.buycraft.net/queue

Example Request

curl -X DELETE -H 'X-Buycraft-Secret: b510b084c9b7ca746c8713ade7003cc6ea6279dc' "https://plugin.buycraft.net/queue?ids[]=1&ids[]=2&ids[]=3"

Example Response


Delete one or more commands which have been executed on the Minecraft Server.

An empty response consisting of a 204 No Content status code will be returned on completion.

Parameters:

Name Type Description
ids array An array of one or more command IDs to delete.

Listing

Endpoint

GET https://plugin.buycraft.net/listing

Example Request

curl -X GET -H 'X-Buycraft-Secret: b510b084c9b7ca746c8713ade7003cc6ea6279dc' "https://plugin.buycraft.net/listing"

Example Response

{
  "categories": [
    {
      "id": 1,
      "order": 0,
      "name": "Ranks",
      "only_subcategories": false,
      "subcategories": [],
      "packages": [
        {
          "id": 1,
          "order": 0,
          "name": "Premium Membership",
          "price": "4.99",
          "sale": {
            "active": false,
            "discount": "0.00"
          }
        },
        {
          "id": 2,
          "order": 1,
          "name": "Ultimate Membership",
          "price": "9.99",
          "sale": {
            "active": true,
            "discount": "1.99"
          }
        }
      ]
    }
  ]
}

Get the categories and packages which should be displayed to players in game.

The returned order of this endpoint does not reflect the desired order of the category/packages - please order based on the order object.

Payments

List all payments

Endpoint

GET https://plugin.buycraft.net/payments

Example Request

curl -X GET -H 'X-Buycraft-Secret: b510b084c9b7ca746c8713ade7003cc6ea6279dc' "https://plugin.buycraft.net/payments"

Example Response

[
  {
    "id": 1,
    "amount": "4.99",
    "date": "2016-01-27T15:40:19+0000",
    "currency": {
      "iso_4217": "GBP",
      "symbol": "£"
    },
    "player": {
      "id": 1,
      "name": "Notch",
      "uuid": "365bfa21803249ee9b634fe890c9d43f"
    }
  },
  {
    "id": 2,
    "amount": "9.99",
    "date": "2016-01-18T11:37:38+0000",
    "currency": {
      "iso_4217": "GBP",
      "symbol": "£"
    },
    "player": {
      "id": 2,
      "name": "7n",
      "uuid": "ef01f2da1b284ad6ba8ba2aaf4432e22"
    }
  }
]

Get the recent payments for displaying on in-game payment signs.

A limit parameter can be specified to restrict the amount of payments returned.

Please note that no more than 100 latest payments will be returned.

Get the required payment fields for a given package

Endpoint

GET https://plugin.buycraft.net/payments/fields/{id}

Example Request

curl -X GET -H 'X-Buycraft-Secret: b510b084c9b7ca746c8713ade7003cc6ea6279dc' "https://plugin.buycraft.net/payments/fields/123"

Example Response

[
  {
    "name": "price",
    "value": "Custom Price",
    "type": "numeric"
  },
  {
    "name": "server",
    "description": "Select a server to run commands on",
    "type": "dropdown",
    "options": [
      {
        "label": "Test Store",
        "value": 7
      },
      {
        "label": "Empty Server",
        "value": 21
      }
    ]
  },
  {
    "name": "uname",
    "description": "uname",
    "type": "username",
    "options": false
  },
  {
    "name": "global",
    "description": "Global level",
    "type": "numeric",
    "options": false
  }  
]

Get the required fields for any package by ID.

An array of all the fields required will be returned - for a payment creation to succeed, a value must be set for each field.

Create a manual payment

Endpoint

POST https://plugin.buycraft.net/payments/

Example Request

curl -X POST \
-H 'X-Buycraft-Secret: b510b084c9b7ca746c8713ade7003cc6ea6279dc' "https://plugin.buycraft.net/payments/" \
-H 'Content-Type: application/json' \
-d '{"ign"  : "test", "price": 10.00, "packages" : [ { "id"    : 57, "options"  : { "price"  : 9000, "server": 7, "uname" : "hfmx", "global": 1 } }, { "id"    : 75, "options"  : { } } ] }'

Example Success Response

204 No Content

Example Failure Response

{
  "error_code": 400,
  "error_message":  "Please select a valid server for the Package The First Package."
}

Create a manual payment in the same way as is possible from the control panel. One or more packages should be added to the payment, and the package commands will be processed in the same way as would be for a standard manual payment.

Parameters:

Name Type Description
ign username The IGN of the user to apply the payment to
price numeric The value of the payment being created
packages array An array of package options containing the following fields:
packages.id numeric The ID of the package
packages.options object An object of key => value pairs for the required option fields (as retrieved with the /fields/ API)

Checkout

Endpoint

POST https://plugin.buycraft.net/checkout

Example Request

curl -X POST -H 'X-Buycraft-Secret: b510b084c9b7ca746c8713ade7003cc6ea6279dc' "https://plugin.buycraft.net/checkout?username=Notch&package_id=123"

Example Response

{
  "url": "http://blocktastic.buycraft.net/buy/gj48f",
  "expires": "2015-11-30T18:10:18+0000"
}

Creates a URL which will redirect the player to the webstore and add the package to their basket.

Parameters:

Name Type Description
username string The username of the Minecraft player.
package_id int The ID of the package the player wants to purchase.

Gift Cards

List all gift cards

Endpoint

GET https://plugin.buycraft.net/gift-cards

Example Request

curl -X GET -H 'X-Buycraft-Secret: b510b084c9b7ca746c8713ade7003cc6ea6279dc' "https://plugin.buycraft.net/gift-cards"

Example Response

{
  "data": [
    {
      "id": 38,
      "code": "165261930219",
      "balance": {
        "starting": "25.00",
        "remaining": "12.60",
        "currency": "GBP"
      },
      "void": false
    }
  ]
}

Returns an array of all gift cards on your account.

Create a gift card

Endpoint

POST https://plugin.buycraft.net/gift-cards

Example Request

curl -X POST -H 'X-Buycraft-Secret: b510b084c9b7ca746c8713ade7003cc6ea6279dc' "https://plugin.buycraft.net/gift-cards"

Example Response

{
  "data": {
    "id": 40,
    "code": "094006746161",
    "balance": {
      "starting": "60.00",
      "remaining": "60.00",
      "currency": "GBP"
    },
    "void": false
  }
}

Create a gift card of a specified amount.

Parameters:

Name Type Description
amount string The currency value the gift card should have upon creation.

Retrieve an individual gift card

Endpoint

GET https://plugin.buycraft.net/gift-cards/{id}

Example Request

curl -X GET -H 'X-Buycraft-Secret: b510b084c9b7ca746c8713ade7003cc6ea6279dc' "https://plugin.buycraft.net/gift-cards/23"

Example Response

{
  "data": {
    "id": 23,
    "code": "094104746161",
    "balance": {
      "starting": "20.00",
      "remaining": "12.00",
      "currency": "GBP"
    },
    "void": false
  }
}

View a gift card by its ID.

Set a gift card as void

Endpoint

DELETE https://plugin.buycraft.net/gift-cards/{id}

Example Request

curl -X DELETE -H 'X-Buycraft-Secret: b510b084c9b7ca746c8713ade7003cc6ea6279dc' "https://plugin.buycraft.net/gift-cards/23"

Example Response

{
  "data": {
    "id": 23,
    "code": "094104746161",
    "balance": {
      "starting": "20.00",
      "remaining": "12.00",
      "currency": "GBP"
    },
    "void": true
  }
}

Void a gift card to prevent it from being used.

Coupons

List all coupons

Endpoint

GET https://plugin.buycraft.net/coupons

Example Request

curl -X GET -H 'X-Buycraft-Secret: b510b084c9b7ca746c8713ade7003cc6ea6279dc' "https://plugin.buycraft.net/coupons"

Example Response

{
  "data": [
    {
      "id": 2,
      "code": "mycode-123",
      "effective": {
        "type": "cart",
        "packages": [],
        "categories": []
      },
      "discount": {
        "type": "value",
        "percentage": 0,
        "value": 2
      },
      "expire": {
        "type": "never",
        "limit": 0,
        "date": "1901-12-13T20:45:52+0000"
      },
      "basket_type": "single",
      "start_date": "2017-01-01T00:00:00+0000",
      "user_limit": 1,
      "minimum": 5
    }
  ]
}

Returns an array of all coupons on your account.

Retrieve an individual coupon

Endpoint

GET https://plugin.buycraft.net/coupons/{id}

Example Request

curl -X GET -H 'X-Buycraft-Secret: b510b084c9b7ca746c8713ade7003cc6ea6279dc' "https://plugin.buycraft.net/coupons/2"

Example Response

{
  "data": {
    "id": 2,
    "code": "mycode-123",
    "effective": {
      "type": "cart",
      "packages": [],
      "categories": []
    },
    "discount": {
      "type": "value",
      "percentage": 0,
      "value": 2
    },
    "expire": {
      "type": "never",
      "limit": 0,
      "date": "1901-12-13T20:45:52+0000"
    },
    "basket_type": "single",
    "start_date": "2017-01-01T00:00:00+0000",
    "user_limit": 1,
    "minimum": 5
  }
}

View a coupon by its ID.

Create a coupon

Endpoint

POST https://plugin.buycraft.net/coupons

Example Request

curl -X POST -H 'X-Buycraft-Secret: b510b084c9b7ca746c8713ade7003cc6ea6279dc' "https://plugin.buycraft.net/coupons"

Example Response

{
  "data": {
    "id": 3,
    "code": "mycode-123",
    "effective": {
      "type": "cart",
      "packages": [],
      "categories": []
    },
    "discount": {
      "type": "value",
      "percentage": 0,
      "value": 2
    },
    "expire": {
      "type": "never",
      "limit": 0,
      "date": "-0001-11-30T00:00:00+0000"
    },
    "basket_type": "single",
    "start_date": "2017-01-01T00:00:00+0000",
    "user_limit": 1,
    "minimum": 5
  }
}

Create a coupon code.

Parameters:

Name Type Description
code [a-z0-9]+ The code of the coupon
effective_on package,category,cart What this coupon should be effective on
packages[] int[] If effective_on == ‘package’ one or more packages[] entries with the package_ids this should apply to
categories[] int[] If effective_on == 'category’ one or more categories[] entries with the category_ids this should apply to
discount_type percentage,value The discount type of this package
discount_amount numeric The currency amount to discount
discount_percentage numeric The percentage amount to discount
expire_type never,timestamp,limit The expire type of the coupon
expire_limit numeric Required field but only used if expire_type == limit
expire_date yyyy-mm-dd Required field but only used if expire_type == timestamp
start_date yyyy-mm-dd The start date of the coupon
basket_type single,subscription,both The type of basket this coupon should apply to
minimum numeric Minimum value of basket before the coupon can be redeemed
redeem_limit numeric Per user limit for redeeming this coupon

Delete a coupon

Endpoint

DELETE https://plugin.buycraft.net/coupons/{id}

Example Request

curl -X DELETE -H 'X-Buycraft-Secret: b510b084c9b7ca746c8713ade7003cc6ea6279dc' "https://plugin.buycraft.net/coupons/2"

Example Response


Delete a coupon code.

Returns 204 No Content if coupon has been deleted.