square-wrapi

Square Connect API Wrapper ▣

Client interface for accessing Square Connect API.

Update

This is a breaking change.

Applications created after February 16, 2016 will not be able to use the merchant methods. Instead, use business methods. For older apps use version 0.1.0. More info.: https://docs.connect.squareup.com/articles/connect-api-changes-2016-02/

Usage

Create a client object to connect to Square Connect API endpoints.

var squareWrapi = require('square-wrapi');

var client = new squareWrapi('v1', API_ACCESS_TOKEN);

A note about LOCATION_ID:

Most endpoint paths include a location_id parameter that indicates which of a business's locations your application is acting on behalf of. You can get a business's location IDs with the business.locations() endpoint method.

There are two ways to use the API (use #1 or #2 - not both):

• For a specific location.

If you have the location id, create the client object with the location id.

var client = new squareWrapi('v1', API_ACCESS_TOKEN, LOCATION_ID);

square-wrapi will use this location id. on calls that require location id and you do not have to provide it on each call.

• For all locations.

Create the client object without location id.

var client = new squareWrapi('v1', API_ACCESS_TOKEN);

Provide location_id as the first parameter to all the calls that require location id.

Once you have the client object, you are ready to make API calls to Square.

Provide parameters and a callback.

API calls follow this syntax:

client.apigroup.action(param1, ..., queryString, callback);

• param - (if required) url parameters - eg: For payments.retrieve the value for :payment_id. Provide location_id if you created the client without LOCATION_ID.
• queryString - (as required) API endpoint parameters as key-value pairs.

Examples

List Payments

client.payments.list({
    "begin_time": "2015-12-01T00:00:00Z",
    "end_time": "2015-12-31T00:00:00Z"
  },
  function(err, data) {
    if (!err) {
      console.log(data);
    } 
  }
);

// Or with location_id
client.payments.list('JGHJ0343', {
    "begin_time": "2015-12-01T00:00:00Z",
    "end_time": "2015-12-31T00:00:00Z"
  },
  function(err, data) {
    if (!err) {
      console.log(data);
    } 
  }
);

Fetch Single Payment

client.payments.retrieve('Jq74mCczmFXk1tC10GB', function(err, data) {
  if (!err) {
    console.log(data);
  } 
});

Create a Refund

client.refunds.create({
    "payment_id": "Jq74mCczmFXk1tC10GB",
    "type": "PARTIAL",
    "reason": "Returned Goods",
    "refunded_money": {
      "amount": -500,
      "currency_code": "USD"
    },
    "request_idempotence_key": "1"
  }, 
  function(err, data) {
    if (!err) {
      console.log(data);
    } 
  }
);

Update an item

client.items.update("442d1344-6d2b-4238-83d0-0284dfd335d8", {
    "name": "Milkshake",
    "description": "It's better than yours",
    "visibility": "PRIVATE"
  },
  function(err, data) {
    if (!err) {
      console.log(data);
    } 
  }
);

Upload Item Image

client.items.uploadImage(
  {
    formData: {
      custom_file: {
        value:  fs.createReadStream('/path/to/MyImage.png.png'),
        options: {
          filename: 'MyImage.png',
          contentType: 'image/png'
        }
      }
    }
  }, 
  function(err, data) {
    if (!err) {
      console.log(data);
    } 
  }
);

Deletes an existing fee (tax).

client.fees.del(FEE_ID, function(err, data) {
  if (!err) {
    console.log(data);
  } 
});

// or with location_id
client.fees.del(LOCATION_ID, FEE_ID, function(err, data) {
  if (!err) {
    console.log(data);
  } 
});

Removes a fee assocation from an item.

client.fees.remove(ITEM_ID, FEE_ID, function(err, data) {
  if (!err) {
    console.log(data);
  } 
});

// or with location_id
client.fees.remove(LOCATION_ID, ITEM_ID, FEE_ID, function(err, data) {
  if (!err) {
    console.log(data);
  } 
});

API Functions

Business Management

Business & Locations

• business.me
• business.locations

Employees

• employees.create
• employees.list
• employees.retrieve
• employees.update

Roles

• roles.create
• roles.list
• roles.retrieve
• roles.update

Timecards

• timecards.create
• timecards.list
• timecards.retrieve
• timecards.update
• timecards.del
• timecards.uploadImage

Cash Drawer Shifts

• cashDrawerShifts.list
• cashDrawerShifts.retrieve

Transaction Management

Payments

• payments.list
• payments.retrieve

Settlements

• settlements.list
• settlements.retrieve

Refunds

• refunds.create
• refunds.list

Orders

• orders.list
• orders.retrieve
• orders.update

Merchant (Deprecated)

• merchant.me
• merchant.retrieve

Bank Accounts

• bankAccounts.list
• bankAccounts.retrieve

Item Management

Items

• items.create
• items.list
• items.retrieve
• items.update
• items.del
• items.uploadImage

Variations

• variations.create
• variations.update
• variations.del

Inventory

• inventory.list
• inventory.adjust

Modifier Lists

• modifierLists.create
• modifierLists.list
• modifierLists.retrieve
• modifierLists.update
• modifierLists.del
• modifierLists.apply
• modifierLists.remove

Modifier Options

• modifierOptions.create
• modifierOptions.update
• modifierOptions.del

Categories

• categories.create
• categories.list
• categories.update
• categories.del

Discounts

• discounts.create
• discounts.list
• discounts.update
• discounts.del

Fees

• fees.create
• fees.list
• fees.update
• fees.del
• fees.apply
• fees.remove

Pages

• pages.create
• pages.list
• pages.update
• pages.del

Cells

• cells.update
• cells.del

License

MIT