Merchants API

Merchants

This object represents a merchant of your business. Use it to track receipts that belong to the same merchant.

merchants.read merchants.write

Core principles

A merchant should be unique by website.

SBMerchant

Create a merchant

Create a new merchant. Requires scope merchants.write

POST https://api.smartbills.io/v1/merchants

Request Body

Requires body of type MerchantCreateRequest

ParameterDescriptionTypeRequired
nameName of the merchantstringrequired
addressAddress of the merchantAddressRequestrequired
logoURL of the merchant's logostringrequired
timezoneTimezone of the merchantstringrequired
currencyCurrency used by the merchantstringrequired
websiteWebsite of the merchantstringrequired
phoneNumberPhone number of the merchantstringrequired
localeLocale of the merchantstringrequired
MerchantCreateRequest
{
  "name": "string",
  "address": {
    "line1": "string",
    "line2": "string",
    "city": "string",
    "state": "string",
    "country": "string",
    "stateCode": "string",
    "countryCode": "string",
    "postalCode": "string",
    "location": {
      "latitude": 43,
      "longitude": -73
    }
  },
  "logo": "string",
  "timezone": "string",
  "currency": "string",
  "website": "string",
  "phoneNumber": "string",
  "locale": "string"
}

Response

Returns a SBMerchant

SBMerchant
{
  "id": 0,
  "name": "string",
  "address": {
    "line1": "string",
    "line2": "string",
    "city": "string",
    "state": "string",
    "stateCode": "string",
    "country": "string",
    "countryCode": "string",
    "postalCode": "string",
    "location": {
      "latitude": -43.532,
      "longitude": -73.154
    },
    "formattedAddress": "string"
  },
  "currency": "string",
  "slug": "string",
  "timezone": "string",
  "website": "string",
  "phoneNumber": "string",
  "logo": "string",
  "createdAt": "2025-01-21T00:56:42.273Z",
  "updatedAt": "2025-01-21T00:56:42.273Z"
}

Code example

import { SBClient, SBMerchant, MerchantCreateRequest } from "@smartbills/sdk"
 
const client = new SBClient();
const request = {
	"name": "John's Store",
	"address": {
		"line1": "123 Main St",
		"line2": "Suite 100",
		"city": "Anytown",
		"state": "CA",
		"country": "USA",
		"stateCode": "CA",
		"countryCode": "US",
		"postalCode": "12345",
		"location": {
			"latitude": 37.7749,
			"longitude": -122.4194
		}
	},
	"logo": "https://example.com/logo.png",
	"timezone": "PST",
	"currency": "USD",
	"website": "https://example.com",
	"phoneNumber": "555-555-5555",
	"locale": "en-US"
};
 
const merchant = await client.merchant.create(request);

Retrieve merchant

Retrieve a merchant by ID. Requires scope merchants.read

GET https://api.smartbills.io/v1/merchants/:id

Path parameters

ParameterDescriptionTypeRequired
idID of the merchant to retrievelongrequired

Response

Returns a SBMerchant

SBMerchant
{
  "id": 0,
  "name": "string",
  "address": {
    "line1": "string",
    "line2": "string",
    "city": "string",
    "state": "string",
    "stateCode": "string",
    "country": "string",
    "countryCode": "string",
    "postalCode": "string",
    "location": {
      "longitude": 0,
      "latitude": 0
    },
    "formattedAddress": "string"
  },
  "currency": "string",
  "slug": "string",
  "timezone": "string",
  "website": "string",
  "phoneNumber": "string",
  "logo": "string",
  "createdAt": "2025-01-21T00:56:42.273Z",
  "updatedAt": "2025-01-21T00:56:42.273Z"
}

Code example

import { SBClient, SBMerchant } from "@smartbills/sdk"
 
const client = new SBClient();
const merchant = await client.merchant.getByIdAsync(1);

List merchants

Retrieve a list of merchants. Requires scope merchants.read

GET https://api.smartbills.io/v1/merchants?page=1&pageSize=100

Query parameters

Requires query parameters of type MerchantListRequest

ParameterDescriptionTypeRequiredDefault
pageCurrent pagelongrequired1
pageSizeNumber of records to returnlongrequired100
orderByOrder the results by a key of SBMerchantkeyof SBMerchantcreatedAt
sortOrderOrder of the sortasc or descdesc
MerchantListRequest
{
    "page": 1,
    "pageSize": 100,
	"orderBy": "createdAt",
	"sortOrder": "desc",
}

Response

Returns a SBList<SBMerchant>

SBList<SBMerchant>
{
    "data": [{
        "id": 0,
        "name": "string",
        "address": {
            "line1": "string",
            "line2": "string",
            "city": "string",
            "state": "string",
            "stateCode": "string",
            "country": "string",
            "countryCode": "string",
            "postalCode": "string",
            "location": {
                "latitude": -43.532,
                "longitude": -73.154
            },
            "formattedAddress": "string"
        },
        "currency": "string",
        "slug": "string",
        "timezone": "string",
        "website": "string",
        "phoneNumber": "string",
        "logo": "string",
        "createdAt": "2025-01-21T00:56:42.273Z",
        "updatedAt": "2025-01-21T00:56:42.273Z"
    }],
    "metadata": {
        "page": 1,
        "pageSize": 100,
        "totalPages": 1,
        "count": 1
    }
}

Code example

import { SBClient, SBMerchant, SBList, MerchantListRequest } from "@smartbills/sdk"
 
const client = new SBClient();
const request = {
	"page": 1,
	"pageSize": 100,
	"orderBy": "createdAt",
	"sortOrder": "desc"
};
 
const merchants = await client.merchant.list(request);

Update a merchant

Update information about a merchant. Requires scope merchants.write

PUT https://api.smartbills.io/v1/merchants/:id

Path parameters

ParameterDescriptionTypeRequired
idID of the merchant to updatelongrequired

Body parameters

Requires a body of type MerchantUpdateRequest

ParameterDescriptionTypeRequired
nameName of the merchantstringrequired
addressAddress of the merchantAddressRequestrequired
logoURL of the merchant's logostringrequired
timezoneTimezone of the merchantstringrequired
currencyCurrency used by the merchantstringrequired
websiteWebsite of the merchantstringrequired
phoneNumberPhone number of the merchantstringrequired
localeLocale of the merchantstringrequired
MerchantUpdateRequest
{
  "name": "string",
  "address": {
    "line1": "string",
    "line2": "string",
    "city": "string",
    "state": "string",
    "country": "string",
    "stateCode": "string",
    "countryCode": "string",
    "postalCode": "string",
    "location": {
      "latitude": 43,
      "longitude": -73
    }
  },
  "logo": "string",
  "timezone": "string",
  "currency": "string",
  "website": "string",
  "phoneNumber": "string",
  "locale": "string"
}

Response

Returns a SBMerchant

SBMerchant
{
  "id": 0,
  "name": "string",
  "address": {
    "line1": "string",
    "line2": "string",
    "city": "string",
    "state": "string",
    "stateCode": "string",
    "country": "string",
    "countryCode": "string",
    "postalCode": "string",
	"location": {
		"latitude": -43.532,
		"longitude":-73.154
	},
    "formattedAddress": "string"
  },
  "currency": "string",
  "slug": "string",
  "timezone": "string",
  "website": "string",
  "phoneNumber": "string",
  "logo": "string",
  "createdAt": "2025-01-21T00:56:42.273Z",
  "updatedAt": "2025-01-21T00:56:42.273Z"
}

Code example

import { SBClient, SBMerchant, MerchantUpdateRequest } from "@smartbills/sdk"
	
const client = new SBClient();
const request = {
	"name": "John's Store Updated",
	"address": {
		"line1": "123 Main St",
		"line2": "Suite 100",
		"city": "Anytown",
		"state": "CA",
		"country": "USA",
		"stateCode": "CA",
		"countryCode": "US",
		"postalCode": "12345",
		"location": {
			"latitude": 37.7749,
			"longitude": -122.4194
		}
	},
	"logo": "https://example.com/logo.png",
	"timezone": "PST",
	"currency": "USD",
	"website": "https://example.com",
	"phoneNumber": "555-555-5555",
	"locale": "en-US"
};
 
const merchant = await client.merchants.updateAsync(1, request);

Delete a merchant

Delete a merchant. Requires scope merchants.write

DELETE https://api.smartbills.io/v1/merchants/:id

Path parameters

ParameterDescriptionTypeRequired
idID of the merchant to deletelongrequired

Response

Returns a SBMerchant

SBMerchant
{
  "id": 0,
  "name": "string",
  "address": {
    "line1": "string",
    "line2": "string",
    "city": "string",
    "state": "string",
    "stateCode": "string",
    "country": "string",
    "countryCode": "string",
    "postalCode": "string",
    "location": {
      "longitude": 0,
      "latitude": 0
    },
    "formattedAddress": "string"
  },
  "currency": "string",
  "slug": "string",
  "timezone": "string",
  "website": "string",
  "phoneNumber": "string",
  "logo": "string",
  "createdAt": "2025-01-21T00:56:42.273Z",
  "updatedAt": "2025-01-21T00:56:42.273Z"
}

Code example

import { SBClient, SBMerchant } from "@smartbills/sdk"
	
const client = new SBClient();
const merchant = await client.merchants.deleteAsync(1);
Going into productionLocations API