Locations

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

Scopes

locations:write locations.read

Core principles

A location should be unique by address.

Create a location

Create a new location. Requires scope locations:write

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

Request Body

Requires body of type LocationCreateRequest

Parameter	Description	Type	Required
`name`	Name of the location	`string`	`required`
`address`	Address of the location	`AddressRequest`	`required`
`website`	Website of the location	`string`	`optional`
`description`	Description of the location	`string`	`optional`
`merchantCategoryCode`	Merchant category code	`string`	`required`
`currency`	Currency used	`string`	`optional`
`timezone`	Timezone of the location	`string`	`optional`
`phoneNumber`	Phone number of the location	`string`	`optional`
`facebookUrl`	Facebook URL of the location	`string`	`optional`
`instagramUsername`	Instagram username of the location	`string`	`optional`
`twitterUsername`	Twitter username of the location	`string`	`optional`
`isActive`	Indicates if the location is active	`bool`	`optional`
`locale`	Locale of the location	`string`	`optional`
`email`	Email of the location	`string`	`optional`
`logo`	Logo URL of the location	`string`	`optional`
`images`	List of images associated with the location	`List<ImageCreateRequest>`	`optional`

LocationCreateRequest

{
    "name": "Main Store",
    "address": {
        "street": "123 Main St",
        "city": "Anytown",
        "state": "California",
        "stateCode": "CA",
        "postalCode": "12345",
        "country": "USA",
        "countryCode": "US",
        "location": {
			"longitude": -122.4194,
			"latitude": 37.7749
		}
    },
    "merchantCategoryCode": "1234",
    "currency": "USD",
    "timezone": "America/Los_Angeles",
    "phoneNumber": "(555) 555-5555",
    "email": "[email protected]",
    "locale": "en-CA",
    "isActive": true
}

Response

Returns a SBLocation

SBLocation

{
    "id": 1,
    "name": "Main Store",
    "address": {
        "street": "123 Main St",
        "city": "Anytown",
        "state": "California",
        "stateCode": "CA",
        "postalCode": "12345",
        "country": "USA",
        "countryCode": "US",
        "location": {
			"longitude": -122.4194,
			"latitude": 37.7749
		}
    },
    "merchantCategoryCode": "1234",
    "currency": "USD",
    "timezone": "America/Los_Angeles",
    "phoneNumber": "(555) 555-5555",
    "email": "[email protected]",
    "locale": "en-CA",
    "isActive": true
}

Code example

import { SBClient, SBLocation, LocationCreateRequest} from "@smartbills/sdk"
 
const client: SBClient = new SBClient();
const request: LocationCreateRequest = {
    "name": "Main Store",
    "address": {
        "street": "123 Main St",
        "city": "Anytown",
        "state": "California",
        "stateCode": "CA",
        "postalCode": "12345",
        "country": "USA",
        "countryCode": "US",
        "longitude": -122.4194,
        "latitude": 37.7749
    },
    "merchantCategoryCode": "1234",
    "currency": "USD",
    "timezone": "America/Los_Angeles",
    "phoneNumber": "(555) 555-5555",
    "email": "[email protected]",
    "locale": "en-CA",
    "isActive": true
};
 
const location: SBLocation = await client.location.create(request);

Retrieve location

Retrieve a location by ID. Requires scope locations.read

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

Path parameters

Parameter	Description	Type	Required
`id`	ID of the location to retrieve	`long`	`required`

Response

Returns a SBLocation

SBLocation

{
    "id": 1,
    "name": "Main Store",
    "address": {
        "street": "123 Main St",
        "city": "Anytown",
        "state": "California",
        "stateCode": "CA",
        "postalCode": "12345",
        "country": "USA",
        "countryCode": "US",
        "location": {
			"longitude": -122.4194,
			"latitude": 37.7749
		}
    },
    "merchantCategoryCode": "1234",
    "currency": "USD",
    "timezone": "America/Los_Angeles",
    "phoneNumber": "(555) 555-5555",
    "email": "[email protected]",
    "locale": "en-CA",
    "isActive": true
}

Code example

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

List locations

Retrieve a list of locations. Requires scope locations.read

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

Query parameters

Requires query parameters of type LocationListRequest

Parameter	Description	Type	Required	Default
`page`	Current page	`long`	`required`	1
`pageSize`	Number of records to return	`long`	`required`	100
`orderBy`	Order the results by a key of SBLocation	`keyof SBLocation`		`createdAt`
`sortOrder`	Order of the sort	`asc` or `desc`		`desc`

LocationListRequest

{
    "page": 1,
    "pageSize": 100,
    "orderBy": "createdAt",
    "sortOrder": "desc"
}

Response

Returns a SBList<SBLocation>

SBList<SBLocation>

{
    "data": [{
        "id": 1,
        "name": "Main Store",
        "address": {
            "street": "123 Main St",
            "city": "Anytown",
            "state": "California",
            "stateCode": "CA",
            "postalCode": "12345",
            "country": "USA",
            "countryCode": "US",
            "longitude": -122.4194,
            "latitude": 37.7749
        },
        "merchantCategoryCode": "1234",
        "currency": "USD",
        "timezone": "America/Los_Angeles",
        "phoneNumber": "(555) 555-5555",
        "email": "[email protected]",
        "locale": "en-CA",
        "isActive": true
    }],
    "metadata": {
        "page":1,
        "pageSize":100,
        "totalPages":1,
        "count":1
    }
}

Code example

import { SBClient, SBLocation, SBList, LocationListRequest} from "@smartbills/sdk"
 
const client = new SBClient();
const request: LocationListRequest = {
    "page": 1,
    "pageSize": 100,
    "orderBy": "createdAt",
    "sortOrder": "desc"
};
 
const locations: SBList<SBLocation> = await client.location.list(request);

Update a location

Update information about a location. Requires scope locations.write

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

Path parameters

Parameter	Description	Type	Required
`id`	ID of the location to update	`long`	`required`

Body parameters

Requires a body of type LocationUpdateRequest

Parameter	Description	Type	Required
`name`	Name of the location	`string`	`required`
`address`	Address of the location	`AddressRequest`	`required`
`website`	Website of the location	`string`	`optional`
`description`	Description of the location	`string`	`optional`
`merchantCategoryCode`	Merchant category code	`string`	`required`
`currency`	Currency used	`string`	`optional`
`timezone`	Timezone of the location	`string`	`optional`
`phoneNumber`	Phone number of the location	`string`	`optional`
`facebookUrl`	Facebook URL of the location	`string`	`optional`
`instagramUsername`	Instagram username of the location	`string`	`optional`
`twitterUsername`	Twitter username of the location	`string`	`optional`
`isActive`	Indicates if the location is active	`bool`	`optional`
`locale`	Locale of the location	`string`	`optional`
`email`	Email of the location	`string`	`optional`
`logo`	Logo URL of the location	`string`	`optional`
`images`	List of images associated with the location	`List<ImageCreateRequest>`	`optional`

LocationUpdateRequest

{
    "name": "Main Store",
    "address": {
        "street": "123 Main St",
        "city": "Anytown",
        "state": "California",
        "stateCode": "CA",
        "postalCode": "12345",
        "country": "USA",
        "countryCode": "US",
        "location": {
			"longitude": -122.4194,
			"latitude": 37.7749
		}
    },
    "merchantCategoryCode": "1234",
    "currency": "USD",
    "timezone": "America/Los_Angeles",
    "phoneNumber": "(555) 555-5555",
    "email": "[email protected]",
    "locale": "en-CA",
    "isActive": true
}

Response

Returns a SBLocation

SBLocation

{
    "id": 1,
    "name": "Main Store",
    "address": {
        "street": "123 Main St",
        "city": "Anytown",
        "state": "California",
        "stateCode": "CA",
        "postalCode": "12345",
        "country": "USA",
        "countryCode": "US",
        "location": {
			"longitude": -122.4194,
			"latitude": 37.7749
		}
    },
    "merchantCategoryCode": "1234",
    "currency": "USD",
    "timezone": "America/Los_Angeles",
    "phoneNumber": "(555) 555-5555",
    "email": "[email protected]",
    "locale": "en-CA",
    "isActive": true
}

Code example

 
import { SBClient, SBLocation, LocationUpdateRequest} from "@smartbills/sdk"
    
    const client:SBClient = new SBClient();
    const request: LocationUpdateRequest = {
        "name": "Main Store",
        "address": {
            "street": "123 Main St",
            "city": "Anytown",
            "state": "California",
            "stateCode": "CA",
            "postalCode": "12345",
            "country": "USA",
            "countryCode": "US",
            "longitude": -122.4194,
            "latitude": 37.7749
        },
        "merchantCategoryCode": "1234",
        "currency": "USD",
        "timezone": "America/Los_Angeles",
        "phoneNumber": "(555) 555-5555",
        "email": "[email protected]",
        "locale": "en-CA",
        "isActive": true
    }
    const location:SBLocation = await client.locations.updateAsync(1, request);

Delete a location

Delete a location. Requires scope locations:write

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

Path parameters

Parameter	Description	Type	Required
`id`	ID of the location to delete	`long`	`required`

Response

Returns a SBLocation

SBLocation

{
    "id": 1,
    "name": "Main Store",
    "address": {
        "street": "123 Main St",
        "city": "Anytown",
        "state": "California",
        "stateCode": "CA",
        "postalCode": "12345",
        "country": "USA",
        "countryCode": "US",
        "location": {
			"longitude": -122.4194,
			"latitude": 37.7749
		}
    },
    "merchantCategoryCode": "1234",
    "currency": "USD",
    "timezone": "America/Los_Angeles",
    "phoneNumber": "(555) 555-5555",
    "email": "[email protected]",
    "locale": "en-CA",
    "isActive": true
}

Code example

 
import { SBClient, SBLocation} from "@smartbills/sdk"
    
    const client:SBClient = new SBClient();
    const location:SBLocation = await client.locations.deleteAsync(1);

Merchants API Customers API